Difference between revisions of "FAQ Order SSL Certificates"

From Overbyte
Jump to navigation Jump to search
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
−
== SSL/TLS X509 certificates ==
+
== SSL/TLS X509 certificates ==
  
 
There are effectively three classes of SSL/TLS X509 certificates, Domain Validated,
 
There are effectively three classes of SSL/TLS X509 certificates, Domain Validated,
Line 6: Line 6:
 
usually with three variations, single domain, multiple domains (SANs), and
 
usually with three variations, single domain, multiple domains (SANs), and
 
wildcard.  Adding multiple domains to a certificate can ease administration and
 
wildcard.  Adding multiple domains to a certificate can ease administration and
−
is cheaper than multiple certificates, wild card means any subdmains usually for
+
is cheaper than multiple certificates, wild card means any sub domains usually for
 
the cost of about six single domains.
 
the cost of about six single domains.
  
Line 32: Line 32:
 
validation if legal evidence is required.  Once approved, the certificate and be
 
validation if legal evidence is required.  Once approved, the certificate and be
 
downloaded automatically.
 
downloaded automatically.
 +
 +
 +
== ACME Suppliers Supported ==
 +
 +
More information about these suppliers and Acme in general at: https://acmeprotocol.dev/getting-started/
 +
 +
Not spent much time testing the commercial ACME suppliers, will only do so if
 +
there is commercial need.  It's possible the component will need tweaking slightly
 +
since each supplier interprets the ACME RFC in slightly different ways.
 +
 +
=== AcmeLetsEncrypt, AcmeLetsEncryptTest ===
 +
 +
Let's Encrypt, domain validated, multiple domains, multiple wildcards allowed, 90 day.
 +
https://letsencrypt.org/
 +
External account: Not Required
 +
ICS Status: Tested OK, email no longer required.
 +
Certificate: 90 day expiry, reducing to 10 days in 2029.
 +
Challenges: HTTP, DNS, ALPN
 +
 +
 +
=== AcmeGoogle, AcmeGoogleTest ===
 +
 +
Public Certificate Authority, from Google Trust Services, multiple wild cards allowed, 1 to 90 day.
 +
https://pki.goog/
 +
External account: Required, get EAB Credentials by installing Google Cloud CLI Windows application, creating
 +
a new Google Cloud project, binding an existing Google account to the project, enabled GoogleAPIs, then finally
 +
running a command that returns the EAB credentials, just a new command lines in a Command Window.  EAB
 +
credential can only be used once for a new Acme account (ie new public key).
 +
ICS Status: Tested OK.
 +
Certificate: 1 to 90 day expiry selectable, Issuer: WR1, Root: GTS Root R1 (optionally GlobalSign)
 +
Limits: unlimited and free.
 +
Challenges: HTTP, DNS, ALPN
 +
 +
 +
=== AcmeDigicert, AcmeDigicertTest ===
 +
 +
No free certificates, only organisation and extended validation commercial certificates
 +
https://docs.digicert.com/en/certcentral/certificate-tools/certificate-lifecycle-automation-guides/third-party-acme-integration.html
 +
External account: Required, https://www.digicert.com/account/signup/, certificate organisations need pre-authorisation,
 +
payment details needed, different EAB credentials seem to be provided for different types of certificates, although
 +
directory seems to be the same.
 +
ICS Status: Testing for account only, no certificates ordered, only commercial so needs prepayment.
 +
Challenges: HTTP, DNS
 +
 +
 +
=== AcmeZeroSSL ===
 +
 +
ZeroSSL, Domain Validated, 3 90 day certs free, paid accounts for more and for one year and wild card.
 +
https://zerossl.com/documentation/api/
 +
External account: Required, get EAB Credentials from https://app.zerossl.com/dashboard/start
 +
ICS Status: Testing failed, could not create an Acme account, might need billing information.
 +
 +
 +
=== AcmeSslcomRSA, AcmeSslcomECC ===
 +
Free 90 day single domain certificates, paid accounts one year and other certificate types.
 +
If account has funds, issues one year.
 +
https://www.ssl.com/how-to/order-free-90-day-ssl-tls-certificates-with-acme/
 +
External account: Required, get EAB Credentials from https://secure.ssl.com/users/new
 +
ICS Status: Testing failed, could not create an Acme account, might need billing information.
 +
 +
 +
  
 
== TSslX509Certs Overview ==
 
== TSslX509Certs Overview ==
  
 
The TSslX509Certs component automatically downloads SSL/TLS X509 certificates from
 
The TSslX509Certs component automatically downloads SSL/TLS X509 certificates from
−
various suppliers, including free certificates from Let's Encrypt, and commercial
+
various ACME suppliers, including free certificates from Let's Encrypt and Google
−
certificates for Digicert, Comodo, Thawte and GeoTrust from CertCentre AG and
+
Trust Services, and commercial certificates from other ACME suppliers such as
−
Servertastic (not done yet). The component automates the process from creating
+
DigiCert, ZeroSSL, SSL.com, The component automates the process from creating
 
a new private key and certificate request, placing the order, arranging for
 
a new private key and certificate request, placing the order, arranging for
 
domain validated certificates to be checked by various challenge methods,
 
domain validated certificates to be checked by various challenge methods,
Line 48: Line 110:
 
validated certificates with very little extra code.
 
validated certificates with very little extra code.
  
−
The component supports the Acme V2 protocol specified in RFC8555 as implemented
+
The component supports the Acme V2 protocol specified in RFC8555 as originally
−
by Let's Encrypt to download free domain validated certificates. Note the Acme
+
implemented by Let's Encrypt to download free domain validated certificates.
−
protocol is only implemented sufficiently for Let's Encrypt, it is designed
 
−
to also handle commercial certificates which are more complicated to process.
 
−
The component will be updated to support commercial suppliers with Acme, when
 
−
we find one.
 
−
 
 
 
You don't need to register with Let's Encrypt, but it only supplies domain
 
You don't need to register with Let's Encrypt, but it only supplies domain
 
validated certificates so the domains for which you order certificates must
 
validated certificates so the domains for which you order certificates must
Line 60: Line 117:
 
challenges.
 
challenges.
  
−
Commercial suppliers of certificates have their own APIs, usually using HTTP
+
Earlier versions of this component also supported a custom REST API at CertCentre
−
REST, currently the component supports CertCentre AG https://www.certcenter.de/,
+
AG in Germany for DigiCert commercial certificates, but this service is now
−
https://www.certcenter.co.uk/ or https://www.certcenter.com/ from where you
+
discontinued and support removed from the component. DigiCert themselves now
−
can buy certificates issued by Comondo/Sectigo, DigiCert (including GeoTrust,
+
use ACME for commercial certificates, but this has not yet been tested with ICS.
−
Symantec and Thawte) and GlobalSign. You need to register with
 
−
CertCentre AG and open a reseller account to pay for any certificates bought,
 
−
although for testing most can be cancelled within 30 days without charge.
 
−
CertCentre AG uses OAuth2 authentication which is complex to set-up, but then
 
−
mostly invisible.  Domain validated certificates can be purchased and downloaded
 
−
automatically using file or DNS challenges, other types of certificates can be
 
−
ordered and then downloaded when the order is completed.
 
  
 
The TSslX509Certs component includes a database of certificate orders and pending
 
The TSslX509Certs component includes a database of certificate orders and pending
Line 78: Line 128:
 
or failure, allowing the application to inform the user (by email) of certificate
 
or failure, allowing the application to inform the user (by email) of certificate
 
ordering progress.
 
ordering progress.
 +
 +
ICS includes a sample OverbyteIcsX509CertsTst that is effectively an X509
 +
certificate management and ordering tool that can be used standalone to order
 +
certificates from Let's Encrypt and Google Trust Services for testing or
 +
commercial use, including wild card certificates provided you run your own
 +
Windows DNS Server.  These certificates can be used automatically by most
 +
non-ICS servers such as Windows IIS or Apache.
 +
 +
 +
 +
== TSslX509Certs Acme Supplier Accounts ==
 +
 +
From V9.5, ICS has a central Acme Supplier Account database that contains a list
 +
of the Acme work directories previously only referenced in separate IcsHosts INI
 +
files. The database is at C:\ProgramData\ICS-Acme-Accounts\ics-acme-accounts.db,
 +
and each Supplier Account has a Supplier Account Title, Acme Supplier Name, and
 +
Account Directory, which defaults to: C:\ProgramData\ICS-Acme-Accounts\SupplierTitle\
 +
but can be located elsewhere if required.
 +
 +
If an ICS server with automatic certificate ordering starts and no Acme Supplier
 +
Accounts are configured, the server will attempt to create one.  If the INI file
 +
was used prior to V9.5 and CertDirWork is specified with old account details,
 +
a new supplier AcmeLetsEncrypt-Old is created for that existing directory, and
 +
everything should work as previously.  If the INI file has SupplierTitle, no
 +
CertDirWork and sufficient details in IcsHosts, a new supplier is created with
 +
that title, the ICS samples use 'LetsEncrypt-New'.  Note this only happens if
 +
no suppliers are configured, so a typo in INI file does not create an unwanted
 +
supplier.
 +
 +
Otherwise, Acme Supplier Accounts must be created manually using the sample
 +
OverbyteIcsX509CertsTst or functions from the TSslX509Certs component in your
 +
application.  Note Google and other supplier accounts must be created manually,
 +
since they need extra external accounting details that are not in IcsHosts.
 +
 +
Each Supplier Account has an Account Directory in which the account private
 +
key file AcmePrivateKey.pem is created and stored, and all certificate and
 +
related files will be saved, with a database file ics-control.db containing
 +
information about the account, certificate orders and pending challenges.
 +
The account private key (separate to certificate private keys) is used to
 +
identify the account to the supplier and is created automatically if the
 +
directory is blank. This account private key will be needed to cancel or
 +
revoke any certificates issued using it.  Note an account directory and
 +
database can only be accessed by one application at a time, they can
 +
generally not be shared between different servers.
 +
 +
The sample OverbyteIcsX509CertsTst has tabs 'Acme Suppliers' and  'Supplier
 +
Details' that allows accounts to be created and edited, see later for details.
 +
 +
 +
== TSslX509Certs Work and Certificate Files ==
 +
 +
When ordering a new certificate, temporary files may be created in the account
 +
directory, the new certificate private key and certificate request.  Once the
 +
order is accepted and an order number is available, these files are renamed to
 +
include the order number for historic purposes, and when the order is completed
 +
a second copy of all files is saved without the order number for final distribution
 +
to the web server, and optionally copied to the web server using a UNC file share.
 +
Note the files without order numbers are always automatically overwritten by new
 +
orders.  So an Let's Encrypt order for the domain test3.telecom-tariffs.co.uk
 +
will generally find the following files upon completion:
 +
 +
ics-control.db
 +
AcmePrivateKey.pem
 +
AcmePublicKey.pem
 +
LE-SA-v1.2-November-15-2017.pdf
 +
LE-5860824-test3_telecom-tariffs_co_uk-bundle.pem
 +
LE-5860824-test3_telecom-tariffs_co_uk-certonly.pem
 +
LE-5860824-test3_telecom-tariffs_co_uk-inters.pem
 +
LE-5860824-test3_telecom-tariffs_co_uk-privatekey.pem
 +
LE-5860824-test3_telecom-tariffs_co_uk-request.pem
 +
LE-5860824-test3_telecom-tariffs_co_uk.pfx
 +
test3_telecom-tariffs_co_uk-bundle.pem
 +
test3_telecom-tariffs_co_uk-certonly.pem
 +
test3_telecom-tariffs_co_uk-inters.pem
 +
test3_telecom-tariffs_co_uk-privatekey.pem
 +
test3_telecom-tariffs_co_uk-request.pem
 +
test3_telecom-tariffs_co_uk.pfx
 +
 +
There is a PEM certificate signing request (CSR) file, separate PEM files for the
 +
private key, domain certificate and intermediate certificates, then a combined PEM
 +
bundle  with the certificates and private key, and a PKCS12 PFX file which is a
 +
similar bundle that Windows certificate store accepts.  The certificate private
 +
key files (and bundles) may be optionally password protected, the PFX file always
 +
has a password since Windows requires that, it will be 'password' if not otherwise
 +
specified. Note AcmePrivateKey is unprotected.  A wildcard order for
 +
*.telecom-tariffs.co.uk will have a file name x_telecom-tariffs_co_uk since * can
 +
not be used in file names.  Until the order number is available, the file name
 +
will be LE-work, or CC-work for CertCentre.  There are component options to
 +
ignore some of these files, if not needed.
 +
 +
 +
== TSslX509Certs Supplier Order Database ==
 +
 +
For each account there is a database file ics-control.db containing information
 +
about the account. certificate orders and pending challenges.  This is a simple
 +
INI file, and is generally updated only by the TSslX509Certs component.
 +
 +
There is an [account] section or record with general information about the
 +
supplier, logging, next order sequence number, ACME account private key, etc.
 +
 +
There are then multiple [domain-mydomain] sections or records for each X509 order
 +
placed where my-domain is the Common Name of the certificate, and then one
 +
section or record for each Subject Alternate Name on the certificate
 +
[san-mydomain=mysan] including the Common Name which are used for domain
 +
validation. These records are updated as the order progresses and may be
 +
checked afterwards to see the main files created and certificate details.  The
 +
record may be used to re-order a certificate, but not on the same day a
 +
certificate was downloaded to prevent wild repeated orders.
 +
 +
When an order has been placed, a temporary section [challenge-mysan] is created
 +
for each SAN on the certificate to keep track of challenge progress, effectively
 +
a queue of waiting challenges.  This queue is checked every 30 seconds and
 +
the supplier contacted to see if the challenge has completed or failed, the
 +
section is then removed with the main domain and san records updated.
 +
 +
The sample OverbyteIcsX509CertsTst has tabs 'Supplier Orders',  'Cert Domain',
 +
'Cert Admin' and 'Supplier New Order' that show all existing orders and allow
 +
new orders to be started.
  
  
Line 91: Line 259:
 
