FAQ Using TSslCertTools

The TSslCertTools component is designed to create, read, save and validate X509 SSL/TLS certificates, private keys, certificate signing requests and bundle files.

The main test application for the TSslCertTools component is the OverbyteIcsPemtool sample, which illustrates use of all the methods and properties.

OverbyteIcsPemtool may be used to create the private key and certificate request needed to buy a commercial SSL certificate from a public certificate authority. Once the new SSL certificate has been received from the CA, usually as a PEM file or email, it may be converted into other formats and saved as a single PEM or PKS12 bundle with the original private key making it easier to distribute and install on servers.

ICS Cryptography Types

ICS message digests or hashes types, note SHA3 and Shake needed OpenSSL 1.1.1 or later:

 TEvpDigest = (
    Digest_md5, 
    Digest_mdc2, 
    Digest_sha1, 
    Digest_sha224,
    Digest_sha256, 
    Digest_sha384, 
    Digest_sha512, 
    Digest_ripemd160,
    Digest_sha3_224,    
    Digest_sha3_256,
    Digest_sha3_384,
    Digest_sha3_512,
    Digest_shake128,
    Digest_shake256,
    Digest_None);       

ICS private key algorithm and key length in bits types, bracketed comment is security level and effective bits, beware long RSA key lengths increase SSL overhead heavily. Creating new RSA keys is computationally expensive, 4,096 bits a couple of seconds, 7,680 bits maybe a minute, 15,360 bit takes hours. Note RSA PSS keys need OpenSSL 1.1.1 or later.

 TSslPrivKeyType = (
    PrivKeyRsa1024,   { level 1 - 80 bits  }
    PrivKeyRsa2048,   { level 2 - 112 bits }
    PrivKeyRsa3072,   { level 3 - 128 bits }
    PrivKeyRsa4096,   { level 3 - 128 bits }
    PrivKeyRsa7680,   { level 4 - 192 bits }
    PrivKeyRsa15360,  { level 5 - 256 bits }
    PrivKeyECsecp256, { level 3 - 128 bits }
    PrivKeyECsecp384, { level 4 - 192 bits }
    PrivKeyECsecp512, { level 5 - 256 bits }
    PrivKeyEd25519,   { level 3 - 128 bits }    
    PrivKeyRsaPss2048,   { level 2 - 112 bits } 
    PrivKeyRsaPss3072,   { level 3 - 128 bits }
    PrivKeyRsaPss4096,   { level 3 - 128 bits }
    PrivKeyRsaPss7680,   { level 4 - 192 bits }
    PrivKeyRsaPss15360); { level 5 - 256 bits }

ICS private key file encryption types:

 TSslPrivKeyCipher = (
    PrivKeyEncNone, 
    PrivKeyEncTripleDES,       
    PrivKeyEncIDEA, 
    PrivKeyEncAES128,
    PrivKeyEncAES192, 
    PrivKeyEncAES256, 
    PrivKeyEncBlowfish128);

Create a new private key file

A private key is required to create a self signed certificate or a certificate request, and needs to be installed on any SSL servers (never distribute it).

1. Set property PrivKeyType (RSA or EC) from TSslPrivKeyType.
2. Create keys using DoKeyPair method checking exception for any errors.
3. PrivateKey property contains pointer to new private key.
4. If file to be encrypted, set property PrivKeyCipher from TSslPrivKeyCipher.
5. Save private key to file using PrivateKeySaveToPemFile method with optional password.
6. Optionally save public key to file using PublicKeySaveToPemFile method.

Create a new certificate signing request from properties

A certificate signing request (CSR) is needed to buy a commercial SSL certificate from a public certificate authority and most importantly specifies the host domain name or names of the public SSL server it will secure.

1. Create a new private key (see above) or load an old key using PrivateKeyLoadFromPemFile or PrivateKeyLoadFromText methods.
2. Specify request properties, CommonName (host domain name), Country, State, Locality, Organization, OrgUnit, KeyDigiSign, KeyKeyEnc, etc, as needed.
3. Create request using DoCertReqProps method checking exception for any errors.
4. X509Req property contains pointer to new request.
5. Save request to PEM file using SaveReqToFile method.
6. Optionally save request to string using SaveReqToText method.

Create a new certificate signing request from old certificate

This is a shorter way to create a new request when renewing an existing certificate with the same private key.

1. Load existing certificate using LoadFromFile or LoadFromText methods.
2. Load private key for existing certificate using PrivateKeyLoadFromPemFile or PrivateKeyLoadFromText methods.
3. Create request using DoCertReqOld method checking exception for any errors.
4. X509Req property contains pointer to new request.
5. Save request to PEM file using SaveReqToFile method.
6. Optionally save request to string using SaveReqToText method.

