SVN and the overnight zip have been updated with a new TSslX509Certs component that automatically downloads SSL/TLS X509 certificates from various suppliers, and a new sample application to test it. This is still a beta component, with a number of planned improvements that should be done in June, but is fully functional now for free single domain certificates from Let's Encrypt and commercial certifications from CertCentre AG.
The new component uses the recent REST, OAuth2 and Jose units, which also have minor changes and fixes from practical use. The Let's Encrypt functions use Json REST and Json Web Signatures signed by private keys, while the CertCentre AG functions use OAuth2 with unsigned Json REST requests. There is a new sample that will order and download certificates, but currently none of this is integrated into SocketServer, which will happen in June so the process is automatic in background. Overview -------- 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 three 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, 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. A fourth method Server Name Indication (SNI) validation has been used in the past which allows an SSL server to check a special domain name, but security weakness in some implementations mean this is not currently used. File and domain validation challenges can both be automated, file is easiest using a simple HTTP server, while domain validation 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 supplier may have a queue of challenges waiting to the tested, but usually happen without a couple of minutes. Applications need to be aware the wait may be longer. 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 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 component supports automated file challenge for Domain Validated certificates, initially using an external HTTP server to which files may be copied using UNC shares, but the next release will support a built-in HTTP server as well. 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, likewise email challenge needs an external email application. The component supports the Acme V1 and V2 protocols as implemented by Let's Encrypt to download free domain validated certificates, beware V1 bears little resemblance to any of the Acme Internet Draft specifications, V2 is much closer 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. Note that Acme V1 has been superseded by V2, and was only supported because V2 did not go public until March 2018. 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 HTTP (not HTTPS) server where the component can copy a challenge file for Let's Encrypt to access to prove domain ownership. Let's Encrypt also supports DNS challenges but this is not yet implemented by the component. Currently only single domains are supported, multiple domains and wildcard will be added for V2 shortly. 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, DigiCert (including GeoTrust, Symantec and Thawte) and GlobalSign, and free certificates from AlwaysOnSSL (by resellers only), see https://alwaysonssl.com/issue.php. You need to register with CertCentre AG and open an 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 challenge, other types of certificates can be ordered and then downloaded when the order is completed. 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 extra information about the account. The next release will include an account database file to keep track of domains being ordered and when they need renewing. 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. When ordering a new certificate, temporary files may be created in the account directory, the new certified 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 find the following files upon completion: 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. TSslX509Certs Sample Application -------------------------------- There is a sample 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. Note that currently there must be a external HTTP (not HTTPS) server where the component can copy challenge files to prove domain ownership. 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). For CertCentre AG, you must create an account on their web site 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, copy the various OAuth2 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 is still running. For certificate orders, on the Common Tab set the challenge method and optional private key password and encryption type (3DES) if needed, on the Domain tab set the certificate common domain name (note alternate names not yet supported), then the 'Web Server UNC HTTP .Well-Known Directory' and optionally 'Web Server UNC Public Certificates Directory' where the final certificates will be copied. Clicking the 'Test Well-Known' button will copy a file to the web server and attempt to access it using the domain name, to prove future challenges will be successful. The Cert Admin tab has a lot more fields relating to certificate order needed to create a private key and certificate signing request, many can be ignored for Let's Encrypt (except email) but commercial certificates need most of the fields, including certificate period in months, usually 12 or 24, but this may be overwritten by the order process. Currently only RSA keys and SHA-2 are tested, not ECC or SHA-3. TSslX509Certs Order Process --------------------------- Let's Encrypt offers live and staging servers, the latter is best for testing since it issue certificates signed by a fake CA. Select a directory for the account and certificates and the server. For Let's Encrypt, click 'Register Account' which will create a new account private key or open an old one, and then register the account. For CertCentre, Get Profile will trigger OAuth2 if necessary, then check your account and list the certificate products that can be ordered, from which one will be selected, and the details and cost will be displayed. Next, click 'Check Order' which will check the challenge method specified on the Common tab is valid for the certificate product, and repeat the local 'Test Well-Known' check for file challenges. If the checks succeed, the Order button will be enabled. For Let's Encrypt Acme and AlwaysOnSSL, click the Order button to start the order process. There will be another local 'Test Well-Known' check. Then the supplier is asked if it can register the domain name. If the name is acceptable, information about the actual challenge is returned by the supplier and the component creates the domain validation file in the web server .well-known directory and requests the supplier to test it, returning an order number. The component then waits up to two minutes periodically checking the order status to see if the challenge has been completed and been successful. The next release of the component will remove this wait and instead implement a queue of challenge checks over days if necessary, allowing multiple domains to be handled. Once the challenge succeeds, the 'Collect Certificate' button is enabled and should be clicked. Another check is made the challenge has been completed OK, then a private key and certificate signing request will be created and submitted. If the CSR matches the challenged domain, a new domain SSL/TLS X509 certificate is generated 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 finally a third time by copying to the web server certificate directory. Some web servers, such as those based on TWSocketServer 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 are intended to be renewed automatically. AlwaysOnSSL is a similar free certificate available to resellers of CertCentre, and the order process is similar to Acme, except the CSR is supplied before the challenge starts, and the certificate is returned when the challenge succeeds, but may be downloaded again later if needed by using the order number. AlwaysOnSSL certificates are valid up to one year. 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 and AlwaysOnSSL. For email validation, organisation and extended validated certificates, an order number is returned and the process now stalls for manual processing. 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. Pending - more documentation Pending - database (ini file) of domains, challenges and expiry for automation Pending - support multiple challenges (needs database) Pending - collect certificate when challenge passed (needs database) Pending - local web server (needs database) Pending - integrate with SocketServer component (for web server, proxy server) Pending - multiple SAN domains for AcmeV2 and CertCentre Pending - wild cards and DNS validation for AcmeV2 Pending - Acme EC accounts, signing currently fails validation Pending - Acme EC certificates, not properly tested yet Pending - Acme revoke certificate Pending - CertCentre re-issue certificate, use ModifiedOrders for last x days Pending - Servertastic APIv2 for commercial certificates Pending - install PKCS12 certificates into Windows cert store for IIS Pending - better error reporting and logging Angus -- To unsubscribe or change your settings for TWSocket mailing list please goto http://lists.elists.org/cgi-bin/mailman/listinfo/twsocket Visit our website at http://www.overbyte.be
