PKCS#12 Import/Export

In this tutorial you will learn how to easily create, import, export and manage PKCS#12 bundles. This page includes command examples for the most common use cases.

What is a PKCS#12 Bundle?

A PKCS#12 bundle is an archive file format for cryptographic material. It usually contains a public-private key pair together with a corresponding certificate (though it can store more complex data structures). Optionally, the bundle can be protected (symmetrically encrypted) with a password. This makes it a convenient format for transferring or archiving cryptographic material. The most common file extensions are .p12 and .pfx.

Prerequisites

To be able to export a PKCS#12 bundle, you first need a key pair and a corresponding certificate stored on the HSM. These objects should all have the same label.

info

There are restrictions on whether a key can be exported. In particular, you should set extractable=true and sensitive=false when generating or importing a key that you want to export later.

Step 1: Generate a Key Pair

First, we need to generate a key pair. Follow the steps in the Creating a Key guide. Make sure to set the key attributes as described above!

Step 2: Generate a Certificate

Next, we need to create a certificate. If you have a CA signed certificate already, you can continue to the next section. If you do not have a certificate, you can generate a self-signed certificate directly on the HSM.

Now that you have your key pair and certificate created on the HSM, you can export them as a PKCS#12 bundle.

PKCS#12 Export

info

REST API: v2.4.0 and higher
Supported Algorithms: EC & RSA (not yet ML-DSA)

To export your PKCS#12 bundle, set the values of label, password, pkcs12ContainerPassword according to your choice. Set the type to be PKCS12. Then execute the request:

GET: /v1/key/export/plain

{
  "label": "p12-bundle",
  "password": "12345678",
  "type": "PKCS12",
  "pkcs12ContainerPassword": "87654321"
}

Field	Explanation
label	The label of the key you want to export.
password	Optional. Set if the key is password-protected.
type	The export format. Set to PKCS12.
pkcs12ContainerPassword	The password with which the resulting PKCS#12 bundle should be protected.

The response looks like this:

{ "pkcs12container": "MIIKSgIBAzCCCfQGCSqGSIb3DQEHAaCCCe..." }

Take the value of pkcs12container, base64-decode it, and save the result to a .p12 or .pfx file:

base64 -d securosys-p12-cert.p12.b64 > securosys-p12-cert.p12

You can now view the full content of the bundle by running this OpenSSL command:

openssl pkcs12 -in ./securosys-p12-cert.p12 -info -nodes -passin pass:87654321

PKCS#12 Import

info

REST API: v2.4.0 and higher
Supported Algorithms: EC & RSA (not yet ML-DSA)

This section shows how to import a PKCS#12 bundle. This allows you to import keying material that was not generated on the HSM.

Step 1: Create a PKCS#12 Bundle

Let's assume that you have a key pair in a ca.key file and a certificate in a ca.crt file. You can use OpenSSL to create a PKCS#12 bundle from them:

openssl pkcs12 -export -in ca.crt -inkey ca.key -out securosys-p12-cert.p12 -name my-key-alias -passout pass:12345678

Parameters

Parameter	Description
-in	-in infile (Input file)
-inkey	Private key, else read from -in input file
-out	Output file
-name	Use name as friendly name
-passout	Output file pass phrase source (this parameter sets the KeyPassword and PKCS#12 container password)
-password	Set PKCS#12 import/export password source

Step 2: Base64-Encode the Bundle

PKCS#12 bundles are binary files. To be able to pass it to the Primus REST API, the file needs to be Base64-encoded. Encode the file:

• Unix: base64 securosys-p12-cert.p12 -w 0
  
• Windows (cmd): certutil -encode securosys-p12-cert.p12 cert.b64
  
• Windows (PowerShell): powershell -Command "[Convert]::ToBase64String([IO.File]::ReadAllBytes('securosys-p12-cert.p12'))"

The above command will output the content in clear text -w 0 (without newlines!) on your terminal. We will need this output as the value for of pkcs12 in our API requests below.

Step 3: Import the Bundle

POST: /v1/importPlainKey

To import the PKCS#12 bundle, update the values of label, pkcs12, pkcs12KeyName, pkcs12KeyPassword, pkcs12KeystorePassword and execute the request with the following body:

{
    "label": "my-pkcs12-imported-key",
    "pkcs12": "MIIQuAIBAzCCEG4GCSqGSIb3DQEHAaCCEF8EghBbMIIQVzCCBhoGCSqGSIb3DQEHBqCCBgswgg...",
    "pkcs12KeyName": "my-key-alias",
    "pkcs12KeyPassword": "12345678",
    "pkcs12KeystorePassword": "12345678",
    "attributes": {
        "encrypt": null,
        "decrypt": true,
        "verify": null,
        "sign": true,
        "wrap": null,
        "unwrap": true,
        "derive": true,
        "bip32": false,
        "slip10": false,
        "extractable": true,
        "modifiable": true,
        "destroyable": true,
        "sensitive": false,
        "copyable": false
    },
    "policy": null
}

Now the key pair and the certificate from your PKCS#12 bundle are uploaded and stored on the HSM.

You may now remove any local copies of the PKCS#12 bundle. If needed, and allowed by the key attributes you set, you can export the bundle again from the HSM in the future.

warning

If you want to export the key again, make sure that you understand the restrictions that apply. In particular:

• You must set the "extractable": true and "sensitive": false attributes.
• If policy is explicitly set to null, the key will be imported as a normal key. If policy is not defined, the key will be a non-exportable SKA key with an empty, always fulfillable policy! Therefore, it is recommended to either have a null policy or a fully defined one.