OPENSSL-PKCS11.CONF(5) ====================== :doctype: manpage :man version: @PACKAGE_VERSION@ NAME ---- openssl-pkcs11.conf - PKCS#11 configuration file for openssl keys DESCRIPTION ----------- The PKCS#11 exporter module is a library which exports the PKCS#11 API but is driven by a static file loading openssl keys. Its design is to allow for easy exporting of TPM2 engine keys, but it can be used to export absolutely any openssl key at all. The primary use case is for toolkits (like mozilla nss or gnutls) where PKCS#11 is understood but engine plug ins are not. The PKCS#11 exporter obtains its configuration information from the following sources . The file named by the environment variable *OPENSSL_PKCS11_CONF* . The Home Directory relative file ~/.config/openssl-pkcs11/openssl-pkcs11.conf The module is activated by specifying the *openssl-pkcs11.so* module as input to any PKCS#11 supporting code. The library behaves like it supports an array of tokens, each in an individual slot and responds to the usual token search directives. Provided the *openssl-pkcs11.so* module is installed in the correct directory, the tokens can also be used by any p11-kit supporting system, including gnutls and openssl with the libp11 engine using the standard PKCS#11 URI. The current implementation supports RSA and Elliptic curve public and private keys and also X.509 certificates in place of the public key. FILE FORMAT ----------- The file uses standard ini file format: sections headed by *[
]* Comprising lists of * = * directives. The first section is the optional *[global]* section which supplies defaults for every other section. The remaining sections name individual tokens. The layout is one openssl key per token. [global] section ~~~~~~~~~~~~~~~~ This specifies the elements that are specific to the library. *manufacturer id*:: This specifies the default library manufacturer for all of the tokens, can be retrieved by *C_GetInfo*. if not set defaults to "@PACKAGE_NAME@". *library description*:: The specific library description for *C_GetInfo*. *model*:: Sets the model returned by *C_GetTokenInfo*. If not set defaults to the package version number (@PACKAGE_VERSION@) [] section ~~~~~~~~~~~~~~~~~ There can be many of these, one per token supported by the library. Each token may have one and only one key (This simplifies the PKCS#11 export, but is explicitly not a requirement of PKCS#11 itself). The section name ** is used for the *label* attribute of *C_GetTokenInfo*. *id*:: Sets the *CKA_ID* attribute of the token. Defaults to key type if not set. *label*:: Sets the *CKA_LABEL* attribute of the token. Defaults to the token section name if not set. This is the object of the PKCS#11 URI. *public key*:: Specifies the absolute file name of the openssl public key. Is required if *certificate* is not provided. *private key*:: Specifies the openssl file name of the private key. This is required. The private key _must_ be password protected and the password must conform to PKCS#11 standards (it will be used to *C_Login* to the token), so at least 4 characters and no longer than 32 characters. *engine*:: Optional engine specification. If this is specified, ENGINE_load_private_key will be used to retrieve the private key. This may thus be used to export operations for private keys which are embedded in openssl engines. *certificate*:: Specifies an X.509 public certificate which will be supplied by the token. Substitutes for *public key*. *manufacturer id*:: Sets the *manufacturerID* attribute of *C_GetTokenInfo*. If not set defaults to the global section value of *manufacturer id*. *serial*:: Sets the *serial* attribute of *C_GetTokenInfo*. If not set it defaults to the hex string of the first 10 digits of the sha256 hash of the public key. *slot description*:: Sets the *slotDescription* attribute of *C_GetSlotInfo*. Defaults to the token section name if not set. *model*:: Sets the *model* attribute of *C_GetSlotInfo*. Defaults to the global section setting if not set in the token section. EXAMPLES -------- These examples are based on a simple configuration file manufacturer id = Test library description = Lib model = Mod [rsa] private key = /tmp/rsa.priv public key = /tmp/rsa.pub [ec] private key = /tmp/ec.priv certificate = /tmp/ec.crt Leads to this output for *p11-kit list-modules* is openssl-pkcs11-export: openssl-pkcs11-export.so library-description: Lib library-manufacturer: Test library-version: 0.6 token: rsa manufacturer: Test model: Mod serial-number: 3c2b025769622d71 flags: login-required user-pin-initialized token-initialized token: ec manufacturer: Test model: Mod serial-number: db63309be2413143 flags: login-required user-pin-initialized token-initialized and the output of *p11tool --list-token-urls* is pkcs11:model=Mod;manufacturer=Test;serial=3c2b025769622d71;token=rsa pkcs11:model=Mod;manufacturer=Test;serial=db63309be2413143;token=ec to create a self signed certificate using openssl and the libp11 engine (also demonstrating PKCS#11 URIs can be shortened provided they still uniquely specify the key): openssl req -new -x509 -subj '/CN=Test/' -engine pkcs11 \ -keyform engine -out tmp.crt \ -key pkcs11:model=Mod;manufacturer=Test;token=rsa Using TPM2 keys with gnutls ~~~~~~~~~~~~~~~~~~~~~~~~~~~ To use a TPM2 key with gnutls via a PKCS#11 URI, first create the key (this example creates the key local to the tpm using the P-256 NIST curve): create_tpm2_key --auth --ecc prime256v1 /tmp/tpm.key This key can be used for both the public and private parts in the token stanza (to use this, the engine must allow public key load *without* a password, otherwise you need to create a separate public key file), so the config file should contain [tpm] public key = /tmp/tmp.key private key = /tmp/tpm.key engine = tpm2 Now to use this TPM2 resident key to create a self signed certificate using the gnutls certtool, simply do certtool -s --load-privkey 'pkcs11:token=tpm;object=tpm;type=private' Note that due to the vagaries of gnutls, the specifiers object=_label_ and type=private are both required. FILES ----- The default location of the configuration file is ~/.config/openssl-pkcs11/openssl-pkcs11.conf Although this can be changed by setting the *OPENSSL_PKCS11_CONF* environment variable. The p11-kit location for the PKCS#11 module should be @pkcs11_dir@/openssl-pkcs11-export.so AUTHOR ------ James E.J. Bottomley REPORTING BUGS -------------- Report bugs to @PACKAGE_BUGREPORT@