Note: this component stores cluster-wide configuration data and is mirrored across all servers in the topology within the the same cluster.
Note: changes to cluster-wide configuration objects are immediately and automatically mirrored across all servers within the same cluster, so offline changes are not supported.
The Key Pair represents a public-private key pair that may be used to provide credentials for digital signatures and public-key encryption. An administrator may either import an existing key-pair or have the system generate a new one.
When importing an existing key-pair, the key must be provided as a PEM-encoded string of its PKCS#8 binary representation. A third-party tool such as openssl tool may be used to generate it. The certificate chain must also be provided in PEM-encoded format with each certificate in its own begin and end headers. The first certificate in the chain should be the end-entity certificate, i.e. the certificate whose public key corresponds to the provided private key. On the other hand, if the certificate chain and private key are not provided, a new certificate signing request, a self-signed certificate and the corresponding private key will be automatically generated by the system. The certificate signing request may be submitted to a Certificate Authority to obtain a signed certificate chain, following which the Key Pair may be updated with the new certificate chain.
The following components have a direct aggregation relation to Key Pairs:
The properties supported by this managed object are as follows:
| Basic Properties: | Advanced Properties: |
|---|---|
| key-algorithm | None |
| self-signed-certificate-validity | |
| certificate-validity-period | |
| subject-dn | |
| certificate-signing-request | |
| certificate-chain | |
| private-key |
| Description | The algorithm name and the length in bits of the key, e.g. RSA_2048. |
| Default Value | RSA_2048 |
| Allowed Values | RSA_2048 - RSA with a key length of 2048 bits RSA_3072 - RSA with a key length of 3072 bits RSA_4096 - RSA with a key length of 4096 bits EC_256 - Elliptic curve with a key length of 256 bits EC_384 - Elliptic curve with a key length of 384 bits EC_521 - Elliptic curve with a key length of 521 bits |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
self-signed-certificate-validity (Read-Only)
| Description | The validity period for a self-signed certificate. If not specified, the self-signed certificate will be valid for approximately 20 years. This is not used when importing an existing key-pair. The system will not automatically rotate expired certificates. It is up to the administrator to do that when that happens. |
| Default Value | 7300 days |
| Allowed Values | A duration. Lower limit is 1 days. Upper limit is 365000 days. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
certificate-validity-period (Read-Only)
| Description | The validity period for the end-entity certificate, i.e. the certificate whose public key corresponds to the private key in the certificate chain. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The DN that should be used as the subject for the self-signed certificate and certificate signing request. This is not used when importing an existing key-pair. |
| Default Value | cn=Directory Server,O=Ping Identity Key Pair |
| Allowed Values | A valid DN. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
certificate-signing-request (Read-Only)
| Description | The PEM-encoded certificate signing request that is automatically generated by the server. It may be submitted to a Certificate Authority to obtain a signed certificate chain, following which the certificate-chain property may be updated with the new value. This should never be created by the administrator. When importing an existing key-pair, the system will not automatically generate this. |
| Default Value | None |
| Allowed Values | application/pkcs10 |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The PEM-encoded X.509 certificate chain. The first certificate in the chain should be the end-entity certificate, i.e. the certificate whose public key corresponds to the private-key. If not specified, it will initially be populated with a self-signed certificate that is generated when this Key Pair is created. However, an administrator may remove it and replace it with certificate(s) from a Certificate Authority. To obtain a new certificate chain signed by a well known entity, the contents of the certificate-signing-request property must be submitted to a Certificate Authority. If the administrator deletes all certificates, the server will generate a new self-signed certificate for the original key-pair. |
| Default Value | None |
| Allowed Values | application/x-x509-server-cert |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The base64-encoded private key that is encrypted using the preferred encryption settings definition. |
| Default Value | A new private key will be generated if a value is omitted while creating a Key Pair for the first time. |
| Allowed Values | application/pkcs8 |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured Key Pairs:
dsconfig list-key-pairs
[--property {propertyName}] ...
To view the configuration for an existing Key Pair:
dsconfig get-key-pair-prop
--pair-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Key Pair:
dsconfig set-key-pair-prop
--pair-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Key Pair:
dsconfig create-key-pair
--pair-name {name}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Key Pair:
dsconfig delete-key-pair
--pair-name {name}