Create new self signed certificate from properties

Self signed certificates are mostly used for testing SSL applications on temporary servers, prior to final deployment to a public server with a commercial SSL certificate. Can also used for internal networks. May also be used to create your own CA certificate if you want to sign your own certificates.

1. Create a new private key (see above) or load an old key using PrivateKeyLoadFromPemFile or PrivateKeyLoadFromText methods.
2. Specify certificate properties, CommonName (host domain name), Country, State, Locality, Organization, OrgUnit, KeyDigiSign, KeyKeyEnc, etc, as needed.
3. Select CertDigest (hash) property from TEvpDigest.
4. Create certificate using DoSelfSignCert method checking exception for any errors.
5. X509 property contains pointer to new certificate.
6. If file to be encrypted, set property PrivKeyCipher from TSslPrivKeyCipher.
7. Save certificate to file using SaveToFile method with the file extension specifying the format that should be used. Options include IncludePrivateKey which will save the private key into the same PEM or P12 file, and optional password.
8. Optionally save certificate to string using SaveCertToText method.

Create new CA signed certificate from certificate request

This is how commercial certificate authorities create SSL certificates from a request, signing it with their own CA certificate (root or intermediate) that will be trusted by Windows due to the root already being installed locally. For development, you can create your own CA root certificate and install it in the Windows certificate store of any test computers, then create certificates signed by the root and they will be trusted by Windows without needing to accept security exceptions as happens with self signed certificates.

1. The CA certificate and CA private key need to loaded using LoadFromFile and PrivateKeyLoadFromPemFile into X509 and PrivateKey, and these properties assigned to X509CA and PrivKeyCA respectively.
2. Load certificate request using LoadReqFromFile.
3. Currently the subject certificate properties are taken from the request and can not be edited, extended properties are currently taken from properties, KeyDigiSign, KeyKeyEnc, etc, as needed. This needs more work for flexibility.
4. Select CertDigest (hash) property from TEvpDigest.
5. Create certificate using DoSignCertReq method checking exception for any errors.
6. X509 property contains pointer to new certificate.
7. If file to be encrypted, set property PrivKeyCipher from TSslPrivKeyCipher.
8. Save certificate to file using SaveToFile method with the file extension specifying the format that should be used. Options include IncludePrivateKey which will save the private key into the same PEM or P12 file, and optional password.
9. Optionally save certificate to string using SaveCertToText method.

Beware the private key used to create the request must be loaded into PrivateKey property before saving a private key with the certificate, otherwise the CA key may be incorrectly saved.

The TSslX509Certs component includes an Own CA Order Process which create new CA signed certificate with fewer steps, and saves details of certificates created to database, to support transparency and certificate revocation lists.

Convert certificate from one file format to another

1. Load existing certificate using LoadFromFile or LoadFromText methods.
2. Optionally load private key for existing certificate using PrivateKeyLoadFromPemFile or PrivateKeyLoadFromText methods.
3. If file to be encrypted, set property PrivKeyCipher from TSslPrivKeyCipher.
4. Save certificate to file using SaveToFile method with the file extension specifying the format that should be used. Options include IncludePrivateKey which will save the private key into the same PEM or P12 file, and optional password.

One use for this is to convert base64 DER/PEM certificates into P12/PVX format that can be easily installed into the Windows certificate store.

Create New DHParams File

DHParams contain prime numbers needed to support old DH and DHE ciphers (but not ECDH and ECDHE). Ideally they should be unique per server and/or application and some applications even generate new params each day. But finding prime numbers is time consuming, the shortest 1,024 bits can take up a minute, 2,048 bits several minutes, 4,096 bits a few hours, and gave up with 8,192 bits after two days.

ICS include constants sslDHParams2048 and sslDHParams4096 to save you calculating your own, if you really need to use old DH and DHE ciphers.

1. Assign OnKeyProgress event handler with Application.ProcessMessages and optionally a progress indicator so the application remains responsive while calculating DHParams.
2. Create DHParams using DoDHParams method passing new file name and number of bits, 768, 1024, 20248, 4096, 8192.
3. Optionally save DHParams string returned by DoDHParams method.

Create Certificate Bundle

Builds a new PEM or PKCS12 file by combining certificate, private key and intermediate files (in any formats with correct file extension). For servers, a bundle file is easier to distribute and load than three separate files.

1. CreateCertBundle is a simple function, that requires four full file names for the three input files and output file, optional load and save passwords, and the cipher optionally to encrypt the output file.