PKCS#11 Engine Patch (including the token access) for OpenSSL 0.9.8l (el)
By janp on Nov 19, 2009
I have generated a PKCS#11 patch for OpenSSL 0.9.8l. It includes one new feature I have recently integrated into Nevada - RSA Keys by Reference. You can read the README here, and download the PKCS#11 patch.
As a test I've built the code on Solaris 10 and one Linux distro (which identified itself as GNU/Linux, I have no idea which distro was that). I had to make a couple of modifications since other systems do not have getpassphrase() function, and Linux distros have no strlcpy() function (because GNU C library has none). Hopefully I have not broken anything.
If you plan to use the patch, do not forget to check out examples and the PKCS#11 URI format in the presentation for the project. As usual, if you find problems with the patch, let me know please. And of course, if you find it really useful, you can say that as well :-)
The man page will be updated soon but before that gets to a public build it will take some time. So, below is the current draft change for the openssl(5) man page. Note that the man page in section 5 is for OpenSSL in Solaris, the one in section 1 is the original man page from the OpenSSL project. Obviously, we ship both. Use "man -s 5 openssl" to see the Sun's one, or "man -a" if unsure about sections.
openssl(5) planned addition:
Accessing RSA Keys in PKCS#11 Keystores OpenSSL can access RSA keys in PKCS#11 keystores using the following functions of the ENGINE API: EVP_PKEY \*ENGINE_load_private_key(ENGINE \*e, const char \*key_id, UI_METHOD \*ui_method, void \*callback_data) EVP_PKEY \*ENGINE_load_public_key(ENGINE \*e, const char \*key_id, UI_METHOD \*ui_method, void \*callback_data) key_id, formerly for filenames only, can be now also set to a PKCS#11 URI. The EVP_PKEY structure is newly allocated and caller is responsible to free the structure later. To avoid clashes with existing filenames, "file://" prefix for filenames is now also accepted but only when the PKCS#11 engine is in use. The PKCS#11 URI specification follows: pkcs11:[token=<label>][;manuf=<label>][;serial=<label>] [;model=<label>][;object=<label>] [;objecttype=(public|private|cert)] [;passphrasedialog=(builtin|exec:<file>)] The ordering of keywords is not significant. The PKCS#11 engine uses the keystore for the slot chosen for public key operations whic is metaslot on a standardly configured machine. Currently, the PKCS#11 engine ignores "objecttype" keyword. The only mandatory keyword is "object" which is the key object label. For information on how to use a different, possibly hardware, keystore with metaslot see libpkcs11(3LIB). The token PIN is provided via "passphrasedialog" keyword and is either read from the terminal ("builtin") or from the output of an external command ("exec:<file>"). The PIN is used to log into the token and by default is deleted from the memory then. The keyword "pin" is intentionally not provided due to inherent security problems of possible use of a password in the process arguments. Due to fork safety issues the application must re-login if the child continues to use the PKCS#11 engine. It is done inside of the engine automatically if fork is detected and in that case, "exec:<file>" option of the "passphrasedialog" keyword can be used. Alternatively, an enviroment variable OPENSSL_PKCS11_PIN_CACHING_POLICY can be used to allow the PIN to be cached in memory and reused in the child. It can be set to "none" which is the default, "memory" to store the PIN in memory, and "mlocked-memory" keep the PIN in a locked page via mlock(3C). Note that PRIV_PROC_LOCK_MEMORY privilege is required in that case. Sensitive parts of private keys are never read from the token to the process memory no matter whether the key is tagged with sensitive flag or not. The PKCS#11 engine uses the public compoments as a search key to get a PKCS#11 object handle to the private key. Note that in order to use the RSA keys by reference, high level API functions must be used, like RSA_public_decrypt(), EVP_PKEY_set1_RSA(), or EVP_SignInit(). Low level functions might go around the engine and thus fail to make use of the feature. Additional Documentation Extensive additional documentation for OpenSSL modules is available in the /usr/share/man/man1openssl, /usr/share/man/man3openssl, /usr/share/man/man5openssl, and /usr/share/man/man7openssl directories. To view the license terms, attribution, and copyright for OpenSSL, see /var/sadm/pkg/SUNWopensslr/install/copyright. EXAMPLES Example 1: generate and print a public key stored in an already initilized PKCS#11 keystore. Note the use of "-engine pkcs11" and "-inform e". $ pktool gencert keystore=pkcs11 label=mykey \\ subject="CN=test" keytype=rsa keylen=1024 serial=01 $ openssl rsa -in \\ "pkcs11:object=mykey;passphrasedialog=builtin" \\ -pubout -text -engine pkcs11 -inform e