chore: add client specification and Duvet annotations

Author: kessplas

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "specification"]
+	path = specification
+	url = [email protected]:awslabs/aws-encryption-sdk-specification.git
+	branch = kessplas/s3-ec-v3

Makefile

@@ -0,0 +1,14 @@
+# Used for misc supporting functions like Duvet and prettier. Builds, tests, etc. should use the usual Java/Maven tooling.
+
+duvet: | duvet_extract duvet_report
+
+duvet_extract:
+	rm -rf compliance
+	$(foreach file, $(shell find specification/s3-encryption -name '*.md'), duvet extract -o compliance -f MARKDOWN $(file);)
+
+duvet_report:
+	duvet \
+		report \
+		--spec-pattern "compliance/**/*.toml" \
+		--source-pattern "src/**/*.java" \
+		--html specification_compliance_report.html

specification

@@ -75,7 +75,11 @@ private DecryptionMaterials prepareMaterialsFromRequest(final GetObjectRequest g
         }
 
         AlgorithmSuite algorithmSuite = contentMetadata.algorithmSuite();
+        //= specification/s3-encryption/client.md#enable-legacy-unauthenticated-modes
+        //# When enabled, the S3EC MUST be able to decrypt objects encrypted with all content encryption algorithms (both legacy and fully supported).
         if (!_enableLegacyUnauthenticatedModes && algorithmSuite.isLegacy()) {
+            //= specification/s3-encryption/client.md#enable-legacy-unauthenticated-modes
+            //# When disabled, the S3EC MUST NOT decrypt objects encrypted using legacy content encryption algorithms.
             throw new S3EncryptionClientException("Enable legacy unauthenticated modes to use legacy content decryption: " + algorithmSuite.cipherName());
         }
 
