Difference between revisions of "FAQ Order SSL Certificates"

From Overbyte
Jump to navigation Jump to search
 
Line 19: Line 19:
 
with a supplier link that must be clicked to confirm receipt and domain ownership.
 
with a supplier link that must be clicked to confirm receipt and domain ownership.
  
File, SNI and domain validation challenges can both be automated, file is easiest
+
File, TLS-ALPN and domain validation challenges can be automated, file is easiest
using a simple HTTP server, SNI using an HTTPS server, while domain validation is
+
using a simple HTTP server, TLS-ALPN using an HTTPS server, while domain validation
dependent on being able to access and control the DNS server of which there are
+
is dependent on being able to access and control the DNS server of which there are
many different products.  Note file validation challenges are not instant, the
+
many different products.  Note validating challenges are not instant, the supplier
supplier may have a queue of challenges waiting to the tested, but usually happen
+
may have a queue of challenges waiting to the tested, but usually happen within a
within a couple of minutes. Applications need to be aware the wait may be longer.
+
couple of minutes. Applications need to be aware the wait may be longer.
 
Automated wild card certificates typically use the domain validation challenge.
 
Automated wild card certificates typically use the domain validation challenge.
  
 
Organisation and Extended Validated certificates can be ordered online, but
 
Organisation and Extended Validated certificates can be ordered online, but
 
require manual validation that the company or organisation legally exists and is
 
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
+
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
 
validation if legal evidence is required.  Once approved, the certificate and be
 
downloaded automatically.
 
downloaded automatically.
 
  
 
== 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 suppliers, including free certificates from Let's Encrypt, and commercial
 
certificates for Digicert, Comodo, Thawte and GeoTrust from CertCentre AG and
 
certificates for Digicert, Comodo, Thawte and GeoTrust from CertCentre AG and
Servertastic (not done yet).  The component automates the process from creating
+
Servertastic (not done yet).  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 46: Line 44:
 
with the private key, then copying the files to the web server ready for
 
with the private key, then copying the files to the web server ready for
 
automatic installation. The TSslWSocketServer, TSslHttpServer, TSslHttpAppSrv,
 
automatic installation. The TSslWSocketServer, TSslHttpServer, TSslHttpAppSrv,
TIcsProxy and TIcsHttpProxy components can assign a TSslX509Certs component to
+
TIcsProxy, TIcsHttpProxy, TSslFtpServer and TIcsIpStrmLog components can assign
support automatic certificate ordering of domain validated certificates with
+
a TSslX509Certs component to support automatic certificate ordering of domain
very little extra code.
+
validated certificates with very little extra code.
 
 
The component supports automated file challenge for Domain Validated certificates,
 
using an external HTTP server such as IIS or HTTP server component such as
 
TSslHttpServer or TSslHttpAppSrv to which files may be copied using UNC
 
shares, or a built-in local HTTP server so the component is self contained.
 
In all cases, the web server must be accessible from the public internet for the
 
domain (or domains) for which a certificate is being ordered.  The application
 
can also use an FTP server to copy files to an external HTTP server. DNS
 
challenge currently require the application to update the DNS server, the demo
 
application waits a few minutes for the user to manually update the DNS server
 
which allows wild card certificates to be ordered.  A pending feature is
 
TLS-ALPN SSL SNI challenges for Let's Encrypt using HTTPS.
 
  
The component supports the ACME V1 and V2 protocols as implemented by Let's
+
The component supports the Acme V2 protocol specified in RFC8555 as implemented
Encrypt to download free domain validated certificates, beware V1 bears little
+
by Let's Encrypt to download free domain validated certificates. Note the Acme
resemblance to any of the Acme Internet Draft specifications, V2 is much closer
+
protocol is only implemented sufficiently for Let's Encrypt, it is designed
to draft 10 but only implemented sufficiently for Let's Encrypt, V2 is designed
 
 
to also handle commercial certificates which are more complicated to process.
 