{| border=1
 
{| border=1
 
| width="130" valign="top" |ChallFileUNC||
 
| width="130" valign="top" |ChallFileUNC||
−
File - Web Server - UNC: copies a small file into the .well-known
+
ChallFileUNC  - File - Web Server - UNC: copies a small file into the .well-known
 
directory of the server using a UNC path, may be any type of web
 
directory of the server using a UNC path, may be any type of web
 
server on the same or remote PC.  Once the challenge is done,
 
server on the same or remote PC.  Once the challenge is done,
Line 102: Line 270:
 
|-
 
|-
 
| valign="top" |ChallFileFtp||
 
| valign="top" |ChallFileFtp||
−
File - Web Server - FTP: similar to ChallFileUNC, but the
+
ChallFileFtp  - File - Web Server - FTP: similar to ChallFileUNC, but the
 
application needs extra code to copy the file using FTP.
 
application needs extra code to copy the file using FTP.
 
|-
 
|-
 
| valign="top" |ChallFileApp||
 
| valign="top" |ChallFileApp||
−
File App Web Server: similar to ChallFileUNC, but handles the
+
File - App Web Server: similar to ChallFileUNC, but handles the
 
challenge file virtually without creating any files using a
 
challenge file virtually without creating any files using a
 
little code in the web server onWellKnownDir event to call an
 
little code in the web server onWellKnownDir event to call an
Line 116: Line 284:
 
|-
 
|-
 
| valign="top" |ChallFileSrv||
 
| valign="top" |ChallFileSrv||
−
File Local Web Server: similar to ChallFileApp, but uses a
+
File - Local Web Server: similar to ChallFileApp, but uses a
 
local web server TSimpleWebSrv listening on port 80 and the
 
local web server TSimpleWebSrv listening on port 80 and the
 
domain being validated, provided no other web server is using
 
domain being validated, provided no other web server is using
−
the same port and address.  This is used by the sample
+
the same port and IPv4 and IPv6 addresses.  This is used by the
−
OverbyteIcsX509CertsTst to order certificates separately without
+
sample OverbyteIcsX509CertsTst to order certificates separately
−
needing a web server, and by the TSslFtpServer and TIcsIpStrmLog
+
without needing a web server, and by the TSslFtpServer and other
 
components which don't usually listen on port 80.  The local web
 
components which don't usually listen on port 80.  The local web
 
server is only run while waiting for the challenge to be accessed
 
server is only run while waiting for the challenge to be accessed
Line 132: Line 300:
 
this requires application code to access the DNS server which is
 
this requires application code to access the DNS server which is
 
in the sample OverbyteIcsX509CertsTst.  It uses WMI to access a
 
in the sample OverbyteIcsX509CertsTst.  It uses WMI to access a
−
Windows 2012 or later public DNS Server on the same PC.  The next
+
Windows 2012 or later public DNS Server on the same PC.  Future
−
release will also support Cloudfare DNS via a REST API, and maybe
+
releases could support Cloudflare DNS via a REST API, and maybe
 
other cloud providers.  The benefit of using DNS is no conflicts
 
other cloud providers.  The benefit of using DNS is no conflicts
−
with web servers, and ordering wild card certificates like *.ftptest.org  
+
with web servers, and ordering wild card certificates like
−
that work with any sub-domains to avoid ordering
+
*.ftptest.org that work with any sub-domains to avoid ordering
 
certificates for each.  A certificate may have multiple wild card
 
certificates for each.  A certificate may have multiple wild card
 
names, such as *.ftptest.org.uk and *.ftptest.co.uk.
 
names, such as *.ftptest.org.uk and *.ftptest.co.uk.
 +
|-
 +
| valign="top" |ChallDnsAcnt||
 +
DNS Account- Automatic: similar to ChallDnsAuto, but adds an
 +
account hash before _acme-challenge.domain. This challenge is
 +
Acme account specific, so different accounts can get certificates
 +
for the same domain name allowing redundancy.  Not tested yet
 +
since not supported by any suppliers.
 
|-
 
|-
 
| valign="top" |ChallDnsMan||
 
| valign="top" |ChallDnsMan||
Line 158: Line 333:
 
Only catch with this challenge is requesting the first certificate
 
Only catch with this challenge is requesting the first certificate
 
for a new domain, the server won't start without a certificate,
 
for a new domain, the server won't start without a certificate,
−
so will automatically create a self signed certificate to start.
+
so the TWSocketServer component automatically creates an ICS
 +
signed certificate so the service can start, which is ideally
 +
replaced a few seconds later when the order completes.
 
|-
 
|-
 
| valign="top" |ChallAlpnSrv||
 
| valign="top" |ChallAlpnSrv||
Line 174: Line 351:
 
| valign="top" |ChallEmail||
 
| valign="top" |ChallEmail||
 
Email Manually:  calls an event in the application, that could
 
Email Manually:  calls an event in the application, that could
−
send an email automatically, only supported for CertCentre.
+
send an email automatically, was supported for CertCentre.
 
|}
 
|}
  
Line 182: Line 359:
 
challenge data from the supplier and again checking it can be accessed from the
 
challenge data from the supplier and again checking it can be accessed from the
 
public internet, before asking the supplier to start testing the challenges.
 
public internet, before asking the supplier to start testing the challenges.
−
Let's Encrypt currently tests challenges three times from servers on different
+
Let's Encrypt and Google now test challenges several times from servers in
−
networks to avoid DNS spoofing.  In practice this all takes placed within
+
different countries networks to avoid DNS spoofing.  In practice this all
−
seconds.
+
takes place within seconds.
  
 
Beware that within a few seconds of a certificate order being completed, hackers
 
Beware that within a few seconds of a certificate order being completed, hackers
Line 192: Line 369:
 
transparency logs, and the hackers watch these logs.
 
transparency logs, and the hackers watch these logs.
  
−
 
−
== TSslX509Certs Accounts ==
 
−
 
−
The TSslX509Certs component has a concept of an Account Directory for a
 
−
certificate supplier into which all certificate and related files will be saved,
 
−
with a database file ics-control.db containing information about the account.
 
−
certificate orders and pending challenges.  For Let's Encrypt Acme, the directory
 
−
includes an account private key (separate to certificate private keys) that is
 
−
used to identify the account, this is created automatically if the directory is
 
−
blank. This account private key will be needed to cancel or revoke any
 
−
certificates issued using it.  Note an account directory and database can only
 
−
be accessed by one application at a time, they can not be shared between
 
−
different servers.
 
−
 
−
When ordering a new certificate, temporary files may be created in the account
 
−
directory, the new certificate private key and certificate request.  Once the
 
−
order is accepted and an order number is available, these files are renamed to
 
−
include the order number for historic purposes, and when the order is completed
 
−
a second copy of all files is saved without the order number for final distribution
 
−
to the web server, and optionally copied to the web server using a UNC file share.
 
−
Note the files without order numbers are always automatically overwritten by new
 
−
orders.  So an Let's Encrypt order for the domain test3.telecom-tariffs.co.uk
 
−
will generally find the following files upon completion:
 
−
 
−
ics-control.db
 
−
AcmePrivateKey.pem
 
−
AcmePublicKey.pem
 
−
LE-SA-v1.2-November-15-2017.pdf
 
−
LE-5860824-test3_telecom-tariffs_co_uk-bundle.pem
 
−
LE-5860824-test3_telecom-tariffs_co_uk-certonly.pem
 
−
LE-5860824-test3_telecom-tariffs_co_uk-inters.pem
 
−
LE-5860824-test3_telecom-tariffs_co_uk-privatekey.pem
 
−
LE-5860824-test3_telecom-tariffs_co_uk-request.pem
 
−
LE-5860824-test3_telecom-tariffs_co_uk.pfx
 
−
test3_telecom-tariffs_co_uk-bundle.pem
 
−
test3_telecom-tariffs_co_uk-certonly.pem
 
−
test3_telecom-tariffs_co_uk-inters.pem
 
−
test3_telecom-tariffs_co_uk-privatekey.pem
 
−
test3_telecom-tariffs_co_uk-request.pem
 
−
test3_telecom-tariffs_co_uk.pfx
 
−
 
−
There is a PEM certificate signing request (CSR) file, separate PEM files for the
 
−
private key, domain certificate and intermediate certificates, then a combined PEM
 
−
bundle  with the certificates and private key, and a PKCS12 PFX file which is a
 
−
similar bundle that Windows certificate store accepts.  The certificate private
 
−
key files (and bundles) may be optionally password protected, the PFX file always
 
−
has a password since Windows requires that, it will be 'password' if not otherwise
 
−
specified. Note AcmePrivateKey is unprotected.  A wildcard order for
 
−
*.telecom-tariffs.co.uk will have a file name x_telecom-tariffs_co_uk since * can
 
−
not be used in file names.  Until the order number is available, the file name
 
−
will be LE-work, or CC-work for CertCentre.  There are component options to
 
−
ignore some of these files, if not needed.
 
−
 
−
 
−
== TSslX509Certs Database ==
 
−
 
−
For each account there is a database file ics-control.db containing information
 
−
about the account. certificate orders and pending challenges.  This is a simple
 
−
INI file, and is generally updated only by the TSslX509Certs component.
 
−
 
−
There is an [account] section or record with general information about the
 
−
supplier, logging, next order sequence number, account private key (for Let's
 
−
Encrypt), etc.
 
−
 
−
There are then multiple [domain-mydomain] sections or records for each X509 order
 
−
placed where my-domain is the Common Name of the certificate, and then one
 
−
section or record for each Subject Alternate Name on the certificate
 
−
[san-mydomain=mysan] including the Common Name which are used for domain
 
−
validation. These records are updated as the order progresses and may be
 
−
checked afterwards to see the main files created and certificate details.  The
 
−
record may be used to re-order a certificate, but not on the same day a
 
−
certificate was downloaded to prevent wild repeated orders.
 
−
 
−
When an order has been placed, a temporary section [challenge-mysan] is created
 
−
for each SAN on the certificate to keep track of challenge progress, effectively
 
−
a queue of waiting challenges.  This queue is checked every 30 seconds and
 
−
the supplier contacted to see if the challenge has completed or failed, the
 
−
section is then removed with the main domain and san records updated.
 
  
 
== TSslX509Certs IssueState ==
 
== TSslX509Certs IssueState ==
  
 
The component keeps the IssueState for each order and pending challenge reflecting
 
The component keeps the IssueState for each order and pending challenge reflecting
−
the order progress, saved in the database as type TIssueState, as follows:
+
the order progress, saved in the database as type TIssueState. Several of these
 +
states relate directly to the supplier Acme order status. The states are as follows:
  
 
{| border=1
 
{| border=1
 
| width="130" valign="top" |IssStateNone||
 
| width="130" valign="top" |IssStateNone||
−
Not started.
+
Not started, previous order completed or new order failed
−
|-
+
and needs to be restarted. Acme supplier status: Invalid.
−
| valign="top" |IssStateAccount||
 
−
Account with certificate supplier has been opened.
 
 
|-
 
|-
 
| valign="top" |IssStateChecked||
 
| valign="top" |IssStateChecked||
 
Basic local checks completed, chosen domain challenge allowed,
 
Basic local checks completed, chosen domain challenge allowed,
−
such as copying a test file to .WellKnown directory and
+
such as copying a test file to .WellKnown directory or creating
−
accessing it by domain name from the public internet or
+
an TlsApln certificate, starting the local web server if needed,
−
checking a domain name server can be reached.
+
and then accessing the file or certificate by domain name from
 +
the public internet or checking a domain name server can be
 +
reached.  Note the Acme Supplier is not accessed at this stage.
 
|-
 
|-
 
| valign="top" |IssStateChallgReq||
 
| valign="top" |IssStateChallgReq||
−
Received acceptable challenge methods and data from supplier,
+
The order process has started and the supplier has been given
−
component will prepare some challenges, others may need to
+
a list of domain names and maybe IP addresses to be included
−
done manually or by the application such as DNS.  The
+
in the certificate, and the certificate profile and expiry
−
challenge data should remain valid for up to a week.
+
details, depending on supplier.  If acceptable, an order
 +
number is created and a URL for each domain which contains
 +
one or more domain challenges. The component selects the
 +
appropriate challenge according to the chosen method and will
 +
prepare some challenges, others may need to done manually
 +
or by the application such as DNS.  The challenges should
 +
remain valid for up to a week, the expiry date is shown
 +
on the Supplier Order tab. Acme supplier status: Pending.
 +
|-
 +
| valign="top" |IssStateChallgWaitTest||
 +
Does not appear to be used at present.
 
|-
 
|-
 
| valign="top" |IssStateChallgTest||
 
| valign="top" |IssStateChallgTest||
−
Challenges have been tested as ready for checking by supplier,
+
Challenges have been tested locally as ready for checking by
−
.WellKnown and TlsApln have been accessed from the public
+
supplier, .WellKnown and TlsApln have been accessed from the
−
internet or the DNS returns the correct TXT record.
+
public internet or the DNS returns the correct TXT record.
 +
The supplier order is ready to start. Acme supplier status:
 +
Pending.
 
|-
 
|-
 
| valign="top" |IssStateChallgPend||
 
| valign="top" |IssStateChallgPend||
−
Pending a response from the certificate supplier to the
+
The order process has started and the supplier has been asked
−
challenges, may be 30 seconds or several days if manual
+
to check the order domain challenges.  Waiting for a response
−
intervention is required.
+
from the certificate supplier to the challenges, may happen
 +
within 15 seconds, but each challenge is accessed from multiple
 +
servers around the world so may take longer.  DNS challenges
 +
sometimes take longer to propagate to secondary DNS servers.
 +
Acme supplier status: Pending.
 
|-
 
|-
 
| valign="top" |IssStateChallgOK||
 
| valign="top" |IssStateChallgOK||
 
All domain challenges have been passed by the supplier who is
 
All domain challenges have been passed by the supplier who is
 
now ready to accept a certificate supply request (CSR) and
 
now ready to accept a certificate supply request (CSR) and
−
issue the CA signed certificate.
+
issue the CA signed certificate. Acme supplier status: Ready.
 +
|-
 +
| valign="top" |IssStateFinalPend||
 +
All domain challenges have been passed by the supplier who is
 +
now ready to accept a certificate supply request (CSR) and
 +
issue the CA signed certificate. Acme supplier status: Ready.
 +
|-
 +
| valign="top" |ssStateIssuePend||
 +
The order has been accepted and finalised, but there is now
 +
a short delay while the new certificate is issued, perhaps a
 +
queue is the supplier is busy. Acme supplier status: Processing.
 +
|-
 +
| valign="top" |IssStateIssued||
 +
The new certificate has been issued and is ready to be
 +
collected by the component.  This normally happens
 +
automatically. Acme supplier status: Valid.
 
|-
 
|-
 
| valign="top" |IssStateCollect||
 
| valign="top" |IssStateCollect||
−
The CA signed certificate has been collected OK.  The
+
The new certificate has been collected OK, and all the
−
certificate can be collected again if something failed.
+
various certificate files, private keys, etc, have been
 +
created and copied to the specified directories.  The
 +
certificate can be collected again if something failed
 +
for a few days, usually. Acme supplier status: Valid.
 
|-
 
|-
−
| valign="top" |IssStateInstall||
+
| valign="top" |IssStateFinished||
−
Certificate has been installed for the server by the
+
The new certificate has been collected OK and the supplier
−
component. not supported yet.
+
has finished with this order, so it can not be collected
 +
again. Acme supplier status: Invalid.
 
|-
 
|-
 
| valign="top" |IssStateCancel||
 
| valign="top" |IssStateCancel||
−
Cancelled order, perhaps revoked certificate, so can not
+
Cancelled order, perhaps revoked certificate, so can not collect certificate again.
−
collect certificate again.
 
 
|}
 
|}
  
Line 327: Line 461:
 
== TSslX509Certs Sample Application ==
 
== TSslX509Certs Sample Application ==
  
−
There is a application Samples\Delphi\SslInternet\OverbyteIcsX509CertsTst.dpr
+
There is a application Samples\demos-delphi-vcl\OverbyteIcsX509CertsTst.dpr
 
that illustrates all the functionality of the TSslX509Certs component, allowing
 
that illustrates all the functionality of the TSslX509Certs component, allowing
 
certificates to be ordered and collected by clicking a few buttons.  The
 
