diff --git a/include/aws/cryptosdk/enc_ctx.h b/include/aws/cryptosdk/enc_ctx.h index dc3913fb8..2783eedaf 100644 --- a/include/aws/cryptosdk/enc_ctx.h +++ b/include/aws/cryptosdk/enc_ctx.h @@ -32,6 +32,16 @@ extern "C" { * for the most part, aws_hash_table methods are used to manipulate these structures, * but we provide some higher-level helper methods in this section. These helpers * will mostly be of interest to developers of custom CMMs or keyrings. + * + * The values provided to the encryption context SHOULD be UTF-8 bytes. + * While it is technically possible to provide invalid UTF-8 bytes, + * doing so is strongly discouraged. + * Messages that include invalid UTF-8 bytes in their encryption context + * will not be interoperable across different language implementations + * of the AWS Encryption SDK. + * The ESDK for C permits writing and reading encryption contexts that + * contain invalid UTF-8 bytes, but ESDKs in other languages will neither + * read nor write messages whose encryption context contains invalid UTF-8. * @{ */ diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 223f8cd24..446c77859 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -136,6 +136,16 @@ struct aws_cryptosdk_enc_request { * The encryption context for this message. CMMs are permitted to modify this * hash table in order to inject additional keys or otherwise modify the encryption * context. + * + * The values provided to the encryption context SHOULD be UTF-8 bytes. + * While it is technically possible to provide invalid UTF-8 bytes, + * doing so is strongly discouraged. + * Messages that include invalid UTF-8 bytes in their encryption context + * will not be interoperable across different language implementations + * of the AWS Encryption SDK. + * The ESDK for C permits writing and reading encryption contexts that + * contain invalid UTF-8 bytes, but ESDKs in other languages will neither + * read nor write messages whose encryption context contains invalid UTF-8. */ struct aws_hash_table *enc_ctx; /** @@ -187,6 +197,21 @@ struct aws_cryptosdk_enc_materials { */ struct aws_cryptosdk_dec_request { struct aws_allocator *alloc; + /** + * The encryption context for this message. CMMs are permitted to modify this + * hash table in order to inject additional keys or otherwise modify the encryption + * context. + * + * The values provided to the encryption context SHOULD be UTF-8 bytes. + * While it is technically possible to provide invalid UTF-8 bytes, + * doing so is strongly discouraged. + * Messages that include invalid UTF-8 bytes in their encryption context + * will not be interoperable across different language implementations + * of the AWS Encryption SDK. + * The ESDK for C permits writing and reading encryption contexts that + * contain invalid UTF-8 bytes, but ESDKs in other languages will neither + * read nor write messages whose encryption context contains invalid UTF-8. + */ const struct aws_hash_table *enc_ctx; struct aws_array_list encrypted_data_keys; enum aws_cryptosdk_alg_id alg;