to also handle commercial certificates which are more complicated to process.
Note that Acme V1 has been superseded by V2, and was only supported because V2
+
The component will be updated to support commercial suppliers with Acme, when
did not go public until March 2018.
+
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
already be registered and have DNS pointing to a live HTTP (HTTPS next release)
+
already be registered and have DNS pointing to a live server to satisfy most
server to satisfy the domain challenge.
+
challenges.
  
 
Commercial suppliers of certificates have their own APIs, usually using HTTP
 
Commercial suppliers of certificates have their own APIs, usually using HTTP
 
REST, currently the component supports CertCentre AG https://www.certcenter.de/,
 
REST, currently the component supports CertCentre AG https://www.certcenter.de/,
 
https://www.certcenter.co.uk/ or https://www.certcenter.com/ from where you
 
https://www.certcenter.co.uk/ or https://www.certcenter.com/ from where you
can buy certificates issued by Comondo, DigiCert (including GeoTrust, Symantec
+
can buy certificates issued by Comondo/Sectigo, DigiCert (including GeoTrust,
and Thawte) and GlobalSign, and free certificates from AlwaysOnSSL (by resellers
+
Symantec and Thawte) and GlobalSign.  You need to register with
only), see https://alwaysonssl.com/issue.php.  You need to register with
 
 
CertCentre AG and open a reseller account to pay for any certificates bought,
 
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.
 
although for testing most can be cancelled within 30 days without charge.
Line 94: Line 78:
 
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.
 +
 +
 +
