Because a self-signed certificate claims itself as its own issuer, the process of creating one is straightforward. Although self-signed certificates are convenient for testing environments, clients do not trust them by default. Consequently, we do not recommended using them as listener certificates in production environments.
The manage-certificates tool offers a generate-self-signed-certificate subcommand that can be used to 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:
- --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.
Note: 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 as follows:
- 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. Conversely, 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 keystore (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 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, we recommend specifying 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}
- server-auth
- client-auth
- code-signing
- email-protection
- time-stamping
- ocsp-signing
To include multiple extended key usages, specify the – Indicates that the certificate is expected to have an extended key usage extension with the specified value. The following values are allowed:--extended-key-usage {value} argument multiple times.
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