LibAwsCal

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

__JL_Ctag_76

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

aws_cal_errors

Documentation not found.

aws_cal_log_subject

Documentation not found.

aws_ecc_curve_name

Documentation not found.

aws_ecc_key_pair

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

aws_ecc_key_pair_vtable

Documentation not found.

aws_ed25519_key_export_format

Documentation not found.

Documentation not found.

aws_hash

Documentation not found.

Documentation not found.

aws_hash_vtable

Documentation not found.

aws_hmac

Documentation not found.

Documentation not found.

aws_hmac_vtable

Documentation not found.

aws_rsa_encryption_algorithm

Documentation not found.

aws_rsa_key_export_format

Documentation not found.

Documentation not found.

aws_rsa_signature_algorithm

Documentation not found.

Documentation not found.

aws_symmetric_cipher_state

Documentation not found.

aws_aes_cbc_256_new(allocator, key, iv)

Creates an instance of AES CBC with 256-bit key. If key and iv are NULL, they will be generated internally. You can get the generated key and iv back by calling:

aws_symmetric_cipher_get_key() and aws_symmetric_cipher_get_initialization_vector()

respectively.

If they are set, that key and iv will be copied internally and used by the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_cbc_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key, const struct aws_byte_cursor *iv);

aws_aes_ctr_256_new(allocator, key, iv)

Creates an instance of AES CTR with 256-bit key. If key and iv are NULL, they will be generated internally. You can get the generated key and iv back by calling:

aws_symmetric_cipher_get_key() and aws_symmetric_cipher_get_initialization_vector()

respectively.

If they are set, that key and iv will be copied internally and used by the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_ctr_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key, const struct aws_byte_cursor *iv);

aws_aes_gcm_256_new(allocator, key, iv, aad)

Creates an instance of AES GCM with 256-bit key. If key, iv are NULL, they will be generated internally. You can get the generated key and iv back by calling:

aws_symmetric_cipher_get_key() and aws_symmetric_cipher_get_initialization_vector()

respectively.

If aad is set it will be copied and applied to the cipher.

If they are set, that key and iv will be copied internally and used by the cipher.

For decryption purposes tag can be provided via aws_symmetric_cipher_set_tag method. Note: for decrypt operations, tag must be provided before first decrypt is called. (this is a windows bcrypt limitations, but for consistency sake same limitation is extended to other platforms) Tag generated during encryption can be retrieved using aws_symmetric_cipher_get_tag method after finalize is called.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_gcm_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key, const struct aws_byte_cursor *iv, const struct aws_byte_cursor *aad);

aws_aes_keywrap_256_new(allocator, key)

Creates an instance of AES Keywrap with 256-bit key. If key is NULL, it will be generated internally. You can get the generated key back by calling:

aws_symmetric_cipher_get_key()

If key is set, that key will be copied internally and used by the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_keywrap_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key);

aws_cal_library_clean_up()

Documentation not found.

Prototype

void aws_cal_library_clean_up(void);

aws_cal_library_init(allocator)

Documentation not found.

Prototype

void aws_cal_library_init(struct aws_allocator *allocator);

aws_cal_thread_clean_up()

Documentation not found.

Prototype

void aws_cal_thread_clean_up(void);

aws_ecc_curve_name_from_oid(oid, curve_name)