certificates to be ordered and collected by clicking a few buttons.  The
 
sample also shows all certificates ordered by ICS components and saved in the
 
sample also shows all certificates ordered by ICS components and saved in the
−
account databases and allows them to be re-ordered.
+
supplier account databases and allows them to be re-ordered.
 +
 
 +
 
 +
=== Tab: Acme Suppliers ===
 +
 
 +
[[File:X509-acme-suppliers-1.png|1000px]]
 +
 
 +
The 'Acme Suppliers' tab shows all the supplier accounts created with their
 +
details, and which allows new accounts to be created or old ones deleted.  If
 +
upgrading from ICS 9.4 or earlier, use the 'Import Old Account' button to
 +
import the old Let's Encrypt account into a new supplier 'AcmeLetsEncrypt-Old'.
 +
 
 +
A supplier account must be opened by double clicking on the list or clicking
 +
Open Supplier Account before orders may be viewed.  There is an inactivity
 +
Account Close Timeout on the Account Common tab, that closes accounts in
 +
case applications attempt to access them, since there is currently no account
 +
locking, defaults to five minutes.
 +
 
 +
To create a new Acme Supplier, select the Acme Supplier Name from the list,
 +
a default Account Title and Account Directory will be filled but can be changed
 +
if required.  Most suppliers offers live and staging servers, the latter is
 +
best for testing since it issue certificates signed by a fake CA and there are
 +
fewer rate limits than the live server which may get blocked if you make
 +
too many mistakes during ordering. When 'Save New Account' is clicked, the
 +
Supplier Details tab will appear for more supplier information.
 +
 
 +
 
 +
=== Tab: Supplier Details ===
  
−
In the following sample descriptions, all the fields and buttons mentioned have
+
[[File:X509-acme-details-1.png|1000px]]
−
corresponding properties and methods in the TSslX509Certs component itself.
 
  
−
On the Common tab, there are various logging options, to keep track of activity
+
The 'Supplier Details' tab specifies the type of private and public keys
−
and for diagnostics when things don't work as expected, if the Log Directory is
+
for the account, Elliptic Curve secp256 is smallest so best. These keys
 +
are used to authenticate the account to the supplier, using a Json Web Key
 +
created from the private key to sign each POST request with a Json Web
 +
Signature, no user name is needed.
 +
 
 +
HTTP proxy URL is if the server is behind a NAT firewall so does not have a
 +
public address, the URL format is 'http://host:port' where :port is optional.
 +
 
 +
Let's Encrypt does not require any email or external accounting information,
 +
but these are needed for most other suppliers, taken from the console where
 +
you created an ACME account, see details about different suppliers earlier.
 +
 
 +
Socket Family is generally Any, unless the account should only be accessed
 +
over IPv4 or IPv6 specifically.  The Account Local Web Server is only needed
 +
if the sample uses the ChallFileSrv or ChallAlpnSrv challenges to locally
 +
order certificates without using a separate web server, for domains whose
 +
address is this server.  Select the server IP addresses, they may be public
 +
addresses or LAN if there is a NAT router forwarding an external IP to this
 +
PC, as is often done for development and testing. If the domain has both
 +
IPv4 (A) and IPv6 (AAAA) records, both family IP addresses must be specified,
 +
since they are both tested.  The local web server is only started when order
 +
processing starts and closed immediately after, but will not start if any
 +
other server is using the same IP addresses.
 +
 
 +
There are various logging options, to keep track of activity and for
 +
diagnostics when things don't work as expected, if the Log Directory is
 
not blank.  There are several levels of debug logging from just connections,
 
not blank.  There are several levels of debug logging from just connections,
 
through SSL negotiations, then HTTP headers and content, also Json logging for
 
through SSL negotiations, then HTTP headers and content, also Json logging for
−
protocol errors (or changes).  The Domain Challenge Methods are File Web Server
+
protocol errors (or changes).
−
UNC (external), File Web Server FTP (manual), File Local Web Server (built in),
+
 
−
Domain Name Server (manual), Email Manually, TLS-ALPN Cert (next release).  If
+
Click Save Supplier Details and the component will attempt to create an
−
using the Local Web Server, specify the IP address from the drop down box and
+
account or check it already exists.  The account number will appear on
−
start it with the button, this IP address must routed to be accessible from the
+
the tab, but is not really used for anything.
−
public internet with any domains requiring certificates pointing at it. Specify
+
 
−
a Supplier Account Email address for orders, that will receive progress
+
 
−
information. Add an optional private key password and encryption type (3DES) if
+
=== Tab: Accounts Common ===
−
needed.  Certificate CSR Origin specifies whether the component should create a
+
 
 +
[[File:X509-accOunts-common-1.png|1000px]]
 +
 
 +
The Accounts Common tab contains information common to all accounts on the
 +
PC, mostly specific to this sample.
 +
 
 +
Log Directory if not blank is where the sample will write a daily log file
 +
of all activity in the sample, as shown in the log window.  This directory
 +
does not apply to other applications using the component, they must
 +
implement their own logging.  Account Close Timeout is how long the sample
 +
keeps an account open for, default five minutes.  DNS Challenge can be
 +
selected as Local Windows DNS Server or Cloudflare DNS Server, but the
 +
latter is not yet supported, this applies when using the DNS Automatic
 +
challenges that only work if this server has a Windows DNS Server hosting
 +
the domain records for which an order is being placed, which will be
 +
accessed using WMI functions.
 +
 
 +
Private Key File Encryption specifies the type of encryption and password
 +
for any private key files generated, nearly always AES256.  Note the
 +
password is not encrypted in the database files.  It is primarily to
 +
allow private keys to be imported into Windows Store.  Default password
 +
is 'password'.
 +
 
 +
 
 +
=== Tab: Supplier Orders - View Orders ===
 +
 
 +
[[File:X509-supplier-orders-1.png|1000px]]
 +
 
 +
Once an old Suppler account is opened, the 'Supplier Orders' tab shows all
 +
the orders created for that account, and has buttons to start edit old
 +
orders to review certificates.  To start a new local order, skip this tab
 +
and go straight to the Cert Domain tab.
 +
 
 +
The order lists shows the Common Name, Order Date, Issue State,  Order Id,
 +
Issued Date, Expiry Date, Renew From Date, Challenge Type, Profile and
 +
Subject Alternate Names. Clicking on an order row shows further details
 +
with certificate dates and challenge details, maybe error for failures.
 +
 
 +
Orders for local server challenges can be started from this tab, old
 +
orders deleted or revoked, or old orders opened for limited editing.
 +
 
 +
 
 +
=== Tab: Cert Domain ===
 +
 
 +
[[File:X509-cert-domain-1.png|1000px]]
 +
 
 +
A new local order can be created by opening a Supplier Account, and selecting
 +
the 'Cert Domain' tab. Specify the Certificate Domain Common Name and any
 +
Subject Alternate Names, the sample application will add the Common Name to
 +
the SAN list if not done manually. If Domain Challenge is for UNC file, set
 +
the Web Server UNC HTTP .Well-Known Directory' for the Common Name, and
 +
optionally for each SAN if different.
 +
 
 +
If the final certificates are to be copied to the web server, set the Web
 +
Server UNC Public Certificates Directory.  There are various Output
 +
Certificate Formats that may be ticked or unticked to reduce the number
 +
of unneeded files, Separate PEM Files, PEM Bundle File, PKCS12/PFX Bundle
 +
File, PKCS7 Bundle File and CSR PEM File.
 +
 
 +
Windows Cert Store means the final certificate will be installed into the
 +
specified Windows Certificate Store for use by IIS web servers or other
 +
servers. The two stores are Current User or Local Machine Store, the latter
 +
needs Admin Rights for the sample if used for local orders, the former is
 +
not available for most Windows Services.
 +
 
 +
 
 +
=== Tab: Cert Admin ===
 +
 
 +
[[File:X509-cert-admin-1.png|1000px]]
 +
 
 +
The 'Cert Admin' tab contains further information needed for a new certificate
 +
order.  All certificates need to specify a Private Key Type and Size depending
 +
on security requirements, RSA2048 used to be common but Elliptic Curve secp256
 +
is smaller and more common now. Signature Digest Type usually SHA256. Serial
 +
Number Type is only used for Own CA orders, and is either random or sequential
 +
(stored in the database).
 +
 
 +
Most of the other admin fields, names, addresses, email, phone number, etc
 +
are for commercial certificates only, not domain validated certificates, and
 +
may be ignored.
 +
 
 +
 
 +
=== Tab: Supplier New Order - Settings ===
 +
 
 +
[[File:X509-new-order-1.png|1000px]]
 +
 
 +
Once the Cert Domain and Cert Admin tabs have been completed for a new order,
 +
click on the 'Supplier New Order' tab.  Specify the 'Domain Challenge Method',
 +
details of which were discussed above but are: File - Web Server UNC (external),
 +
File - Web Server FTP (manual), File - Local Web Server (built in), File - App
 +
Web Server (ICS server), DNS Automatic, DNS Account Automatic,  DNS manual,
 +
Email Manually (not supported), TLS-ALPN - Web UNC (external), TLS-ALPN -
 +
Local Web (built-in) TLS-ALPN - App Web (ICS server).
 +
 
 +
Certificate CSR Origin specifies whether the component should create a
 
new private key and CSR for a new order, or use files previously created, in
 
new private key and CSR for a new order, or use files previously created, in
 
which case both should be specified and many properties will be ignored.  Click
 
which case both should be specified and many properties will be ignored.  Click
 
the 'Check CSR' button to read the files and check they contain the correct
 
the 'Check CSR' button to read the files and check they contain the correct
−
domain and the key matches.  Automatic Order Completion being ticked means the
+
domain and the key matches.  Normally used for commercial orders only.
−
component will check every 30 seconds to see if an order is ready for collection
 
−
and finish it automatically.
 
  
−
For CertCentre AG, you must create an account at https://www.certcenter.com/signup
+
Automatic Order Completion being ticked means the component will check every
−
first, then go to Settings, Your Apps & API Keys, under OAuth2 Your Apps, click
+
few seconds to see if an order is ready for collection and finish it
−
the blue + icon to create a new App, with OAuth2 Redirect-URI:
+
automatically.
−
http://localhost:8080/certcenter/. Back in the sample application, on the
 
−
CertCentre 0Auth tab, copy the various parameters from your new app to the sample
 
−
fields, App Auth URl, Client ID, Client Secret and Redirect-URI, set App Token
 
−
URL to https://api.certcenter.com/oauth2/token and scope to write, web server IP
 
−
to 127.0.0.1 port 8080.  The first time you access a CertCentre function, OAuth2
 
−
authentication will be triggered to display an account login page in your default
 
−
browser, then a German language page appears so click the 'Akzeptieren' button
 
−
which should result in the sample application completing OAuth2 and displaying
 
−
access and refresh tokens with an expiry date and time, and the browser saying
 
−
'App Token Generated Successfully'.  The tokens initially remain valid for 24
 
−
hours before another login is required, but may be refreshed manually or
 
−
automatically before they expire without needing another login. Refreshed tokens
 
−
expire after six hours, but can be extended again and again, provided the sample
 
−
application is still running.
 
  
−
On the Domain tab set the Certificate Domain Common Name and any Subject
+
Cert Profile or Type is currently for Let's Encrypt only and customises the
−
Alternate Names, the sample application will add the Common Name to the SAN list
+
certificate. 'Classic' is the original 90 days expiry certificate, 'tlsserver'
−
if not done manually. If Domain Challenge is for UNC file, set the Web Server UNC
+
is a simpler certificate missing the common name which is always duplicated
−
HTTP .Well-Known Directory' for the Common Name, and optionally for each SAN if
+
in the list of Alternate Subject Names. 'Shortlived' is a 160 hour (6.6 days)
−
different.  If the final certificates are to be copied to the web server, set the
+
expiring certificate that may also include IP addresses, currently only from
−
Web Server UNC Public Certificates Directory. Clicking the Test Domain Challenges
+
the test staging server, due for public use in late 2025. There is also a
−
button set-up challenges for all the domains and try to access them locally, to
+
tlsclient profile but this disappears in early 2026.  The profiles also
−
prove future challenges will be successful.  If commercial certificates are being
+
change order validity periods, classic authorisations remains valid for seven
−
ordered using Email Challenge, each SAN should specify the Approval Email address
+
days but that is reduced to one hour new newer profile, order lifetime used
−
required (scroll across the grid).  There are various Output Certificate Formats
+
to be seven days, but is now eight hours.
−
that may be ticked or unticked to reduce the number of unneeded files, Separate
 
−
PEM Files, PEM Bundle File, PKCS12/PFX Bundle File, PKCS7 Bundle File and CSR
 
−
PEM File.
 
  
−
The Cert Admin tab has a lot more fields relating to certificate orders. All
+
Certificate Period (days) is currently for Google certificates only, instead
−
certificates need to specify a Private Key Type and Size depending on security
+
of the Profile used by Let's Encrypt, to specify the expiry period, anywhere
−
requirements (generally RSA2048, EC256 is better but not supported by many
+
from three to 90 days at present, but the maximum will reduce over the next
−
certificates), Signature Digest Type usually SHA256, Serial Number Type either
+
few years. Very useful to allow testing short lived renewals today.
−
random or sequential (stored in the database), Certificate Period in days,
 
−
usually 365 for one year, 366 or more for two years, ignored for Let's Encrypt
 
−
which is always 90 days.  For commercial certificates, contact details,
 
−
organisation name, address, email and phone numbers are usually required as well.
 
−
Note that private keys EdDSA ED25519 and SHA3 hashes are not yet tested since
 
−
they are not supported by any certificate suppliers, likewise longer keys and
 
−
SHA sizes may not work.
 
  
 +
Once the order settings are specified, click the 'Save Order' button to
 +
update the account database.  The 'Check Order' button may be clicked to
 +
locally check the order, see below.
  
−
== TSslX509Certs ACME/Let's Encrypt Order Process ==
 
  
−
ACME (Automatic Certificate Management Environment) is the protocol designed by
+
=== Tab: Supplier New Order - Local Order ===
−
Let's Encrypt, currently at draft 16 and which should eventually become an
 
−
official RFC.  It is hoped other certificate suppliers will use ACME in future,
 
−
but currently only Let's Encrypt.  ACME V1 is partially supported by the
 
−
component since it was done before V2 became public, but should generally be
 
−
ignored.  Beware Let's Encrypt does not implement any of the ACME draft protocols
 
−
precisely, which is difficult for developers, but they are getting closer with V2.
 
  
−
Let's Encrypt offers live and staging servers, the latter is best for testing
+
The 'Supplier New Order' tab has a series of buttons labelled with steps 1 to
−
since it issue certificates signed by a fake CA and there are fewer rate limits
+
7 that allow the sample to order a certificate using the Local Web Server
−
than the live server which will only issue five duplicate certificates a week
+
specified for the account, with Local Web File or ALPN, or DNS Automatic
−
(if ordering goes mad), no more than 50 per domain per week and five failed
+
challenges (if the server has a public Windows Domain Name Server).  Local
−
domain validations per hour.  The component stops more than one order per
+
orders may also be started from the Supplier Order tab, but some of these
−
day for each domain.
+
seven steps are combined so there only five buttons.  Buttons are greyed and
 +
