Hardware-accelerated cryptography. Platforms should only only implement this when there are hardware-accelerated hardware-accelerated cryptography facilities. Applications must fall back to platform-independent CPU-based algorithms if the cipher algorithm isn't supported in hardware.
You should implement cipher algorithms in this descending order of priority to maximize usage for SSL.
GCM - The preferred block cipher mode for OpenSSL, mainly due to speed.
CTR - This can be used internally with GCM, as long as the CTR implementation only uses the last 4 bytes of the IV for the counter. (i.e. 96-bit IV, 32-bit counter)
ECB - This can be used (with a null IV) with any of the other cipher block modes to accelerate the core AES algorithm if none of the streaming modes can be accelerated.
CBC - GCM is always preferred if the server and client both support it. If not, they will generally negotiate down to AES-CBC. If this happens, and CBC is supported by SbCryptography, then it will be accelerated appropriately. But, most servers should support GCM, so it is not likely to come up much, which is why it is the lowest priority.
Further reading on block cipher modes:
https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
https://crypto.stackexchange.com/questions/10775/practical-disadvantages-of-gcm-mode-encryption
String literal for the AES symmetric block cipher. https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
Well-defined value for an invalid transformer.
The method of chaining encrypted blocks in a sequence. https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
kSbCryptographyBlockCipherModeCbc
Cipher Block Chaining mode.
kSbCryptographyBlockCipherModeCfb
Cipher Feedback mode.
kSbCryptographyBlockCipherModeCtr
Counter mode: A nonce is combined with an increasing counter.
kSbCryptographyBlockCipherModeEcb
Electronic Code Book mode: No chaining.
kSbCryptographyBlockCipherModeOfb
Output Feedback mode.
kSbCryptographyBlockCipherModeGcm
Galois/Counter Mode.
The direction of a cryptographic transformation.
kSbCryptographyDirectionEncode
Cryptographic transformations that encode/encrypt data into a target format.
kSbCryptographyDirectionDecode
Cryptographic transformations that decode/decrypt data into its original form.
A handle to a cryptographic transformer.
typedef SbCryptographyTransformerPrivate* SbCryptographyTransformer
Creates an SbCryptographyTransformer with the given initialization data. It can then be used to transform a series of data blocks. Returns kSbCryptographyInvalidTransformer if the algorithm isn't supported, or if the parameters are not compatible with the algorithm.
An SbCryptographyTransformer contains all state to start decrypting a sequence of cipher blocks according to the cipher block mode. It is not thread-safe, but implementations must allow different SbCryptographyTransformer instances to operate on different threads.
All parameters must not be assumed to live longer than the call to this function. They must be copied by the implementation to be retained.
This function determines success mainly based on whether the combination of algorithm, direction, block_size_bits, and mode is supported and whether all the sizes passed in are sufficient for the selected parameters. In particular, this function cannot verify that the key and IV used were correct for the ciphertext, were it to be used in the decode direction. The caller must make that verification.
For example, to decrypt AES-128-CTR: SbCryptographyCreateTransformer(kSbCryptographyAlgorithmAes, 128, kSbCryptographyDirectionDecode, kSbCryptographyBlockCipherModeCtr, ...);
algorithm: A string that represents the cipher algorithm. block_size_bits: The block size variant of the algorithm to use, in bits. direction: The direction in which to transform the data. mode: The block cipher mode to use. initialization_vector: The Initialization Vector (IV) to use. May be NULL for block cipher modes that don‘t use it, or don’t set it at init time. initialization_vector_size: The size, in bytes, of the IV. key: The key to use for this transformation. key_size: The size, in bytes, of the key.
SbCryptographyTransformer SbCryptographyCreateTransformer(const char *algorithm, int block_size_bits, SbCryptographyDirection direction, SbCryptographyBlockCipherMode mode, const void *initialization_vector, int initialization_vector_size, const void *key, int key_size)
Destroys the given transformer instance.
void SbCryptographyDestroyTransformer(SbCryptographyTransformer transformer)
Calculates the authenticator tag for a transformer and places up to out_tag_size bytes of it in out_tag. Returns whether it was able to get the tag, which mainly has to do with whether it is compatible with the current block cipher mode.
bool SbCryptographyGetTag(SbCryptographyTransformer transformer, void *out_tag, int out_tag_size)
Returns whether the given transformer handle is valid.
static bool SbCryptographyIsTransformerValid(SbCryptographyTransformer transformer)
Sets additional authenticated data (AAD) for a transformer, for chaining modes that support it (GCM). Returns whether the data was successfully set. This can fail if the chaining mode doesn't support AAD, if the parameters are invalid, or if the internal state is invalid for setting AAD.
bool SbCryptographySetAuthenticatedData(SbCryptographyTransformer transformer, const void *data, int data_size)
Sets the initialization vector (IV) for a transformer, replacing the internally- set IV. The block cipher mode algorithm will update the IV appropriately after every block, so this is not necessary unless the stream is discontiguous in some way. This happens with AES-GCM in TLS.
void SbCryptographySetInitializationVector(SbCryptographyTransformer transformer, const void *initialization_vector, int initialization_vector_size)
Transforms one or more block_size_bits-sized blocks of in_data, with the given transformer, placing the result in out_data. Returns the number of bytes that were written to out_data, unless there was an error, in which case it will return a negative number.
transformer: A transformer initialized with an algorithm, IV, cipherkey, and so on. in_data: The data to be transformed. in_data_size: The size of the data to be transformed, in bytes. Must be a multiple of the transformer's block-size_bits, or an error will be returned. out_data: A buffer where the transformed data should be placed. Must have at least capacity for in_data_size bytes. May point to the same memory as in_data.
int SbCryptographyTransform(SbCryptographyTransformer transformer, const void *in_data, int in_data_size, void *out_data)