Get the curve name from the oid. OID here is the payload of the DER encoded ASN.1 part (doesn't include type specifier or length. On success, the value of curve_name will be set.

Prototype

int aws_ecc_curve_name_from_oid(struct aws_byte_cursor *oid, enum aws_ecc_curve_name *curve_name);

aws_ecc_key_coordinate_byte_size_from_curve_name(curve_name)

Documentation not found.

Prototype

size_t aws_ecc_key_coordinate_byte_size_from_curve_name(enum aws_ecc_curve_name curve_name);

aws_ecc_key_new_from_hex_coordinates(allocator, curve_name, pub_x_hex_cursor, pub_y_hex_cursor)

Creates an Elliptic curve public key from x and y coordinates encoded as hex strings Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_new_from_hex_coordinates( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name, struct aws_byte_cursor pub_x_hex_cursor, struct aws_byte_cursor pub_y_hex_cursor);

aws_ecc_key_pair_acquire(key_pair)

Adds one to an ecc key pair's ref count.

Prototype

void aws_ecc_key_pair_acquire(struct aws_ecc_key_pair *key_pair);

aws_ecc_key_pair_derive_public_key(key_pair)

Derives a public key from the private key if supported by this operating system (not supported on OSX). key_pair::pub_x and key_pair::pub_y will be set with the raw key buffers.

Prototype

int aws_ecc_key_pair_derive_public_key(struct aws_ecc_key_pair *key_pair);

aws_ecc_key_pair_get_private_key(key_pair, private_d)

Documentation not found.

Prototype

void aws_ecc_key_pair_get_private_key( const struct aws_ecc_key_pair *key_pair, struct aws_byte_cursor *private_d);

aws_ecc_key_pair_get_public_key(key_pair, pub_x, pub_y)

Documentation not found.

Prototype

void aws_ecc_key_pair_get_public_key( const struct aws_ecc_key_pair *key_pair, struct aws_byte_cursor *pub_x, struct aws_byte_cursor *pub_y);

aws_ecc_key_pair_new_from_asn1(allocator, encoded_keys)

Creates an Elliptic Curve public/private key pair from a DER encoded key pair. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Whether or not signing or verification can be perform depends on if encoded_keys is a public/private pair or a public key.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_from_asn1( struct aws_allocator *allocator, const struct aws_byte_cursor *encoded_keys);

aws_ecc_key_pair_new_from_private_key(allocator, curve_name, priv_key)

Creates an Elliptic Curve private key that can be used for signing. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Note: priv_key::len must match the appropriate length for the selected curve_name.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_from_private_key( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name, const struct aws_byte_cursor *priv_key);

aws_ecc_key_pair_new_from_public_key(allocator, curve_name, public_key_x, public_key_y)

Creates an Elliptic Curve public key that can be used for verifying. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Note: public_key_x::len and public_key_y::len must match the appropriate length for the selected curve_name.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_from_public_key( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name, const struct aws_byte_cursor *public_key_x, const struct aws_byte_cursor *public_key_y);

aws_ecc_key_pair_new_generate_random(allocator, curve_name)

Creates an Elliptic Curve public/private key pair that can be used for signing and verifying. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Note: On Apple platforms this function is only supported on MacOS. This is due to usage of SecItemExport, which is only available on MacOS 10.7+ (yes, MacOS only and no other Apple platforms). There are alternatives for ios and other platforms, but they are ugly to use. Hence for now it only supports this call on MacOS.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_generate_random( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name);

aws_ecc_key_pair_release(key_pair)

Subtracts one from an ecc key pair's ref count. If ref count reaches zero, the key pair is destroyed.

Prototype

void aws_ecc_key_pair_release(struct aws_ecc_key_pair *key_pair);

aws_ecc_key_pair_sign_message(key_pair, message, signature)

Uses the key_pair's private key to sign message. The output will be in signature. Signature must be large enough to hold the signature. Check aws_ecc_key_pair_signature_length() for the appropriate size. Signature will be DER encoded.

It is the callers job to make sure message is the appropriate cryptographic digest for this operation. It's usually something like a SHA256.

Prototype

int aws_ecc_key_pair_sign_message( const struct aws_ecc_key_pair *key_pair, const struct aws_byte_cursor *message, struct aws_byte_buf *signature);

aws_ecc_key_pair_signature_length(key_pair)

Documentation not found.

Prototype

size_t aws_ecc_key_pair_signature_length(const struct aws_ecc_key_pair *key_pair);

aws_ecc_key_pair_verify_signature(key_pair, message, signature)

Uses the key_pair's public key to verify signature of message. Signature should be DER encoded.

It is the callers job to make sure message is the appropriate cryptographic digest for this operation. It's usually something like a SHA256.

returns AWS_OP_SUCCESS if the signature is valid.

Prototype

int aws_ecc_key_pair_verify_signature( const struct aws_ecc_key_pair *key_pair, const struct aws_byte_cursor *message, const struct aws_byte_cursor *signature);

aws_ecc_oid_from_curve_name(curve_name, oid)

Get the DER encoded OID from the curve_name. The OID in this case will not contain the type or the length specifier.

Prototype

int aws_ecc_oid_from_curve_name(enum aws_ecc_curve_name curve_name, struct aws_byte_cursor *oid);

aws_ed25519_key_pair_acquire(key_pair)

Adds one to an Ed25519 key pair's ref count. Returns key_pair pointer.

Prototype

struct aws_ed25519_key_pair *aws_ed25519_key_pair_acquire(struct aws_ed25519_key_pair *key_pair);

aws_ed25519_key_pair_get_private_key(key_pair, format, out)

Documentation not found.

Prototype

int aws_ed25519_key_pair_get_private_key( const struct aws_ed25519_key_pair *key_pair, enum aws_ed25519_key_export_format format, struct aws_byte_buf *out);

aws_ed25519_key_pair_get_private_key_size(format)

Gets the size of the exported private key.

Prototype

size_t aws_ed25519_key_pair_get_private_key_size(enum aws_ed25519_key_export_format format);

aws_ed25519_key_pair_get_public_key(key_pair, format, out)

Documentation not found.

Prototype

int aws_ed25519_key_pair_get_public_key( const struct aws_ed25519_key_pair *key_pair, enum aws_ed25519_key_export_format format, struct aws_byte_buf *out);

aws_ed25519_key_pair_get_public_key_size(format)

Gets the size of the exported public key.

Prototype

size_t aws_ed25519_key_pair_get_public_key_size(enum aws_ed25519_key_export_format format);

aws_ed25519_key_pair_new_generate(allocator)

Generate new Ed25519 key. Returns a new instance of aws_ed25519_key_pair if the key was successfully generated. Otherwise returns NULL. Note: keygen is not supported on all platforms and will return NULL for the key and raise AWS_ERROR_CAL_UNSUPPORTED_ALGORITHM. Examples of unsupported cases: - openssl pre 1.1.1 (Note: aws-lc and boringssl both expose the needed functions) - win/mac builds without special flag that forces linking to libcrypto to support this

Prototype

struct aws_ed25519_key_pair *aws_ed25519_key_pair_new_generate(struct aws_allocator *allocator);

aws_ed25519_key_pair_release(key_pair)

Subtracts one from an Ed25519 key pair's ref count. If ref count reaches zero, the key pair is destroyed. Always returns NULL.

Prototype

struct aws_ed25519_key_pair *aws_ed25519_key_pair_release(struct aws_ed25519_key_pair *key_pair);

aws_hash_destroy(hash)

Cleans up and deallocates hash.

Prototype

void aws_hash_destroy(struct aws_hash *hash);

aws_hash_finalize(hash, output, truncate_to)

Completes the hash computation and writes the final digest to output. Allocation of output is the caller's responsibility. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example, if you want a SHA256 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_hash_finalize(struct aws_hash *hash, struct aws_byte_buf *output, size_t truncate_to);

aws_hash_update(hash, to_hash)

Updates the running hash with to_hash. this can be called multiple times.

Prototype

int aws_hash_update(struct aws_hash *hash, const struct aws_byte_cursor *to_hash);

aws_hmac_destroy(hmac)

Cleans up and deallocates hmac.

Prototype

void aws_hmac_destroy(struct aws_hmac *hmac);

aws_hmac_finalize(hmac, output, truncate_to)

Completes the hmac computation and writes the final digest to output. Allocation of output is the caller's responsibility. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example if you want a SHA256 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_hmac_finalize(struct aws_hmac *hmac, struct aws_byte_buf *output, size_t truncate_to);

aws_hmac_update(hmac, to_hmac)

Updates the running hmac with to_hash. this can be called multiple times.

Prototype

int aws_hmac_update(struct aws_hmac *hmac, const struct aws_byte_cursor *to_hmac);

aws_md5_compute(allocator, input, output, truncate_to)

Computes the md5 hash over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory.

Prototype

int aws_md5_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *input, struct aws_byte_buf *output, size_t truncate_to);

