PingDirectory

Generating self-signed certificates

A self-signed certificate claims itself as its own issuer, so it is a straightforward process to create one. It’s convenient for testing, but because no clients trust it by default, it’s not recommended as a listener certificate for production use.

The manage-certificates tool offers a generate-self-signed-certificate subcommand that can be used to create one. In addition to the arguments used to provide information about the key store, certificate alias, and optional private key password, the following arguments are also available.

Argument Description

--subject-dn <subject>

The subject distinguished name (DN) for the certificate to create. This must be provided.

--days-valid <number>

The number of days that the certificate is valid. If this is not provided, a default value of 365 is used.

--validity-start-time <timestamp>

A timestamp that indicates when the certificate should begin its validity window. The value should be in the form YYYYMMDDhhmmss (for example, 20190102030405 indicates January 2, 2019 at 3:04:05 a.m.) and is assumed to be in the local time zone. If this is not provided, then the current time is used.

--key-algorithm <name>

The name of the algorithm to use to generate the key pair. For a listener certificate, the value is typically either “RSA” or “EC”. This cannot be used in conjunction with the --replace-existing-certificate argument. If neither that argument nor this argument is provided, a default value of “RSA” is used.

--key-size-bits <number>

The length of the key to generate, in bits. This must be provided if the --key-algorithm argument is also given, and it must not be provided if the --replace-existing-certificate argument is given. Typical key sizes are 2048 or 4096 bits when using an RSA key, and 256 or 384 bits for an elliptic curve key. If a default RSA key is used and this argument is not provided, then a default key size of 2048 bits is used.

--signature-algorithm <name>

The name of the algorithm to use to sign the certificate. Typical signature algorithms are SHA256withRSA for certificates with RSA keys, or SHA256withECDSA for certificates with elliptic curve keys. This must not be provided if the --replace-existing-certificate argument is used, but it must be given if the --key-algorithm argument is used to specify an algorithm other than RSA. If a default key algorithm is used and this argument is not provided, then a default value of SHA256withRSA is used.

--replace-existing-certificate

Indicates that the new certificate should replace an existing certificate in the key store (in the same alias) and that the key for that certificate should be re-used.

--inherit-extensions

Indicates that when replacing an existing certificate, the new certificate should have the same set of extensions as the existing certificate. If the --replace-existing-certificate argument is provided but this argument is omitted, then the new certificate only has the arguments that are explicitly provided.

--subject-alternative-name-dns <name>

Indicates that the certificate should have a subject alternative name extension with the provided DNS name. The given name should be fully qualified, although it can contain an asterisk as a wildcard in the leftmost component. This argument can be provided multiple times if multiple DNS names are to be included in the subject alternative name extension.

--subject-alternative-name-ip-address <address>

Indicates that the certificate should have a subject alternative name extension with the provided IP address. The given address must be a valid IPv4 or IPv6 address, with no wildcards allowed. This argument can be provided multiple times if multiple IP addresses are to be included in the subject alternative name extension.

--subject-alternative-name-email-address <address>

Indicates that the certificate should have a subject alternative name extension with the provided email address. This argument can be provided multiple times if multiple email addresses are to be included in the subject alternative name extension.

--subject-alternative-name-uri <uri>

Indicates that the certificate should have a subject alternative name extension with the provided URI. This argument can be provided multiple times if multiple URIs are to be included in the subject alternative name extension.

--subject-alternative-name-oid <oid>

Indicates that the certificate should have a subject alternative name extension with the provided object identifier (OID). The given value must be a valid OID. This argument can be provided multiple times if multiple OIDs are to be included in the subject alternative name extension.

--basic-constraints-is-ca <value>

Indicates that the certificate should have a basic constraints extension with the specified value (which must be either true or false) for the flag indicating whether the certificate should be considered a certification authority and can therefore be used to sign other certificates. This should be present with a value of true for root and intermediate CA certificates. It can optionally be present with a value of false for end-entity certificates. It’s probably a good idea for it to be present with a value of false for self-signed certificates to indicate that it should not be considered a CA certificate.

--basic-constraints-maximum-path-length <number>

Indicates that the basic constraints extension should include a path length constraint element with the specified value. This can only be used if --basic-constraints-is-ca is provided with a value of true. A path length constraint value of zero indicates that the certificate can only be used to issue end-entity certificates. If it has a value of one, then it can be used to sign intermediate CA certificates that can only be used to sign end-entity certificates (although it could also be used to sign end-entity certificates). If it has a value that is greater than one, then that means there can be that many intermediate CA certificates between it and the end-entity certificate at the head of the chain.

--key-usage <value>

Indicates that the certificate should have a key usage extension with the specified value. Allowed values include digital-signature, non-repudiation, key-encipherment, data-encipherment, key-agreement, key-cert-sign, crl-sign, encipher-only, and decipher-only. This argument can be provided multiple times to include multiple key usages.

--extended-key-usage <value>

Indicates that the certificate should have an extended key usage extension with the specified value. Allowed values include server-auth, client-auth, code-signing, email-protection, time-stamping, and ocsp-signing. This argument can be provided multiple times to include multiple extended key usages.

For example, a command like the following can be used to generate a self-signed server certificate.

$ bin/manage-certificates generate-self-signed-certificate \
     --keystore config/keystore \
     --keystore-password-file config/keystore.pin \
     --keystore-type JKS \
     --alias server-cert \
     --subject-dn "CN=ds.example.com,O=Example Corp,C=US" \
     --key-algorithm EC \
     --key-length-bits 256 \
     --signature-algorithm SHA256withECDSA \
     --subject-alternative-name-dns ds.example.com \
     --subject-alternative-name-dns ds1.example.com \
     --subject-alternative-name-ip-address 1.2.3.4 \
     --key-usage digital-signature \
     --key-usage key-encipherment \
     --key-usage key-agreement \
     --extended-key-usage server-auth \
     --extended-key-usage client-auth

Successfully created a new JKS keystore.

Successfully generated the following self-signed certificate:
Subject DN:  CN=ds.example.com,O=Example Corp,C=US
Issuer DN:  CN=ds.example.com,O=Example Corp,C=US
Validity Start Time:  Monday, January 27, 2020 at 03:40:13 PM CST (0 seconds ago)
Validity End Time:  Tuesday, January 26, 2021 at 03:40:13 PM CST (364 days, 23 hours, 59 minutes, 59 seconds from now)
Validity State:  The certificate is currently within the validity window.
Signature Algorithm:  SHA-256 with ECDSA
Public Key Algorithm:  EC (secP256r1)
SHA-1 Fingerprint:  4f:41:82:7f:08:e9:d8:05:8c:19:8b:3e:5b:bc:59:98:d3:15:71:3a
SHA-256 Fingerprint:  76:e6:8e:c5:c8:8d:27:ce:2b:85:b9:8c:9d:49:3c:06:f4:40:f1:d0:70:67:39:24:fc:31:bc:f8:51:83:f2:42