== 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.
 +
 +
{| border=1
 +
| width="130" valign="top" |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.
 +
|-
 +
| valign="top" |ChallFileFtp||
 +
File - Web Server - FTP: similar to ChallFileUNC, but the
 +
application needs extra code to copy the file using FTP.
 +
|-
 +
| valign="top" |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.
 +
|-
 +
| valign="top" |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 address.  This is used by the sample
 +
OverbyteIcsX509CertsTst to order certificates separately without
 +
needing a web server, and by the TSslFtpServer and TIcsIpStrmLog
 +
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.
 +
|-
 +
| valign="top" |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.  The next
 +
release will also support Cloudfare 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.
 +
|-
 +
| valign="top" |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.
 +
|-
 +
| valign="top" |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 will automatically create a self signed certificate to start.
 +
|-
 +
| valign="top" |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.
 +
|-
 +
| valign="top" |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.
 +
|-
 +
| valign="top" |ChallEmail||
 +
Email Manually:  calls an event in the application, that could
 +
send an email automatically, only 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 currently tests challenges three times from servers on different
 +
networks to avoid DNS spoofing.  In practice this all takes placed 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.
  
  
Line 173: Line 270:
 
the supplier contacted to see if the challenge has completed or failed, the
 
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.
 
section is then removed with the main domain and san records updated.
 +
 +
== TSslX509Certs IssueState ==
 +
 +
The component keeps the IssueState for each order and pending challenge reflecting
 +
the order progress, saved in the database as type TIssueState, as follows:
 +
 +
{| border=1
 +
| width="130" valign="top" |IssStateNone||
 +
Not started.
 +
|-
 +
| valign="top" |IssStateAccount||
 +
Account with certificate supplier has been opened.
 +
|-
 +
| valign="top" |IssStateChecked||
 +
Basic local checks completed, chosen domain challenge allowed,
 +
such as copying a test file to .WellKnown directory and
 +
accessing it by domain name from the public internet or
 +
checking a domain name server can be reached.
 +
|-
 +
| valign="top" |IssStateChallgReq||
 +
Received acceptable challenge methods and data from supplier,
 +
component will prepare some challenges, others may need to
 +
done manually or by the application such as DNS.  The
 +
challenge data should remain valid for up to a week.
 +
|-
 +
| valign="top" |IssStateChallgTest||
 +
Challenges have been tested as ready for checking by supplier,
 +
.WellKnown and TlsApln have been accessed from the  public
 +
internet or the DNS returns the correct TXT record.
 +
|-
 +
| valign="top" |IssStateChallgPend||
 +
Pending a response from the certificate supplier to the
 +
challenges, may be 30 seconds or several days if manual
 +
intervention is required.
 +
|-
 +
| valign="top" |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.
 +
|-
 +
| valign="top" |IssStateCollect||
 +
The CA signed certificate has been collected OK.  The
 +
certificate can be collected again if something failed.
 +
|-
 +
| valign="top" |IssStateInstall||
 +
Certificate has been installed for the server by the
 +
component. not supported yet.
 +
|-
 +
| valign="top" |IssStateCancel||
 +
Cancelled order, perhaps revoked certificate, so can not
 +
collect certificate again.
 +
|}
 +
  
  
Line 229: Line 379:
 
HTTP .Well-Known Directory' for the Common Name, and optionally for each SAN if
 
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
 
different.  If the final certificates are to be copied to the web server, set the
Web Server UNC Public Certificates Directory. Clicking the Test Well-Known button
+
Web Server UNC Public Certificates Directory. Clicking the Test Domain Challenges
will copy a file to the web server and attempt to access it using the domain name,
+
button set-up challenges for all the domains and try to access them locally, to
to prove future challenges will be successful.  If commercial certificates are
+
prove future challenges will be successful.  If commercial certificates are being
being ordered using Email Challenge, each SAN should specify the Approval Email
+
ordered using Email Challenge, each SAN should specify the Approval Email address
address required (scroll across the grid).  There are various Output Certificate
+
required (scroll across the grid).  There are various Output Certificate Formats
Formats that may be ticked or unticked to reduce the number of unneeded files,
+
that may be ticked or unticked to reduce the number of unneeded files, Separate
Separate PEM Files, PEM Bundle File, PKCS12/PFX Bundle File, PKCS7 Bundle File
+
PEM Files, PEM Bundle File, PKCS12/PFX Bundle File, PKCS7 Bundle File and CSR
and CSR PEM File.
+
PEM File.
  
 
The Cert Admin tab has a lot more fields relating to certificate orders. All
 
The Cert Admin tab has a lot more fields relating to certificate orders. All
Line 265: Line 415:
 
than the live server which will only issue five duplicate certificates a week
 
than the live server which will only issue five duplicate certificates a week
 
(if ordering goes mad), no more than 50 per domain per week and five failed
 
(if ordering goes mad), no more than 50 per domain per week and five failed
domain validations per hour.
+
domain validations per hour.  The component stops more than one order per
 +
day for each domain.
 +
 
 +
For local orders using the sample, there are six buttons numbered in the sequence
 +
in which they are used during ordering.  For orders from applications, some of
 +
these steps are combined.
  
 
Select a Account Directory for the database and certificates files, either by
 
Select a Account Directory for the database and certificates files, either by
 
typing a path or clicking the square path box to select a Database Directory
 
typing a path or clicking the square path box to select a Database Directory
using a dialog window.  Click 'Register Account' which will create a new account
+
using a dialog window.  Click 'Register Account (1)' which will create a new
private key or open an old one, and then register the account.  Once the account
+
account private key or open an old one, and then register the account.  Once the
is open, the Supplier Database tab will be updated with account details and any
+
account is open, the Supplier Database tab will be updated with account details
certificate orders in the account database, with their issue state and details.
+
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
 
After completing all the necessary domain name and certificate details on the
Common, Domain and Cert Admin tabs, click 'Check Order' which will check the
+
Common, Domain and Cert Admin tabs, click 'Check Order (2)' which will check the
challenge method specified on the Common tab is valid and repeat the local
+
challenge method specified on the Common tab is valid and locally test all the
'Test Well-Known' check for file challenges.  If the checks succeed, the order
+
challenges for all domains specified.  If the local order checks succeed, the
will be written to the account database, and the 'Order Certificate' button
+
order will be written to the account database, and the 'Get Challenges (3)'
enabled.  The Supplier Database tab will be updated with the new order with
+
button enabled.  The Supplier Database tab will be updated with the new order
an Issue State of Checked.
+
with an Issue State of Checked.
 +
 
 +
Now click the 'Get Challenges (3)' button to start the order process.  Let's
 +
Encrypt is 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 files, creating special
 +
SSL certificates or adding records to a Domain Name Server.  Let's Encrypt
 +
challenge data remains valid for about one week, so the certificate does not
 +
need to ordered immediately, or the same domains may have further certificates
 +
issued without new challenges.  This also allows time for a Domain Name Server
 +
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
 +
state changes to ChallgReq.
  
Now click the 'Order Certificate' button to start the order process.  There will
+
Clicking 'Test Challenges (4)' button starts locally test them, to make sure the
be another local 'Test Well-Known' check.  Then Let's Encrypt is asked if it can
+
domains, files, etc are available from the public internet correctlyOnce
register each of the domain names for the certificateIf the names are
+
successful the 'Start Challenges (5)' button is enabled and order state changes
acceptable, information about the actual challenge is returned by the supplier
+
to ChallgTest.
and the component prepares it by writing a queue record to the database and then
 
by copying a file to the web server .well-known directory or starting the local
 
web server, or for FTP and DNS by raising an event so the application can prepare
 
the challenge before returning.  The sample application waits five minutes for
 
the DNS server to be updated manually.
 
  
Once the challenge is ready, Let's Encrypt is instructed to test the challenge,
+
Clicking 'Start Challenges (5)' asks Let's Encrypt to test the challenges,
which may take a few seconds or minutes, and the Issue State on the Supplier
+
which usually takes from 15 seconds to a minute, unless they are very busy.
Database tab will be updated to 'Challg Pend', and the 'Collect Certificate'
+
there are usually at least three challenge tests from different networks.
button will be enabled.
+
The Issue State on the Supplier Database tab will be updated to ChallgPend.
  
 
If Automatic Order Completion is enabled (on the Common tab), the component will
 
If Automatic Order Completion is enabled (on the Common tab), the component will
check for successful or failed challenges every 30 seconds while the sample
+
check for successful or failed challenges every 10 seconds while the sample
application is running, updating Issue Status to 'Challg OK', 'Collected' and
+
application is running, updating Issue Status to ChallgOK, Collected and
'Installed' if the order is successful, or 'None' if it fails the challenges or
+
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
+
problems in collecting the certificate.
enabled, clicking the 'Collect Certificate' button will check if the challenges
+
 
have been successful and proceed to collect the new SSL certificate.
+
If Automatic Order Completion is not enabled, clicking the 'Collect Certificate
 +
(6)' button will check if the challenges have been successful and proceed to
 +
collect the new SSL certificate.
  
 
Multiple certificate orders may be placed using the same account, without waiting
 
Multiple certificate orders may be placed using the same account, without waiting
Line 321: Line 486:
 
the Issue Status updated to 'Collected'.  If a Web Server UNC Public Certificate
 
the Issue Status updated to 'Collected'.  If a Web Server UNC Public Certificate
 
Directory has been specified, the certificates will be copied to the servers,
 
Directory has been specified, the certificates will be copied to the servers,
and the Issue Status updated to 'Installed'.  Servers based on TWSocketServer
+
and the Issue Status updated to 'Installed'.
will periodically check for new SSL certificates (RecheckSslCerts method) and
 
will automatically install the new certificate.
 
  
 
Note that Let's Encrypt certificates are only valid for three months since they
 
Note that Let's Encrypt certificates are only valid for three months since they
 
are intended to be renewed automatically.
 
are intended to be renewed automatically.
  
 +
Servers based on TWSocketServer will periodically check for new SSL certificates
 +
(RecheckSslCerts method) and will automatically order and install new
 +
certificates typically 30 days before the old one expires.
 +
 +
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.
  
 
==TSslX509Certs CertCentre Order Process ==
 
==TSslX509Certs CertCentre Order Process ==
Line 363: Line 534:
 
  CA: Comodo, Refund Period: 30 days
 
  CA: Comodo, Refund Period: 30 days
 
  DV Methods: "FILE","DNS","EMAIL"
 
  DV Methods: "FILE","DNS","EMAIL"
  Predicted Approval Duration: 3 mins  
+
  Predicted Approval Duration: 3 mins
  
 
  Comodo mit EV Multi-Domain (MDC)
 
  Comodo mit EV Multi-Domain (MDC)
Line 371: Line 542:
 
  SANMaxHosts: 250 at 60.2 GBP/year each
 
  SANMaxHosts: 250 at 60.2 GBP/year each
 
  Predicted Approval Duration: 3 hours
 
  Predicted Approval Duration: 3 hours
+
 
 
Only certifcates showing DV Methods as FILE or DNS can use automated challenges,
 
Only certifcates showing DV Methods as FILE or DNS can use automated challenges,
 
EMAIL will need a manual response but collection will be automatic.  Organisation
 
EMAIL will need a manual response but collection will be automatic.  Organisation
Line 408: Line 579:
 
will access servers running certificates issued by the CA.
 
will access servers running certificates issued by the CA.
  
The sample application does not currently create self signed SSL certificates,
+
The sample application has a button that will create self signed SSL certificates
you need to use the OverbyteIcsPemTool sample instead. You should create a new
+
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,
 
private key and self signed certificate with your organisation's common name,
 
ie Magenta Development CA.  Rather than signing certificates directly with the
 
ie Magenta Development CA.  Rather than signing certificates directly with the
Line 454: Line 626:
 
disabled depending on each Issue State.
 
disabled depending on each Issue State.
  
Buttons available are: Check Order, Order Certificate, Collect Certificate,
+
Buttons available are: Check Order, Get Challenges, Order Certificate (same as
Redistribute (copy to web server again), Cancel Order (without revoke), Revoke
+
Test and Start Challenges above), Collect Certificate, Redistribute (copy to web
Certificate and Remove Order (removed from database only), most of which have
+
server again), Cancel Order (without revoke), Revoke Certificate and Remove
been described for the order process earlier.
+
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
 
Revoke an order should generally only be done if the certificate is in public
Line 550: Line 723:
  
  
'''function CertOrderDomain(const aDomain: String): Boolean;
+
'''function CertOrderDomain(const aDomain: String): Boolean;'''
'''
+
 
 
First calls CertCheckDomain, if that passes continues to place the SSL
 
First calls CertCheckDomain, if that passes continues to place the SSL
 
certificate order with the supplier, whose processes vary as described in
 
certificate order with the supplier, whose processes vary as described in
Line 564: Line 737:
  
  
'''function CertCancelDomain(const aDomain: String): Boolean;
+
'''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
 
with the supplier, which may result in a refund if done within a reasonable
 
with the supplier, which may result in a refund if done within a reasonable

Latest revision as of 10:15, 19 May 2020

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 subdmains 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.

TSslX509Certs Overview

The TSslX509Certs component automatically downloads SSL/TLS X509 certificates from various suppliers, including free certificates from Let's Encrypt, and commercial certificates for Digicert, Comodo, Thawte and GeoTrust from CertCentre AG and Servertastic (not done yet). 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 implemented by Let's Encrypt to download free domain validated certificates. Note the Acme 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 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.

Commercial suppliers of certificates have their own APIs, usually using HTTP REST, currently the component supports CertCentre AG https://www.certcenter.de/, https://www.certcenter.co.uk/ or https://www.certcenter.com/ from where you can buy certificates issued by Comondo/Sectigo, DigiCert (including GeoTrust, 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 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.


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

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

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 address. This is used by the sample OverbyteIcsX509CertsTst to order certificates separately without needing a web server, and by the TSslFtpServer and TIcsIpStrmLog 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. The next release will also support Cloudfare 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.

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 will automatically create a self signed certificate to start.

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, only 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 currently tests challenges three times from servers on different networks to avoid DNS spoofing. In practice this all takes placed 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 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

The component keeps the IssueState for each order and pending challenge reflecting the order progress, saved in the database as type TIssueState, as follows:

IssStateNone

Not started.

IssStateAccount

Account with certificate supplier has been opened.

IssStateChecked

Basic local checks completed, chosen domain challenge allowed, such as copying a test file to .WellKnown directory and accessing it by domain name from the public internet or checking a domain name server can be reached.

IssStateChallgReq

Received acceptable challenge methods and data from supplier, component will prepare some challenges, others may need to done manually or by the application such as DNS. The challenge data should remain valid for up to a week.

IssStateChallgTest

Challenges have been tested as ready for checking by supplier, .WellKnown and TlsApln have been accessed from the public internet or the DNS returns the correct TXT record.

IssStateChallgPend

Pending a response from the certificate supplier to the challenges, may be 30 seconds or several days if manual intervention is required.

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.

IssStateCollect

The CA signed certificate has been collected OK. The certificate can be collected again if something failed.

IssStateInstall

Certificate has been installed for the server by the component. not supported yet.

IssStateCancel

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


TSslX509Certs Sample Application

There is a application Samples\Delphi\SslInternet\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 account databases and allows them to be re-ordered.

In the following sample descriptions, all the fields and buttons mentioned have corresponding properties and methods in the TSslX509Certs component itself.

On the Common tab, 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). The Domain Challenge Methods are File Web Server 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 using the Local Web Server, specify the IP address from the drop down box and start it with the button, this IP address must routed to be accessible from the 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 needed. 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. Automatic Order Completion being ticked means the 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 first, then go to Settings, Your Apps & API Keys, under OAuth2 Your Apps, click the blue + icon to create a new App, with OAuth2 Redirect-URI: 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 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. Clicking the Test Domain Challenges button set-up challenges for all the domains and try to access them locally, to prove future challenges will be successful. If commercial certificates are being ordered using Email Challenge, each SAN should specify the Approval Email address required (scroll across the grid). 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.

