Starboard Module Reference: cryptography.h

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.

  1. GCM - The preferred block cipher mode for OpenSSL, mainly due to speed.

  2. 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)

  3. 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.

  4. 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://crbug.com/442572

https://crypto.stackexchange.com/questions/10775/practical-disadvantages-of-gcm-mode-encryption

Macros

kSbCryptographyAlgorithmAes

String literal for the AES symmetric block cipher. https://en.wikipedia.org/wiki/Advanced_Encryption_Standard

kSbCryptographyInvalidTransformer

Well-defined value for an invalid transformer.

Enums

SbCryptographyBlockCipherMode

The method of chaining encrypted blocks in a sequence. https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation

Values

  • 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.

SbCryptographyDirection

The direction of a cryptographic transformation.

Values

  • kSbCryptographyDirectionEncode

    Cryptographic transformations that encode/encrypt data into a target format.

  • kSbCryptographyDirectionDecode

    Cryptographic transformations that decode/decrypt data into its original form.

Typedefs

SbCryptographyTransformer

A handle to a cryptographic transformer.

Definition

typedef SbCryptographyTransformerPrivate* SbCryptographyTransformer

Functions

SbCryptographyCreateTransformer

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.

Declaration

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)

SbCryptographyDestroyTransformer

Destroys the given transformer instance.

Declaration

void SbCryptographyDestroyTransformer(SbCryptographyTransformer transformer)

SbCryptographyGetTag

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.

Declaration

bool SbCryptographyGetTag(SbCryptographyTransformer transformer, void *out_tag, int out_tag_size)

SbCryptographyIsTransformerValid

Returns whether the given transformer handle is valid.

Declaration

static bool SbCryptographyIsTransformerValid(SbCryptographyTransformer transformer)

SbCryptographySetAuthenticatedData

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.

Declaration

bool SbCryptographySetAuthenticatedData(SbCryptographyTransformer transformer, const void *data, int data_size)

SbCryptographySetInitializationVector

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.

Declaration

void SbCryptographySetInitializationVector(SbCryptographyTransformer transformer, const void *initialization_vector, int initialization_vector_size)

SbCryptographyTransform

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.

Declaration

int SbCryptographyTransform(SbCryptographyTransformer transformer, const void *in_data, int in_data_size, void *out_data)