unresponsive until prior order steps are completed, and may by bypassed
 +
if Automatic Order Completion is selected with the buttons being enabled in
 +
sequence as the order progresses, often completed in less than one minute.
  
−
For local orders using the sample, there are six buttons numbered in the sequence
+
Clicking 'Check Order (1)' which will check the challenge method is valid for
−
in which they are used during ordering.  For orders from applications, some of
+
a local order by the sample, will then create local test challenges for all
−
these steps are combined.
+
domains specified and make HTTP requests to those domains to ensure they are
 +
accessible from the public internet.
  
−
Select a Account Directory for the database and certificates files, either by
+
Generally, the sample will be run on a PC or server with public internet
−
typing a path or clicking the square path box to select a Database Directory
+
addresses.  But for testing, the PC or server might only have LAN IP
−
using a dialog window.  Click 'Register Account (1)' which will create a new
+
addresses, with a NAT firewall forwarding public request to the LAN IPs.
−
account private key or open an old one, and then register the account. Once the
+
In this case, it may be necessary to use a public HTTP proxy server to
−
account is open, the Supplier Database tab will be updated with account details
+
access the public IP addresses, set-up on the Supplier Details tab.
−
and any certificate orders in the account database, with their issue state and
 
−
details.
 
  
−
After completing all the necessary domain name and certificate details on the
+
If the local challenges are not accessible, there is no point in the order
−
Common, Domain and Cert Admin tabs, click 'Check Order (2)' which will check the
+
being placed since it fail.  If the domains are accessible, the Order Issue
−
challenge method specified on the Common tab is valid and locally test all the
+
State changes to Checked, and the order can be started.
−
challenges for all domains specified.  If the local order checks succeed, the
 
−
order will be written to the account database, and the 'Get Challenges (3)'
 
−
button enabled.  The Supplier Database tab will be updated with the new order
 
−
with an Issue State of Checked.
 
  
−
Now click the 'Get Challenges (3)' button to start the order process. Let's
+
Clicking 'Start Order (2)' will to start the order process with the supplier.
−
Encrypt is asked to issue challenges for each of the domain names requested,
+
They are asked to issue challenges for each of the domain names requested,
 
which the component then prepares and writes to queue records in the database.
 
which the component then prepares and writes to queue records in the database.
−
As discussed above, challenges may include writing files, creating special
+
As discussed above, challenges may include writing server files, creating
−
SSL certificates or adding records to a Domain Name Server. Let's Encrypt
+
special SSL certificates or adding records to a Domain Name Server.
−
challenge data remains valid for about one week, so the certificate does not
+
Previously satisfied challenges remain valid for a period varying from eight
−
need to ordered immediately, or the same domains may have further certificates
+
hours to 30 days (for classic certificates) so the supplier may report the
−
issued without new challenges. This also allows time for a Domain Name Server
+
challenges already complete at the this stage.
−
to me manually updated (only for orders from the sample application).  Once
+
 
−
the challenges are ready, the 'Test Challenges (4)' button is enabled and order
+
Once the challenges are ready, Acme Order State becomes Pending, and the
−
state changes to ChallgReq.
+
Order Issue State changes to ChallgReq.
  
−
Clicking 'Test Challenges (4)' button starts locally test them, to make sure the
+
Clicking 'Test Challenges (3)' starts testing the supplier challenges, to
−
domains, files, etc are available from the public internet correctly. Once
+
make sure the domains, files, etc are available from the public internet
−
successful the 'Start Challenges (5)' button is enabled and order state changes
+
correctly, effectively repeating 'Check Order' but with real challenges.
−
to ChallgTest.
+
Once successful the Order Issue State changes to ChallgTest.
  
−
Clicking 'Start Challenges (5)' asks Let's Encrypt to test the challenges,
+
Clicking 'Start Challenges (4)' asks the supplier to test the challenges,
 
which usually takes from 15 seconds to a minute, unless they are very busy.
 
which usually takes from 15 seconds to a minute, unless they are very busy.
−
there are usually at least three challenge tests from different networks.
+
There are usually several challenge tests from different networks in
−
The Issue State on the Supplier Database tab will be updated to ChallgPend.
+
different countries. The Order Issue State will be updated to ChallgPend.
−
 
+
For HTTP challenges, the log window will display activity for the local
−
If Automatic Order Completion is enabled (on the Common tab), the component will
+
web server, which should be receiving and responding to multiple page
−
check for successful or failed challenges every 10 seconds while the sample
+
requests.
−
application is running, updating Issue Status to ChallgOK, Collected and
 
−
Installed if the order is successful, or None if it fails the challenges or
 
−
problems in collecting the certificate.
 
  
−
If Automatic Order Completion is not enabled, clicking the 'Collect Certificate
+
If Automatic Order Completion is enabled, the component will check the
−
(6)' button will check if the challenges have been successful and proceed to
+
Order Status (next button) for successful or failed challenges every five
−
collect the new SSL certificate.
+
seconds while the sample application is running, waiting for the Acme
 +
Order Status to change from Pending to Ready, then updating Issue Status
 +
to ChallgOK when that happens.
  
−
Multiple certificate orders may be placed using the same account, without waiting
+
Clicking 'Order Status (5)' makes a request to the supplier to check the
−
for earlier orders to be completed.  If the sample application is stopped, the
+
Acme Order Status which will change from Pending to Ready once the challenges
−
next time it is run and the Supplier Account opened, any pending orders will be
+
for all domains have been successfully tested.  The Order Issue State then
−
checked and completed if possible, or failed.
+
changes to FinalPend.  If any challenges fail, the Order Issue State changes
 +
to None and the order must be restarted.  The Supplier Orders tab should
 +
display the reason for failure, usually just unable to access the public
 +
server.
  
−
Once all challenges succeed, the component proceeds to collect the certificate.
+
Clicking 'Finalize Order (6)' is only possible once all challenges are
−
First, a new private key and certificate signing request will be created and
+
checked by the supplier and the Order Issue State is ChallgOK or FinalPend.
−
submitted or old ones uses if so specified on the Common tab. If the CSR matches
+
The component creates a new private key and certificate signing request
−
the domain challenge, a new domain SSL/TLS X509 certificate is downloaded and
+
using the domain details and sends a request to supplier to finalize the
−
saved including the order number, then the intermediate certificate that will be
+
order.  The supplier then matches the CSR against approved domain challenge
−
needed by the web server, then the PEM and PKCS12 bundles are built by adding the
+
and commences issue of a new certificate, which may take a few seconds. The
−
private key, as detailed above.  Finally the component runs a check to validate
+
Acme Order status changes to Processing and Order Issue State to IssuePend.
−
the certificate chain, and reports all the details. If validation passes, all the
+
Clicking 'Order Status (5)' again will check the Acme Order Status which
−
files are saved a second time without the order number, as detailed above. and
+
changes to Valid once the certificate is issued, with Order Issue State
−
the Issue Status updated to 'Collected'.  If a Web Server UNC Public Certificate
+
to Issued. If Automatic Order Completion is enabled, this happens
−
Directory has been specified, the certificates will be copied to the servers,
+
automatically.
−
and the Issue Status updated to 'Installed'.
 
  
−
Note that Let's Encrypt certificates are only valid for three months since they
+
Clicking 'Collect Certificate (7)' is only possible once Order Issue State
−
are intended to be renewed automatically.
+
is Issued.  The new SSL/TLS certificate is downloaded with any intermediate
 +
certificates needed to validate the trust chain.  The component then creates
 +
several files including the order number containing certificate, private
 +
keys, bundles, etc, depending on the 'Output Certificate Format' settings
 +
on the Cert Domain tab.  Finally the component runs a check to validate
 +
the certificate chain, and reports all the details in the log. If validation
 +
passes, all the files are saved a second time without the order number, as
 +
detailed above and the Order Issue State updated to Collected.  If a Web
 +
Server UNC Public Certificate Directory has been specified, the certificates
 +
will be copied to the servers.
  
−
Servers based on TWSocketServer will periodically check for new SSL certificates
+
Finally, the component will ask the supplier for Renewal Information for the
−
(RecheckSslCerts method) and will automatically order and install new
+
certificate.  This specifies how many days before expiry a certificate should
−
certificates typically 30 days before the old one expires.
+
be renewed, and how often these dates should be rechecked to see if the
 +
certificate needs immediate renewal due to being revoked. These dates are
 +
reported on the Supplier Orders tab.  Recheck is usually between six and 24
 +
hours and is done automatically by ICS servers.
  
 
Beware the account database is not designed to shared between multiple
 
Beware the account database is not designed to shared between multiple
Line 500: Line 760:
 
and only use the sample application to briefly check orders.
 
and only use the sample application to briefly check orders.
  
−
==TSslX509Certs CertCentre Order Process ==
+
=== Tab: Supplier Orders - Start or Revoke Orders ===
  
−
CertCentra AG orders are similar in concept to Let's Encrypt, but require a
+
[[File:X509-supplier-orders-2.png|1000px]]
−
commercial reseller account to opened to pay for commercial certificates, as
 
−
described earlier.  It is also necessary to choose the Certificate Product
 
−
carefully, probably with the assistance of the CertCentre web site, although
 
−
the sample application provides basic certificate features and cost.  Note
 
−
that Certificate Products change periodically as companies change name, issue
 
−
new products or cease old ones.  So renewing orders annually may not always work.
 
  
−
Select a Account Directory for the database and certificates files.  Click the
+
Back to the Supplier Order tab, there are various buttons, some of which
−
'Get Profile' button  will trigger OAuth2 if necessary (see earlier), then
+
match the supplier New Order tab and do the same thing, others combine tasks.
−
check your account  and list the Certificate Products that can be ordered as
 
−
a list. Clicking on a Certificate Product will display details and cost,
 
−
similarly to these examples:
 
  
−
PositiveSSL
+
Check Order - if the order use challenges FileApp or AlpnApp for a server,
−
Cost 6.7 GBP/year
+
just enables the Start Order button.  For a local order, does as it
−
  Max Validity: 24 months, Features: "DV","ECC"
+
suggests, checking local challenges.
−
CA: Comodo, Refund Period: 30 days
 
−
DV Methods: "FILE","DNS","EMAIL"
 
−
Predicted Approval Duration: 3 mins
 
  
−
InstantSSL
+
Start Order - if the order use challenges FileApp or AlpnApp for a server,
−
  Cost 23.1 GBP/year
+
a flag is set in the account database that will be checked next time the
−
Max Validity: 24 months, Features: "OV","RI","ECC"
+
server check renewal information, and will start an immediate order,
−
  CA: Comodo, Refund Period: 30 days
+
may take several hours since the database is not checked regularly. For
−
Predicted Approval Duration: 2 hours
+
a local order, starts the order, gets and checks the challenges, then
 +
asks the supplier to check the challenges. If Automatic Order Completion
 +
is enabled, Order status is checked every five seconds and everything
 +
just happens until the order is completed.
  
−
PositiveSSL Wildcard
+
Order Status - as above.
−
Cost 77. GBP/year
 
−
Max Validity: 24 months, Features: "DV","WC","ECC"
 
−
CA: Comodo, Refund Period: 30 days
 
−
DV Methods: "FILE","DNS","EMAIL"
 
−
Predicted Approval Duration: 3 mins
 
  
−
Comodo mit EV Multi-Domain (MDC)
+
Finalise Order - as above.
−
Cost 183.2 GBP/year
 
−
Max Validity: 24 months, Features: "EV","SAN","RI","ECC"
 
−
CA: Comodo, Refund Period: 30 days
 
−
SANMaxHosts: 250 at 60.2 GBP/year each
 
−
Predicted Approval Duration: 3 hours
 
  
−
Only certifcates showing DV Methods as FILE or DNS can use automated challenges,
+
Collect Order - as above.
−
EMAIL will need a manual response but collection will be automatic.  Organisation
 
−
and Extended validation (OV and EV) are processed manually.  ECC means that
 
−
EC private keys are supported.  WC means wild card, SAN is multiple domain names.
 
  
−
For commercial certificates, when checking the order a quotation is returned for
+
Cancel Order - allows an order to be stopped part way through the process.
−
the certificate cost.  The word BUY needs to typed to avoid spending money
 
−
too easily, then 'Order Commercial Cert' clicked. The private key and CSR are
 
−
generated and the order placed.  A number of errors may occur at this stage,
 
−
mostly related to missing fields such as address, telephone, etc.  For domain
 
−
validated certificates, challenge validation will then start, being automatic
 
−
for file similarly to Acme.  For email validation, organisation
 
−
and extended validated certificates, an order number is returned and the process
 
−
now stalls for manual processing.
 
  
−
If Automatic Order Completion is enabled (on the Common tab), the component will
+
Revoke Certificate - if a certificate has been issued but should no longer
−
check for successful or failed challenges and completed orders ready to collect
+
be trusted, it may be revoked.  Revoking an order should generally only be
−
the certificate, and complete them.
+
done if the certificate is in public use and the private key has been
 +
compromised.  Revoke means the certificate will be added to supplier CRL
 +
databases which may be checked by browsers to prevent compromised
 +
certificates being trusted until expiry. The reduced issue period of
 +
certificates is partly to avoid then needing to be revoked.
  
−
The 'List Orders' button will generate a list in the log of recent CertCentre
+
Remove Order - clears an old order from the supplier database but does not
−
orders with their order number and status.  For orders that are completed, the
+
revoke the certificate.
−
order number can be entered in the field and 'Collect Order' clicked to collect
 
−
the certificate, similarly to Acme.  Likewise, specific orders may be cancelled
 
−
within 30 days, and certificates revoked if necessary.
 
  
−
The Supplier Database tab also shows any orders for the account in the database,
+
Reset Order - sometimes challenge failure can mean the order gets stuck
−
and allows them to be Collected, Cancelled or Revoked.
+
and not complete or do anything useful, so this button resets the Issue
 +
State to none so it can be restarted.
  
−
== TSslX509Certs Own CA Order Process ==
+
Renewal Information - works for all unexpired collected or finished
 +
orders. Ask the supplier for Renewal Information for the certificate.
 +
This specifies how many days before expiry a certificate should be
 +
renewed, and how often these dates should be rechecked to see if the
 +
certificate needs immediate renewal due to being revoked.
  
−
For internal network use and testing, it is possible to create your Own
+
Edit Order - loads the selected order into Cert Domain, Cert Admin
−
Certificate Authority and issue your own SSL certificates for devices that are
+
and Supplier New Order tabs, allowing some settings to be changed
−
not accessible from the public internet.  To avoid horrible browser warnings,
+
and saved by the 'Save Order' button on the New Order tab.  While
−
your CA certificate needs to be installed as a trusted root on each device that
+
this works for local orders, those created by servers may change
−
will access servers running certificates issued by the CA.
+
the order information according to the IcsHosts and server settings.
 +
 
 +
:List Challenges - for an order in progress, will log the state of
 +
challenges being tested.
 +
 
 +
Redistribute - for a collected order, redistributes the certificate
 +
files according to the 'Output Certificate Format' settings.
 +
 
 +
 
 +
=== Tab: Own CA ===
 +
 
 +
