Programming with openCryptoki

How it works

Shortly spoken, an openCryptoki application must specify, which token(s) it uses. Then it can invoke C_...() functions of openCryptoki. Where required, input to these functions is an appropriate CKM_ mechanism that must be offered by the selected token. The mechanism defines how to perform the using function. For example, the CKM_RSA_PKCS mechanism defines to functions C_EncryptInit() and C_Encrypt() to encrypt clear text with a (previously generated) private RSA key.

Each mechanism is coded in such a way that it exploits one or more adequate APIs from the connected cryptographic library specified with the token definition in the opencryptoki.conf file.

Terminology

openCryptoki application programs deal with the following main items:

• Functions: Prefix C_
• Data types or general constants: Prefix CK_
• Attributes: Prefix CKA_
• Mechanisms: Prefix CKM_
• Return codes: Prefix CKR_

Handling RSA decrypt operation errors

There are attacks on RSA operations for which the timing of a computation may deliver a hint for well- or malformed input and thus, whether an attack may have a chance to be successful. RSA operations that may be the target of such attacks are for example, wrong RSA-OAEP padding or malformed RSA PKCS#1 v1.5 input messages. Starting with version 3.21, openCryptoki itself cares for hiding the computation times, however, PKCS #11 applications that might be subject to RSA timing attacks (for example, a SSL/TLS software stack) must make sure to handle certain RSA decryption errors in a constant-time manner itself.

openCryptoki can only make internal differences in computation times transparent, but can not influence the code in the cryptographic coprocessors, in the respective host libraries, nor in the calling applications. Therefore, it is the PKCS #11 application’s responsibility to further handle such an error situation in a constant-time manner to not be vulnerable to timing attacks. That is, the PKCS #11 application should not expose a timing difference when an RSA decryption operation fails (for example. due to wrong padding), compared to a successful operation.

For example, to mitigate the Bleichenbacher attack on SSL/TLS RSA key exchange, the application should return a random pre-computed RSA secret, if the RSA decryption using PKCS#1 v1.5 padding fails due to padding errors. The random secret must be generated in any case, prior to performing the decrypt operation.

To protect PKCS #11 applications using the ICA token and the Soft token from attacks against RSA operations, RSA message blinding is applied to messages on all operations using the RSA private key (decryption and signature creation).