aws_md5_new(allocator)

Allocates and initializes an md5 hash instance.

Prototype

struct aws_hash *aws_md5_new(struct aws_allocator *allocator);

aws_rsa_key_pair_acquire(key_pair)

Adds one to an RSA key pair's ref count. Returns key_pair pointer.

Prototype

struct aws_rsa_key_pair *aws_rsa_key_pair_acquire(struct aws_rsa_key_pair *key_pair);

aws_rsa_key_pair_block_length(key_pair)

Documentation not found.

Prototype

size_t aws_rsa_key_pair_block_length(const struct aws_rsa_key_pair *key_pair);

aws_rsa_key_pair_decrypt(key_pair, algorithm, ciphertext, out)

Documentation not found.

Prototype

int aws_rsa_key_pair_decrypt( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_encryption_algorithm algorithm, struct aws_byte_cursor ciphertext, struct aws_byte_buf *out);

aws_rsa_key_pair_encrypt(key_pair, algorithm, plaintext, out)

Documentation not found.

Prototype

int aws_rsa_key_pair_encrypt( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_encryption_algorithm algorithm, struct aws_byte_cursor plaintext, struct aws_byte_buf *out);

aws_rsa_key_pair_get_private_key(key_pair, format, out)

Documentation not found.

Prototype