[[File:X509-own-ca-1.png|1000px]]
 +
 
 +
For internal network use and testing, it is possible to issue your own
 +
SSL/TLS certificates for devices that are not accessible from the public
 +
internet.  These can be self signed certificates, but to try and avoid
 +
horrible browser warnings it is better to issue certificates signed by
 +
trusted root CA certificate that is installed in the Windows Store (and
 +
maybe other stores) as a trusted root on each device that will access
 +
servers running certificates issued by the CA.
 +
 
 +
ICS now has it's own SSL root certificate 'ICS Root CA' and two intermediates, 'ICS
 +
Intermediate' and 'ICS Intermediate Short', the last of which includes a private key
 +
so can be used to automatically sign new certificates by ICS server applications,
 +
rather than just self signed certificates as before. If the 'ICS Root CA' certificate
 +
is installed in the Window Store and browser stores, it should stop certificate
 +
warnings appearing. ICS applications automatically trust the ICS root, so will give
 +
no warnings. The short intermediate has a maximum 200 day expiry, so new versions will
 +
be issued regularly. There is a single function CreateSelfSignCertEx that creates
 +
signed certificates, and another IcsInstallIcsRoot that installs the ICS root into
 +
the Windows Store, so easy to use. It is possible to replace the ICS root with your
 +
own private root certificate and have servers create their own certificates against
 +
that root, for internal networks.
 +
 
 +
The ICS SSL root certificate is loaded automatically with the SslRootCAStore.Initialise
 +
function that loads the CA Root Store, and with the define OpenSSL_AutoLoad_CA_Bundle,
 +
to verify any ICS issued certificates.  The SslRootCAStore.Initialise functions also
 +
tries to load the file C:\ProgramData\ICS-OpenSSL\ExtraRootCABundle.pem which is an
 +
optional private root bundle that can be used for private customer or developer root
 +
CA certificates, in PEM format.
 +
 
 +
Alternatively, you can create your own certificate authority and intermediate
 +
to sign your own certificates.
  
 
The sample application has a button that will create self signed SSL certificates
 
The sample application has a button that will create self signed SSL certificates
Line 596: Line 874:
 
being shown.
 
being shown.
  
−
To issue your own signed SSL certificates, the usual settings on the Domain and
+
To issue your own signed SSL certificates, the usual settings on the Cert Domain
−
Cert Admin tabs should be completed, and the 'CA Signed Cert' button pressed.
+
and Cert Admin tabs should be completed, and the 'CA Signed Cert' button pressed.
 
The component will then create a new private key and CSR files, then a new
 
The component will then create a new private key and CSR files, then a new
 
certificate signed by the Own CA, in a process otherwise identical to collecting
 
certificate signed by the Own CA, in a process otherwise identical to collecting
Line 612: Line 890:
  
  
−
== TSslX509Certs Supplier Database ==
+
== TSslX509Certs: Main Methods for Accounts and Orders ==
−
 
 
−
As mention above, each Supplier Directory includes an Account Database, and
 
−
the Supplier Database tab has options to view Supplier Certificate Orders, and
 
−
perform most of functions previously discussed on those orders.
 
  
−
First select a Supplier Database from the drop down box, or a new one either by
+
The TSslX509Certs component provides many methods for dealing with accounts
−
typing a path or clicking the square path box to select a Database Directory
+
and the database, which relate closely to the buttons on the Orders tab.
−
using a dialog window.  Click the 'Open Supplier' button, the database will be
+
These functions are used by the TSslWSocketServer methods DoCheckOrderCert and
−
opened, the supplier details shown in the yellow box and the Supplier Certificate
+
DoProcOrderCert which are how severs using IcsHosts order certificates.
−
Orders list populated with the principal order details, clicking any line will
 
−
show extra details in the yellow box.  Certain buttons will be enabled or
 
−
disabled depending on each Issue State.
 
  
−
Buttons available are: Check Order, Get Challenges, Order Certificate (same as
+
=== function DBSuppliersRead: Boolean; ===
−
Test and Start Challenges above), Collect Certificate, Redistribute (copy to web
 
−
server again), Cancel Order (without revoke), Revoke Certificate and Remove
 
−
Order (removed from database only), most of which have been described for the
 
−
order process earlier.
 
  
−
Revoke an order should generally only be done if the certificate is in public
+
Opens and read the Acme Supplier Database C:\ProgramData\ICS-Acme-Accounts\ics-acme-accounts.db
−
use and the private key has been compromised. Revoke means the certificate will
+
into an array of AcmeSuppRecs records.
−
be added to supplier CRL and OCSP databases which are checked by browsers to
 
−
prevent compromised certificates being trusted until expiry.
 
  
−
The TSslX509Certs component provides several functions for dealing with accounts
 
−
and the database, which relate closely to the buttons on the Supplier Database
 
−
tab.  These functions are used by the TSslWSocketServer method OrderCert.
 
  
 +
=== function DBFindAccSupp(const ATitle: String): Integer; ===
  
−
== TSslX509Certs Main Functions ==
+
Searches for a Supplier Title in the AcmeSuppRecs records, returning the index if
 +
found, or -1.  The application should set the component properties:
 +
X509Cert.CertDirWork := AcmeSuppRecs[Idx].ASuppDir;
 +
X509Cert.AcmeSupplier := AcmeSuppRecs[Idx].ASupplier;
  
  
−
'''function OpenAccount(const WorkDir: String; CreateNew: Boolean = False): Boolean;'''
+
=== function SetAcmeAccount(CreateNew: Boolean = False): Boolean; ===
  
−
Opens the supplier account in the specified directory, optionally creating a new
+
Opens the supplier account as in CertDirWork, optionally creating a new
−
account if the directory does not exist or is empty. For a new account, several
+
account for AcmeSupplier if the directory does not exist or is empty.
−
properties are needed: DebugLevel, DomWebSrvIP, LogJson, LogPkeys, SupplierEmail,
+
For a new account, several properties can be set: DebugLevel, DomWebSrvIP,
−
SupplierProto, SupplierServer and SupplierTitle. SupplierEmail and SupplierProto
+
LogJson, LogPkeys, SupplierEmail, SupplierProto, SupplierServer.
−
as SuppProtoAcmeV2 and SuppProtoCertCentre and SupplierServer from
 
−
GetServerAPIUrl are required, others are optional.  For SuppProtoCertCentre
 
−
several more OAuth2 properties for the CertCentre AG account are needed: OAAppUrl,
 
−
OAClientId. OAClientSecret, OARedirectUrl, OARefrMinsPrior, OAScope, OATokenUrl,
 
−
OAWebSrvIP and OAWebSrvPort, see sample application for more info.
 
  
 
Once the account is opened, the property DomainItems returns an array of
 
Once the account is opened, the property DomainItems returns an array of
Line 662: Line 923:
  
 
The function will fail if ics-control.db can not be found or the working
 
The function will fail if ics-control.db can not be found or the working
−
directory mismatches the database.
+
directory mismatches the database. Call ClearAccount before using this.
 +
 
 +
 
 +
=== function CloseAccount: Boolean; ===
  
−
'''
 
−
function CloseAccount: Boolean;
 
−
'''
 
 
Close the account, if open.
 
Close the account, if open.
  
  
−
'''function CertReadDomain(const aDomain: String): Boolean;'''
+
=== function DBReadCNDomain(const CNDomain: String): Boolean; ===
  
−
For an open account, reads all the properties for an X509 SSL certificate with
+
For an open supplier account, reads all the properties for an order with
−
the Common Name from the database, if found, including one or more subject
+
the Common Name from the account database, if found, including one or more
−
alternate names.
+
subject alternate names.
  
 
The function will fail if the domain has not been saved in the database.
 
The function will fail if the domain has not been saved in the database.
 +
Call ClearCertOrder before using this.
 +
 +
 +
=== function DBWriteCNDomain: Boolean; ===
 +
 +
Save or update properties for CertCommonName certificate to the account database.
 +
There are many possible properties, all of which are illustrated in the sample
 +
application.  The main properties are: CertCommonName, AcmeSupplier,
 +
SuppCertChallenge, CertPKeyType, CertSignDigest, CertCsrOrigin, CertSerNumType,
 +
CertOutFmts, DirWellKnown, DirPubWebCert, PrivKeyPassword, PrivKeyCipher,
 +
CertSubAltNames, CertAcmeProfile and CertValidity (Google only).
 +
 +
Fails if account not opened, but does not check properties for validity.
 +
 +
 +
=== function AcmeCheckSaveOrder(DomainCheck: Boolean = True; UpdateDB: Boolean = False): Boolean; ===
 +
 +
This is the main function to start a certificate order, used by the
 +
'Check Order' buttons in the sample.  All required order properties must
 +
have been read using DBReadCNDomain or set as properties, and will be saved
 +
using DBWriteCNDomain if UpdateDB is set.  It checks the Common Name is
 +
included in the SANs and adds it if not, then checks the challenge method
 +
and SAN number are supported by the certificate product.
 +
 +
This function restarts the order process for an old order setting Order
 +
Issue State changes to None, even if old challenges are still valid.
 +
If DomainCheck is true, checks the domain is accessible from the public
 +
internet for domain challenges.  If the domains are accessible, the
 +
Order Issue State changes to Checked, and the order can be started.
 +
 +
 +
=== function AcmeV2GetChallgs: Boolean; ===
 +
 +
This is the main function to place a certificate order with the supplier,
 +
used by the 'Start Order' buttons in the sample. AcmeCheckSaveOrder must
 +
have passed first.  The supplier provides challenges for each domain in
 +
the order which the components prepares and the Order Issue State changes
 +
to ChallgReq.
 +
 +
 +
=== function AcmeV2TestChallgs: Boolean; ===
 +
 +
Once challenges have been acquired from the supplier, this function locally
 +
tests them, called by the 'Test Challenges' button.  Once done OK, the Order
 +
Issue State changes to ChallgTest.
  
  
−
'''function CertSaveDomain(const aDomain: String): Boolean;'''
+
=== function AcmeV2StartChallgs: Boolean; ===
  
−
Save or update properties for an X509 SSL certificate with the Common Name to
+
Once the challenges have been tested, this function asks the supplier to
−
the database.  There are many possible properties, depending on the type of
+
test them, called by the 'Start Challenges' button. Testing usually takes
−
certificate being ordered, the supplier, challenge type, etc, all of which are
+
from 15 seconds to a minute, sometimes a lot longer, and the Order Issue
−
illustrated in the sample application. The main properties are: CertCommonName,
+
State will be updated to ChallgPend. If Automatic Order Completion is
−
SuppCertChallenge as TChallengeType supports ChallFileUNC, ChallFileFtp,
+
enabled, the component will check the Order Status for successful or
−
ChallFileSrv, ChallDNS, ChallEmail, ChallAlpnUNC, ChallAlpnSrv, ChallManual,
+
failed challenges every five seconds waiting for the Acme Order Status
−
CertPKeyType as type TSslPrivKeyType typically PrivKeyRsa2048, CertSignDigest as
+
to change from Pending to Ready, then updating Issue Status to ChallgOK
−
type TEvpDigest typically Digest_sha256, CertCsrOrigin usually CsrOriginProps,
+
when that happens, and then calling AcmeV2OrderFinal and AcmeV2CollectCert.
−
CertSerNumType usually SerNumRandom, CertOutFmts usually set [OutFmtBudl,
 
−
OutFmtP12], DirWellKnown if ChallFileUNC, DirPubWebCert as a path,
 
−
PrivKeyPassword, PrivKeyCipher usually PrivKeyEncTripleDES, CertSubAltNames as
 
−
multiple subject alternate names if supported by the certificate, CertValidity
 
−
in days (usually 365 or 730), SuppCertProduct.
 
  
−
For SuppProtoCertCentre contact and address details are required: CertAddress,
 
−
CertContactEmail, CertContactFirst, CertContactLast, CertContactTitle,
 
−
CertCountry, CertLocality, CertOrgUnit, CertOrganization, CertPhone,
 
−
CertPostCode, CertState.  For commercial certificates, the sample application
 
−
provides ProductCA, ProductCertType, ProductDVAuth, ProductFeatures,
 
−
ProductMaxSan and ProductQuote, and will show the price of the certificate
 
−
with a warning before the product is saved, but once in the database it can
 
−
be ordered automatically if the CertCentre AG account has sufficient credit.
 
−
CertApprovEmail for email challenge.
 
  
−
Fails if account not opened, if CertCommonName does not match aDomain, if
+
=== function AcmeV2OrderStatus: Boolean; ===
−
SupplierProto is not set, or CertSubAltNames is empty.  But otherwise does
 
−
not check properties for validity.
 
  
 +
Requests the Acme order status at any point during the order process,
 +
but in particular when waiting for something to happen, called by
 +
the five second timer that runs Automatic Order Completion to check
 +
for status changes with the Order Issue State updated appropriately.
 +
Called by the 'Order Status 'button'.
  
−
'''function CertCheckDomain(const aDomain: String): Boolean;'''
 
  
−
For an open account, reads all the properties for an X509 SSL certificate with
+
=== function AcmeV2OrderFinal(LogErrors: Boolean = True): Boolean; ===
−
the Common Name from the database, if found, including one or more subject
 
−
alternate names. If CertCsrOrigin is CsrOriginCSR, the Common Name and SANs
 
−
are read from an old CSR file at CertOldCsrFile and the key file from
 
−
CertOldPrvKey.  It then checks the Common Name is included in the SANs and adds
 
−
it if not, then checks the challenge method and SAN number are supported by
 
−
the certificate product. Finally for domain file validation, the component copies
 
−
a file to the server Well-Known directory and checks it can be accessed using
 
−
each of the SANs domain names.  Any changes are saved to the database.
 
  
 +
Once the challenges have all been tested by the supplier, the order
 +
can be finalised, called by the 'Finalize Order' button.  The component
 +
creates a new private key and certificate signing request using the domain
 +
details and sends a request to supplier to finalize the order.  The
 +
supplier then matches the CSR against approved domain challenge and
 +
commences issue of a new certificate, which may take a few seconds.
 +
The Order Issue State becomes IssuePend. If Automatic Order Completion
 +
is enabled, the component will wait for the certificate to be issued
 +
by checking AcmeV2OrderStatus for Order Issue State Issued.
  
−
'''function CertOrderDomain(const aDomain: String): Boolean;'''
 
  
−
First calls CertCheckDomain, if that passes continues to place the SSL
+
=== function AcmeV2CollectCert: Boolean; ===
−
certificate order with the supplier, whose processes vary as described in
 
−
the ACME and CertCentre AG order processes earlier.  Collection will be
 
−
automatic once the challenges succeed.
 
  
 +
Once the certificate is issued by the supplier, it may be collected,
 +
called by the 'Collect Certificate' button or by Automatic Order
 +
Completion'.  The new SSL/TLS certificate is downloaded with any
 +
intermediate certificates needed to validate the trust chain.  The
 +
component then creates several files depending on the 'Output
 +
Certificate Format' settings, runs a check to validate the certificate
 +
chain and the Order Issue State updated to Collected.  If a Web
 +
Server UNC Public Certificate Directory has been specified, the
 +
certificates will be copied to the servers.
  
