Enumerations | |
| enum | aws_cryptosdk_alg_id { ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 = 0x0578 , ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY = 0x0478 , ALG_AES256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 = 0x0378 , ALG_AES192_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 = 0x0346 , ALG_AES128_GCM_IV12_TAG16_HKDF_SHA256_ECDSA_P256 = 0x0214 , ALG_AES256_GCM_IV12_TAG16_HKDF_SHA256 = 0x0178 , ALG_AES192_GCM_IV12_TAG16_HKDF_SHA256 = 0x0146 , ALG_AES128_GCM_IV12_TAG16_HKDF_SHA256 = 0x0114 , ALG_AES256_GCM_IV12_TAG16_NO_KDF = 0x0078 , ALG_AES192_GCM_IV12_TAG16_NO_KDF = 0x0046 , ALG_AES128_GCM_IV12_TAG16_NO_KDF = 0x0014 } |
| enum | aws_cryptosdk_mode { AWS_CRYPTOSDK_ENCRYPT = 0x9000 , AWS_CRYPTOSDK_DECRYPT = 0x9001 , AWS_CRYPTOSDK_DECRYPT_UNSIGNED = 0x9002 } |
Functions | |
| struct aws_cryptosdk_session * | aws_cryptosdk_session_new_from_keyring_2 (struct aws_allocator *allocator, enum aws_cryptosdk_mode mode, struct aws_cryptosdk_keyring *keyring) |
| struct aws_cryptosdk_session * | aws_cryptosdk_session_new_from_cmm_2 (struct aws_allocator *allocator, enum aws_cryptosdk_mode mode, struct aws_cryptosdk_cmm *cmm) |
| void | aws_cryptosdk_session_destroy (struct aws_cryptosdk_session *session) |
| int | aws_cryptosdk_session_reset (struct aws_cryptosdk_session *session, enum aws_cryptosdk_mode mode) |
| int | aws_cryptosdk_session_set_frame_size (struct aws_cryptosdk_session *session, uint32_t frame_size) |
| int | aws_cryptosdk_session_set_message_size (struct aws_cryptosdk_session *session, uint64_t message_size) |
| int | aws_cryptosdk_session_set_message_bound (struct aws_cryptosdk_session *session, uint64_t max_message_size) |
| int | aws_cryptosdk_session_set_commitment_policy (struct aws_cryptosdk_session *session, enum aws_cryptosdk_commitment_policy commitment_policy) |
| int | aws_cryptosdk_session_set_max_encrypted_data_keys (struct aws_cryptosdk_session *session, size_t max_encrypted_data_keys) |
| int | aws_cryptosdk_session_process (struct aws_cryptosdk_session *session, uint8_t *outp, size_t outlen, size_t *out_bytes_written, const uint8_t *inp, size_t inlen, size_t *in_bytes_read) |
| int | aws_cryptosdk_session_process_full (struct aws_cryptosdk_session *session, uint8_t *outp, size_t outlen, size_t *out_bytes_written, const uint8_t *inp, size_t inlen) |
| bool | aws_cryptosdk_session_is_done (const struct aws_cryptosdk_session *session) |
| int | aws_cryptosdk_session_get_alg_id (const struct aws_cryptosdk_session *session, enum aws_cryptosdk_alg_id *alg_id) |
| void | aws_cryptosdk_session_estimate_buf (const struct aws_cryptosdk_session *AWS_RESTRICT session, size_t *AWS_RESTRICT outbuf_needed, size_t *AWS_RESTRICT inbuf_needed) |
| const struct aws_hash_table * | aws_cryptosdk_session_get_enc_ctx_ptr (const struct aws_cryptosdk_session *session) |
| struct aws_hash_table * | aws_cryptosdk_session_get_enc_ctx_ptr_mut (struct aws_cryptosdk_session *session) |
| const struct aws_array_list * | aws_cryptosdk_session_get_keyring_trace_ptr (const struct aws_cryptosdk_session *session) |
Detailed Description
The session is the primary API that encrypts or decrypts your data. To encrypt or decrypt data, configure your CMM, create a session object, and process your plaintext or ciphertext through this session object.
If encrypting or decrypting data all at once (i.e. with the entire plaintext/ciphertext in a single buffer), using a session object will proceed through the following phases:
- Create and configure a session object (or reuse an existing session that you have reset and configured)
- Invoke aws_cryptosdk_session_process_full providing all of the input plaintext or ciphertext, to produce the output data
If encrypting or decrypting streamed input, using a session object will instead proceed through the following phases:
- Create and configure a session object (or reuse an existing session that you have reset and configured)
- Invoke aws_cryptosdk_session_process in a loop that provide all of the input plaintext or ciphertext, and produces some output data
- When encrypting, after all input data is consumed, aws_cryptosdk_session_set_message_size (if it hasn't been called already) to mark the end of the message.
- To process or generate trailing data, invoke aws_cryptosdk_session_process in a loop with no input data until aws_cryptosdk_session_is_done returns true.
Most configuration functions will fail if invoked after the first call to aws_cryptosdk_session_process, as the header is generated (thus committing the session to a particular set of parameters) at this time.
The session object does not internally buffer your data; if you pass buffers that are too small, it may process only a portion of the supplied data, or none at all. The aws_cryptosdk_session_estimate_buf function can be used to get a more accurate estimate of the amount of buffer space required to make further progress.
Enumeration Type Documentation
◆ aws_cryptosdk_alg_id
| enum aws_cryptosdk_alg_id |
Known algorithm suite names. For more information, see the Algorithms Reference.
◆ aws_cryptosdk_mode
| enum aws_cryptosdk_mode |
Note that the current signed message format requires reading the full encrypted message before the signature can be verified, so it is important to avoid processing any plaintext until that point.
AWS_CRYPTOSDK_DECRYPT_UNSIGNED is recommended if you only need to process unsigned messages, and calling aws_cryptosdk_session_process_full is recommended instead of calling aws_cryptosdk_session_process directly if you are able to provide the complete encrypted message in a single buffer.
| Enumerator | |
|---|---|
| AWS_CRYPTOSDK_ENCRYPT | |
| AWS_CRYPTOSDK_DECRYPT | |
| AWS_CRYPTOSDK_DECRYPT_UNSIGNED | |
Function Documentation
◆ aws_cryptosdk_session_destroy()
| void aws_cryptosdk_session_destroy | ( | struct aws_cryptosdk_session * | session | ) |
Destroys a previously allocated session
◆ aws_cryptosdk_session_estimate_buf()
| void aws_cryptosdk_session_estimate_buf | ( | const struct aws_cryptosdk_session *AWS_RESTRICT | session, |
| size_t *AWS_RESTRICT | outbuf_needed, | ||
| size_t *AWS_RESTRICT | inbuf_needed ) |
Estimates the amount of buffer space needed to make forward progress. Supplying the amount of data indicated here to aws_cryptosdk_session_process guarantees that some kind of progress will be made - although this progress may in some cases only mean that the size estimates are updated with a (larger) more accurate value.
This method never fails, but if the session is in an error state or is only partially initialized, the returned sizes may not be meaningful.
◆ aws_cryptosdk_session_get_alg_id()
| int aws_cryptosdk_session_get_alg_id | ( | const struct aws_cryptosdk_session * | session, |
| enum aws_cryptosdk_alg_id * | alg_id ) |
Returns the algorithm ID in use for this message via *alg_id. Raises AWS_CRYPTOSDK_ERR_BAD_STATE if the algorithm ID has not yet been determined (in this case, the session remains usable and does not enter an error state). Guaranteed to succeed if aws_cryptosdk_session_is_done returns true, but may succeed earlier in the message as well.
◆ aws_cryptosdk_session_get_enc_ctx_ptr()
| const struct aws_hash_table * aws_cryptosdk_session_get_enc_ctx_ptr | ( | const struct aws_cryptosdk_session * | session | ) |
Returns a read-only pointer to the encryption context held by the session. This will return NULL if it is called too early in the decryption process, before the SDK has finished deserializing and handling the encryption context from the header of the ciphertext.
This may be called at any time during or after the encryption process for read-only access to the encryption context, but for setting the encryption context, use aws_cryptosdk_get_enc_ctx_ptr_mut instead.
The hash table pointed to by this pointer lives until the session is reset or destroyed. If you want a copy of the encryption context that will outlive the session, you should duplicate it with aws_cryptosdk_enc_ctx_clone and then deallocate the copy with aws_cryptosdk_enc_ctx_clean_up when done with it.
◆ aws_cryptosdk_session_get_enc_ctx_ptr_mut()
| struct aws_hash_table * aws_cryptosdk_session_get_enc_ctx_ptr_mut | ( | struct aws_cryptosdk_session * | session | ) |
Returns a mutable pointer to the encryption context held by the session. This will only return non-NULL when the session is in encrypt mode AND aws_cryptosdk_session_process has not yet been called.
The returned pointer will always point to an already initialized hash table. Callers MUST not clean up or re-initialize the hash table. The encryption context is an aws_hash_table with key and value both using the aws_string type.
See the interfaces in hash_table.h and string.h in aws-c-common for guidance on how to add elements to the encryption context.
Do not use this pointer across calls to the session. Doing so results in undefined behavior.
See documentation of aws_cryptosdk_session_get_enc_ctx_ptr for how to make your own copy of the encryption context, if desired.
◆ aws_cryptosdk_session_get_keyring_trace_ptr()
| const struct aws_array_list * aws_cryptosdk_session_get_keyring_trace_ptr | ( | const struct aws_cryptosdk_session * | session | ) |
Returns a read-only pointer to the keyring trace held by the session. This will return NULL if called too early in the encryption or decryption process. For best results, call after checking that aws_cryptosdk_session_is_done returns true.
When this returns a non-NULL pointer, it will always point to an already initialized aws_array_list with elements of type struct aws_cryptosdk_keyring_trace_record.
See keyring_trace.h for more information on the format of the trace.
The trace pointed to by this pointer lives until the session is reset or destroyed. If you want a copy of the trace that will outlive the session, you should duplicate it with aws_cryptosdk_keyring_trace_copy_all and then deallocate the copy with aws_cryptosdk_keyring_trace_clean_up when done with it.
◆ aws_cryptosdk_session_is_done()
| bool aws_cryptosdk_session_is_done | ( | const struct aws_cryptosdk_session * | session | ) |
Returns true if the session has finished processing the entire message.
Your application should continue calling aws_cryptosdk_session_process until this function returns true; trailing signatures require that some ciphertext data be processed after all plaintext has been consumed or generated.
◆ aws_cryptosdk_session_new_from_cmm_2()
| struct aws_cryptosdk_session * aws_cryptosdk_session_new_from_cmm_2 | ( | struct aws_allocator * | allocator, |
| enum aws_cryptosdk_mode | mode, | ||
| struct aws_cryptosdk_cmm * | cmm ) |
Creates a new encryption or decryption session from an underlying CMM.
- Returns
- The new session, or NULL on failure (in which case, an AWS error code is set)
- Parameters
-
allocator The allocator to use for the session object and any temporary data allocated for the session mode The aws_cryptosdk_mode to start in. This can be changed later with aws_cryptosdk_session_reset cmm The crypto material manager which will provide key material for this session.
◆ aws_cryptosdk_session_new_from_keyring_2()
| struct aws_cryptosdk_session * aws_cryptosdk_session_new_from_keyring_2 | ( | struct aws_allocator * | allocator, |
| enum aws_cryptosdk_mode | mode, | ||
| struct aws_cryptosdk_keyring * | keyring ) |
Creates a new encryption or decryption session from an underlying keyring.
- Returns
- The new session, or NULL on failure (in which case, an AWS error code is set)
- Parameters
-
allocator The allocator to use for the session object and any temporary data allocated for the session mode The aws_cryptosdk_mode to start in. This can be changed later with aws_cryptosdk_session_reset keyring The keyring which will encrypt or decrypt data keys for this session. This function uses a default CMM to link the session and keyring.
◆ aws_cryptosdk_session_process()
| int aws_cryptosdk_session_process | ( | struct aws_cryptosdk_session * | session, |
| uint8_t * | outp, | ||
| size_t | outlen, | ||
| size_t * | out_bytes_written, | ||
| const uint8_t * | inp, | ||
| size_t | inlen, | ||
| size_t * | in_bytes_read ) |
Attempts to process some data through the cryptosdk session. This method may do any combination of
- Consuming some data from the input buffer
- Producing some data in the output buffer
- Entering an error state, and raising the error in question.
The data referenced by the input and output cursors must not overlap. If this method raises an error, the contents of the output buffer will be zeroed. The buffer referenced by the input buffer will never be modified.
If there is insufficient output space and/or insufficient input data, this method may not make any progress. The aws_cryptosdk_session_estimate_buf method may be used to determine how much data may be needed at this stage of processing. Note that these estimates may change once the header has been parsed.
Upon return, *out_bytes_written and *in_bytes_read will report the number of bytes consumed from the output and input buffers, respectively.
This method will return successfully unless the session has entered an error state. Use aws_cryptosdk_session_is_done to determine if the entire message has been processed.
If the input buffer is large enough to hold the entire plaintext, and the output buffer is large enough to hold the entire ciphertext (or vice versa), you need to call this method only once. You should still call aws_cryptosdk_session_is_done afterwards to verify that the entire input has been processed.
◆ aws_cryptosdk_session_process_full()
| int aws_cryptosdk_session_process_full | ( | struct aws_cryptosdk_session * | session, |
| uint8_t * | outp, | ||
| size_t | outlen, | ||
| size_t * | out_bytes_written, | ||
| const uint8_t * | inp, | ||
| size_t | inlen ) |
Attempts to process an entire message through the cryptosdk session. The session must not have processed any data (e.g. using aws_cryptosdk_session_process) or be in an error state.
The data referenced by the input and output cursors must not overlap. If this method raises an error, the contents of the output buffer will be zeroed. The buffer referenced by the input buffer will never be modified. If there is insufficient output space and/or insufficient input data, this method raises an error.
Upon return, *out_bytes_written will report the number of bytes written to the output buffer.
This method will return successfully if it processed an entire message and did not enter an error state.
◆ aws_cryptosdk_session_reset()
| int aws_cryptosdk_session_reset | ( | struct aws_cryptosdk_session * | session, |
| enum aws_cryptosdk_mode | mode ) |
Resets the session, preparing it for a new message. This function can also change a session from encrypt to decrypt, or vice versa. After reset, the currently configured allocator, CMM, key commitment policy, max encrypted data keys, and frame size to use for encryption are preserved.
- Parameters
-
session The session to reset mode The new mode of the session
◆ aws_cryptosdk_session_set_commitment_policy()
| int aws_cryptosdk_session_set_commitment_policy | ( | struct aws_cryptosdk_session * | session, |
| enum aws_cryptosdk_commitment_policy | commitment_policy ) |
Sets the key commitment policy to use for encryption and decryption. The key commitment policy must be set before encryption or decryption.
◆ aws_cryptosdk_session_set_frame_size()
| int aws_cryptosdk_session_set_frame_size | ( | struct aws_cryptosdk_session * | session, |
| uint32_t | frame_size ) |
Sets the frame size to use for encryption. If zero is specified, the message will be processed in an unframed mode. If this function is not called, a reasonable default will be used.
This function will fail if invoked in decrypt mode, or if aws_cryptosdk_session_process has been called.
◆ aws_cryptosdk_session_set_max_encrypted_data_keys()
| int aws_cryptosdk_session_set_max_encrypted_data_keys | ( | struct aws_cryptosdk_session * | session, |
| size_t | max_encrypted_data_keys ) |
Sets the maximum number of encrypted data keys allowed during encryption and decryption. This must be set before encryption or decryption.
◆ aws_cryptosdk_session_set_message_bound()
| int aws_cryptosdk_session_set_message_bound | ( | struct aws_cryptosdk_session * | session, |
| uint64_t | max_message_size ) |
Provides an upper bound on the message size. This hint is useful when the exact message size is not known up-front, but the configured CMM still needs to make use of message size information. For example, the caching CMM enforces an upper bound on the number of bytes encrypted under a cached key. If this method is not called, it must assume that you are processing an unbounded amount of data, and it will therefore bypass the cache.
This method may be called more than once (the smallest call wins). The session will enter an error state if more than the smallest bound of data is written, or if the precise message size passed to aws_cryptosdk_session_set_message_size exceeds the bound.
It is recommended that the bound be set before invoking aws_cryptosdk_session_process; failing to do so will result in the CMM being passed an unbounded message size. This is an issue in particular with the caching CMM, which must then assume that your message will exceed size-based usage limits on cached keys.
◆ aws_cryptosdk_session_set_message_size()
| int aws_cryptosdk_session_set_message_size | ( | struct aws_cryptosdk_session * | session, |
| uint64_t | message_size ) |
Sets the precise size of the message to encrypt. This function must be called exactly once during an encrypt operation. You do not need to call it before beginning to pass data, but providing the message size up front may improve efficiency.
If the session has already processed more than message_size bytes, or if this method is called more than once, the session will enter an error state.
This method is how the end of data is determined. If this is not called, aws_cryptosdk_session_process cannot write the end-of-message frames and instead will continue to expect additional data.
Note that if the frame size is set to zero (i.e. this is a one-shot encrypt), a message size must be set before any input data can be processed.
Generated by
1.13.2