The Cert Admin tab has a lot more fields relating to certificate orders. All certificates need to specify a Private Key Type and Size depending on security requirements (generally RSA2048, EC256 is better but not supported by many certificates), Signature Digest Type usually SHA256, Serial Number Type either 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.


TSslX509Certs ACME/Let's Encrypt Order Process

ACME (Automatic Certificate Management Environment) is the protocol designed by 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 since it issue certificates signed by a fake CA and there are fewer rate limits than the live server which will only issue five duplicate certificates a week (if ordering goes mad), no more than 50 per domain per week and five failed domain validations per hour. The component stops more than one order per day for each domain.

For local orders using the sample, there are six buttons numbered in the sequence in which they are used during ordering. For orders from applications, some of these steps are combined.

Select a Account Directory for the database and certificates files, either by typing a path or clicking the square path box to select a Database Directory using a dialog window. Click 'Register Account (1)' which will create a new account private key or open an old one, and then register the account. Once the account is open, the Supplier Database tab will be updated with account details 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 Common, Domain and Cert Admin tabs, click 'Check Order (2)' which will check the challenge method specified on the Common tab is valid and locally test all the 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 Encrypt is 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 files, creating special SSL certificates or adding records to a Domain Name Server. Let's Encrypt challenge data remains valid for about one week, so the certificate does not need to ordered immediately, or the same domains may have further certificates issued without new challenges. This also allows time for a Domain Name Server 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 state changes to ChallgReq.