−
'''function CertCollectDomain(const aDomain: String): Boolean;'''
 
  
−
For an order with issue state challenge pending, checks if all the challenges
+
=== function DBReadCNDomDates(const CNDomain: String): Boolean; ===
−
have been completed successfully and then collects the order.
 
  
 +
Similar to DBReadCNDomain but only reads sufficient properties to
 +
check certificate renewal and whether the Acme supplier should
 +
be contacted to update renewal information.
  
−
'''function CertCancelDomain(const aDomain: String): Boolean;'''
+
 
 +
=== function CertRenewalDomain(const aDomain: String): Boolean; ===
 +
 
 +
Only available if a previously issued certificate is available, asks
 +
the Acme supplier how many days before expiry the certificate should
 +
be renewed.
 +
 
 +
 
 +
=== function CertCancelDomain(const aDomain: String): Boolean; ===
  
 
For an order with issue state Collected or Installed, will cancel the order
 
For an order with issue state Collected or Installed, will cancel the order
Line 744: Line 1,053:
  
  
−
'''function CertRevokeDomain(const aDomain: String): Boolean;'''
+
=== function CertRevokeDomain(const aDomain: String): Boolean; ===
  
 
For an order with issue state Collected or Installed, will cancel and revoke the
 
For an order with issue state Collected or Installed, will cancel and revoke the
Line 750: Line 1,059:
  
  
−
'''function CertRemoveDomain(const aDomain: String): Boolean;'''
+
=== function CertRemoveDomain(const aDomain: String): Boolean; ===
  
 
Removes any order from the database, to stop further processing or re-use.
 
Removes any order from the database, to stop further processing or re-use.
  
  
−
'''function CertRedistDomain(const aDomain: String): Boolean;'''
+
=== function CertRedistDomain(const aDomain: String): Boolean; ===
  
 
For an order with issue state Collected or Installed, copies the certificate
 
For an order with issue state Collected or Installed, copies the certificate
 
files to the web server again, if lost.
 
files to the web server again, if lost.
 +
 +
 +
== TSslWSocketServer and IcsHosts Configuration ==
 +
 +
The TSslWSocketServer, TSslHttpServer, TSslHttpAppSrv, TIcsProxy, TIcsHttpProxy, TSslFtpServer components
 +
all use the TSslX509Certs component to order certificates, using various properties specified in TSslWSocketServer
 +
and the IcsHosts properties it use to specify listeners.
 +
 +
Information about all these properties may be found in the OverbyteIcsWSocketS.pas unit and the Wiki web pages
 +
[[TWSocketServer]] and [[TWSocketServer.IcsHosts]]

Latest revision as of 16:55, 16 October 2025

Contents

SSL/TLS X509 certificates

There are effectively three classes of SSL/TLS X509 certificates, Domain Validated, Organisation Validated and Extended Validated, in order of cost and benefit, usually with three variations, single domain, multiple domains (SANs), and wildcard. Adding multiple domains to a certificate can ease administration and is cheaper than multiple certificates, wild card means any sub domains usually for the cost of about six single domains.

Domain Validated certificate issuance is mostly automated so they are cheap (or free), using one of four challenge methods: file validation where the supplier checks for a specific file under the domain, usually http://domain/.well-known/file, domain validation where a special DNS record is created that can be accessed by the supplier, TLS-ALPN SSL SNI (server name indication) validated where an https://domain/ connection is opened passing data using the ALPN extension, with the server returning a special self signed SSL certificate. and email validation where an email is sent to a predefined address at the domain, ie admin@domain, with a supplier link that must be clicked to confirm receipt and domain ownership.

File, TLS-ALPN and domain validation challenges can be automated, file is easiest using a simple HTTP server, TLS-ALPN using an HTTPS server, while domain validation is dependent on being able to access and control the DNS server of which there are many different products. Note validating challenges are not instant, the supplier may have a queue of challenges waiting to the tested, but usually happen within a couple of minutes. Applications need to be aware the wait may be longer. Automated wild card certificates typically use the domain validation challenge.

Organisation and Extended Validated certificates can be ordered online, but require manual validation that the company or organisation legally exists and is entitled to use the domain name which may take several days or weeks for extended validation if legal evidence is required. Once approved, the certificate and be downloaded automatically.


ACME Suppliers Supported

More information about these suppliers and Acme in general at: https://acmeprotocol.dev/getting-started/

Not spent much time testing the commercial ACME suppliers, will only do so if there is commercial need. It's possible the component will need tweaking slightly since each supplier interprets the ACME RFC in slightly different ways.

AcmeLetsEncrypt, AcmeLetsEncryptTest

Let's Encrypt, domain validated, multiple domains, multiple wildcards allowed, 90 day.
https://letsencrypt.org/
External account: Not Required
ICS Status: Tested OK, email no longer required.
Certificate: 90 day expiry, reducing to 10 days in 2029.
Challenges: HTTP, DNS, ALPN


AcmeGoogle, AcmeGoogleTest

Public Certificate Authority, from Google Trust Services, multiple wild cards allowed, 1 to 90 day.
https://pki.goog/
External account: Required, get EAB Credentials by installing Google Cloud CLI Windows application, creating
a new Google Cloud project, binding an existing Google account to the project, enabled GoogleAPIs, then finally
running a command that returns the EAB credentials, just a new command lines in a Command Window.   EAB
credential can only be used once for a new Acme account (ie new public key).
ICS Status: Tested OK.
Certificate: 1 to 90 day expiry selectable, Issuer: WR1, Root: GTS Root R1 (optionally GlobalSign)
Limits: unlimited and free.
Challenges: HTTP, DNS, ALPN


AcmeDigicert, AcmeDigicertTest

No free certificates, only organisation and extended validation commercial certificates
https://docs.digicert.com/en/certcentral/certificate-tools/certificate-lifecycle-automation-guides/third-party-acme-integration.html
External account: Required, https://www.digicert.com/account/signup/, certificate organisations need pre-authorisation,
payment details needed, different EAB credentials seem to be provided for different types of certificates, although
directory seems to be the same.
ICS Status: Testing for account only, no certificates ordered, only commercial so needs prepayment.
Challenges: HTTP, DNS


AcmeZeroSSL

ZeroSSL, Domain Validated, 3 90 day certs free, paid accounts for more and for one year and wild card.
https://zerossl.com/documentation/api/
External account: Required, get EAB Credentials from https://app.zerossl.com/dashboard/start
ICS Status: Testing failed, could not create an Acme account, might need billing information.


AcmeSslcomRSA, AcmeSslcomECC

Free 90 day single domain certificates, paid accounts one year and other certificate types.
If account has funds, issues one year.
https://www.ssl.com/how-to/order-free-90-day-ssl-tls-certificates-with-acme/
External account: Required, get EAB Credentials from https://secure.ssl.com/users/new
ICS Status: Testing failed, could not create an Acme account, might need billing information.



TSslX509Certs Overview

The TSslX509Certs component automatically downloads SSL/TLS X509 certificates from various ACME suppliers, including free certificates from Let's Encrypt and Google Trust Services, and commercial certificates from other ACME suppliers such as DigiCert, ZeroSSL, SSL.com, The component automates the process from creating a new private key and certificate request, placing the order, arranging for domain validated certificates to be checked by various challenge methods, collecting the certificate and intermediate, creating PEM and PKC12 bundle files with the private key, then copying the files to the web server ready for automatic installation. The TSslWSocketServer, TSslHttpServer, TSslHttpAppSrv, TIcsProxy, TIcsHttpProxy, TSslFtpServer and TIcsIpStrmLog components can assign a TSslX509Certs component to support automatic certificate ordering of domain validated certificates with very little extra code.

The component supports the Acme V2 protocol specified in RFC8555 as originally implemented by Let's Encrypt to download free domain validated certificates. You don't need to register with Let's Encrypt, but it only supplies domain validated certificates so the domains for which you order certificates must already be registered and have DNS pointing to a live server to satisfy most challenges.

Earlier versions of this component also supported a custom REST API at CertCentre AG in Germany for DigiCert commercial certificates, but this service is now discontinued and support removed from the component. DigiCert themselves now use ACME for commercial certificates, but this has not yet been tested with ICS.

The TSslX509Certs component includes a database of certificate orders and pending challenges, allowing certificates to be re-ordered and the supplier periodically checked to see if a challenge has been successful when the X509 certificate can be automatically downloaded and installed. Events are generated upon completion or failure, allowing the application to inform the user (by email) of certificate ordering progress.

ICS includes a sample OverbyteIcsX509CertsTst that is effectively an X509 certificate management and ordering tool that can be used standalone to order certificates from Let's Encrypt and Google Trust Services for testing or commercial use, including wild card certificates provided you run your own Windows DNS Server. These certificates can be used automatically by most non-ICS servers such as Windows IIS or Apache.


TSslX509Certs Acme Supplier Accounts

From V9.5, ICS has a central Acme Supplier Account database that contains a list of the Acme work directories previously only referenced in separate IcsHosts INI files. The database is at C:\ProgramData\ICS-Acme-Accounts\ics-acme-accounts.db, and each Supplier Account has a Supplier Account Title, Acme Supplier Name, and Account Directory, which defaults to: C:\ProgramData\ICS-Acme-Accounts\SupplierTitle\ but can be located elsewhere if required.

If an ICS server with automatic certificate ordering starts and no Acme Supplier Accounts are configured, the server will attempt to create one. If the INI file was used prior to V9.5 and CertDirWork is specified with old account details, a new supplier AcmeLetsEncrypt-Old is created for that existing directory, and everything should work as previously. If the INI file has SupplierTitle, no CertDirWork and sufficient details in IcsHosts, a new supplier is created with that title, the ICS samples use 'LetsEncrypt-New'. Note this only happens if no suppliers are configured, so a typo in INI file does not create an unwanted supplier.

Otherwise, Acme Supplier Accounts must be created manually using the sample OverbyteIcsX509CertsTst or functions from the TSslX509Certs component in your application. Note Google and other supplier accounts must be created manually, since they need extra external accounting details that are not in IcsHosts.

Each Supplier Account has an Account Directory in which the account private key file AcmePrivateKey.pem is created and stored, and all certificate and related files will be saved, with a database file ics-control.db containing information about the account, certificate orders and pending challenges. The account private key (separate to certificate private keys) is used to identify the account to the supplier and is created automatically if the directory is blank. This account private key will be needed to cancel or revoke any certificates issued using it. Note an account directory and database can only be accessed by one application at a time, they can generally not be shared between different servers.

The sample OverbyteIcsX509CertsTst has tabs 'Acme Suppliers' and 'Supplier Details' that allows accounts to be created and edited, see later for details.


TSslX509Certs Work and Certificate Files

When ordering a new certificate, temporary files may be created in the account directory, the new certificate private key and certificate request. Once the order is accepted and an order number is available, these files are renamed to include the order number for historic purposes, and when the order is completed a second copy of all files is saved without the order number for final distribution to the web server, and optionally copied to the web server using a UNC file share. Note the files without order numbers are always automatically overwritten by new orders. So an Let's Encrypt order for the domain test3.telecom-tariffs.co.uk will generally find the following files upon completion: 

ics-control.db
AcmePrivateKey.pem
AcmePublicKey.pem
LE-SA-v1.2-November-15-2017.pdf
LE-5860824-test3_telecom-tariffs_co_uk-bundle.pem
LE-5860824-test3_telecom-tariffs_co_uk-certonly.pem
LE-5860824-test3_telecom-tariffs_co_uk-inters.pem
LE-5860824-test3_telecom-tariffs_co_uk-privatekey.pem
LE-5860824-test3_telecom-tariffs_co_uk-request.pem
LE-5860824-test3_telecom-tariffs_co_uk.pfx
test3_telecom-tariffs_co_uk-bundle.pem
test3_telecom-tariffs_co_uk-certonly.pem
test3_telecom-tariffs_co_uk-inters.pem
test3_telecom-tariffs_co_uk-privatekey.pem
test3_telecom-tariffs_co_uk-request.pem
test3_telecom-tariffs_co_uk.pfx

There is a PEM certificate signing request (CSR) file, separate PEM files for the private key, domain certificate and intermediate certificates, then a combined PEM bundle with the certificates and private key, and a PKCS12 PFX file which is a similar bundle that Windows certificate store accepts. The certificate private key files (and bundles) may be optionally password protected, the PFX file always has a password since Windows requires that, it will be 'password' if not otherwise specified. Note AcmePrivateKey is unprotected. A wildcard order for

  • .telecom-tariffs.co.uk will have a file name x_telecom-tariffs_co_uk since * can

not be used in file names. Until the order number is available, the file name will be LE-work, or CC-work for CertCentre. There are component options to ignore some of these files, if not needed.


TSslX509Certs Supplier Order Database

For each account there is a database file ics-control.db containing information about the account. certificate orders and pending challenges. This is a simple INI file, and is generally updated only by the TSslX509Certs component.

There is an [account] section or record with general information about the supplier, logging, next order sequence number, ACME account private key, etc.

There are then multiple [domain-mydomain] sections or records for each X509 order placed where my-domain is the Common Name of the certificate, and then one section or record for each Subject Alternate Name on the certificate [san-mydomain=mysan] including the Common Name which are used for domain validation. These records are updated as the order progresses and may be checked afterwards to see the main files created and certificate details. The record may be used to re-order a certificate, but not on the same day a certificate was downloaded to prevent wild repeated orders.

When an order has been placed, a temporary section [challenge-mysan] is created for each SAN on the certificate to keep track of challenge progress, effectively a queue of waiting challenges. This queue is checked every 30 seconds and the supplier contacted to see if the challenge has completed or failed, the section is then removed with the main domain and san records updated.

The sample OverbyteIcsX509CertsTst has tabs 'Supplier Orders', 'Cert Domain', 'Cert Admin' and 'Supplier New Order' that show all existing orders and allow new orders to be started.


TSslX509Certs Challenges

To authenticate Domain Validated X509 certificates, the TSslX509Certs component offers various challenge methods, variously used by different suppliers, products and ICS components. Challenges work by the supplier generating a short random phrase which must become accessible on the public internet using the domains for which a certificate is being ordered to prove that domain is controlled by whoever placed the order.

ChallFileUNC

ChallFileUNC - File - Web Server - UNC: copies a small file into the .well-known directory of the server using a UNC path, may be any type of web server on the same or remote PC. Once the challenge is done, the issued X509 certificate may be copied to that server. Requires a web server listening on port 80 and the domain being validated and path /.well-known/. If a certificate is being ordered with two or more Alternate Subject Names, separate challenges are required for each separate domain name. Wild card certificates are not supported.

ChallFileFtp

ChallFileFtp - File - Web Server - FTP: similar to ChallFileUNC, but the application needs extra code to copy the file using FTP.

ChallFileApp

File - App Web Server: similar to ChallFileUNC, but handles the challenge file virtually without creating any files using a little code in the web server onWellKnownDir event to call an function in TSslX509Certs where the path is checked and a virtual file returned with the challenge data. Currently supported by the SslHttpServer, TSslHttpAppSrv, TIcsProxy and TIcsHttpProxy components, see SslHttpAppSrv1WellKnownDir in the sample OverbyteIcsSslMultiWebServ1.pas for an example.

ChallFileSrv

