Certificate management service


Certificate management

The certificate management service provides an implementation that supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs. The service manages:

  • Customer-provided certificates
  • Customer-provided signing/encryption keys
  • Ping-generated certificates (PKI).
  • Ping-generated signing/encryption keys.

The certificate management service listens for the “create organization” event, and when the organization is created, the certificate management service creates a default key and certificate for the organization. The default organization certificate includes the following details:

Property Value
version V3 (2)
serialNumber Secure Random generated
algorithmID sha256WithRSAEncryption
issuer commonName: Ping Identity v2; organizationalUnit: www.pingidentity.com; organization: Ping Identity Corporation; country: US
subject commonName: value; Organization Name: value; organizationalUnit: value; organization: value; country: value
validity not before: current date, not after: 1 year from current date
extensions none

The service also listens for “create environment” events and creates the default key and certificate for the environment resource. The default organization certificate signs all environment certificates.

The default environment certificate includes the following details:

Property Value
version V3 (2)
serialNumber Secure Random generated
algorithmID sha256WithRSAEncryption

The default environment key includes the following details:

Property Value
algorithm RSA
validity period 1 year
key length 2048

When uploading certificates, the certificate must be valid at the time of upload. You cannot upload a certificate before its validity period begins (the certificate’s NotBefore date) or after it expires (the certificate’s NotAfter date). The private key must be unencrypted. You cannot upload a private key that is protected by a password or passphrase. The certificate, private key, and certificate chain must all be PEM-encoded unless uploading a pkcs12 file format.

The certificate management service also manages encryption and decryption operations as well as signing and validation operations.

Certificate management API operations

The certificate management service supports the following endpoint operations:

For hands-on experience with the certificate management API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Run in Postman button here

Certificate management data model

Property Description
algorithm A string that specifies the key algorithm. Options are RSA, EC, and UNKNOWN.
createdAt The time the resource was created.
defaultKey A string that specifies the default key type. Options are SIGNING, ENCRYPTION, and NONE.
environment.id A string that specifies the environment resource’s unique identifier associated with the sign-on policy.
expiresAt The time the key resource expires.
id A string that specifies the resource’s unique identifier.
issuerDN A string that specifies the distinguished name of the certificate issuer.
keyLength An integer that specifies the key length. For RSA keys, options are 2048, 3072, and 7680. For elliptical curve (EC) keys, options are 224, 256, and 384.
name A string that specifies the resource name.
serialNumber An integer that specifies the serial number of the key.
signatureAlgorithm A string that specifies the signature algorithm of the key. Options are SHA256withRSA and SHA512withRSA.
startsAt The time the validity period starts.
status A string that specifies the status of the key. Options are VALID, EXPIRED, NOT_YET_VALID, and REVOKED.
subjectDN A string that specifies the distinguished name of the subject being secured.
validityPeriod An integer that specifies the number of days the key is valid.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
404 The specified object doesn’t exist.
409 Uniqueness constraint violation (for example, duplicate name).

Endpoint examples

Get certificates

The GET /environments/{environmentId}/certificates endpoint returns a list of all certificate resources for the specified environment.

The following sample returns the complete list of certificate resources associated with the environment ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/certificates" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

data to come

Get one certificate

To get data for a specific environment certificate, the GET /environments/{environmentId}/certificates/{certificateId} operation returns data for the certificate resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/certificates/{certificateId}" \
-H "Content-type: application/pks7-mime" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

Data to come

Create certificates

The POST /environments/{environmentId}/certificates operation creates a new environment certificate resource for the specified environment. It creates a certificate from an upload of a pkcs7 file with public and trust certificates. Properties returned in the response are parsed from the uploaded certificates.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/certificates" \
-H 'Content-type: application/pks7-mime' \
-H 'Authorization: Bearer jwtToken' \

Get keys

The GET /environments/{environmentId}/keys endpoint returns a list of all key resources for the specified environment.

The following sample returns the complete list of key resources associated with the environment ID specified in the request URL:

curl -X "GET" "https://api.pingone.com/environments/{environmentId}/keys" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

data to come

Get one key

To get data for a specific environment key, the GET /environments/{environmentId}/keys/{keyId} operation returns data for the key resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/keys/{keyId}" \
-H "Content-type: application/pks7-mime" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

Data to come

Create keys

The POST /environments/{environmentId}/keys operation creates a new environment key resource for the specified environment.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/keys" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "algorithm": "RSA",
  "defaultKey": "SIGNING",
  "keyLength": 0,
  "signatureAlgorithm": "SHA256withRSA,
  "status": "VALID",
  "subjectDN": "dn",
  "validityPeriod": 0
}'

For the subjectDN attribute, a valid DN must contain commonName, organization, organizationUnit, city, state, and country (CN=commonName, O=organization, OU=organizationUnit, C=country, ST=state, L=city).

The response data looks like this:

Data to come

Create an organization key

The PUT /environments/{environmentId}/keys/org operation creates a new organization key resource.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/keys/org" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "algorithm": "RSA",
  "defaultKey": "SIGNING",
  "keyLength": 0,
  "signatureAlgorithm": "SHA256withRSA,
  "status": "VALID",
  "subjectDN": "dn",
  "validityPeriod": 0
}'

The response data looks like this:

Data to come

Update keys

The PUT /environments/{environmentId}/signOnPolicies/{policyId} operation updates the current key to be the default signing or encryption key for an environment.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/signOnPolicies/{policyId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "defaultKey": "ENCRYPTION"
}'

The response data looks like this:

Data to come

Encrypt data

The POST /environments/{environmentId}/encryptions operation encrypts the plaintext string specified in the request body. You must also specify the certificate ID and the key ID in the request.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/encryptions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{   
	“plainText”: “string”
  "key": {
    "id": "{ID}"
  },
  "certificate": {
    "id": "{ID}"
  }
}'

The response data looks like this:

Data to come

Decrypt data

The POST /environments/{environmentId}/decryptions operation decrypts the cypher text string specified in the request body. You must also specify the key ID in the request.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/decryptions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{   
	"cypherText": “string”
  "key": {
    "id": "{ID}"
  }
}'

The response data looks like this:

Data to come

Sign data

The POST /environments/{environmentId}/signings operation signs the string specified by the plainText attribute in the request body. You must also specify the key ID in the request.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signings" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{   
	"plainText": “string”
  "key": {
    "id": "{ID}"
  }
}'

The response data looks like this:

Data to come

Verify signed data

The POST /environments/{environmentId}/signings operation uses the public key to verify the signed plain text string. You must also specify the key ID in the request. You must also specify the signature ID, certificate ID, and the key ID in the request.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/signings" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{   
  “plainText”: “string”
  "key": {
    "id": "{ID}"
  },
  "certificate": {
    "id": "{ID}"
  },
  "signature": {
    "id": "{ID}"
  }
}'

The response data looks like this:

Data to come