From f763abd0e28dc7cdbde88e10a3e7ddb0fdac59d2 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 12:46:29 -0700 Subject: [PATCH 1/7] chore: Document encryption context interoperability for invalid UTF-8 --- include/aws/cryptosdk/materials.h | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 223f8cd24..40ec5390b 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -136,6 +136,15 @@ 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 encoded bytes. + * You may provide invalid UTF-8 characters in the encryption context, + * but this is discouraged. + * Messages with invalid UTF-8 characters will not be interoperable + * with other language implementations of the encryption SDK. + * The encryption SDK for C will allow writing and reading messages with invalid UTF-8, but + * the encryption SDK in other languages will neither read nor write + * messages with invalid UTF-8. */ struct aws_hash_table *enc_ctx; /** From 90c1d92211ee34833615ae1a46ed2ce4b115fda2 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 13:22:36 -0700 Subject: [PATCH 2/7] m --- include/aws/cryptosdk/materials.h | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 40ec5390b..0520f62b3 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -137,14 +137,14 @@ struct aws_cryptosdk_enc_request { * 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 encoded bytes. - * You may provide invalid UTF-8 characters in the encryption context, + * The values provided to the encryption context SHOULD be UTF-8 bytes. + * You may choose to provide invalid UTF-8 bytes in the encryption context, * but this is discouraged. - * Messages with invalid UTF-8 characters will not be interoperable - * with other language implementations of the encryption SDK. - * The encryption SDK for C will allow writing and reading messages with invalid UTF-8, but - * the encryption SDK in other languages will neither read nor write - * messages with invalid UTF-8. + * Messages whose encryption contexts contain invalid UTF-8 characters will + * not be interoperable with other language implementations of the encryption SDK. + * The encryption SDK for C will allow writing and reading invalid UTF-8 to encryption + * contexts, but the encryption SDK in other languages will neither read nor write + * messages whose encryption context contains invalid UTF-8 characters. */ struct aws_hash_table *enc_ctx; /** From b6a106ab64c7ba75015fa422c1d4ea705d568747 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 13:25:02 -0700 Subject: [PATCH 3/7] m --- include/aws/cryptosdk/materials.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 0520f62b3..83c8f0237 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -142,7 +142,7 @@ struct aws_cryptosdk_enc_request { * but this is discouraged. * Messages whose encryption contexts contain invalid UTF-8 characters will * not be interoperable with other language implementations of the encryption SDK. - * The encryption SDK for C will allow writing and reading invalid UTF-8 to encryption + * The encryption SDK for C will allow writing and reading invalid UTF-8 in encryption * contexts, but the encryption SDK in other languages will neither read nor write * messages whose encryption context contains invalid UTF-8 characters. */ From 522467d104b6a8649a580d5c6662638de2111785 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 16:35:05 -0700 Subject: [PATCH 4/7] m --- include/aws/cryptosdk/materials.h | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 83c8f0237..886323bfa 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -138,13 +138,14 @@ struct aws_cryptosdk_enc_request { * context. * * The values provided to the encryption context SHOULD be UTF-8 bytes. - * You may choose to provide invalid UTF-8 bytes in the encryption context, - * but this is discouraged. - * Messages whose encryption contexts contain invalid UTF-8 characters will - * not be interoperable with other language implementations of the encryption SDK. - * The encryption SDK for C will allow writing and reading invalid UTF-8 in encryption - * contexts, but the encryption SDK in other languages will neither read nor write - * messages whose encryption context contains invalid UTF-8 characters. + * 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 language will neither + * read nor write messages whose encryption context contains invalid UTF-8. */ struct aws_hash_table *enc_ctx; /** From 3ae54487838c89a2f21a897d6c3be34faaa08861 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 16:35:20 -0700 Subject: [PATCH 5/7] m --- include/aws/cryptosdk/materials.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 886323bfa..5399a9a1e 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -144,7 +144,7 @@ struct aws_cryptosdk_enc_request { * 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 language will neither + * 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; From 6ece1805caf70bfc594390fcb27d977deb67884a Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 16:37:21 -0700 Subject: [PATCH 6/7] m --- include/aws/cryptosdk/enc_ctx.h | 10 ++++++++++ 1 file changed, 10 insertions(+) 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. * @{ */ From 65cc58b9c18b17dc6f3baf393fd79da896d09fe7 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Thu, 10 Apr 2025 16:52:55 -0700 Subject: [PATCH 7/7] m --- include/aws/cryptosdk/materials.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/include/aws/cryptosdk/materials.h b/include/aws/cryptosdk/materials.h index 5399a9a1e..446c77859 100644 --- a/include/aws/cryptosdk/materials.h +++ b/include/aws/cryptosdk/materials.h @@ -197,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;