@@ -146,11 +150,15 @@ public void onStream(SdkPublisher<ByteBuffer> ciphertextPublisher) {
             if (algorithmSuite.equals(AlgorithmSuite.ALG_AES_256_CBC_IV16_NO_KDF)
                     || algorithmSuite.equals(AlgorithmSuite.ALG_AES_256_CTR_IV16_TAG16_NO_KDF)
                     || _enableDelayedAuthentication) {
+                //= specification/s3-encryption/client.md#enable-delayed-authentication
+                //# When enabled, the S3EC MAY release plaintext from a stream which has not been authenticated.
                 // CBC and GCM with delayed auth enabled use a standard publisher
                 CipherPublisher plaintextPublisher = new CipherPublisher(ciphertextPublisher,
                         getObjectResponse.contentLength(), desiredRange, contentMetadata.contentRange(), algorithmSuite.cipherTagLengthBits(), materials, iv);
                 wrappedAsyncResponseTransformer.onStream(plaintextPublisher);
             } else {
+                //= specification/s3-encryption/client.md#enable-delayed-authentication
+                //# When disabled the S3EC MUST NOT release plaintext from a stream which has not been authenticated.
                 // Use buffered publisher for GCM when delayed auth is not enabled
                 BufferedCipherPublisher plaintextPublisher = new BufferedCipherPublisher(ciphertextPublisher,
                         getObjectResponse.contentLength(), materials, iv, _bufferSize);

src/main/java/software/amazon/encryption/s3/S3EncryptionClient.java

@@ -74,6 +74,8 @@ public CreateMultipartUploadResponse createMultipartUpload(CreateMultipartUpload
                 .overrideConfiguration(API_NAME_INTERCEPTOR)
                 .build();
 
+        //= specification/s3-encryption/client.md#api-operations
+        //# If implemented, CreateMultipartUpload MUST initiate a multipart upload.
         CreateMultipartUploadResponse response = _s3AsyncClient.createMultipartUpload(request).join();
 
         MultipartUploadMaterials mpuMaterials = MultipartUploadMaterials.builder()
@@ -133,13 +135,18 @@ public UploadPartResponse uploadPart(UploadPartRequest request, RequestBody requ
             throw new S3EncryptionClientException("No client-side information available on upload ID " + uploadId);
         }
         final UploadPartResponse response;
-        // Checks the parts are uploaded in series
+        //= specification/s3-encryption/client.md#api-operations
+        //# Each part MUST be encrypted in sequence.
         materials.beginPartUpload(actualRequest.partNumber(), partContentLength);
+        //= specification/s3-encryption/client.md#api-operations
+        //# Each part MUST be encrypted using the same cipher instance for each part.
         Cipher cipher = materials.getCipher(materials.getIv());
 
         ExecutorService singleThreadExecutor = Executors.newSingleThreadExecutor();
 
         try {
+            //= specification/s3-encryption/client.md#api-operations
+            //# UploadPart MUST encrypt each part.
             final AsyncRequestBody cipherAsyncRequestBody = new CipherAsyncRequestBody(
                 AsyncRequestBody.fromInputStream(
                     requestBody.contentStreamProvider().newStream(),
@@ -159,6 +166,7 @@ public UploadPartResponse uploadPart(UploadPartRequest request, RequestBody requ
             }
             // Ensures parts are not retried to avoid corrupting ciphertext
             AsyncRequestBody noRetryBody = new NoRetriesAsyncRequestBody(cipherAsyncRequestBody);
+            //= specification/s3-encryption/client.md#api-operations
             response =  _s3AsyncClient.uploadPart(actualRequest, noRetryBody).join();
         } finally {
             materials.endPartUpload();
@@ -187,6 +195,8 @@ public CompleteMultipartUploadResponse completeMultipartUpload(CompleteMultipart
                 .overrideConfiguration(API_NAME_INTERCEPTOR)
                 .build();
 
+        //= specification/s3-encryption/client.md#api-operations
+        //# CompleteMultipartUpload MUST complete the multipart upload.
         CompleteMultipartUploadResponse response = _s3AsyncClient.completeMultipartUpload(actualRequest).join();
 
         _multipartUploadMaterials.remove(uploadId);
@@ -198,6 +208,8 @@ public AbortMultipartUploadResponse abortMultipartUpload(AbortMultipartUploadReq
         AbortMultipartUploadRequest actualRequest = request.toBuilder()
                 .overrideConfiguration(API_NAME_INTERCEPTOR)
                 .build();
+        //= specification/s3-encryption/client.md#api-operations
+        //# AbortMultipartUpload MUST abort the multipart upload.
         return _s3AsyncClient.abortMultipartUpload(actualRequest).join();
     }
 

src/main/java/software/amazon/encryption/s3/internal/GetEncryptedObjectPipeline.java

@@ -5,13 +5,13 @@
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import software.amazon.encryption.s3.S3EncryptionClientException;
 
+import javax.crypto.SecretKey;
 import java.nio.charset.StandardCharsets;
 import java.security.GeneralSecurityException;
 import java.security.SecureRandom;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
-import javax.crypto.SecretKey;
 
 /**
  * This serves as the base class for all the keyrings in the S3 encryption client.
@@ -115,7 +115,11 @@ public DecryptionMaterials onDecrypt(final DecryptionMaterials materials, List<E
             throw new S3EncryptionClientException("The keyring does not support the object's key wrapping algorithm: " + keyProviderInfo);
         }
 
+        //= specification/s3-encryption/client.md#enable-legacy-wrapping-algorithms
+        //# When enabled, the S3EC MUST be able to decrypt objects encrypted with all supported wrapping algorithms (both legacy and fully supported).
         if (decryptStrategy.isLegacy() && !_enableLegacyWrappingAlgorithms) {
+            //= specification/s3-encryption/client.md#enable-legacy-wrapping-algorithms
+            //# When disabled, the S3EC MUST NOT decrypt objects encrypted using legacy wrapping algorithms.
             throw new S3EncryptionClientException("Enable legacy wrapping algorithms to use legacy key wrapping algorithm: " + keyProviderInfo);
         }