Skip to main content

PKI Module

Tested with HC Vault version: 1.2.8

PKI Module is modified to support hcvault-plugin-secrets-engine to generate keys on HSM and sign certificates using these keys. All original PKI Module functionality are supported.

note

To use keys to creating issuer etc., always use keyId/key as a reference!

Requirements​

info

PKI Module needs at last one configured hcvault-plugin-secrets-engine on Hashicorp Vault.

Keep in mind that this modification uses only the first configured hcvault-plugin-secrets-engine.

In the Rest-API commands below, substitute localhost:8200 with your respective HC instance details.

Additional Commands​

There are serval ways to work with the module:

  • Generate a new key and store it on the HSM - with this endpoint the key will be generated or registered as a reference to an existing key on the HSM
  • Import cert and key to Vault PKI and store key on HSM - this scenario is used when a user wants to import own certificate and private key to PKI.
  • Import key to HC Vault PKI and store it on HSM - this scenario is used when a user wants to import own private key to PKI.
note

All keys are stored as reference to existing keys on HSM

Generate new key and store it on HSM​

This endpoint will generate key on HSM only when string sending in parameter managed_key_name are not exists as a key label on TSB. If the PKI module finds that the key name managed_key_name on TSB exists, then the PKI module will store only the reference to this key.

POST http://127.0.0.1:8200/v1/pki/keys/generate/securosys-hsm

    {
      "key_name":"key_name_in_pki",
      "key_type":"rsa",
      "key_bits":"4096",
      "managed_key_name":"key_name_on_hsm"
    }

Where:

  • key_type - can be rsa, ec or ed25519
  • key_bits - can be 2048, 3072 or 4096 for rsa key and 254, 256, 384 or 521 for ec key.
info

key_bits will be ignored for ed25519 key

Example response:

{
    "request_id": "08cc4c8b-bfa6-4175-f2ac-11c264dd8ac6",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "key_id": "eb2b44a3-d3c4-caf7-31c9-d91e292467bd",
        "key_name": "key_name_in_pki",
        "key_type": ""
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}
info

key_id parameter is important to make this key work on Hashicorp Vault PKI Module UI.

Import cert and key to Vault PKI and store key on HSM​

This endpoint provide option to import own certificate and private key to PKI Module.

note

Key will be imported to HSM and stored in PKI Module as reference.

POST http://127.0.0.1:8200/v1/pki/issuers/import/securosys-hsm

    {
      "pem_bundle":"-----BEGIN PRIVATE KEY-----\n PRIVATE KEY \n-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----\n PRIVATE KEY \n-----END CERTIFICATE-----\n"
    }

Where pem_bundle needs to be combined private key and certificate bundle.

Example response:

{
    "request_id": "d8de0e3f-8d09-7f57-ce60-8056b7668b18",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "existing_issuers": null,
        "existing_keys": null,
        "imported_issuers": [
            "0be3e384-d114-b775-d7a9-4fb928ecc5b0"
        ],
        "imported_keys": [
            "8ccf569a-474d-1e94-8540-26ae96228e88"
        ],
        "mapping": {
            "0be3e384-d114-b775-d7a9-4fb928ecc5b0": "8ccf569a-474d-1e94-8540-26ae96228e88"
        }
    },
    "wrap_info": null,
    "warnings": [],
    "auth": null
}
info

key_id parameter is important to make this key work on Hashicorp Vault PKI Module UI.

Import key to HC Vault PKI and store it on HSM​

This endpoint provide option to import own private key to PKI Module.

note

Key will be imported to HSM and stored in PKI Module as reference.

POST http://127.0.0.1:8200/v1/pki/keys/import/securosys-hsm

    {
      "key_name":"key_name_in_pki",
      "managed_key_name":"key_name_on_hsm",
      "pem_bundle":"-----BEGIN PRIVATE KEY-----\n PRIVATE KEY \n-----END PRIVATE KEY-----\n"
    }

Where pem_bundle needs to be private key

note

managed_key_name needs to be unique!.

Example response:

{
    "request_id": "37384e65-1b00-23eb-2104-343bfd1d5a24",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "key_id": "98995760-438d-cfc6-4ead-a38df12e9b7e",
        "key_name": "key_name_in_pki",
        "key_type": ""
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}
info

Reference in imported_keys array parameter is important to make this key work on Hashicorp Vault PKI Module UI.

Export private key in PKCS#11 Provider URI format PEM​

This endpoint provide option to export private key in PKCS#11 Provider URI format.

GET http://127.0.0.1:8200/v1/pki/key/{key_reference}/export?pkcs11Token={pkcs11_token}

Where:

  • key_reference - can be key_reference or key_name from PKI Module
  • pkcs11_token - it has to be pkcs11_token - YOUR_HSM_USERNAME

Example response:

{
    "request_id": "385973f0-1ba2-d89a-2efe-57c34da3b966",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "key_id": "private_key_reference",
        "key_name": "private_key_name",
        "privateKeyReferencePem": "-----BEGIN PKCS#11 PROVIDER URI-----\n{PKCS#11_PRIVATE_KEY}\n-----END PKCS#11 PROVIDER URI-----",
        "subject_key_id": "26:1a:4d:e5:cb:73:e2:3b:d9:93:ed:0e:a2:5f:68:43:85:a4:ea:b9"
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Export private key in PKCS#11 Provider URI format PEM and certificate​

This endpoint provide option to export private key in PKCS#11 Provider URI format along with certificate.

GET http://127.0.0.1:8200/v1/pki/issuer/{issuer_reference}/export?pkcs11Token={pkcs11_token}

Where:

  • issuer_reference - it has to be issuer reference
  • pkcs11_token - it has to be pkcs11_token - YOUR_HSM_USERNAME

Example response:

{
    "request_id": "57eea29b-8190-93fc-29a8-58cc208fa7ec",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "ca_chain": [
            "-----BEGIN CERTIFICATE-----\n{CA_CERTIFICATE}\n-----END CERTIFICATE-----\n"
        ],
        "certificate": "-----BEGIN CERTIFICATE-----\n{CERTIFICATE}\n-----END CERTIFICATE-----\n",
        "crl_distribution_points": [],
        "issuer_id": "issuer_reference",
        "issuer_name": "issuer_name",
        "issuing_certificates": [],
        "key_id": "private_key_reference",
        "leaf_not_after_behavior": "err",
        "manual_chain": null,
        "ocsp_servers": [],
        "privateKeyReferencePem": "-----BEGIN PKCS#11 PROVIDER URI-----\n{PKCS#11_PRIVATE_KEY}\n-----END PKCS#11 PROVIDER URI-----",
        "revocation_signature_algorithm": "",
        "revoked": false,
        "usage": "issuing-certificates,ocsp-signing,read-only"
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}
Last updated on