Mastercard pkcs11-tools

pkcs11-tools is a toolkit of small utilities designed for key management tasks on cryptographic tokens that implement a PKCS#11 interface. It provides a CLI experience similar to Unix utilities (like ls, mv, rm) but specialized for cryptographic operations.

Key capabilities include:

• Key Generation & Management: Generate keys (including Post-Quantum Cryptography), CSRs (PKCS#10), and self-signed certificates.
• Import/Export: Import certificates, public keys, and data files.
• Wrapping/Unwrapping: Support for symmetric and asymmetric key wrapping/unwrapping, including session key generation and direct wrapping.
• Advanced Operations: Key rewrapping (unwrap as session key then rewrap), token initialization, and reset.
• Compatibility: Works with software tokens like SoftHSM, NSS, and Kryoptic, as well as hardware tokens like YubiHSM and AWS CloudHSM.
• Algorithm Support: DES, 3DES, AES, HMAC, RSA, DSA, DH, NIST curves, Edwards curves, and Post-Quantum Cryptography (ML-KEM, ML-DSA, SLH-DSA).

The pkcs11-tools toolkit is a collection of command-line utilities for managing cryptographic objects on PKCS#11 tokens (HSMs, smart cards, or software keystores like SoftHSM2 or NSS).

Key commands include:

• p11ls: List token contents by object class.
• p11keygen: Generate keys or key pairs (with optional wrapping).
• p11importcert: Import PEM/DER certificates and bind them to private keys via CKA_ID.
• p11importpubk: Import public keys (adjusts CKA_ID per IBM JCA rules).
• p11importdata: Import arbitrary files as data objects.
• p11wrap / p11unwrap: Export/Import keys using the pkcs11-wrap(5) format.
• p11rm: Delete objects or classes of objects.
• p11setattr: Change object attributes.
• p11cat: Print certificates or public keys in PEM format.
• p11more: Display decoded, human-readable certificate/key content.
• p11od: Object dumper (prints all attributes in hex).
• p11req: Generate PKCS#10 CSRs.
• p11kcv: Compute Key Check Values (KCV) for symmetric keys.
• p11init: Initialize or reset a token/PIN.
• p11slotinfo: Print slot/token info and supported mechanisms.
• p11mv: Rename token objects.
• p11mkcert: Generate self-signed certificates for Java JCA.
• masqreq: Adjust subject DN/extensions of an existing CSR.

The with_xxx scripts are POSIX shell wrappers that simplify running pkcs11-tools commands against specific PKCS#11 vendor libraries. Instead of manually locating library paths and setting environment variables, you can use the appropriate wrapper for your hardware or software token.

Each wrapper automatically:

1. Locates the vendor PKCS#11 library via auto-detection.
2. Sources configuration from .pkcs11rc or .pkcs11rc.<vendor>.
3. Sets necessary environment variables like PKCS11LIB.
4. Executes the requested pkcs11-tools command.

Available Wrappers:

• with_aws: AWS CloudHSM
• with_beid: Belgian national eID
• with_kryoptic: Kryoptic software token
• with_luna: Thales/Gemalto SafeNet Luna HSM
• with_nfast: Entrust (nCipher) nShield HSM
• with_nss: Mozilla NSS soft token (defaults to Slot 1)
• with_softhsm: OpenDNSSEC SoftHSM v2
• with_utimaco: Utimaco SecurityServer HSM
• with_yubico: Yubico YubiHSM 2

with_softhsm p11ls
with_luna p11keygen -k rsa -b 2048 -i my-rsa-key sign verify

The pkcs11-wrap file format is a text-based, self-describing container for a PKCS#11-wrapped key. It is used to transport keys between different PKCS#11 tokens.

Key Characteristics

• Producers: Created by p11wrap and p11keygen (using the -W parameter).
• Consumers: Consumed by p11unwrap and p11rewrap.
• Format: A POSIX text file where lines are terminated by newlines, blank lines are ignored, and lines starting with # are comments. The lexer is case-insensitive for header keywords and algorithm names.
• Structure: A file typically consists of:
  1. Header lines: Describe file type, grammar version, wrapping key, algorithm, and PKCS#11 attributes.
  2. PEM-style base64 blocks: Carry the encrypted key material.
  3. Optional Public Key: An embedded PEM block used in envelope wrapping.

Alternative Format: JWK

When p11wrap or p11keygen is invoked with the -J flag, the output is in JWK (JSON Web Key, RFC 7517) format. Note that the JWK format does not support envelope wrapping.

Beyond standard command-line options, p11keygen allows you to set specific PKCS#11 attributes (prefixed with CKA_ or bare) using positional ATTRIBUTE=VALUE arguments. This is useful for fine-grained control over key usage (e.g., signing, encryption, or sensitivity).

Supported Value Syntax:

• Boolean: true, false, yes, no, on, off, or bare name (for true), or prefix with ! or no (for false).
• String: Double-quoted ASCII, e.g., "mykey".
• Hex: Even-digit hex prefixed with 0x, e.g., 0xdeadbeef.
• Date: YYYYMMDD format.
• Mechanism: PKCS#11 mechanism names starting with CKM_.
• Templates: Attribute arrays in { }, e.g., { encrypt decrypt sensitive !extractable }.

# Example: Generate an AES key that is specifically marked as non-extractable and can be used for encryption/decryption
p11keygen -i "my-aes-key" -k aes CKA_EXTRACTABLE=false CKA_ENCRYPT=true CKA_DECRYPT=true