PingAuthorize

Using manage-certificates as a simple certification authority

If your server instances need to support an arbitrary or unknown set of clients, configure them with certificates from a trusted issuer, such as a commercial authority or the free Let’s Encrypt service.

About this task

If you control every client that accesses the servers, you might want to create your own internal certification authority so that you have a common issuer for all servers. In such a scenario, the clients need to trust only the certificates that the issuer signs. Commercial and open-source software packages provide full-featured certification authority functionality, but you can use the manage-certificates tool to create a certificate authority (CA) certificate that you can use to sign certificate-signing requests.

Steps

  1. Create a CA certificate.

    A CA certificate is a self-signed certificate that possesses the following extensions:

    • A key usage extension that includes at least the keyCertSign usage

    • A basic constraints extension that identifies the certificate as a CA certificate

    If you do not plan to use an intermediate CA certificate, the basic constraints extension must have a path length constraint of 0. If you plan to use an intermediate CA certificate, the path length constraint must be 1. Because certificates that the CA certificate signs are valid only for as long as all certificates in the chain remain valid, we recommend that you specify a long lifespan for the CA certificate.

    Example:

    The following example creates a new root CA certificate.

    $ bin/manage-certificates generate-self-signed-certificate \
         --keystore /ca/root-ca-keystore \
         --keystore-password-file /ca/root-ca-keystore.pin \
         --keystore-type JKS \
         --alias root-ca-cert \
         --subject-dn "CN=Example Root CA,O=Example Corp,C=US" \
         --days-valid 7300 \
         --key-algorithm RSA \
         --key-size-bits 4096 \
         --signature-algorithm SHA256withRSA \
         --basic-constraints-is-ca true \
         --basic-constraints-maximum-path-length 1 \
         --key-usage key-cert-sign \
         --key-usage crl-sign
    
    Successfully created a new JKS keystore.
    
    Successfully generated the following self-signed certificate:
    Subject DN:  CN=Example Root CA,O=Example Corp,C=US
    Issuer DN:  CN=Example Root CA,O=Example Corp,C=US
    Validity Start Time: Monday, January 27, 2020 at 03:47:29 PM CST (0 seconds ago)
    Validity End Time: Sunday, January 22, 2040 at 03:47:29 PM CST
                       (7299 days, 23 hours, 59 minutes, 59 seconds from now)
    Validity State:  The certificate is currently within the validity window.
    Signature Algorithm: SHA-256 with RSA
    Public Key Algorithm: RSA (4096-bit)
    SHA-1 Fingerprint: bc:8e:5b:30:52:ec:03:63:b4:9a:aa:1a:45:a0:fc:84:49:dd:e8:64
    SHA-256 Fingerprint:
       d5:47:06:cd:a2:95:42:61:1f:c7:aa:04:16:1e:c1:70:41:c4:44:48:bf:74:20:5f:1c:
       61:e2:aa:40:08:3a:ff
  2. Export the public portion of the root CA certificate for future reference.

    When you import a signed certificate, you can import the public portion of the root CA certificate as a standalone certificate into trust stores as well as into part of a certificate chain.

  3. Create a new certificate signing request to create an intermediate CA certificate,

    The certificate signing request uses essentially the same settings as the root CA. If you anticipate only a single intermediate CA, its basic constraints extension must have a path length constraint of 0, rather than 1, to indicate that it is used only to sign end-entity certificates and that it cannot create subordinate CA certificates by itself.

    Example:

    The following example command creates a certificate signing request.

    $ bin/manage-certificates generate-certificate-signing-request \
         --keystore /ca/intermediate-ca-keystore \
         --keystore-password-file /ca/intermediate-ca-keystore.pin \
         --keystore-type JKS \
         --alias intermediate-ca-cert \
         --subject-dn "CN=Example Intermediate CA,O=Example Corp,C=US" \
         --key-algorithm RSA \
         --key-size-bits 4096 \
         --signature-algorithm SHA256withRSA \
         --basic-constraints-is-ca true \
         --basic-constraints-maximum-path-length 0 \
         --key-usage key-cert-sign \
         --key-usage crl-sign \
         --output-file /ca/intermediate-ca-cert.csr \
         --output-format PEM
    
    Successfully created a new JKS keystore.
    
    Successfully generated the key pair to use for the certificate signing
    request.
    
    Successfully wrote the certificate signing request to file
    '/ca/intermediate-ca-cert.csr'.
  4. Use the root CA certificate to sign the certificate signing request for the intermediate CA certificate with the sign-certificate-signing-request subcommand.

    The sign-certificate-signing-request subcommand takes most of the same arguments as generating a self-signed certificate. The primary differences between the argument sets are as follows:

    • The key store that contains the certificate uses the provided key store arguments to sign the request. To specify the name of the certificate to use when signing the request, use the --signing-certificate-alias argument.

    • To specify the path to the file that contains the certificate signing request file to generate, provide a --request-input-file argument.

    • To specify the path to the file to which the signed certificate is written, provide a --certificate-output-file argument. If this argument is omitted, the PEM representation of the certificate is written to standard output.

    • To specify the format, PEM or DER, in which the certificate is written to the output file, provide an --output-format argument.

    • To specify the subject to use for the signed certificate, use the --subject-dn argument. To use the subject DN from the certificate signing request, omit this argument.

    • To specify the name of the signature algorithm, use the --signature-algorithm argument.

    Because the requester generated the key, you cannot specify the key algorithm or the key length.

    • To indicate that the signed certificate includes every extension that is listed in the certificate signing request, use the --include-requested-extensions argument. If this argument is not provided, explicitly specify the set of extensions to include.

    Example:

    The following example command signs the certificate signing request for an intermediate CA certificate.

    $ bin/manage-certificates sign-certificate-signing-request \
         --keystore /ca/root-ca-keystore \
         --keystore-password-file /ca/root-ca-keystore.pin \
         --signing-certificate-alias root-ca-cert \
         --days-valid 7300 \
         --include-requested-extensions \
         --request-input-file /ca/intermediate-ca-cert.csr \
         --certificate-output-file /ca/intermediate-ca-cert.pem \
         --output-format PEM
    
    Read the following certificate signing request:
    
    PKCS #10 Certificate Signing Request Version:  v1
    Subject DN:  CN=Example Intermediate CA,O=Example Corp,C=US
    Signature Algorithm:  SHA-256 with RSA
    Public Key Algorithm:  RSA (4096-bit)
    
    Do you really want to sign this request? yes
    
    Successfully wrote the signed certificate to file
    '/ca/intermediate-ca-cert.pem'.
  5. After you obtain the intermediate CA certificate, create secure, offline backups of the root CA certificate.

  6. Remove the root CA certificate, or at least its private key, from all systems.

    Make certain that all end-entity certificates are signed with the intermediate CA certificate, and that the process is identical to the previous example. Restore the root CA certificate only if you need to sign another intermediate CA certificate.