Skip to main content

PKCS12 Import Export

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

If you have a bundle and are interested in importing it into your HSM partition, or exporting an existing bundle, skip to:

Generating PKCS#12 Components​

If you do not already have a pkcs12 bundle available, here are some commands to create the components for one directly on your HSM partition.

Generate Key Pair​

First we need to generate the key pair. The process of achieving this is described in detail on our How to Create a Key?

Generate 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 it directly on the HSM. Similarly to the key pair, we provide detailed instructions on our Self-Signed Certificate page.

Now that you have your Key pair and Certificate created on the HSM, you can Export via Rest-API, knowing that all components of the bundle are generated and stored securely on the HSM.

PKCS#12 Export via Rest-API​

info

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

To export your PKCS#12 bundle, update the values of label (e.g. p12-bundle), password, pkcs12ContainerPassword and chose type to be PKCS12 and execute the following request:

GET: /v1/key/export/plain

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

Setting the type to PKCS12 instructs the TSB to create the bundle. The TSB then reads the label and password to discover the components needed for the bundle. pkcs12ContainerPassword refers to the password needed to open the bundle in the future.Because of this, it is crucial to provide the correct details.

From the output of the above, take the full value of pkcs12container and save it to a file:

"pkcs12container": "MIIKSgIBAzCCCfQGCSqGSIb3DQEHAaCCCe...

Convert the base64 file into 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 via Rest-API​

info

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

SKA-Policy
  • if the policy is not defined in the request below will import an SKA-Key (Smart Key Attributes, e.g. you cannot export it later on but perform multi-authrozation, the policy defined will be empty meaning, always fullfillable).
  • if the policy is null, the key will be a normal key

More information on Smart Key Attributes.

If you are interested in importing a P12 bundle, this implies that some or all of the components of it were not generated on the HSM (e.g. a CA signed certificate). Whether you created your keys and certificates with OpenSSL or another solution, you have to first convert the files into a .p12 or .pfx format.

openssl pkcs12 -export -in ca.crt -inkey ca.key -out securosys-p12-cert.p12 -name my-key-alias -passout pass:12345678
Parameters
ParameterDescription
-in-in infile (Input file)
-inkeyPrivate key, else read from -in input file
-outOutput file
-nameUse name as friendly name
-passoutOutput file pass phrase source (this parameter sets the KeyPassword and PKCS#12 container password)
-passwordSet PKCS#12 import/export password source
passphrase

For the purpose of this tutorial, we use a simple passphrase 12345678, but you should use a secure passphrase.

Then the new file needs to be base64 encoded so that it can be imported into the TSB via Rest-API:

  • 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'))"
note

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

POST: /v1/importPlainKey

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

{
    "label": "p12-bundle",
    "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
}
note

You must update the default values of these 2 attributes, to be "extractable": true and "sensitive": false, as show in the example above, to be able to export the P12 bundle.

Now your PKCS#12 bundle is uploaded and stored on the HSM. You can remove any local copies of it and in the future download it again by following the PKCS#12 Export via Rest-API instructions.

Last updated on