5 View and Manage Keystore Service Keystores

Before using the REST API to view and manage Keystore Service (KSS) keystores, you need to understand how to access the REST resources and other important concepts.

See "About the REST API".

For more information about KSS keystore management, see "Configuring the OPSS Keystore Service for Message Protection" in Administering Web Services.

This chapter includes the following sections:

View and Manage KSS keystores Using REST Resources

You can view and manage KSS keystores using a set of representational state transfer (REST) resources, as summarized below.


Section Method Resource Path

POST New KSS Keystore Method

POST

/idaas/platform/admin/v1/keystoreservice

POST Import KSS Keystore Method

POST

/idaas/platform/admin/v1/keystoreservice/keystore

PUT Password Update KSS Keystore Method

PUT

/idaas/platform/admin/v1/keystoreservice

POST Trusted Certificate KSS Keystore Method

POST

/idaas/platform/admin/v1/keystoreservice/certificates

GET Stripe KSS Keystores Method

GET

/idaas/platform/admin/v1/keystoreservice/{stripeName}

GET Alias KSS Keystore Method

GET

/idaas/platform/admin/v1/keystoreservice/alias/{stripeName}/{keystoreName}/{entryType}

GET Trusted Certificate KSS Keystore Method

GET

/idaas/platform/admin/v1/keystoreservice/certificates

DELETE Trusted Certificate KSS Keystore Method

DELETE

/idaas/platform/admin/v1/keystoreservice/certificates

POST Secret Key KSS Keystore

POST

/idaas/platform/admin/v1/keystoreservice/secretkey

GET Secret Key Properties KSS Keystore Method

GET

/idaas/platform/admin/v1/keystoreservice/secretkey

DELETE Keystore Service KSS Keystore Method

DELETE

/idaas/platform/admin/v1/keystoreservice


POST New KSS Keystore Method

Use the POST method to create a new Keystore Service (KSS) Keystore.

REST Request

POST /idaas/platform/admin/v1/keystoreservice

Request Body


Media Types:

application/json


The request body contains the details of the create request:


Attribute Description

"keystore"

Name for the KSS keystore.

"permission"

Boolean value that specifies whether to create a permission-based keystore.

"pwd"

Password for the KSS keystore.

"stripe"

Name of the stripe to contain the KSS keystore.


Response Body


Media Types:

application/json


The response body returns the status of the create operation, including:


Attribute Description

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".


cURL Example

The following example shows how to create a KSS keystore by submitting a POST request on the REST resource using cURL.

TESTED

curl -i -X POST -u username:password --data @createkss.json -H Content-Type:application/json http://myhost:7001/idaas/platform/admin/v1/keystoreservice

Example of Request Body

The following shows an example of the request body in JSON format.

{
    "stripe" : "myStripe",
    "keystore" : "myKeystore",
    "pwd" : "myPwd",
    "permission" : "false"
}

Note:

A password is required unless creating a permission-based keystore ("permission" : "true").

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 201 Created

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "STATUS": "Succeeded"
}

POST Import KSS Keystore Method

Use the POST method to import a Keystore Service (KSS) keystore from a JKS keystore file.

REST Request

POST /idaas/platform/admin/v1/keystoreservice/keystore

Request Body


Media Types:

multipart/form-data


The response body contains information about the import request, including:


Attribute Description

"keyAliases"

Comma-separated list of aliases for the keys to be imported from the keystoreFile.

"keyPasswords"

Comma-separated list of passwords for the keys to be imported from the keystoreFile.

"keystoreFile"

Name of a valid local JKS keystore file

"keystoreName"

Name for the JKS keystore.

"keystorePassword"

Password for the local keystore file that is being imported and the keystore entry, if password-protected.

"keystoreType"

Keystore type. This value must be set to JKS.

"permission"

Boolean value that specifies whether to import as a permission-based keystore.

"stripeName"

Name of the stripe.


Response Body


Media Types:

application/json


The response body contains information about the import operation, including:


Attribute Description

"alias n"

List of keystores in the stripe, where n serves as an index that starts at 1 and is incremented by 1 for each additional keystore.

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".


cURL Example

The following example shows how to import a KSS keystore by submitting a POST request on the REST resource using cURL.

TESTED