Clicking 'Test Challenges (4)' button starts locally test them, to make sure the domains, files, etc are available from the public internet correctly. Once successful the 'Start Challenges (5)' button is enabled and order state changes to ChallgTest.

Clicking 'Start Challenges (5)' asks Let's Encrypt to test the challenges, 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. The Issue State on the Supplier Database tab will be updated to ChallgPend.

If Automatic Order Completion is enabled (on the Common tab), the component will check for successful or failed challenges every 10 seconds while the sample 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 (6)' button will check if the challenges have been successful and proceed to collect the new SSL certificate.

Multiple certificate orders may be placed using the same account, without waiting for earlier orders to be completed. If the sample application is stopped, the next time it is run and the Supplier Account opened, any pending orders will be checked and completed if possible, or failed.

Once all challenges succeed, the component proceeds to collect the certificate. First, a new private key and certificate signing request will be created and submitted or old ones uses if so specified on the Common tab. If the CSR matches the domain challenge, a new domain SSL/TLS X509 certificate is downloaded and saved including the order number, then the intermediate certificate that will be needed by the web server, then the PEM and PKCS12 bundles are built by adding the private key, as detailed above. Finally the component runs a check to validate the certificate chain, and reports all the details. If validation passes, all the files are saved a second time without the order number, as detailed above. and the Issue Status updated to 'Collected'. If a Web Server UNC Public Certificate Directory has been specified, the certificates will be copied to the servers, and the Issue Status updated to 'Installed'.