File - Local Web Server: similar to ChallFileApp, but uses a local web server TSimpleWebSrv listening on port 80 and the domain being validated, provided no other web server is using the same port and IPv4 and IPv6 addresses. This is used by the sample OverbyteIcsX509CertsTst to order certificates separately without needing a web server, and by the TSslFtpServer and other components which don't usually listen on port 80. The local web server is only run while waiting for the challenge to be accessed by the supplier, usually about a minute, but can not conflict with any other web server on the same IP address.

ChallDnsAuto

DNS - Automatic: the challenge comprises a TXT record in the Domain Name Server Forward Lookup Zone for the domain. Currently, this requires application code to access the DNS server which is in the sample OverbyteIcsX509CertsTst. It uses WMI to access a Windows 2012 or later public DNS Server on the same PC. Future releases could support Cloudflare DNS via a REST API, and maybe other cloud providers. The benefit of using DNS is no conflicts with web servers, and ordering wild card certificates like

  • .ftptest.org that work with any sub-domains to avoid ordering

certificates for each. A certificate may have multiple wild card names, such as *.ftptest.org.uk and *.ftptest.co.uk.

ChallDnsAcnt

DNS Account- Automatic: similar to ChallDnsAuto, but adds an account hash before _acme-challenge.domain. This challenge is Acme account specific, so different accounts can get certificates for the same domain name allowing redundancy. Not tested yet since not supported by any suppliers.

ChallDnsMan

DNS - Manual: similar to ChallDnsAuto, but just calls an event in the application which finds an alternate method of updating the Domain Name Server, supported in OverbyteIcsX509CertsTst which allows DNS to be updated manually before starting the actual certificate order.

ChallAlpnApp

TLS-ALPN - App Web: this challenge uses the normal SSL port 443 to avoid needing a non-SSL web server running on port 80. A special SSL/TLS certificate is created for the domain containing the challenge phrase which is returned instead of the normal certificate when the SSL client hello includes a special ALPN. This needs one line in the onClientConnect event to call a function in TSslX509Certs where the certificate is created. See the sample OverbyteIcsSslMultiWebServ1.pas for an example. Only catch with this challenge is requesting the first certificate for a new domain, the server won't start without a certificate, so the TWSocketServer component automatically creates an ICS signed certificate so the service can start, which is ideally replaced a few seconds later when the order completes.

ChallAlpnSrv

TLS-ALPN - Local Web: similar to ChallAlpnApp, but uses a local web server TSimpleWebSrv listening on port 443 and the domain being validated, provided no other web server is using the same port and address, see comments about ChallFileSrv above.

ChallAlpnUNC

TLS-ALPN - Web UNC: similar to ChallAlpnApp, but copies the special SSL certificate to another server that is responsible for implementing the ALPN part of the process, don't know of such a web server.

ChallEmail

Email Manually: calls an event in the application, that could send an email automatically, was supported for CertCentre.

For all the automated challenges above, the certificate order process involves first testing the challenge with locally generated data to ensure the servers are responding correctly from the public internet, then getting the real challenge data from the supplier and again checking it can be accessed from the public internet, before asking the supplier to start testing the challenges. Let's Encrypt and Google now test challenges several times from servers in different countries networks to avoid DNS spoofing. In practice this all takes place within seconds.

Beware that within a few seconds of a certificate order being completed, hackers will start making intrusion attempts on the server domain name, typically looking for PHP pages used to administer popular web servers, which ICS applications will ignore. This happens because all SSL certificate appear in public transparency logs, and the hackers watch these logs.


TSslX509Certs IssueState

The component keeps the IssueState for each order and pending challenge reflecting the order progress, saved in the database as type TIssueState. Several of these states relate directly to the supplier Acme order status. The states are as follows:

IssStateNone

Not started, previous order completed or new order failed and needs to be restarted. Acme supplier status: Invalid.

IssStateChecked

Basic local checks completed, chosen domain challenge allowed, such as copying a test file to .WellKnown directory or creating an TlsApln certificate, starting the local web server if needed, and then accessing the file or certificate by domain name from the public internet or checking a domain name server can be reached. Note the Acme Supplier is not accessed at this stage.

IssStateChallgReq

The order process has started and the supplier has been given a list of domain names and maybe IP addresses to be included in the certificate, and the certificate profile and expiry details, depending on supplier. If acceptable, an order number is created and a URL for each domain which contains one or more domain challenges. The component selects the appropriate challenge according to the chosen method and will prepare some challenges, others may need to done manually or by the application such as DNS. The challenges should remain valid for up to a week, the expiry date is shown on the Supplier Order tab. Acme supplier status: Pending.

IssStateChallgWaitTest

Does not appear to be used at present.

IssStateChallgTest

Challenges have been tested locally as ready for checking by supplier, .WellKnown and TlsApln have been accessed from the public internet or the DNS returns the correct TXT record. The supplier order is ready to start. Acme supplier status: Pending.

IssStateChallgPend

The order process has started and the supplier has been asked to check the order domain challenges. Waiting for a response from the certificate supplier to the challenges, may happen within 15 seconds, but each challenge is accessed from multiple servers around the world so may take longer. DNS challenges sometimes take longer to propagate to secondary DNS servers. Acme supplier status: Pending.

IssStateChallgOK

All domain challenges have been passed by the supplier who is now ready to accept a certificate supply request (CSR) and issue the CA signed certificate. Acme supplier status: Ready.

IssStateFinalPend

All domain challenges have been passed by the supplier who is now ready to accept a certificate supply request (CSR) and issue the CA signed certificate. Acme supplier status: Ready.

ssStateIssuePend

The order has been accepted and finalised, but there is now a short delay while the new certificate is issued, perhaps a queue is the supplier is busy. Acme supplier status: Processing.

IssStateIssued

The new certificate has been issued and is ready to be collected by the component. This normally happens automatically. Acme supplier status: Valid.

IssStateCollect

The new certificate has been collected OK, and all the various certificate files, private keys, etc, have been created and copied to the specified directories. The certificate can be collected again if something failed for a few days, usually. Acme supplier status: Valid.

IssStateFinished

The new certificate has been collected OK and the supplier has finished with this order, so it can not be collected again. Acme supplier status: Invalid.

IssStateCancel

Cancelled order, perhaps revoked certificate, so can not collect certificate again.


TSslX509Certs Sample Application

There is a application Samples\demos-delphi-vcl\OverbyteIcsX509CertsTst.dpr that illustrates all the functionality of the TSslX509Certs component, allowing certificates to be ordered and collected by clicking a few buttons. The sample also shows all certificates ordered by ICS components and saved in the supplier account databases and allows them to be re-ordered.


Tab: Acme Suppliers

X509-acme-suppliers-1.png

The 'Acme Suppliers' tab shows all the supplier accounts created with their details, and which allows new accounts to be created or old ones deleted. If upgrading from ICS 9.4 or earlier, use the 'Import Old Account' button to import the old Let's Encrypt account into a new supplier 'AcmeLetsEncrypt-Old'.

A supplier account must be opened by double clicking on the list or clicking Open Supplier Account before orders may be viewed. There is an inactivity Account Close Timeout on the Account Common tab, that closes accounts in case applications attempt to access them, since there is currently no account locking, defaults to five minutes.

To create a new Acme Supplier, select the Acme Supplier Name from the list, a default Account Title and Account Directory will be filled but can be changed if required. Most suppliers offers live and staging servers, the latter is best for testing since it issue certificates signed by a fake CA and there are fewer rate limits than the live server which may get blocked if you make too many mistakes during ordering. When 'Save New Account' is clicked, the Supplier Details tab will appear for more supplier information.


Tab: Supplier Details

X509-acme-details-1.png

The 'Supplier Details' tab specifies the type of private and public keys for the account, Elliptic Curve secp256 is smallest so best. These keys are used to authenticate the account to the supplier, using a Json Web Key created from the private key to sign each POST request with a Json Web Signature, no user name is needed.

HTTP proxy URL is if the server is behind a NAT firewall so does not have a public address, the URL format is 'http://host:port' where :port is optional.

Let's Encrypt does not require any email or external accounting information, but these are needed for most other suppliers, taken from the console where you created an ACME account, see details about different suppliers earlier.

Socket Family is generally Any, unless the account should only be accessed over IPv4 or IPv6 specifically. The Account Local Web Server is only needed if the sample uses the ChallFileSrv or ChallAlpnSrv challenges to locally order certificates without using a separate web server, for domains whose address is this server. Select the server IP addresses, they may be public addresses or LAN if there is a NAT router forwarding an external IP to this PC, as is often done for development and testing. If the domain has both IPv4 (A) and IPv6 (AAAA) records, both family IP addresses must be specified, since they are both tested. The local web server is only started when order processing starts and closed immediately after, but will not start if any other server is using the same IP addresses.

There are various logging options, to keep track of activity and for diagnostics when things don't work as expected, if the Log Directory is not blank. There are several levels of debug logging from just connections, through SSL negotiations, then HTTP headers and content, also Json logging for protocol errors (or changes).

Click Save Supplier Details and the component will attempt to create an account or check it already exists. The account number will appear on the tab, but is not really used for anything.


Tab: Accounts Common

X509-accOunts-common-1.png

The Accounts Common tab contains information common to all accounts on the PC, mostly specific to this sample.

Log Directory if not blank is where the sample will write a daily log file of all activity in the sample, as shown in the log window. This directory does not apply to other applications using the component, they must implement their own logging. Account Close Timeout is how long the sample keeps an account open for, default five minutes. DNS Challenge can be selected as Local Windows DNS Server or Cloudflare DNS Server, but the latter is not yet supported, this applies when using the DNS Automatic challenges that only work if this server has a Windows DNS Server hosting the domain records for which an order is being placed, which will be accessed using WMI functions.

Private Key File Encryption specifies the type of encryption and password for any private key files generated, nearly always AES256. Note the password is not encrypted in the database files. It is primarily to allow private keys to be imported into Windows Store. Default password is 'password'.


Tab: Supplier Orders - View Orders

X509-supplier-orders-1.png

Once an old Suppler account is opened, the 'Supplier Orders' tab shows all the orders created for that account, and has buttons to start edit old orders to review certificates. To start a new local order, skip this tab and go straight to the Cert Domain tab.

The order lists shows the Common Name, Order Date, Issue State, Order Id, Issued Date, Expiry Date, Renew From Date, Challenge Type, Profile and Subject Alternate Names. Clicking on an order row shows further details with certificate dates and challenge details, maybe error for failures.

Orders for local server challenges can be started from this tab, old orders deleted or revoked, or old orders opened for limited editing.


Tab: Cert Domain

X509-cert-domain-1.png

A new local order can be created by opening a Supplier Account, and selecting the 'Cert Domain' tab. Specify the Certificate Domain Common Name and any Subject Alternate Names, the sample application will add the Common Name to the SAN list if not done manually. If Domain Challenge is for UNC file, set the Web Server UNC HTTP .Well-Known Directory' for the Common Name, and optionally for each SAN if different.

If the final certificates are to be copied to the web server, set the Web Server UNC Public Certificates Directory. There are various Output Certificate Formats that may be ticked or unticked to reduce the number of unneeded files, Separate PEM Files, PEM Bundle File, PKCS12/PFX Bundle File, PKCS7 Bundle File and CSR PEM File.

Windows Cert Store means the final certificate will be installed into the specified Windows Certificate Store for use by IIS web servers or other servers. The two stores are Current User or Local Machine Store, the latter needs Admin Rights for the sample if used for local orders, the former is not available for most Windows Services.


Tab: Cert Admin

X509-cert-admin-1.png

The 'Cert Admin' tab contains further information needed for a new certificate order. All certificates need to specify a Private Key Type and Size depending on security requirements, RSA2048 used to be common but Elliptic Curve secp256 is smaller and more common now. Signature Digest Type usually SHA256. Serial Number Type is only used for Own CA orders, and is either random or sequential (stored in the database).

Most of the other admin fields, names, addresses, email, phone number, etc are for commercial certificates only, not domain validated certificates, and may be ignored.


Tab: Supplier New Order - Settings

X509-new-order-1.png

Once the Cert Domain and Cert Admin tabs have been completed for a new order, click on the 'Supplier New Order' tab. Specify the 'Domain Challenge Method', details of which were discussed above but are: File - Web Server UNC (external), File - Web Server FTP (manual), File - Local Web Server (built in), File - App Web Server (ICS server), DNS Automatic, DNS Account Automatic, DNS manual, Email Manually (not supported), TLS-ALPN - Web UNC (external), TLS-ALPN - Local Web (built-in) TLS-ALPN - App Web (ICS server).

Certificate CSR Origin specifies whether the component should create a new private key and CSR for a new order, or use files previously created, in which case both should be specified and many properties will be ignored. Click the 'Check CSR' button to read the files and check they contain the correct domain and the key matches. Normally used for commercial orders only.

Automatic Order Completion being ticked means the component will check every few seconds to see if an order is ready for collection and finish it automatically.

Cert Profile or Type is currently for Let's Encrypt only and customises the certificate. 'Classic' is the original 90 days expiry certificate, 'tlsserver' is a simpler certificate missing the common name which is always duplicated in the list of Alternate Subject Names. 'Shortlived' is a 160 hour (6.6 days) expiring certificate that may also include IP addresses, currently only from the test staging server, due for public use in late 2025. There is also a tlsclient profile but this disappears in early 2026. The profiles also change order validity periods, classic authorisations remains valid for seven days but that is reduced to one hour new newer profile, order lifetime used to be seven days, but is now eight hours.

Certificate Period (days) is currently for Google certificates only, instead of the Profile used by Let's Encrypt, to specify the expiry period, anywhere from three to 90 days at present, but the maximum will reduce over the next few years. Very useful to allow testing short lived renewals today.

Once the order settings are specified, click the 'Save Order' button to update the account database. The 'Check Order' button may be clicked to locally check the order, see below.


Tab: Supplier New Order - Local Order

The 'Supplier New Order' tab has a series of buttons labelled with steps 1 to 7 that allow the sample to order a certificate using the Local Web Server specified for the account, with Local Web File or ALPN, or DNS Automatic challenges (if the server has a public Windows Domain Name Server). Local orders may also be started from the Supplier Order tab, but some of these seven steps are combined so there only five buttons. Buttons are greyed and unresponsive until prior order steps are completed, and may by bypassed if Automatic Order Completion is selected with the buttons being enabled in sequence as the order progresses, often completed in less than one minute.

Clicking 'Check Order (1)' which will check the challenge method is valid for a local order by the sample, will then create local test challenges for all domains specified and make HTTP requests to those domains to ensure they are accessible from the public internet.

Generally, the sample will be run on a PC or server with public internet addresses. But for testing, the PC or server might only have LAN IP addresses, with a NAT firewall forwarding public request to the LAN IPs. In this case, it may be necessary to use a public HTTP proxy server to access the public IP addresses, set-up on the Supplier Details tab.

If the local challenges are not accessible, there is no point in the order being placed since it fail. If the domains are accessible, the Order Issue State changes to Checked, and the order can be started.

