PingDirectory

Generating certificate signing requests

A certificate signing request (CSR) contains all of the information needed for a certification authority to issue a certificate.

The request format (also known as PKCS #10) is defined in RFC 2986 and includes the following elements:

  • The certificate signing request version.

  • The requested subject distinguished name (DN) for the certificate.

  • The public key for the requested certificate.

  • The requested set of extensions for the certificate.

  • A signature that proves the requester has the private key for the given public key.

The manage-certificates generate-certificate-signing-request command can be used to create a certificate signing request. It generates a public and private key pair and store it in a key store with a given alias, and it also outputs the certificate signing request to the terminal and optionally write it to a file. Because a certificate signing request contains many of the same elements as a certificate, the command to generate one takes most of the same arguments as for generating a self-signed certificate. However, the following arguments are not available when generating a CSR:

  • --replace-existing-certificate

  • --days-valid <number>

  • --validity-start-time <timestamp>

The following arguments are available when generating a certificate signing request but not a self-signed certificate.

Argument Description

--output-file <path>

The path to a file to which the certificate signing request should be written. If this is not provided, then the request is only written to the terminal in PEM form.

--output-format <value>

The format to use when writing the certificate signing request. The value can be either PEM or DER, but the DER format can only be used in conjunction with the --output-file argument. If this argument is not provided, the PEM format is used by default.

--use-existing-key-pair

Indicates that the certificate signing request should use a key pair that already exists in the key store with the given alias rather than generating a new key pair, in which case the given alias must not already be in use in the key store.

For example, a command like the following can be used to create a certificate signing request.

$ bin/manage-certificates generate-certificate-signing-request \
     --output-file ds1-cert.csr \
     --output-format PEM \
     --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 key pair to use for the certificate signing
request.

Successfully wrote the certificate signing request to file
'/ds/build/package/{pingdir}/ds1-cert.csr'.

The contents of the resulting certificate signing request file can be provided to a certification authority to be signed, and the resulting signed certificate can be imported into the key store as described in Importing signed and trusted certificates.

You can also print out the contents of a certificate signing request file using the display-certificate-signing-request-file subcommand. This subcommand only supports a couple of arguments.

Argument Description

--certificate-signing-request-file <path>

The path to the file containing the certificate signing request to be displayed.

--verbose

Indicates that the command should display verbose information about the request rather than just a basic set of information.

For example, the following demonstrates the basic output from the command.

$ bin/manage-certificates display-certificate-signing-request-file \
     --certificate-signing-request-file ds1-cert.csr

PKCS #10 Certificate Signing Request Version:  v1
Subject DN:  CN=ds.example.com,O=Example Corp,C=US
Signature Algorithm:  SHA-256 with ECDSA
Public Key Algorithm:  EC (secP256r1)

The following demonstrates the verbose output.

$ bin/manage-certificates display-certificate-signing-request-file \
     --certificate-signing-request-file ds1-cert.csr \
     --verbose

PKCS #10 Certificate Signing Request Version:  v1
Subject DN:  CN=ds.example.com,O=Example Corp,C=US
Signature Algorithm:  SHA-256 with ECDSA
Signature Value:
 	30:45:02:20:46:31:be:9e:6d:2f:0e:e3:d0:80:5c:88:ef:da:86:07:fd:15:b7:62:83:45:
 	39:0a:c9:f2:f9:17:eb:08:94:ff:02:21:00:c8:bd:df:57:fa:ea:8c:04:df:c5:27:76:e5:
 	b3:3b:4f:df:ec:d3:e4:09:5b:c0:6c:7b:86:39:ec:d0:0e:c1:64
Public Key Algorithm:  EC (secP256r1)
Elliptic Curve Public Key Is Compressed:  false
Elliptic Curve X-Coordinate:  20862853790475796319788947166709823976229663879966243650207011227930243221133
Elliptic Curve Y-Coordinate:  47969773922664499050574346494178826942092250865477716840891990625413960212095
Certificate Extensions:
 	Subject Key Identifier Extension:
      	OID:  2.5.29.14
      	Is Critical:  false
      	Key Identifier:
           	f2:de:fd:bf:d3:2f:96:ef:01:70:2d:0e:85:f5:fb:17:d5:a0:9e:67
 	Subject Alternative Name Extension:
      	OID:  2.5.29.17
      	Is Critical:  false
      	DNS Name:  ds.example.com
      	DNS Name:  ds1.example.com
      	IP Address:  1.2.3.4
 	Key Usage Extension:
      	OID:  2.5.29.15
      	Is Critical:  false
      	Key Usages:
           	Digital Signature
           	Key Encipherment
           	Key Agreement
 	Extended Key Usage Extension:
      	OID:  2.5.29.37
      	Is Critical:  false
      	Key Purpose ID:  TLS Server Authentication
      	Key Purpose ID:  TLS Client Authentication