Note that Let's Encrypt certificates are only valid for three months since they are intended to be renewed automatically.

Servers based on TWSocketServer will periodically check for new SSL certificates (RecheckSslCerts method) and will automatically order and install new certificates typically 30 days before the old one expires.

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.

TSslX509Certs CertCentre Order Process

CertCentra AG orders are similar in concept to Let's Encrypt, but require a 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 'Get Profile' button will trigger OAuth2 if necessary (see earlier), then 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
Cost 6.7 GBP/year
Max Validity: 24 months, Features: "DV","ECC"
CA: Comodo, Refund Period: 30 days
DV Methods: "FILE","DNS","EMAIL"
Predicted Approval Duration: 3 mins
InstantSSL
Cost 23.1 GBP/year
Max Validity: 24 months, Features: "OV","RI","ECC"
CA: Comodo, Refund Period: 30 days
Predicted Approval Duration: 2 hours
PositiveSSL Wildcard
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)
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, 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 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 check for successful or failed challenges and completed orders ready to collect the certificate, and complete them.

The 'List Orders' button will generate a list in the log of recent CertCentre orders with their order number and status. For orders that are completed, the 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, and allows them to be Collected, Cancelled or Revoked.

TSslX509Certs Own CA Order Process

For internal network use and testing, it is possible to create your Own Certificate Authority and issue your own SSL certificates for devices that are not accessible from the public internet. To avoid horrible browser warnings, your CA certificate needs to be installed as a trusted root on each device that will access servers running certificates issued by the CA.

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 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 Supplier Database

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 typing a path or clicking the square path box to select a Database Directory using a dialog window. Click the 'Open Supplier' button, the database will be opened, the supplier details shown in the yellow box and the Supplier Certificate 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 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 use and the private key has been compromised. Revoke means the certificate will 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.