curl -i -X POST -u username:password -H Content-Type:multipart/form-data --form "stripeName=myStripe" --form "keystoreFile=@clientkeystore" --form "keystoreName=myKeystore" --form "keystorePassword=myPwd" --form "keystoreType=JKS" --form "keyAliases=client" --form "keyPasswords=myPwd2" --form "permission=false" http://myhost:7001/idaas/platform/admin/v1/keystoreservice/keystore

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 201 Created

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "STATUS":"Succeeded",
    "SUCCESS_MSG":"Aliases:client imported successfully",
    "alias 1":"client"
}

PUT Password Update KSS Keystore Method

Use the PUT method to update the password for a Keystore Service (KSS) keystore.

REST Request

PUT /idaas/platform/admin/v1/keystoreservice

Request Body


Media Types:

application/json


The response body contains information about the Load Balancer patches, including:


Attribute Description

"keystore"

Name of the KSS keystore.

"newpass"

New password for the keystore.

"oldpass"

Old password for the keystore.

"stripe"

Name of the stripe.


Response Body


Media Types:

application/json


The response body returns the status of the update operation, including:


Attribute Description

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".


cURL Example

The following example shows how to import a KSS keystore by submitting a PUT request on the REST resource using cURL.

TESTED

curl -i -X PUT -u username:password --data @updatekss.json -H Content-Type:application/json http://myhost:7001/idaas/platform/admin/v1/keystoreservice

Example of Request Body

The following shows an example of the request body in JSON format.

{
    "stripe" : "myStripe",
    "keystore" : "mykssstore",
    "oldpass" : "myPwd",
    "newpass" : "myNewPwd"
}

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "STATUS": "Succeeded"
}

POST Trusted Certificate KSS Keystore Method

Use the POST method to Import a trusted certificate into a Keystore Service (KSS) keystore.

REST Request

POST /idaas/platform/admin/v1/keystoreservice/certificates

Request Body


Media Types:

application/json


The response body contains information about the import request, including:


Attribute Description

"keyAlias"

Alias for the trusted certificate.

"keystoreEntry"

Base64-encoded certificate.

"keystoreEntryType"

Keystore entry type. Valid values include: Certificate, TrustedCertificate, or SecretKey.

"keystoreName"

Name of the KSS keystore.

"keystorePassword"

Password for the KSS keystore.

"stripeName"

Name of the stripe.


Response Body


Media Types:

application/json


The response body returns the status of the import operation, including:


Attribute Description

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".

"SUBJECT_DN"

Subject DN list that was imported.


cURL Example

The following example shows how to create a KSS keystore by submitting a POST request on the REST resource using cURL.

TESTED

curl -i -X POST -u username:password --data @importcertkss.json -H Content-Type:application/json http://myhost:7001/idaas/platform/admin/v1/keystoreservice/certificates

Example of Request Body

The following shows an example of the request body in JSON format.

{
    "keyAlias" : "myAlias",
    "keystoreEntry":
"MIIC7DCCAqqgAwIBAgIEalhBSjALBgcqhkjOOAQDBQAwSDEKMAgGA1UEBhMBeTEKMAgGA1UECBMB\neTEKMAgGA1UEBxMBeTEKMAgGA1UEChMBeTEKMAgGA1UECxMBeTEKMAgGA1UEAxMBeTAeFw0xNDA3\nMDMxMTAwMTZaFw0xNDEwMDExMTAwMTZaMEgxCjAIBgNVBAYTAXkxCjAIBgNVBAgTAXkxCjAIBgNV\nBAcTAXkxCjAIBgNVBAoTAXkxCjAIBgNVBAsTAXkxCjAIBgNVBAMTAXkwggG3MIIBLAYHKoZIzjgE\nATCCAR8CgYEA/X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY1Y+r/F9bow\n9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX/rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVU\nE1oWkTL2dfOuK2HXKu/yIgMZndFIAccCFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QKBgQD34aCF1ps9\n3su8q1w2uFe5eZSvu/o66oL5V0wLPQeCZ1FZV4661FlP5nEHEIGAtEkWcSPoTCgWE7fPCTKMyKbh\nPBZ6i1R8jSjgo64eK7OmdZFuo38L+iE1YvH7YnoBJDvMpPG+qFGQiaiD3+Fa5Z8GkotmXoB7VSVk\nAUw7/s9JKgOBhAACgYBrvzkjozmv6t6T0GNJES1R3ypRsBs8VLX2g3GotHd7Kht/TCj4HikelZDd\nuL0t96R5Q4A3srOgSIZ+0INRs1ER8y1Q37LyJNfyqYn5KqLBlN9bhSYAfcuIpjwIXGVfLQGdByD7\ntr4PSvZQx18K6p68HUCh+jXQT9+7n3ZUIBzH5aMhMB8wHQYDVR0OBBYEFPdMpcEBbYSCYMdJiE4r\ncQxf7Me4MAsGByqGSM44BAMFAAMvADAsAhQH/G1ixrEaWAG3lGWafkHgXxnzhwIUW5eSctgmaQBj\nvKaY0E6fYJzcp5c=",
    "keystoreEntryType" : "TrustedCertificate",
    "keystoreName" : "myKeystore",
    "stripeName" : "myStripe",
    "keystorePassword" : "myPwd"
}

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "STATUS": "Succeeded"
    "SUBJECT_DN": "CN=y,OU=y,O=y,L=y,ST=y,C=y"
}