int aws_rsa_key_pair_get_private_key( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_key_export_format format, struct aws_byte_buf *out);

aws_rsa_key_pair_get_public_key(key_pair, format, out)

Documentation not found.

Prototype

int aws_rsa_key_pair_get_public_key( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_key_export_format format, struct aws_byte_buf *out);

aws_rsa_key_pair_max_encrypt_plaintext_size(key_pair, algorithm)

Max plaintext size that can be encrypted by the key (i.e. max data size supported by the key - bytes needed for padding).

Prototype

size_t aws_rsa_key_pair_max_encrypt_plaintext_size( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_encryption_algorithm algorithm);

aws_rsa_key_pair_new_from_private_key_pkcs1(allocator, key)

Creates an RSA private key from RSAPrivateKey as defined in rfc 8017 (aka PKCS1). Returns a new instance of aws_rsa_key_pair if the key was successfully built. Otherwise returns NULL.

Prototype

struct aws_rsa_key_pair *aws_rsa_key_pair_new_from_private_key_pkcs1( struct aws_allocator *allocator, struct aws_byte_cursor key);

aws_rsa_key_pair_new_from_public_key_pkcs1(allocator, key)

Creates an RSA public key from RSAPublicKey as defined in rfc 8017 (aka PKCS1). Returns a new instance of aws_rsa_key_pair if the key was successfully built. Otherwise returns NULL.

Prototype

struct aws_rsa_key_pair *aws_rsa_key_pair_new_from_public_key_pkcs1( struct aws_allocator *allocator, struct aws_byte_cursor key);

aws_rsa_key_pair_release(key_pair)

Subtracts one from an RSA key pair's ref count. If ref count reaches zero, the key pair is destroyed. Always returns NULL.

Prototype

struct aws_rsa_key_pair *aws_rsa_key_pair_release(struct aws_rsa_key_pair *key_pair);

aws_rsa_key_pair_sign_message(key_pair, algorithm, digest, out)

Uses the key_pair's private key to sign message. The output will be in out. out must be large enough to hold the signature. Check aws_rsa_key_pair_signature_length() for the appropriate size.

