chore: Document encryption context interoperability for invalid UTF-8

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.
  * @{
  */
 

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;