Data Encryption, Key Agreement, and Key Transport

201 The RSA algorithm does not require parameters to generate keys, which makes key generation a much simpler affair. OpenSSL provides a single function to create a new RSA key pair, which will create a new RSA object that is initialized with a fresh key pair. RSA RSA_generate_keyint num, unsigned long e, void callbackint, int, void , void cb_arg; num Specifies the number of bits in the public modulus. The minimum this should be to ensure proper security is 1,024 bits, though we recommend 2,048 bits. e The value to use for the public exponent. OpenSSL does not attempt to generate this value randomly, but instead requires you to specify it. You may specify any number you like, but we recommend that you use one of the two constants, RSA_3 or RSA_F4 . callback A pointer to a function that will be called during the prime generation process to report the status of the prime generation. The callback is the same as the callback used by BN_generate_prime , which we discussed in Chapter 4 . This argument may be specified as NULL if no callbacks are desired. cb_arg A pointer to application-specific data. OpenSSL does not use this value for anything itself. It is used only when passed as an argument to the specified callback function. Once keys are generated, it is a good idea to call RSA_check_key to verify that the keys generated by RSA_generate_key are actually usable. The function requires an RSA object as its only argument. The RSA object should be completely filled in, including values for its p , q , n , e , and d members. If the return value from the function is 0, it indicates that there is a problem with the keys, and that they should be regenerated. If the return value from the function is 1, it indicates that all tests passed, and that the keys are suitable for use. If the return value from the function is - 1, an error occurred in performing the tests. When the RSA key is no longer needed, it should be freed by calling RSA_free and passing the RSA object as its only argument.

8.4.3 Data Encryption, Key Agreement, and Key Transport

Now that weve explored key setup, we can look at the different methods of using those keys. The RSA algorithm allows for secrecy because it can encrypt data. Data encrypted with a public key can be decrypted only by an entity possessing the corresponding private key. Before looking at the specifics of these operations, we must first discuss blinding . Any RSA operation involving a private key is susceptible to timing attacks. Given an RSA operation as a black box that we feed data into and collect results from, an attacker can discern information about our key material by measuring the amount of time it takes the various operations to complete. Blinding is essentially a change in the implementation that removes any correlation between the amount of time taken for an operation and the private key value. 202 The function RSA_blinding_on enables blinding for the RSA object passed into it as the first argument. This means that any operation on the RSA object involving the private key will be guarded from timing attacks. The second argument is an optional BN_CTX object, which may be specified as NULL . Likewise, the function RSA_blinding_off disables blinding for the RSA object passed into it. If you ever design a system that allows arbitrary operations on a private key, such as any system that automatically signs data, enabling blinding is important for the safety of the private key. With RSA, it is most common to perform encryption with a public key and decryption with the corresponding private key. The functions RSA_public_encrypt and RSA_private_decrypt provide the means to perform these operations. It is also possible to perform encryption with a private key and decryption with the corresponding public key. Two functions, RSA_private_encrypt and RSA_public_decrypt , are provided by OpenSSL. Theyre intended for those who wish to implement signing at a very low level. In general, they should be avoided. Each of the four functions returns the number of bytes, including padding, that were encrypted or decrypted, or -1 if an error occurs. int RSA_public_encryptint flen, unsigned char from, unsigned char to, RSA rsa, int padding; flen Specifies the number of bytes in the buffer to be encrypted. from A buffer containing the data to be encrypted. to A buffer that will be used to hold the encrypted data. It should be large enough to hold the largest possible amount of encrypted data, which can be determined by calling RSA_size and passing the RSA object that is being used to encrypt as its only argument. rsa The RSA object that contains the public key to use to perform the encryption. padding Specifies which of the built-in padding types supported by OpenSSL should be used when padding is necessary. int RSA_private_decryptint flen, unsigned char from, unsigned char to, RSA rsa, int padding; flen Specifies the number of bytes of data in the buffer to be decrypted. from A buffer containing the data to be decrypted. to 203 A buffer that will be used to hold the decrypted data. It should be large enough to hold the largest possible amount of decrypted data, which can be determined by calling RSA_size and passing the RSA object that is being used to decrypt as its only argument. rsa The RSA object that contains the private key to use to perform the decryption. padding Specifies which of the built-in padding types supported by OpenSSL was used when the data was encrypted. The padding for decryption must be the same as the padding used for encryption. The encryption performed by RSA requires that the data to be encrypted be appropriately formed. If the data to be encrypted does not fit the requirements, it must be padded. OpenSSL supports several types of padding for RSA encryption: RSA_PKCS1_PADDING If this type of padding is used, the length of the data to be encrypted must be smaller than RSA_sizersa-11 . This is an older method of padding that has since been replaced by RSA_PKCS1_OAEP_PADDING . It should be used only for compatibility with older applications. RSA_PKCS1_OAEP_PADDING If this type of padding is used, the length of the data to be encrypted must be smaller than RSA_sizersa-41 . This type of padding is the recommended method for all new applications. RSA_SSLV23_PADDING This type of padding is an SSL-specific modification to the RSA_PKCS1_PADDING type. Under normal circumstances, this type of padding is rarely used. RSA_NO_PADDING This disables automatic padding by the encryption function, and assumes that the caller will perform the padding. It requires that the data to be encrypted is exactly RSA_sizersa bytes.

8.4.4 Signing and Verifying