It is the callers job to make sure message is the appropriate cryptographic digest for this operation. It's usually something like a SHA256.

Prototype

int aws_rsa_key_pair_sign_message( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_signature_algorithm algorithm, struct aws_byte_cursor digest, struct aws_byte_buf *out);

aws_rsa_key_pair_signature_length(key_pair)

Documentation not found.

Prototype

size_t aws_rsa_key_pair_signature_length(const struct aws_rsa_key_pair *key_pair);

aws_rsa_key_pair_verify_signature(key_pair, algorithm, digest, signature)

Uses the key_pair's public key to verify signature of message.

It is the callers job to make sure message is the appropriate cryptographic digest for this operation. It's usually something like a SHA256.

returns AWS_OP_SUCCESS if the signature is valid. raises AWS_ERROR_CAL_SIGNATURE_VALIDATION_FAILED if signature validation failed

Prototype

int aws_rsa_key_pair_verify_signature( const struct aws_rsa_key_pair *key_pair, enum aws_rsa_signature_algorithm algorithm, struct aws_byte_cursor digest, struct aws_byte_cursor signature);

aws_set_md5_new_fn(fn)

Set the implementation of md5 to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_md5_new_fn(aws_hash_new_fn *fn);

aws_set_sha1_new_fn(fn)

Set the implementation of sha1 to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_sha1_new_fn(aws_hash_new_fn *fn);

aws_set_sha256_hmac_new_fn(fn)

Set the implementation of sha256 hmac to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_sha256_hmac_new_fn(aws_hmac_new_fn *fn);

aws_set_sha256_new_fn(fn)

Set the implementation of sha256 to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_sha256_new_fn(aws_hash_new_fn *fn);

aws_sha1_compute(allocator, input, output, truncate_to)

Computes the sha1 hash over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example, if you want a SHA1 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_sha1_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *input, struct aws_byte_buf *output, size_t truncate_to);

aws_sha1_new(allocator)

Allocates and initializes a sha1 hash instance.

Prototype

struct aws_hash *aws_sha1_new(struct aws_allocator *allocator);

aws_sha256_compute(allocator, input, output, truncate_to)

Computes the sha256 hash over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example, if you want a SHA256 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_sha256_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *input, struct aws_byte_buf *output, size_t truncate_to);

aws_sha256_hmac_compute(allocator, secret, to_hmac, output, truncate_to)

Computes the sha256 hmac over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example if you want a SHA256 HMAC digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_sha256_hmac_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *secret, const struct aws_byte_cursor *to_hmac, struct aws_byte_buf *output, size_t truncate_to);

aws_sha256_hmac_new(allocator, secret)

Allocates and initializes a sha256 hmac instance. Secret is the key to be used for the hmac process.

Prototype

struct aws_hmac *aws_sha256_hmac_new(struct aws_allocator *allocator, const struct aws_byte_cursor *secret);

aws_sha256_new(allocator)

Allocates and initializes a sha256 hash instance.

Prototype

struct aws_hash *aws_sha256_new(struct aws_allocator *allocator);

aws_symmetric_cipher_decrypt(cipher, to_decrypt, out)

Decrypts the value in to_decrypt and writes the decrypted data into out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the decrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of to_decrypt + an extra BLOCK to account for padding etc...

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_decrypt( struct aws_symmetric_cipher *cipher, struct aws_byte_cursor to_decrypt, struct aws_byte_buf *out);

aws_symmetric_cipher_destroy(cipher)

Cleans up internal resources and state for cipher and then deallocates it.

Prototype

