Skip to main content
This section covers two examples that invoke Futurex APIs to request an X.509 certificate and associated key pair that is issued as a PKCS #12 file. Then, the KMES Series 3 automatically offloads the passphrase generated for decrypting the PKCS #12 file to Vault. The first example runs the RAUP Excrypt command while connected to the System/Host API port on the KMES by using OpenSSL. The second example sends a POST request to the KMES RESTful API by using the Postman application.

​
Set up the KMES Series 3

Before attempting either of the examples, you must set up the KMES Series 3. See the KMES Series 3 user guide for additional information about completing the following required setup steps:
1
Go to Identity Management> Roles and select [ Add ].
2
Create a Signing Approval role, set Logins Required to 1, and enable all permissions under Certificate Authority, Keys, and Cryptographic operations. Select [ OK ] to finish creating the role.
3
Go to Identity Management> Identities and select [ Add ].
4
Under Assigned Roles, select the Signing Approval role you just created. Under Authentication, set a password for the identity. Select [ OK ] to finish creating the identity.
5
Go to PKI> Signing Workflow and select [ Add ]. Set a name for the signing approval group and select [ OK ]*.
6
Create a CA tree, ensuring that you select the PMK as the major key for all certificates created in this CA Tree.
7
Add an Issuance Policy to the leaf certificate in the CA tree.In the X.509 tab of the Issuance Policy window, ensure that you select all of the permission checkboxes and that you select the signing approval group you created in step 5.
8
Give the created Signing Approval Role the Use permissions on all of the following:
  • The Signing Approval Group created in step 5.
  • The entire CA tree created in step 6.
  • The Cloud Credential that is being used in the Vault API Options menu.

​
Example: RAUP Excrypt command

The following example demonstrates the RAUP command:
1
Ensure that the RAUP command is enabled in the Host API Options menu.
2
Run the following command to connect to the System/Host API port on the KMES by using Slope:
Shell
openssl s_client -connect 10.0.8.28:2001 -cert signed-client-cert.pem -key private-key.pem -CApath . -CAfile chain.pem
You must configure the System/Host API connection pair on the KMES Series 3 so that this OpenSSL connection works. Instructions for setting this up are outside the scope of this guide. See the KMES Series 3 user guide for more information.
3
After you connect successfully, run the RKLO Excrypt command twice to log in with the default Admin users, as shown in the following example:
Shell
[AORKLO;DAAdmin1;CHsafest;]
[AORKLO;ANY;UL1;UT2;RL1;]

[AORKLO;DAAdmin2;CHsafest;]
[AORKLO;ANY;UL2;UT2;RL0;]
4
Run the RAUP command to upload a new X.509 PKI request, as shown in the following example:
Shell
[AORAUP;CADemo CA;RTDemo Sub Cert;NATestUpload;HASHA256;GNDemo Approval Group;ENExample TLS Certificate;SN{2.5.4.3,12,436F6D6D6F6E4E616D6548657265},{1.3.3.7,19,30313233};KTRSA 2048;MP1;]
[AORAUP;ANY;AP1;ID34E2CCE30BC2F336;PW567E463B516F3120246C265446366A585D63636A794342215F344B7D43266F765D454C3B5741307068614F657A487A2234692E51754B5C46342477282856253C;]
If the command shown in the preceding example succeeds, a new X.509 PKI, issued as a PKCS #12 file, generates on the KMES Series 3, and the passphrase for the PKCS #12 file is stored in Vault.
5
Log in to the Vault UI and go to the secret/ folder.
6
Select the created secret.
The Key is passphrase, and the Value is the passphrase for the PKCS #12 file you generated on the KMES Series 3.

​
Example: POST Request to the KMES RESTful API by using Postman

Before trying this example, you must perform the following configurations on the KMES Series 3.

​
Configure a JWT Identity Provider

Perform the following steps to configure a JWT Identity Provider and authentication mechanism:
1
Go to Identity Management> Identity Providers.
2
Right-click and select Add> Provider> JSON Web Token.
3
On the Info tab, specify a name for the provider.
4
On the JWT Options tab, set the issuer as futurex.
5
On the JWT Key tab, select HMAC Key and enter safest123.
6
Select [ OK ] when finished.
7
Right-click the Identity Provider you just created and select Add> Mechanism> JSON Web Token. On the Info tab, specify a name for the mechanism, then select [ OK ] to save.
8
Go to Identity Management> Identities and locate the Signing Approval identity created for the previous example. Right-click it and select Edit.
9
Go to the Authentication tab and select [ Add ]. In the Type drop-down menu, select JSON Web Token and select [ OK ] to return to the Identity editor. Then select [ OK ] to save.
10
Go to Identity Management> Identity Providers. Right-click the Identity Provider you created and select Permission. Give your Signing Approval role the Use permissions and select [ OK ]*.

​
Send a POST Request to the KMES RESTful API by using Postman