TSslX509Certs Main Functions

function OpenAccount(const WorkDir: String; CreateNew: Boolean = False): Boolean;

Opens the supplier account in the specified directory, optionally creating a new account if the directory does not exist or is empty. For a new account, several properties are needed: DebugLevel, DomWebSrvIP, LogJson, LogPkeys, SupplierEmail, SupplierProto, SupplierServer and SupplierTitle. SupplierEmail and SupplierProto 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 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.

function CloseAccount: Boolean; Close the account, if open.


function CertReadDomain(const aDomain: String): Boolean;

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

The function will fail if the domain has not been saved in the database.


function CertSaveDomain(const aDomain: String): Boolean;

Save or update properties for an X509 SSL certificate with the Common Name to the database. There are many possible properties, depending on the type of certificate being ordered, the supplier, challenge type, etc, all of which are illustrated in the sample application. The main properties are: CertCommonName, SuppCertChallenge as TChallengeType supports ChallFileUNC, ChallFileFtp, ChallFileSrv, ChallDNS, ChallEmail, ChallAlpnUNC, ChallAlpnSrv, ChallManual, CertPKeyType as type TSslPrivKeyType typically PrivKeyRsa2048, CertSignDigest as type TEvpDigest typically Digest_sha256, CertCsrOrigin usually CsrOriginProps, 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 SupplierProto is not set, or CertSubAltNames is empty. But otherwise does not check properties for validity.


function CertCheckDomain(const aDomain: String): Boolean;

For an open account, reads all the properties for an X509 SSL certificate with 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.


function CertOrderDomain(const aDomain: String): Boolean;

First calls CertCheckDomain, if that passes continues to place the SSL 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.


function CertCollectDomain(const aDomain: String): Boolean;

For an order with issue state challenge pending, checks if all the challenges have been completed successfully and then collects the order.


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.