Encryption keys and credentials

A credential is the authentication data required to use a resource, which can be a certificate, SSH key, or PGP key. The credential consists of an alias and content, where the name of the alias is unique to the credential/resource pair. See also, Credential formats.

Create a credential

There are three steps to creating a credential to use in Central Governance.

  1. Use a tool such as xca, for example, to create a certificate.
  2. You must encode this content using Base64.
  3. To create a credential in Central Governance, provide the credential alias, content, and password, where you can use the encoded string as the certificateContent or keyContent value, depending on its type.

See Manage SSH keys for more information.

Example 1

In this example, the resource type is sshkeys and the name of the alias is new_key. (A password is required only if you are creating a private credential.)

POST /api/v2/products/businessId/sshkeys

{

"name": "new_key",

"keyContent": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwtxyGu8FSfW7WLoFC7s0+HinhaUSBQsADtyhlpDlQ0k1J9gfvhvdmJdcS6QA67BNo+B5vFu0izdWyPsaHl6aaiMhnO/NI0CU9g42HQ9zB/FCAATZ5TW1j4tEJEAV9slQphCIyNleCyH6DOz79cSQPivNIxEbyoZSuenldc9Cr3NzcMjo6UeqfCH3jURQVXg35is4waq3DoKn2hMobbGDyZybHlg4gDjeomtotX5knrDvY0oGG5uiDjLvLjSdYPkkWQ5UEZbMkSh58cQU3Ds8bWVTwq1KWy0FBZF+LuyR4Ulk7/Tyv717VuJx4elzepSQgd9RF+s81DjLbCWEp1jXSwIDAQAB",

"keyPassword": "1"

}

Retrieve credential contents

Public certificate, SSH key, or PGP key

You can use the GET command to retrieve a public credential's alias and content, and then use these values in your POST and PUT commands.

GET /api/v2/partners/businessId/sshkey?name=my_key

{

"businessId": "173c3a70-4c8f-4b03-84de-0b1814e60148",

"name": "user1.pub.p8",

"keyContent": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0udXQyAGXxyhHdRsh+UCXtEnKmWWQ95UlourzvqB0NG2RxjgNRUNWwYji/EqvsnjTH+A/k26XqEWOQFwyecjfCpC0Yu5jaHEKwP2s0tq1OLjvUNYQsUovtqDQYyNHt6SOzYT44AZ9w5jomD8KLfhoVt1/wilfJiFcRi26ABFCcLdhRd3Ct74rd8pCdujYwJLlwEGJ060HyPYqrx2iKVVkC+0tJGlpAMZbU6lbQbOej1fbxvY2lBGeGJRReFgR0H3Szr5hMKp32wMiuqeiH2LvFMRg3H+W63H5pDnsnQ+agizEyPWftH9VnPV1wKz6ZZUd42via89hhstw2wDWlm0CwIDAQAB",

"isPrivateKey": false

}

Private certificate, SSH key, or PGP key

For security reasons, when retrieving the credentials of a private certificate, SSH key, or PGP key, the content must be encrypted using an encryptionKey. This means that you must use encryptionKey (or X-EncryptionKey) when performing a GET on products to retrieve the certificateContent or keyContent.

There are two types of encryption keys to use with GET:

  • encryptionKey: a password provided as clear text.
  • X-EncryptionKey: a value for the password that is encoded using Base64.

For example, if the encryptionKey = 1, then the equivalent is X-EncryptionKey = MQ==

We recommend that you use X-EncryptionKey. The EncryptionKey is an obsolete field that creates a security issue. It is available in Swagger only for purposes of backwards compatibility.

GET /api/v2/products/businessId/certificates?name=cert1.p12

{

"businessId": "a7d1f025-5796-40c4-8d2e-6d0970c93de7",

"name": "cert1.p12",

"certificateContent": null,

"isPrivateCertificate": true

}

 

GET /api/v2/products/businessId/certificates?name=cert1.p12&?X-EncryptionKey=MQ==

{

"businessId": "a7d1f025-5796-40c4-8d2e-6d0970c93de7",

"name": "cert1.p12",

"certificateContent": "<certificate_content_which_has_password=1>",

"isPrivateCertificate": true

}

 

Note The fields isPrivateCertificate and isPrivateKey are set to the value false for credentials that are created at product registration.

Use an encryption key

The encryption key value does not correspond to any Central Governance configuration setting (when you create a credential,  you use keyPassword or certificatePassword, not encryptionkey). There are, however, two ways to use the encryption key.

Firstly, you can use the value of the encryptionkey in a POST or PUT command. The value is set to certificatePassword/keyPassword; and it is the password that is associated with the contents of the certificate, SSH key, or PGP key.

Alternatively, you can use the encryptionkey as a parameter in a command.

Example 2

In this example, you create the communication profile for the target environment using the JSON retrieved from the source environment. As you can see, you pass the encryptionKey (or the X-EncryptionKey) value as a parameter, but you do not set certificatePassword/keyPassword in the JSON of the command.

POST /api/v2/products/businessId/communicationprofiles?encryptionKey=2