GET Stripe KSS Keystores Method

Use the GET method to return all Keystore Service (KSS) keystores for a stripe.

REST Request

GET /idaas/platform/admin/v1/keystoreservice/{stripeName}

Parameters

The following table summarizes the GET request parameters.


Name Description Type

stripeName

Name of stripe for which you want to view all KSS keystores.

Path


Response Body


Media Types:

application/json


The response body contains information about the certificate, including:


Attribute Description

"keystore n"

List of keystores in the stripe, where n serves as an index that starts at 1 and is incremented by 1 for each additional keystore.


cURL Example

The following example shows how to view all certificates for an alias by submitting a GET request on the REST resource using cURL.

TESTED

curl -i -X GET -u username:password http://myhost:7001/idaas/platform/admin/v1/keystoreservice/myStripe

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "keystore 1":"trust",
    "keystore 2":"castore"
}

GET Alias KSS Keystore Method

Use the GET method to view the alias for the Keystore Service (KSS) keystore.

REST Request

GET /idaas/platform/admin/v1/keystoreservice/alias/{stripeName}/{keystoreName}/{entryType}

Parameters

The following table summarizes the GET request parameters.


Name Description Type

entryType

Keystore type. Valid values include Certificate, TrustedCertificate, or SecretKey.

Path

keystoreName

Name of the keystore.

Path

stripeName

Name of the stripe.

Path


Response Body


Media Types:

application/json


The response body contains information about the certificate, including:


Attribute Description

"keystore n"

List of keystore aliases in the stripe where n serves as an index that starts at 1 and is incremented by 1 for each additional property.


cURL Example

The following example shows how to view all certificates for an alias by submitting a GET request on the REST resource using cURL.

TESTED

curl -i -X GET -u username:password http://myhost:7001/idaas/platform/admin/v1/keystoreservice/alias/myStripe/myKeystore/TrustedCertificate

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
   "keystore 1":"myAlias",
}

GET Trusted Certificate KSS Keystore Method

Use the GET method to view trusted certificates in the Keystore Service (KSS) keystore. If the keystore is password-protected, you must provide a Base64-encoded header value for the keystore password.

REST Request

GET /idaas/platform/admin/v1/keystoreservice/certificates

Parameters

The following table summarizes the GET request parameters.


Name Description Type

keyAlias

Alias for trusted certificate.

Query

keystoreEntryType

Type of keystore entry. Valid values include Certificate, TrustedCertificate, or CertificateChain.

Query

keystoreName

Name of the keystore.

Query

stripeName

Name of the stripe.

Query


Response Body


Media Types:

application/json


The response body contains information about the certificate, including:


Attribute Description

"CONTENT"

Contents of the Base64-encoded certificate.

"Extensions"

Optional extensions that are used to issue a certificate for a specific purpose. Each extension includes the following:

  • Object identifier (oid) that uniquely identifies it

  • Flag indicating whether the extension is critical

  • Set of values

"ISSUER_DN"

List of trusted distinguished names.

"NOT_AFTER"

Date the certificate expires.

"NOT_BEFORE"

Date the certificate is activated.

"SERIAL_NO"

Serial number of the JKS keystore.

"SIGNATURE"

Base64-encoded signature key.

"SIGNING_ALGORITHM"

Signing algorithm for the alias.

"SUBJECT_DN"

Subject distinguished names list.


cURL Example

The following example shows how to view all certificates for an alias by submitting a GET request on the REST resource using cURL.

TESTED

