Contribute in GitHub:

Managing your keys with the key management API

UKO provides a RESTful API for key management. Every action that can be taken via the Web UI can also be invoked with the RESTful API. Additionally, to facilitate key management for volume encryption using zkey, UKO supports export of AES CIPHER keys under some tightly controlled conditions.

Interact with the API using the API explorer

IBM WebSphere Liberty Server provides a built-in API explorer for documentation of the API, but also to try it out. To use the API explorer, perform the following steps:

Select the API menu item and click on the "Read more" link. The API explorer will open in a new window.
Click on the Authorize button in the top right corner.
Specify your client_id. This value has been specified during configuration as EKMF_OAUTH_CLIENT_ID.
Define your scope by setting check marks for every function that you want to authorize.
Click on the Authorize button.
Click on an operation you authorized for, which will be indicated by a closed lock symbol next to the operation name.
Click on the Try it out button. You will now be able to specify your request parameters.
Click Execute to send your request. The response will be shown in the Server response section of the operation.

Interact with the API using the command line

Using OAuth token

One way to use the API is to provide an OAuth bearer token, for example by using a cURL command similar to the following example, which saves the token in a variable called BearerToken (we use the jq command line tool to extract the token from the response, you can use whatever tool you're comfortable with).

Obtaining the OAuth token using passcode

BearerToken=$(curl \
  --request POST "https://ekmfweb.example.com/api/v2/system/login" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  -d '{"userId":"samantha","passcode":"xtNvxqUqQgWnUwUc"}' | jq -r '.authorizationToken')

The userID is the one you use to log on to UKO with. It is case sensitive. To get a passcode, click on API in the menu bar and copy the generated code.

Obtaining the OAuth token using client ID and client secret

BearerToken="Bearer $(curl \
  --request POST 'https://ekmfweb.example.com/oidc/endpoint/EkmfOpenIdConnect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'client_id=client_id_used_in_server.env' \
  --data-urlencode 'client_secret=client_secret_used_in_server.env' \
  --data-urlencode 'username=samantha' \
  --data-urlencode 'password=samanthaspassword' \
  --data-urlencode 'scope=openid profile email' | jq -r .authorization_token)"

You can now perform operations by presenting the bearer token as part of your request, like in the following example, which will return all your keys:

curl \
  --request GET "https://ekmfweb.example.com/api/v2/keys" \
  --header "Accept: application/json" \
  --header "Authorization: ${BearerToken}"

Using mTLS

By far the most secure way to communicate with UKO is through the use of mTLS. Assuming that:

you have correctly set up and exported keys on UKO side (via RACF or similar tool), and
you have a file named ekmf-web-client.p12

If your curl supports PKCS#12

You can use the PKCS#12 file directly in the call to curl to e.g. get a list of keys:

curl \
  --cert-type P12 \
  --cert ekmf-web-client.p12:password-to-pkcs#12 \
  --request GET 'https://ekmfweb.example.com/api/v2/keys' \
  --header 'ekmf-mtls: true' \
  --header 'Accept: application/json'

or to create a key using an existing key template named 'EXAMPLE':

curl \
  --cert-type P12 \
  --cert ekmf-web-client.p12:password-to-pkcs#12 \
  --request POST 'https://ekmfweb.example.com/api/v2/keys' \
  --header 'ekmf-mtls: true' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
 -d '{ "templateName": "EXAMPLE", "labelTags": [ { "name": "APP", "value": "DEMO" }, { "name": "ENV", "value": "TEST" } ] }'

If your curl does not support PKCS#12

First, you need to export the certificate and private key from the PKCS#12 file:

openssl pkcs12 -in ekmf-web-client.p12 -out ekmf-web-client.key -nocerts -nodes
openssl pkcs12 -in ekmf-web-client.p12 -out ekmf-web-client.cer -clcerts -nokeys

Then you can refer to those files in the call to curl to e.g. get a list of keys:

curl \
  --cert ekmf-web-client.cer \
  --key ekmf-web-client.key \
  --request GET 'https://ekmfweb.example.com/api/v2/keys' \
  --header 'ekmf-mtls: true' \
  --header 'Accept: application/json'

or to create a key using an existing key template named 'EXAMPLE':

curl \
  --cert ekmf-web-client.cer \
  --key ekmf-web-client.key \
  --request POST 'https://ekmfweb.example.com/api/v2/keys' \
  --header 'ekmf-mtls: true' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
 -d '{ "templateName": "EXAMPLE", "labelTags": [ { "name": "APP", "value": "DEMO" }, { "name": "ENV", "value": "TEST" } ] }'