To perform the following steps, you must install the Postman application on your local computer. The same concepts apply if you use cURL rather than Postman. However, to use cURL, you must generate the JWT token elsewhere (for example, a website such as https://jwt.io/). With Postman, you can generate a JWT token on the fly when you send the POST request.
Perform the following steps to send a POST Request to the KMES RESTful API by using Postman:
1
Start the Postman application, and select [ New ] on the top-left side of the page.
2
Select Collection.
3
Set any name for the collection, go to the Variable tab, and set jwt_token in the Variable field. Select [ Create ]. You don’t need to set anything else in this window.
4
Right-click the three dots in the new collection and select [ Add Request ].
5
Set any name for the request. The most important part is that the request is associated with the newly created Collection. Save the request.
6
Expand the Collection Folder and select the request that you just created. Set the request URL to https://10.0.5.125:8081/kmes/v6/certificates/signing-requests and change the request type to POST in the drop-down menu.
7
Go to the Authorization tab, set the TYPE to Bearer Token, and set the Token value to {{jwt_token}}.
8
Go to the Body tab, select the Raw bullet, and paste the following JSON code:
JSON
{
"pkiTree": "Demo CA",
"signingCert": "Demo Sub Cert",
"requestName": "Test Request",
"requestType": "PKI",
"hashType": "SHA-256",
"approvalGroup": "Demo Approval Group",
"pkiOptions": {
"extensionProfile": "TLS Certificate",
"keyType": "RSA 2048",
"randomPassphrase": true,
"subject": [
{
"id": "2.5.4.3",
"asn1Type": 12,
"data": "436F6D6D6F6E4E616D6548657265"
}
],
"certExpiration": "2024-11-1 00:00:00"
}
}
In the request body, you specify that you want the KMES Series 3 to create a new X.509 PKI. You define the CA tree that you built on the KMES, along with several other parameters. One of the most important parameters to notice is the randomPassphrase value set to true. The randomPassphrase parameter ensures that the PKI request is issued as PKCS #12. Then, the passphrase for the PKCS #12 file is stored in Vault.
9
Go to the Pre-Request Script tab and paste the following JavaScript:
Javascript
let hmac_key = "safest123";
let header = {
    "alg": "HS256",
    "typ": "JWT"
};
let payload = {
    "iss": pm.globals.get('jwt_issuer'),
    "sub": pm.globals.get("jwt_user"),
    "iat": Math.floor(Date.now() / 1000)
};
function base64url(source) {
    encodedSource = CryptoJS.enc.Base64.stringify(source).replace
        (/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
    return encodedSource;
}
let b64_header = base64url(CryptoJS.enc.Utf8.parse(JSON.stringify
    (header)));
let b64_data = base64url(CryptoJS.enc.Utf8.parse(JSON.stringify
    (payload)));
let message = b64_header + "." + b64_data;
let b64_signature = base64url(CryptoJS.HmacSHA256(message,
    hmac_key));
jwt_token = [b64_header, b64_data, b64_signature].join('.');
pm.collectionVariables.set("jwt_token", jwt_token);
The preceding code generates the JWT Token used to authenticate to the KMES, on-the-fly.
10
After pasting in the JavaScript, select the settings icon in the upper-right corner of the page and select Globals.
11
Add a new variable, jwt_issuer, and enter futurex for both the Initial Value and Current Value.
12
Add a new variable, jwt_user. Set the Current Value to the username of the Signing Approval Identity you created. Select [ Save ].
13
Select [ Save ] on your request and select [ Send ].
If the request is successful, the response body contains the message: Successfully created new entry.
When you log back into the Vault UI and go to Secret Engines > Secret, you see a new entry with ID values after CommonName that matches the requested value in the response body in Postman. This confirms that the KMES Series 3 sent the PKCS #12 passphrase successfully to Vault for storage.

​
Enable the rekey feature

You can apply a renewal threshold in Registration Authority Options. When you request an existing key name, one of the following events occurs:
  • If the key is under the expiration threshold when you request the key, the system returns a new key and certificate.
  • If the key is over the expiration threshold when you request the key, the system returns the same key and certificate.
To apply the renewal threshold, perform the following steps:
1
Go to Administration> Configuration> Registration Authority Options.
2
In Registration Authority Options, locate Renewal Threshold.
3
For the Renewal Threshold option, set a number and use the drop-down list to select Days, Weeks, Months, or years, depending on your needs (for example, 90 days).In this example, a key request with the same name that is over the 90-day threshold returns the same key and certificate. A key request with the same name that is under the 90-day threshold returns a new key and certificate.
4
Select [ Save ] to finish applying your changes.
To use the Rekey feature, add the renewalCheck: true line to the JSON request, as shown in the following example:
JSON
POST renewal check
https://{{url}}/{{v6}}/certificates/signing-requests

{
  "pkiTree": "Registration Authority",
  "signingCert": "RASigner",
  "requestName": "renew1",
  "requestType": "PKI",
  "hashType": "SHA-256",
  "approvalGroup": "ra-group",
  "renewalCheck": true,
  "pkiOptions": {
    "extensionProfile": "Example TLS Client Certificate",
    "keyType": "RSA 2048",
    "randomPassphrase": true,
    "exportPkcs12": true,
    "subject": [
      {
        "id": "2.5.4.3",
        "asn1Type": 12,
        "data": "72656e657731"
      }
    ],
    "certExpiration": "2030-01-01 00:00:00"
  }
}