{

"name": "Target_env_PESIT_SSL",

"description": "PeSIT over Secured Socket",

"type": "SERVER",

"protocol": "PESIT",

"enabled": true,

"networkZone": "Private",

"enableSSL": true,

"fipsEnabled": false,

"certificateContent": "MIAGCSqGSIb3DQEHAqCAMIACAQExADCABgkqhkiG9w0BBwEAAKCCA8swggPHMIICr6ADAgECAgEkMA0G

CSqGSIb3DQEBBQUAMHgxCzAJBgNVBAYTAkZSMRcwFQYDVQQIEw5IQVVUUy1ERS1TRUlORTEQMA4GA1UEBxMHUFVURUFVWDETMBEGA1UEChQ

KQ0ZUX1NBTVBMRTEWMBQGA1UECxQNQ0ZUX0wyX1NBTVBMRTERMA8GA1UEAxQIMmtfbDJfY2EwHhcNMDkwNzI4MDAwMDAwWhcNMjkwNzIyMj

M1OTU5WjB7MQswCQYDVQQGEwJGUjEXMBUGA1UECBMOSEFVVFMtREUtU0VJTkUxEDAOBgNVBAcTB1BVVEVBVVgxEzARBgNVBAoUCkNGVF9TQ

U1QTEUxFjAUBgNVBAsUDUNGVF9MM19TQU1QTEUxFDASBgNVBAMUCzJrX2wzX3VzZXIxMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC

AQEAof2HDrbjXjKjL1t+8xeAdxKGG4jJ9wu4tP1GyCxz82k3iwNiyui2SMZpR7QEbpJEs4XTE8p/xPYOeTHfmeeTsYKcsdRIg57/pC5SdjcU

Jn2aZp2p2rhBx+bwNkZnDH/rhbOvckEFneYv7ullQZ8PuJ4EgnUr16DcprL3SL7WlTZxSOKKKz7IwS6lwI84LwAUbqZ8sDeWM5WoOX/mf3N5

W13q09w7ylTDtK/X5s2lmkvlVDdaZB6m2/PEhaght+vzkxVq2w4Bnt9WLU99YAc58jvXLJxH/UdP1Nf6Uo5d7wKQeVb94xg5X4aWmNbn6qk+

JraJ/uwVp31qurUdfaB2UwIDAQABo1kwVzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIEsDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIw

HgYJYIZIAYb4QgENBBEWD3hjYSBjZXJ0aWZpY2F0ZTANBgkqhkiG9w0BAQUFAAOCAQEAlvxmnM/eBbEBCHuZWabgOMuwZo7lV6j7rnOiYmKg

Ug4x6rCn2CNzf4KtFQ2G8n989V2UXH58dIQugS+IO8ij9odwyA3DeORfao+7pAP+FGxhIn7MecVG6jLpTetL0eazuISuSD5S//WiJ87Q69AH

54X1cL5z3I25ZL9HNqaPKwvzryvN8DPiismsrBBbBJ7wz3gsoEDgu0zd5eS/bBbGt8IrSSpokO4cec9yWSmx3i4tYhHVRKhc89Px541h5g6y

XTXplplGC3euCeGiOVN1HwAiGNONnU9reJzMtRvBM2LEgqI04x4Q2WxJX0EzT6Hl06Y0fPSUTJ0GHIjVDRNncTEAAAAAAAAA",

"certificateAlias": "2k_l3_user1.p12",

"isPrivateCertificate": true,

"networkProtocol": "TCP",

"pesitLogin": "ST_DPG",

"hosts": [

"10.133.66.83"

],

"port": 17627,

"clientAuthenticationRequired": "Optional"

 

}

Use cases in Central Governance

Public certificates, SSH keys, and PGP keys

Resources that use public credentials

Central Governance use case

/api/v2/partners/id/communicationprofiles

/api/v2/partners/id/certificates

/api/v2/partners/id/sshkeys

  1. Create a certificate or SSH key for a specific partner, providing the credential alias and content.
  2. This certificate or SSH key's alias is used in a communication profile.

/api/v2/partners/id/pgpkeys

/api/v2/unmanagedproducts/pgpkeys

/api/v2/applications/id/pgpkeys

  1. Create a PGP key for a specific resource, providing the PGP key alias and content.
  2. The PGP key's alias is used in the resource.

Private certificates, SSH keys, and PGP keys

Resources that use private credentials

Central Governance use cases

/api/v2/products/id/communicationprofiles

  1. Create a credential by providing the credential alias and content, and setting the password. See Example 1.
  2. Reference this credential by its alias in a communication profile.
  3. Update a credential using a dedicated sub-resources for certificates, SSH keys, or PGP keys.

/api/v2/products/id/certificates

/api/v2/products/id/sshkeys

/api/v2/products/id/pgpkeys

  1. Choose an encryptionKey, encode it using Base64, and save the encoded value as X-EncrytionKey.
  2. Retrieve a communication profile in the source Central Governance environment using the X-EncryptionKey parameter.
  3. Create the communication profile on the target Central Governance environment using the JSON obtained from the source environment. See Example 2.
Note If you perform a GET request on the products resource without providing an X-EncryptionKey, the retrieved certificateContent and keyContent represent the public portion of the certificate and key respectively. The same is true for the products sub-resources.

 

Central Governance | Document Directory

Related Links