curl -i -X GET -u username:password -H keystorePassword:cHdkMQ== http://myhost:7001/idaas/platform/admin/v1/keystoreservice/certificates?"stripeName=myStripe&keystoreName=myKeystore&keyAlias=client&keystoreEntryType=Certificate"

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "SUBJECT_DN":"CN=y,OU=y,O=y,L=y,ST=y,C=y",
    "ISSUER_DN":"CN=y,OU=y,O=y,L=y,ST=y,C=y",
    "NOT_BEFORE":"Fri Jul 25 02:45:11 PDT 2014",
    "NOT_AFTER":"Thu Oct 23 02:45:11 PDT 2014",
    "SERIAL_NO":"982191050",
    "SIGNING_ALGORITHM":"1.2.840.10040.4.3",
    "CONTENT":"-----BEGIN CERTIFICATE----- \nMIIC7DCCAqqgAwIBAgIEOosLyjALBgcqhkjOOAQDBQAwS
EKMAgGA1UEBhMBcjEKMAgGA1UECBMB\ncjEKMAgGA1UEBxMBcjEKMAgGA1UEChMBcjEKMAgGA1UECxM
cjEKMAgGA1UEAxMBUjAeFw0xNDA3\nMjUwOTQ1MTFaFw0xNDEwMjMwOTQ1MTFaMEgxCjAIBgNVBAYTA
IxCjAIBgNVBAgTAXIxCjAIBgNV\nBAcTAXIxCjAIBgNVBAoTAXIxCjAIBgNVBAsTAXIxCjAIBgNVBAM
AVIwggG3MIIBLAYHKoZIzjgE\nATCCAR8CgYEA\/X9TgR11EilS30qcLuzk5\/YRt1I870QAwx4\/gL
RJmlFXUAiUftZPY1Y+r\/F9bow\n9subVWzXgTuAHTRv8mZgt2uZUKWkn5\/oBHsQIsJPu6nX\/rfGG
/g7V+fGqKYVDwT7g\/bTxR7DAjVU\nE1oWkTL2dfOuK2HXKu\/yIgMZndFIAccCFQCXYFCPFSMLzLKS
YKi64QL8Fgc9QKBgQD34aCF1ps9\n3su8q1w2uFe5eZSvu\/o66oL5V0wLPQeCZ1FZV4661FlP5nEHE
GAtEkWcSPoTCgWE7fPCTKMyKbh\nPBZ6i1R8jSjgo64eK7OmdZFuo38L+iE1YvH7YnoBJDvMpPG+qFG
iaiD3+Fa5Z8GkotmXoB7VSVk\nAUw7\/s9JKgOBhAACgYAjhpZybXj6rlXDow8srnSFE9dZJJpCKaQV
ACagQogePV+xlqPClDOoiQJ\nuvuUGHerDrThC1\/Wq5Uj1+TnkSKTy0qYxmQoq56xALa47np9TKtqt
4Vy8eUUorakG4lrjNt\/EgR\nfO675n+qINkKXKpcxaCicupRCYPkPXlnT4mtyKMhMB8wHQYDVR0OBB
EFDKbmPa2Il6SylJRPTv8\nQ+4CqpEhMAsGByqGSM44BAMFAAMvADAsAhQbkmlaUG5QDR5mXUiYC74p
\/FBOwIUGx5lc5Y01ppo\nvK3UgL7M8E3eOfc=\n-----END CERTIFICATE-----",
    "SIGNATURE":FEZN2l4SPFEK5jt2QZRb5Q==",
    "Extensions":"{subjectKeyIDExtension {oid = 2.5.29.14 critical = false, value = 329b98f6b6225e92ca52513d3bfc43ee02aa9121}}"
}

DELETE Trusted Certificate KSS Keystore Method

Use the Delete method to delete a certificate from a Keystore Service (KSS) keystore. If the keystore is password-protected, you must provide Base64-encoded header values for the keystore and key passwords.

REST Request

DELETE /idaas/platform/admin/v1/keystoreservice/certificates

Parameters

The following table summarizes the DELETE request parameters.


Name Description Type

keyAlias

Alias for the certificate in the KSS keystore.

Query

keystoreName

Name of the keystore.

Query

stripeName

Name of stripe.

Query


Response Body


Media Types:

application/json


The response body returns the status of the import operation, including:


Attribute Description

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".


cURL Example

