docs: Clarify specification (#244)

Author: lavaleri

DynamoDbEncryption/dafny/DynamoDbEncryptionTransforms/src/GetItemTransform.dfy

@@ -57,9 +57,8 @@ module GetItemTransform {
 
       //= specification/dynamodb-encryption-client/ddb-sdk-integration.md#decrypt-after-getitem
       //= type=implication
-      //# The GetItem response's `Item` field MUST be replaced
-      //# with a value that is equivalent to
-      //# the resulting item.
+      //# The GetItem response's `Item` field MUST be
+      //# replaced by the encrypted DynamoDb Item outputted above.
       && output.value.transformedOutput.Item.Some?
       && (item == output.value.transformedOutput.Item.value)
 

specification/dynamodb-encryption-client/ddb-sdk-integration.md

@@ -331,9 +331,8 @@ is the `Item` field in the original response
 
 Beacons MUST be [removed](ddb-support.md#removebeacons) from the result.
 
-The GetItem response's `Item` field MUST be replaced
-with a value that is equivalent to
-the resulting item.
+The GetItem response's `Item` field MUST be
+replaced by the encrypted DynamoDb Item outputted above.
 
 ### Decrypt after BatchGetItem
 

specification/dynamodb-encryption-client/ddb-support.md

@@ -154,11 +154,11 @@ For any operand in the KeyConditionExpression or FilterExpression which is a bea
 the name MUST be replaced by the internal beacon name (i.e. NAME replaced by aws_dbe_b_NAME).
 
 If the name is used directly in the expression, the name MUST be changed in the expression.
-For example the expression "MyBeacon < :value" must be changed to "aws_dbe_b_MyBeacon < :value".
+For example the expression "MyBeacon = :value" must be changed to "aws_dbe_b_MyBeacon = :value".
 
 If the name is used indirectly through the ExpressionAttributeNames mapping,
 the name MUST be changed in the ExpressionAttributeNames. For example if the query is
-"#Beacon < :value" and ExpressionAttributeNames holds (#Beacon = MyBeacon),
+"#Beacon = :value" and ExpressionAttributeNames holds (#Beacon = MyBeacon),
 the query must remain unchanged and ExpressionAttributeNames changed to (#Beacon = aws_dbe_b_MyBeacon).
 
 In this regard, each use of each operand is handled separately.
@@ -171,7 +171,7 @@ MUST be obtained from the [Beacon Key Materials](../searchable-encryption/search
 as the key.
 
 For example if the query is
-"MyBeacon < :value" and ExpressionAttributeValues holds (:value = banana),
+"MyBeacon = :value" and ExpressionAttributeValues holds (:value = banana),
 then the ExpressionAttributeValues must be changed to (:value = 13fd),
 where "13fd" is the calculated beacon value.
 

specification/dynamodb-encryption-client/decrypt-item.md

@@ -135,6 +135,9 @@ data that was serialized into the header included in the output DynamoDb Item.
 
 ### Signature Scope
 
+The Signature Scope is a client-side configuration of what attributes should be
+included within signature calculations whenever encrypting or decrypting items.
+
 An Attribute on a DynamoDB Item MUST NOT be considered as within the signature scope
 if it's Attribute Name is included in [Unauthenticated Attributes](./ddb-table-encryption-config.md#unauthenticated-attributes)
 or if it's Attribute Name begins with the prefix specified in

specification/dynamodb-encryption-client/encrypt-item.md

@@ -118,6 +118,7 @@ with the following inputs:
     such that the Crypto Action indexed by that attribute name in the Crypto Schema
     equals the Crypto Action indexed by that attribute name in the configured Attribute Actions.
   - The Crypto Schema MUST NOT contain more Crypto Actions than those specified by the previous point.
+    E.g. the Crypto Schema must not specify actions for attributes that don't exist on the item.
 - If configured, the Algorithm Suite MUST be the
   [Algorithm Suite configured on this Item Encryptor](./ddb-table-encryption-config.md#algorithm-suite).
   If not configured on the Item Encryptor, Algorithm Suite MUST NOT be specified.