Clicking 'Start Order (2)' will to start the order process with the supplier. They are asked to issue challenges for each of the domain names requested, which the component then prepares and writes to queue records in the database. As discussed above, challenges may include writing server files, creating special SSL certificates or adding records to a Domain Name Server. Previously satisfied challenges remain valid for a period varying from eight hours to 30 days (for classic certificates) so the supplier may report the challenges already complete at the this stage.

Once the challenges are ready, Acme Order State becomes Pending, and the Order Issue State changes to ChallgReq.

Clicking 'Test Challenges (3)' starts testing the supplier challenges, to make sure the domains, files, etc are available from the public internet correctly, effectively repeating 'Check Order' but with real challenges. Once successful the Order Issue State changes to ChallgTest.

Clicking 'Start Challenges (4)' asks the supplier to test the challenges, which usually takes from 15 seconds to a minute, unless they are very busy. There are usually several challenge tests from different networks in different countries. The Order Issue State will be updated to ChallgPend. For HTTP challenges, the log window will display activity for the local web server, which should be receiving and responding to multiple page requests.

If Automatic Order Completion is enabled, the component will check the Order Status (next button) for successful or failed challenges every five seconds while the sample application is running, waiting for the Acme Order Status to change from Pending to Ready, then updating Issue Status to ChallgOK when that happens.

Clicking 'Order Status (5)' makes a request to the supplier to check the Acme Order Status which will change from Pending to Ready once the challenges for all domains have been successfully tested. The Order Issue State then changes to FinalPend. If any challenges fail, the Order Issue State changes to None and the order must be restarted. The Supplier Orders tab should display the reason for failure, usually just unable to access the public server.

Clicking 'Finalize Order (6)' is only possible once all challenges are checked by the supplier and the Order Issue State is ChallgOK or FinalPend. The component creates a new private key and certificate signing request using the domain details and sends a request to supplier to finalize the order. The supplier then matches the CSR against approved domain challenge and commences issue of a new certificate, which may take a few seconds. The Acme Order status changes to Processing and Order Issue State to IssuePend. Clicking 'Order Status (5)' again will check the Acme Order Status which changes to Valid once the certificate is issued, with Order Issue State to Issued. If Automatic Order Completion is enabled, this happens automatically.

Clicking 'Collect Certificate (7)' is only possible once Order Issue State is Issued. The new SSL/TLS certificate is downloaded with any intermediate certificates needed to validate the trust chain. The component then creates several files including the order number containing certificate, private keys, bundles, etc, depending on the 'Output Certificate Format' settings on the Cert Domain tab. Finally the component runs a check to validate the certificate chain, and reports all the details in the log. If validation passes, all the files are saved a second time without the order number, as detailed above and the Order Issue State updated to Collected. If a Web Server UNC Public Certificate Directory has been specified, the certificates will be copied to the servers.

Finally, the component will ask the supplier for Renewal Information for the certificate. This specifies how many days before expiry a certificate should be renewed, and how often these dates should be rechecked to see if the certificate needs immediate renewal due to being revoked. These dates are reported on the Supplier Orders tab. Recheck is usually between six and 24 hours and is done automatically by ICS servers.

Beware the account database is not designed to shared between multiple applications running at the same time. So it is better for each application that will order certificates to use a separate Acme account and directory, and only use the sample application to briefly check orders.

Tab: Supplier Orders - Start or Revoke Orders

X509-supplier-orders-2.png

Back to the Supplier Order tab, there are various buttons, some of which match the supplier New Order tab and do the same thing, others combine tasks.

Check Order - if the order use challenges FileApp or AlpnApp for a server, just enables the Start Order button. For a local order, does as it suggests, checking local challenges.

Start Order - if the order use challenges FileApp or AlpnApp for a server, a flag is set in the account database that will be checked next time the server check renewal information, and will start an immediate order, may take several hours since the database is not checked regularly. For a local order, starts the order, gets and checks the challenges, then asks the supplier to check the challenges. If Automatic Order Completion is enabled, Order status is checked every five seconds and everything just happens until the order is completed.

Order Status - as above.

Finalise Order - as above.

Collect Order - as above.

Cancel Order - allows an order to be stopped part way through the process.

Revoke Certificate - if a certificate has been issued but should no longer be trusted, it may be revoked. Revoking an order should generally only be done if the certificate is in public use and the private key has been compromised. Revoke means the certificate will be added to supplier CRL databases which may be checked by browsers to prevent compromised certificates being trusted until expiry. The reduced issue period of certificates is partly to avoid then needing to be revoked.

Remove Order - clears an old order from the supplier database but does not revoke the certificate.

Reset Order - sometimes challenge failure can mean the order gets stuck and not complete or do anything useful, so this button resets the Issue State to none so it can be restarted.

Renewal Information - works for all unexpired collected or finished orders. Ask the supplier for Renewal Information for the certificate. This specifies how many days before expiry a certificate should be renewed, and how often these dates should be rechecked to see if the certificate needs immediate renewal due to being revoked.

Edit Order - loads the selected order into Cert Domain, Cert Admin and Supplier New Order tabs, allowing some settings to be changed and saved by the 'Save Order' button on the New Order tab. While this works for local orders, those created by servers may change the order information according to the IcsHosts and server settings.

List Challenges - for an order in progress, will log the state of

challenges being tested.

Redistribute - for a collected order, redistributes the certificate files according to the 'Output Certificate Format' settings.


Tab: Own CA

X509-own-ca-1.png

For internal network use and testing, it is possible to issue your own SSL/TLS certificates for devices that are not accessible from the public internet. These can be self signed certificates, but to try and avoid horrible browser warnings it is better to issue certificates signed by trusted root CA certificate that is installed in the Windows Store (and maybe other stores) as a trusted root on each device that will access servers running certificates issued by the CA.

ICS now has it's own SSL root certificate 'ICS Root CA' and two intermediates, 'ICS Intermediate' and 'ICS Intermediate Short', the last of which includes a private key so can be used to automatically sign new certificates by ICS server applications, rather than just self signed certificates as before. If the 'ICS Root CA' certificate is installed in the Window Store and browser stores, it should stop certificate warnings appearing. ICS applications automatically trust the ICS root, so will give no warnings. The short intermediate has a maximum 200 day expiry, so new versions will be issued regularly. There is a single function CreateSelfSignCertEx that creates signed certificates, and another IcsInstallIcsRoot that installs the ICS root into the Windows Store, so easy to use. It is possible to replace the ICS root with your own private root certificate and have servers create their own certificates against that root, for internal networks.

The ICS SSL root certificate is loaded automatically with the SslRootCAStore.Initialise function that loads the CA Root Store, and with the define OpenSSL_AutoLoad_CA_Bundle, to verify any ICS issued certificates. The SslRootCAStore.Initialise functions also tries to load the file C:\ProgramData\ICS-OpenSSL\ExtraRootCABundle.pem which is an optional private root bundle that can be used for private customer or developer root CA certificates, in PEM format.

Alternatively, you can create your own certificate authority and intermediate to sign your own certificates.

The sample application has a button that will create self signed SSL certificates with a 'CA Cert' check box so it can sign other certificates., but the OverbyteIcsPemTool sample has more control over fields. You should create a new private key and self signed certificate with your organisation's common name, ie Magenta Development CA. Rather than signing certificates directly with the new trusted CA, it is better create an intermediate CA signed by the trusted CA, allowing variations of key types and digests, ie Magenta Intermediate EC CA1. The intermediate CA certificate does not need to be installed on client devices, only the trusted CA.

On the Own CA tab, the Certificate Directory should be specified, note the account database for Own CA certificates currently does not store certificate details so they can not be ordered automatically by TWSocketServer. Then specify the CA Certificate or Bundle File and CA Private Key File (if not in bundle) and click the 'Load CA' button check and load it, with Issued to and Issued by being shown.

To issue your own signed SSL certificates, the usual settings on the Cert Domain and Cert Admin tabs should be completed, and the 'CA Signed Cert' button pressed. The component will then create a new private key and CSR files, then a new certificate signed by the Own CA, in a process otherwise identical to collecting an ACME certificate, using a sequential order number, with files saved with and without the order number and optionally distributed to the web server. Note this sample sets common certificate extensions only, for more control you should create your own CSR using OverbyteIcsPemTool or it's functions.

Each certificate signed by the Own CA is logged to the index.txt database file in the Certificate Directory, in OpenSSL CA command format, which is tab delimited with status, expiry date, SHA1 fingerprint, file name, subject and subject alternate names. This file could be updated if the certificate is revoked and used to support Certificate Revocation Lists (not implemented).


TSslX509Certs: Main Methods for Accounts and Orders

The TSslX509Certs component provides many methods for dealing with accounts and the database, which relate closely to the buttons on the Orders tab. These functions are used by the TSslWSocketServer methods DoCheckOrderCert and DoProcOrderCert which are how severs using IcsHosts order certificates.

function DBSuppliersRead: Boolean;

Opens and read the Acme Supplier Database C:\ProgramData\ICS-Acme-Accounts\ics-acme-accounts.db into an array of AcmeSuppRecs records.


function DBFindAccSupp(const ATitle: String): Integer;

Searches for a Supplier Title in the AcmeSuppRecs records, returning the index if found, or -1. The application should set the component properties: X509Cert.CertDirWork := AcmeSuppRecs[Idx].ASuppDir; X509Cert.AcmeSupplier := AcmeSuppRecs[Idx].ASupplier;


function SetAcmeAccount(CreateNew: Boolean = False): Boolean;

Opens the supplier account as in CertDirWork, optionally creating a new account for AcmeSupplier if the directory does not exist or is empty. For a new account, several properties can be set: DebugLevel, DomWebSrvIP, LogJson, LogPkeys, SupplierEmail, SupplierProto, SupplierServer.

Once the account is opened, the property DomainItems returns an array of TDomainItems containing the main details of each domain record in the database, and an event is triggered whenever this changes.

The function will fail if ics-control.db can not be found or the working directory mismatches the database. Call ClearAccount before using this.


function CloseAccount: Boolean;

Close the account, if open.


function DBReadCNDomain(const CNDomain: String): Boolean;

For an open supplier account, reads all the properties for an order with the Common Name from the account database, if found, including one or more subject alternate names.

The function will fail if the domain has not been saved in the database. Call ClearCertOrder before using this.


function DBWriteCNDomain: Boolean;

Save or update properties for CertCommonName certificate to the account database. There are many possible properties, all of which are illustrated in the sample application. The main properties are: CertCommonName, AcmeSupplier, SuppCertChallenge, CertPKeyType, CertSignDigest, CertCsrOrigin, CertSerNumType, CertOutFmts, DirWellKnown, DirPubWebCert, PrivKeyPassword, PrivKeyCipher, CertSubAltNames, CertAcmeProfile and CertValidity (Google only).

Fails if account not opened, but does not check properties for validity.


function AcmeCheckSaveOrder(DomainCheck: Boolean = True; UpdateDB: Boolean = False): Boolean;

This is the main function to start a certificate order, used by the 'Check Order' buttons in the sample. All required order properties must have been read using DBReadCNDomain or set as properties, and will be saved using DBWriteCNDomain if UpdateDB is set. It checks the Common Name is included in the SANs and adds it if not, then checks the challenge method and SAN number are supported by the certificate product.

This function restarts the order process for an old order setting Order Issue State changes to None, even if old challenges are still valid. If DomainCheck is true, checks the domain is accessible from the public internet for domain challenges. If the domains are accessible, the Order Issue State changes to Checked, and the order can be started.


function AcmeV2GetChallgs: Boolean;

This is the main function to place a certificate order with the supplier, used by the 'Start Order' buttons in the sample. AcmeCheckSaveOrder must have passed first. The supplier provides challenges for each domain in the order which the components prepares and the Order Issue State changes to ChallgReq.


function AcmeV2TestChallgs: Boolean;

Once challenges have been acquired from the supplier, this function locally tests them, called by the 'Test Challenges' button. Once done OK, the Order Issue State changes to ChallgTest.


function AcmeV2StartChallgs: Boolean;

Once the challenges have been tested, this function asks the supplier to test them, called by the 'Start Challenges' button. Testing usually takes from 15 seconds to a minute, sometimes a lot longer, and the Order Issue State will be updated to ChallgPend. If Automatic Order Completion is enabled, the component will check the Order Status for successful or failed challenges every five seconds waiting for the Acme Order Status to change from Pending to Ready, then updating Issue Status to ChallgOK when that happens, and then calling AcmeV2OrderFinal and AcmeV2CollectCert.


function AcmeV2OrderStatus: Boolean;

Requests the Acme order status at any point during the order process, but in particular when waiting for something to happen, called by the five second timer that runs Automatic Order Completion to check for status changes with the Order Issue State updated appropriately. Called by the 'Order Status 'button'.


function AcmeV2OrderFinal(LogErrors: Boolean = True): Boolean;

Once the challenges have all been tested by the supplier, the order can be finalised, called by the 'Finalize Order' button. The component creates a new private key and certificate signing request using the domain details and sends a request to supplier to finalize the order. The supplier then matches the CSR against approved domain challenge and commences issue of a new certificate, which may take a few seconds. The Order Issue State becomes IssuePend. If Automatic Order Completion is enabled, the component will wait for the certificate to be issued by checking AcmeV2OrderStatus for Order Issue State Issued.


function AcmeV2CollectCert: Boolean;

Once the certificate is issued by the supplier, it may be collected, called by the 'Collect Certificate' button or by Automatic Order Completion'. The new SSL/TLS certificate is downloaded with any intermediate certificates needed to validate the trust chain. The component then creates several files depending on the 'Output Certificate Format' settings, runs a check to validate the certificate chain and the Order Issue State updated to Collected. If a Web Server UNC Public Certificate Directory has been specified, the certificates will be copied to the servers.


function DBReadCNDomDates(const CNDomain: String): Boolean;

Similar to DBReadCNDomain but only reads sufficient properties to check certificate renewal and whether the Acme supplier should be contacted to update renewal information.


function CertRenewalDomain(const aDomain: String): Boolean;

Only available if a previously issued certificate is available, asks the Acme supplier how many days before expiry the certificate should be renewed.


function CertCancelDomain(const aDomain: String): Boolean;

For an order with issue state Collected or Installed, will cancel the order with the supplier, which may result in a refund if done within a reasonable period.


function CertRevokeDomain(const aDomain: String): Boolean;

For an order with issue state Collected or Installed, will cancel and revoke the order with the supplier.


function CertRemoveDomain(const aDomain: String): Boolean;

Removes any order from the database, to stop further processing or re-use.


function CertRedistDomain(const aDomain: String): Boolean;

For an order with issue state Collected or Installed, copies the certificate files to the web server again, if lost.


TSslWSocketServer and IcsHosts Configuration

The TSslWSocketServer, TSslHttpServer, TSslHttpAppSrv, TIcsProxy, TIcsHttpProxy, TSslFtpServer components all use the TSslX509Certs component to order certificates, using various properties specified in TSslWSocketServer and the IcsHosts properties it use to specify listeners.

Information about all these properties may be found in the OverbyteIcsWSocketS.pas unit and the Wiki web pages TWSocketServer and TWSocketServer.IcsHosts

Retrieved from "http://wiki.overbyte.eu/wiki/index.php?title=FAQ_Order_SSL_Certificates&oldid=3834"