void aws_symmetric_cipher_destroy(struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_encrypt(cipher, to_encrypt, out)

Encrypts the value in to_encrypt and writes the encrypted data into out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the encrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of to_encrypt + an extra BLOCK to account for padding etc...

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_encrypt( struct aws_symmetric_cipher *cipher, struct aws_byte_cursor to_encrypt, struct aws_byte_buf *out);

aws_symmetric_cipher_finalize_decryption(cipher, out)

Decrypts any remaining data that was reserved for final padding, loads GMACs etc... and if there is any writes any remaining decrypted data to out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the decrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of 2 BLOCKs to account for padding etc...

After invoking this function, you MUST call aws_symmetric_cipher_reset() before invoking any encrypt/decrypt operations on this cipher again.

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_finalize_decryption(struct aws_symmetric_cipher *cipher, struct aws_byte_buf *out);

aws_symmetric_cipher_finalize_encryption(cipher, out)

Encrypts any remaining data that was reserved for final padding, loads GMACs etc... and if there is any writes any remaining encrypted data to out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the decrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of 2 BLOCKs to account for padding etc...

After invoking this function, you MUST call aws_symmetric_cipher_reset() before invoking any encrypt/decrypt operations on this cipher again.

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_finalize_encryption(struct aws_symmetric_cipher *cipher, struct aws_byte_buf *out);

aws_symmetric_cipher_get_initialization_vector(cipher)

Gets the original initialization vector as a cursor. The memory in this cursor is unsafe as it refers to the internal buffer. This was done because the use case doesn't require fetching these during an encryption or decryption operation and it dramatically simplifies the API.

Unlike some other fields, this value does not change after the inital construction of the cipher.

For some algorithms, such as AES Keywrap, this will return an empty cursor.

Prototype

struct aws_byte_cursor aws_symmetric_cipher_get_initialization_vector( const struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_get_key(cipher)

Gets the original key.

The memory in this cursor is unsafe as it refers to the internal buffer. This was done because the use case doesn't require fetching these during an encryption or decryption operation and it dramatically simplifies the API.

Unlike some other fields, this value does not change after the inital construction of the cipher.

Prototype

struct aws_byte_cursor aws_symmetric_cipher_get_key(const struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_get_state(cipher)

Retuns the current state of the cipher. Ther state of the cipher can be ready for use, finalized, or has encountered an error. if the cipher is in a finished or error state, it must be reset before further use.

Prototype

enum aws_symmetric_cipher_state aws_symmetric_cipher_get_state(const struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_get_tag(cipher)

Gets the current GMAC tag. If not AES GCM, this function will just return an empty cursor. The memory in this cursor is unsafe as it refers to the internal buffer. This was done because the use case doesn't require fetching these during an encryption or decryption operation and it dramatically simplifies the API. Only use this function between other calls to this API as any function call can alter the value of this tag.

If you need to access it in a different pattern, copy the values to your own buffer first.

Prototype

struct aws_byte_cursor aws_symmetric_cipher_get_tag(const struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_is_good(cipher)

Returns true if the state of the cipher is good, and otherwise returns false. Most operations, other than aws_symmetric_cipher_reset() will fail if this function is returning false. aws_symmetric_cipher_reset() will reset the state to a good state if possible.

Prototype

bool aws_symmetric_cipher_is_good(const struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_reset(cipher)

Resets the cipher state for starting a new encrypt or decrypt operation. Note encrypt/decrypt cannot be mixed on the same cipher without a call to reset in between them. However, this leaves the key, iv etc... materials setup for immediate reuse. Note: GCM tag is not preserved between operations. If you intend to do encrypt followed directly by decrypt, make sure to make a copy of tag before reseting the cipher and pass that copy for decryption.

Warning: In most cases it's a really bad idea to reset a cipher and perform another operation using that cipher. Key and IV should not be reused for different operations. Instead of reseting the cipher, destroy the cipher and create new one with a new key/iv pair. Use reset at your own risk, and only after careful consideration.

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_reset(struct aws_symmetric_cipher *cipher);

aws_symmetric_cipher_set_tag(cipher, tag)

Sets the GMAC tag on the cipher. Does nothing for ciphers that do not support tag.

Prototype

void aws_symmetric_cipher_set_tag(struct aws_symmetric_cipher *cipher, struct aws_byte_cursor tag);