POLICY.CONF(5)

💖 policy.conf(5) — openCryptoki 💖

okay bestie, sit down, hydrate, and let me tell you about policy.conf(5) — the openCryptoki config file that decides what your crypto is allowed to do. it's giving bouncer-at-the-club energy and honestly? iconic.

---

✨ NAME ✨

policy.conf — the configuration file for openCryptoki policies. yes that's the whole name, short and slay.

---

🌸 DESCRIPTION 🌸

openCryptoki reads a policy configuration file living at:

/etc/opencryptoki/policy.conf

what does it do? it restricts openCryptoki's operations down to a specific set of allowed operations. basically it lets users lock things down: restrict keys to a minimal cryptographic strength, and restrict supported elliptic curves, mechanisms, MGFs, KDFs, or PRFs. gatekeeping, but make it cryptographic 💅

---

🎀 SYNTAX 🎀

the file starts with a version specification of the form version policy-0, and then comes the policy constraints. order matters, bestie, we don't freestyle this.

a policy constraint assigns a value to a configuration key. and the syntax depends on the value of the key — so let's go one by one:

💪 strength

this key defines the minimal required strength for keys, and digest and signature sizes. it corresponds to the definition in /etc/opencryptoki/strength.conf. valid values are 0, 112, 128, 192, and 256. the special value 0 allows every key and arbitrary size of digests and signatures (chaos mode, lowkey). the format is a simple assignment:

strength = number

if other values are used, they are rounded up to the next supported value. and values greater than 256 are rounded down to 256. no cap, the rounding is doing its own thing.

🔧 allowedmechs

this key specifies a list of mechanisms that are allowed by this policy. the list should contain a comma-separated list of CKM_ constants supported by openCryptoki. the list goes inside brackets:

allowedmechs ( mech1, mech2 )

Note: this key is optional. if it's not present, all mechanisms are allowed. but if you provide an empty list, then no mechanism would be allowed. (empty list = zero, not "all", don't get got.)

🦋 allowedcurves

this key specifies a list of allowed elliptic curves. keys that do not belong to any of the allowed curves cannot be created or used. the list has the same format as the allowedmechs key:

allowedcurves ( curve1, curve2 )

valid curve names are:

• BRAINPOOL_P160R1
• BRAINPOOL_P160T1
• BRAINPOOL_P192R1
• BRAINPOOL_P192T1
• BRAINPOOL_P224R1
• BRAINPOOL_P224T1
• BRAINPOOL_P256R1
• BRAINPOOL_P256T1
• BRAINPOOL_P320R1
• BRAINPOOL_P320T1
• BRAINPOOL_P384R1
• BRAINPOOL_P384T1
• BRAINPOOL_P512R1
• BRAINPOOL_P512T1
• PRIME192V1
• SECP224R1
• PRIME256V1
• SECP384R1
• SECP521R1
• SECP256K1
• CURVE25519
• CURVE448
• ED25519
• ED448

Note: this key is optional. if not present, all curves are allowed. an empty list allows no curve. ⚠️

🌈 allowedmgfs

this key specifies the allowed Message Generation Functions (MGFs) for use in RSA OAEP and RSA PSS. the value is a list of CKG_ constants supported by openCryptoki. same format as allowedmechs:

allowedmgfs ( mgf1, mgf2 )

Note: optional again, bestie. if not present, all MGFs are allowed. an empty list allows no MGF.

🧚 allowedkdfs

this key specifies the allowed Key Derivation Functions (KDFs) for use in ECDH key derivation and Kyber KEM. the value is a list of CKD_ constants supported by openCryptoki. and yes, same format as allowedmechs:

allowedkdfs ( kdf1, kdf2 )

Note: optional, you know the drill. if not present, all KDFs are allowed. an empty list allows no KDF.

💜 allowedprfs

this key specifies the allowed Pseudo-Random Functions (PRFs) for use in PKCS #5 PBKDF. the value is a list of PRFs. currently, the only supported value is CKP_PKCS5_PBKD2_HMAC_SHA256 CKP_PKCS5_PBKD2_HMAC_SHA512, which leads to the list:

allowedprfs ( CKP_PKCS5_PBKD2_HMAC_SHA512,
CKP_PKCS5_PBKD2_HMAC_SHA256 )

Note: optional, as always. if not present, all PRFs are allowed. an empty list allows no PRF.

---

📌 NOTES 📌

okay here's the part where you actually pay attention, because the vibes get serious.

the policy configuration file has to be owned by root:pkcs11 and have mode 0640. otherwise, openCryptoki will return CKR_FUNCTION_FAILED on C_Initialize and log the reason into syslog. so set those perms, bestie, it's not optional.

the pound sign ('#') is used to indicate a comment. both the comment character and any text after it, up to the end of the line, are ignored. the comment character can be used at the beginning of a line (including before the file version specification), after the strength value, after a comma, and before and after the bracket. flexible queen 💅

since the policy indirectly refers to a strength configuration, a strength configuration has to exist and be valid. if no strength configuration exists, no policy will be enforced. and if an existing policy configuration is invalid, openCryptoki cannot be used. periodt.

---

🔐 token store tea 🔐

openCryptoki uses some cryptographic operations to store token objects. these operations have to be allowed by the policy. which operations are needed depends on the token store format and the token (since the ICSF Token as a remote token uses different crypto operations to store its management data):

• FIPS compliant format — token stores in the FIPS compliant format need the mechanisms CKM_AES_KEY_GEN, CKM_AES_KEY_WRAP, CKM_AES_GCM, CKM_PKCS5_PBKD2, the PRF CKP_PKCS5_PBKD2_HMAC_SHA512, and must allow 256 bit AES keys.
• legacy format — token stores in legacy format need the mechanisms CKM_DES3_KEY_GEN, CKM_DES3_CBC, CKM_AES_KEY_GEN, CKM_AES_CBC, CKM_SHA1, CKM_MD5 and must allow 2-key TDES keys (80 bit symmetric keys with 64 bit signatures).
• ICSF Token store — CKM_AES_KEY_GEN, CKM_AES_CBC, CKM_SHA1, CKM_MD5 CKM_PKCS5_PBKD2, the PRF CKP_PKCS5_PBKD2_HMAC_SHA256, and must allow 256 bit AES keys.

tokens cannot be loaded if their token store format is not supported by the policy. if a token cannot be loaded, a message is printed into syslog detailing the policy violation. to fix this problem, make sure the token format is allowed by your policy (either by satisfying above constraints or by temporarily removing /etc/opencryptoki/policy.conf) and migrate your token store, e.g., to the FIPS-compliant format. you got this 🫶

---

👀 SEE ALSO 👀

• strength.conf(5)
• opencryptoki(7)
• pkcstok_migrate(1)
• /usr/share/doc/opencryptoki/policy-example.conf

---

and that's the whole page, bestie! this was openCryptoki 3.27.0, dated September 2021 — main character documentation energy, no cap. go forth and configure responsibly 💖✨