The following example shows how to delete a trusted certificate from the keystore by submitting a DELETE request on the REST resource using cURL.

TESTED

curl -i -X DELETE -u username:password -H keystorePassword:cHdkMQ== -H keyPassword:bXlQd2Qy  http://myhost:7001/idaas/platform/admin/v1/keystoreservice/certificates?"stripeName=myStripe&keystoreName=myKeystore&keyAlias=myAlias"

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "STATUS": "Succeeded"
}

POST Secret Key KSS Keystore

Use the POST method to create a secret key used in symmetric encryption/decryption for a KSS keystore.

REST Request

POST /idaas/platform/admin/v1/keystoreservice/secretkey

Request Body


Media Types:

application/json


The request body contains the details of the create request:


Attribute Description

"algorithm"

Controls the cryptographic characteristics of the algorithms that are used when securing messages.

"keyAlias"

Alias for the secret key.

"keyPassword"

Password for the secret key.

"keySize"

Size measured in bits of the of the key used in cryptographic algorithm.

"keystoreName"

Name for the KSS keystore.

"keystorePassword"

Password for the KSS keystore.

"stripeName"

Name of the stripe.


Response Body


Media Types:

application/json


The response body returns the status of the import operation, including:


Attribute Description

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".


cURL Example

The following example shows how to create a secret key by submitting a POST request on the REST resource using cURL.

TESTED

curl -i -X POST -u username:password --data @secretkey.json -H Content-Type:application/json http://myhost:7001/idaas/platform/admin/v1/keystoreservice/secretkey

Example of Request Body

The following shows an example of the request body in JSON format.

{
    "stripeName" : "myStripe",
    "keystoreName" : "myKeystore",
    "keyAlias" : "myKeyAlias",
    "keySize" : "56",
    "algorithm" : "DES",
    "keystorePassword" : "myPwd",
    "keyPassword" : "myKeyPwd"
}

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "STATUS": "Succeeded"
}

GET Secret Key Properties KSS Keystore Method

Use the GET method to view the secret key properties for a KSS keystore. If the keystore is password-protected, you must provide Base64-encoded header values for the keystore and key passwords.

REST Request

GET /idaas/platform/admin/v1/keystoreservice/secretkey

Parameters

The following table summarizes the GET request parameters.


Name Description Type

keyAlias

Alias of the secret key.

Query

keystoreName

Name of the keystore.

Query

stripeName

Name of the stripe.

Query


Response Body


Media Types:

application/json


The response body contains information about the certificate, including:


Attribute Description

"Property n"

List of secret key properties, where n serves as an index that starts at 1 and is incremented by 1 for each additional property.


cURL Example

The following example shows how to view all certificates for an alias by submitting a GET request on the REST resource using cURL.

TESTED

curl -i -X GET -u username:password -H keystorePassword:bXlQd2Q= -H keyPassword:bXlLZXlQd2Q= http://myhost:7001/idaas/platform/admin/v1/keystoreservice/secretkey?"stripeName=myStripe&keystoreName=myKeystore&keyAlias=myKeyAlias"

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 200 OK

Example of Response Body

The following shows an example of the response body in JSON format.

{
   "Property 1":"DES"
}

DELETE Keystore Service KSS Keystore Method

Use the Delete method to delete a Keystore Service (KSS) keystore. If the keystore is password-protected, you must provide Base64-encoded header values for the keystore password.

REST Request

DELETE /idaas/platform/admin/v1/keystoreservice

Parameters

The following table summarizes the DELETE request parameters.


Name Description Type

keystoreName

Name of the keystore.

Query

stripeName

Name of the stripe.

Query


Response Body


Media Types:

application/json


The response body returns the status of the delete operation, including:


Attribute Description

"ERROR_CODE"

If "STATUS" is set to "Failed", provides the error code.

"ERROR_MSG"

If "STATUS" is set to "Failed", provides the contents of the error message.

"STATUS"

Status of operation. For example, "Succeeded" or "Failed".


cURL Example

The following example shows how to delete a trusted certificate from the keystore by submitting a DELETE request on the REST resource using cURL.

TESTED

curl -i -X DELETE -u username:password -H keystorePassword:bXlQd2Q= http://myhost:7001/idaas/platform/admin/v1/keystoreservice?"stripeName=myStripe&keystoreName=myKeystore"

Example of Response Header

The following shows an example of the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods

HTTP/1.1 204 No Content