Generating self-signed certificates

The process of creating a self-signed certificate is straightforward because a self-signed certificate claims itself as its own issuer.

Although self-signed certificates are convenient for testing environments, clients do not trust them by default. Consequently, you should not use them as listener certificates in production environments.

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

Argument Description

--subject-dn {subject}

Subject DN for the certificate to create. This value is required.

--days-valid {number}

Number of days that the certificate remains valid. Defaults to 365 if no value is specified.

--validity-start-time {timestamp}

Indicates the time at which the certificate begins its validity window. This value is assumed to reflect the local time zone, and must be expressed in the form YYYYMMDDhhmmss, where a value of 20190102030405 indicates January 2, 2019, at 3:04:05 AM.

Defaults to the current time if no value is specified.

--key-algorithm {name}

Name of the algorithm to use when generating the key pair. For a listener certificate, this value is typically RSA or EC.

Defaults to RSA if no value is specified.

This argument cannot be used in conjunction with the --replace-existing-certificate argument.

--key-size-bits {number}

Length of the key, in bits, to generate. If the --key-algorithm argument is given, then --key-size-bits {number} must also be specified. Conversely, if the --replace-existing-certificate argument is given, then --key-size-bits {number} must not be specified. Typical key sizes are:

RSA key – 2048 or 4096 bits If a default RSA key is used but this argument is not provided, a default key size of 2048 bits is used.
Elliptic curve key – 256 or 384 bits

--signature-algorithm {name}

Name of the algorithm to use to sign the certificate. If the --key-algorithm argument is used to specify an algorithm other than RSA, then --signature-algorithm {name} must also be specified.

If the --replace-existing-certificate argument is used, then --signature-algorithm {name} must not be specified.

Typical signature algorithms include SHA256withRSA for certificates with RSA keys, and SHA256withECDSA for certificates with elliptic curve keys. If a default key algorithm is used but the --signature-algorithm {name} argument is not provided, a default value of SHA256withRSA is used.

--replace-existing-certificate

Uses the new certificate to replace an existing certificate in the key store (within the same alias), and reuses the key for that certificate.

--inherit-extensions

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

--subject-alternative-name-dns {name}

Indicates that the certificate is expected to have a subject alternative name extension with the provided DNS name. The given name must be fully qualified, although it can contain an asterisk (*) as a wildcard in the leftmost component.

To include multiple DNS names in the subject alternative name extension, specify the --subject-alternative-name-dns {name} argument multiple times.

--subject-alternative-name-ip-address {address}

Indicates that the certificate is expected to have a subject alternative name extension with the provided IP address. The given address must be a valid IPv4 or IPv6 address. No wildcards are allowed.

To include multiple IP addresses in the subject alternative name extension, specify the --subject-alternative-name-ip-address {address} argument multiple times.

--subject-alternative-name-email-address {address}

Indicates that the certificate is expected to have a subject alternative name extension with the provided email address.

To include multiple email addresses in the subject alternative name extension, specify the --subject-alternative-name-email-address {address} argument multiple times.

--subject-alternative-name-uri {uri}

Indicates that the certificate is expected to have a subject alternative name extension with the provided URI.

To include multiple URIs in the subject alternative name extension, specify the --subject-alternative-name-uri {uri} argument multiple times.

--subject-alternative-name-oid {oid}

Indicates that the certificate is expected to have a subject alternative name extension with the provided object identifier (OID). The given value must be a valid OID.

To include multiple OIDs in the subject alternative name extension, specify the --subject-alternative-name-oid {oid} argument multiple times.

--basic-constraints-is-ca {value}

Indicates that the certificate is expected to have a basic constraints extension, with a specified value of true or false, for the flag indicating whether to consider the certificate a certification authority that can be used to sign other certificates.

For root and intermediate certificate authority (CA) certificates, the --basic-constraints-is-ca {value} argument must be present with a value of true.
For end-entity certificates, the --basic-constraints-is-ca {value} argument can optionally be present with a value of false.
For a self-signed certificate, specify the --basic-constraints-is-ca {value} argument with a value of false to indicate that the certificate is not considered a CA certificate.

--basic-constraints-maximum-path-length {number}

Indicates that the basic constraints extension is expected to include a path length constraint element with the specified value. Use this argument only if --basic-constraints-is-ca is provided with a value of true.

A path length constraint value of 0 indicates that the certificate can be used to issue only end-entity certificates. A path length constraint value of 1 indicates that the certificate can be used to sign end-entity certificates or intermediate CA certificates, the latter of which can be used to sign only end-entity certificates.

A value greater than 1 indicates the presence of several intermediate CA certificates between it and the end-entity certificate at the head of the chain.

--key-usage {value}

Indicates that the certificate is expected to have a key usage extension with the specified value. The following values are allowed:

digital-signature
non-repudiation
key-encipherment
data-encipherment
key-agreement
key-cert-sign
crl-sign
encipher-only
decipher-only

To include multiple key usages, specify the --key-usage {value} argument multiple times.

--extended-key-usage {value}

Indicates that the certificate is expected to have an extended key usage extension with the specified value. The following values are allowed:

server-auth
client-auth
code-signing
email-protection
time-stamping
ocsp-signing

Example

For example, the following command 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-dns localhost \
     --subject-alternative-name-ip-address 1.2.3.4 \
     --subject-alternative-name-ip-address 127.0.0.1 \
     --subject-alternative-name-ip-address 0:0:0:0:0:0:0:1 \
     --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

PingDirectory

Generating self-signed certificates

Example