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.
Tips for Porters
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:
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
Cipher Block Chaining mode.
Cipher Feedback mode.
Counter mode: A nonce is combined with an increasing counter.
Electronic Code Book mode: No chaining.
Output Feedback mode.
The direction of a cryptographic transformation.
Cryptographic transformations that encode/encrypt data into a target format.
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
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.
The block size variant of the algorithm to use, in bits.
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
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
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
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
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
int SbCryptographyTransform(SbCryptographyTransformer transformer, const void *in_data, int in_data_size, void *out_data)