PKCS11SIGN(7)

💖 PKCS11SIGN — the pkcs11sign era 💖

okay bestie, sit down, hydrate, because we're talking about pkcs11sign, aka the OpenSSL PKCS#11 sign provider module — section 7 of your misc info manual, and honestly? she's iconic.

---

✨ NAME ✨

pkcs11sign — the OpenSSL PKCS#11 sign provider module, periodt. 💅

---

🌸 DESCRIPTION 🌸

So pkcs11-sign-provider implements the OpenSSL 3.0 provider interface and does cryptographic operations on asymmetric key material that lives in PKCS#11 infrastructure (think opencryptoki and friends, iykyk). She registers a key storage for PKCS#11 URIs (RFC 7512), and every key you reference with a PKCS#11 URI gets handled by pkcs11-sign-provider. Any other keys — like file-based ones, no shade — get forwarded by pkcs11-sign-provider to another OpenSSL-Provider, e.g. the built-in OpenSSL default provider. She's a team player fr fr. 🫶

pkcs11-sign-provider will only process algorithms where there's an existing (private) asymmetric key in the related PKCS11-token. Every other action gets handled by the forward-provider as clear-key operations. She knows her lane and she stays in it. 👑

Also, lowkey important: pkcs11-sign-provider does not support key creation or removal of PKCS#11 keys. For key management you need external tools. Not her job, not her problem. 💀

Supported PKCS#11 mechanisms for RSA:

• CKM_RSA_PKCS
• CKM_RSA_PKCS_OAEP
• CKM_RSA_PSS
• CKM_RSA_X_509

Supported PKCS#11 mechanisms for EC:

• CKM_ECDSA

---

🦋 APPLICATION INTERFACE 🦋

An application that wants to use asymmetric keys in PKCS#11 infrastructure must use an OpenSSL configuration for the pkcs11-sign-provider and refer to the keys by a PKCS#11 URI. That's it. The rest of the application should not need any changes — no glow-up required, she already ate. ✨

🎀 Configuration 🎀

If the system-wide OpenSSL configuration doesn't configure the pkcs11-sign-provider, your application can bring its own OpenSSL configuration file and point at it in its environment variable OPENSSL_CONF. For more details about the configuration, go peek at pkcs11sign.cnf(5). 📖

🍓 Key references 🍓

Instead of referring to a private key file (e.g. "file:/path/to/key.pem"), the application should use the PKCS#11 URI of the key: "pkcs11:<path-attributes>?<queue-attributes>".

The PKCS#11 URI should specify path parameters of the key — at least the ID or label of the key, plus its type. And bestie, the key reference should be unique. No duplicates, that's messy. 🙈

Example for a PKCS#11 URI to a private key:

pkcs11:token=mytok;object=ec-key;type=private&pin-source=/path/to/token-pinfile.txt

Note — The current version of pkcs11-sign-provider supports only the queue parameters pin-value and pin-source. All other queue parameters are not yet supported. Don't come for her, she's growing. 🌱

💜 PIN handling 💜

The PIN is required to login to a PKCS#11 token, to manage or work with sensitive PKCS#11 objects (keys) and should not be proposed to anyone without a need-to-know. Gatekeeping the PIN is valid actually. 🔐

An application that's using key material in a PKCS#11 token has such a need-to-know, so the PIN should be under control of the application.

The pkcs11-sign-provider supports PIN handling in the PKCS#11 URI with the queue attributes pin-value and pin-source. While the first one contains the plain-text PIN, the latter one refers to a file that contains the PIN. It is highly recommended to use the file reference and set the access permissions of the PIN file accordingly. Do it. For you. 🫶

🧚 PIN file 🧚

The PIN gives access to a PKCS#11 token and its objects (keys, certificates, data). It should be treated as secret information and only the application should have access to it. With the right setup, the usage of a PIN file provides the best protection for the PIN. ✨

Rules for the PIN file:

• one PIN per PIN file
• the PIN file must only contain the PIN, no comments, no linefeed or other characters
• the PIN file must be readable by the application
• the PIN file should not be writable by the application
• the PIN file must not be readable nor writable by other unprivileged users.

The following snippet shows how to create a protected PIN file. It will prompt for the PIN and write it to a file, which is only accessible for the user:

PINFILE="/path/to/my_pinfile.txt"
touch "${PINFILE}"
chmod u=rw,g=,o= "${PINFILE}"
(read -rsp "Enter PIN: " PIN; echo -n ${PIN}) > "${PINFILE}"

If required, the file ownership can later be changed to another user and group. This would require extra capabilities (e.g. by using "sudo"). Main character energy, but make it permissions. 👑

---

🌈 SEE ALSO 🌈

pkcs11sign.cnf(5), EVP(7)

---

⭐ Copyright ⭐

Copyright © International Business Machines Corp. 2022, 2023

---

and that's the whole vibe check, bestie 💖 this was pkcs11sign, from the PKCS11SIGN(7) manual — dated 2024-05-14 — mwah, go protect your PIN file, slay, bye! 🎀🦋💅