Amazon S3 Encryption Client for Java examples - Amazon S3 Encryption Client
Instantiating the Amazon S3 Encryption ClientEncrypting and decrypting objectsRanged GET requestsMultipart upload

Amazon S3 Encryption Client for Java examples

The following examples show you how to use the Amazon S3 Encryption Client for Java to encrypt and decrypt Amazon S3 objects. These examples show how to use version 3.x of the Amazon S3 Encryption Client for Java. For more detailed examples, see the amazon-s3-encryption-client-java GitHub repository.

Instantiating the Amazon S3 Encryption Client

After installing the Amazon S3 Encryption Client for Java, you are ready to instantiate your client and begin encrypting and decrypting your Amazon S3 objects. If you have encrypted objects under a previous version of the Amazon S3 Encryption Client, you may need to enable legacy decryption modes when you instantiate the updated client. For more information, see Migrating to version 3.x of the Amazon S3 Encryption Client for Java.

With version 3.x of the Amazon S3 Encryption Client for Java, you can instantiate your client specifying the builder parameter that identifies your wrapping key. The Amazon S3 Encryption Client supports the following wrapping keys: symmetric AWS KMS keys, Raw AES-GCM keys, and Raw RSA keys. Then, the Amazon S3 Encryption Client automatically configures a keyring based on the wrapping key type with default settings and a default cryptographic materials manager (CMM). If you want to customize your client, you can also manually configure your keyring.

Note

If you use Raw RSA or Raw AES-GCM wrapping keys, you are responsible for generating, storing, and protecting the key material, preferably in a hardware security module (HSM) or key management system.

The following examples instantiate the Amazon S3 Encryption Client with the default decryption mode. This means that all objects will be decrypted using the fully supported buffered decryption mode. For more information, see Decryption modes (Version 3.x and later).

AWS KMS wrapping key

To specify a KMS key as your wrapping key, instantiate your client with the kmsKeyId builder parameter.

To use a KMS key as your wrapping key, you need kms:GenerateDataKey and kms:Decrypt permissions on the KMS key. The value of the kmsKeyId parameter can be any valid KMS key identifier. For details, see Key identifiers in the AWS Key Management Service Developer Guide.

// v3

class v3KMSKeyExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .kmsKeyId(kmsKeyId)
                .build();
    }
}

Raw AES wrapping key

To specify a Raw AES key (javax.crypto.SecretKey) as your wrapping key, instantiate your client with the aesKey builder parameter.

// v3

class v3AESKeyExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .build();
    }
}

Raw RSA wrapping key

To specify a Raw RSA key (java.security.KeyPair) as your wrapping key, instantiate your client with the rsaKeyPair builder parameter. You can specify an entire RSA key pair or a partial RSA key pair. The value of the rsaKeyPair parameter must include both the public and private keys in the key pair to perform both encrypt and decrypt operations. You can specify the public key to enable the Amazon S3 Encryption Client to perform encrypt operations, or the private key to enable decrypt operations as needed. By specifying a partial key pair you can limit the exposure of your keys. For examples using a partial key pair, see the amazon-s3-encryption-client-java GitHub repository.

RSA key pair

To instantiate version 3.x of the client to perform both encrypt and decrypt operations, specify both the public and private keys of your key pair.

// v3
                       
class v3RSAKeyPairExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .rsaKeyPair(rsaKeyPair)
                .build();
    }
}
Public key

To instantiate the client to encrypt only, specify the public key. If you specify the public key alone, all GetObject calls will fail because the private key is required to decrypt.

// v3
                   
class v3RSAKeyPairExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .rsaKeyPair(new PartialRsaKeyPair(null, rsaKeyPair.getPublic()))
                .build();
    }
}
Private key

To instantiate the client to decrypt only, specify the private key. If you specify the private key alone, all PutObject calls will fail because the public key is required to encrypt.

// v3
                       
class v3RSAKeyPairExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .rsaKeyPair(new PartialRsaKeyPair(rsaKeyPair.getPrivate(), null))
                .build();
    }
}

Manually instantiate the client

If you want to customize your client, you can manually configure your own keyring and cryptographic materials manager (CMM). The following example manually configures an AWS KMS keyring using a symmetric encryption AWS KMS wrapping key and passes the custom AWS KMS client to the Amazon S3 Encryption Client.

// v3
class v3CustomKeyringExample {
    public static void main(String[] args) {
        KmsKeyring keyring = KmsKeyring.builder()
            .wrappingKeyId(KMS_KEY_ID)
            .kmsClient(customKmsClient)
            .build();

        CryptographicMaterialsManager cmm = DefaultCryptoMaterialsManager.builder()
            .keyring(keyring)
            .build();

        S3Client v3Client = S3EncryptionClient.builder()
            .cryptoMaterialsManager(cmm)
            .build();
    }
}

Encrypting and decrypting Amazon S3 objects

The following example shows you how to use the Amazon S3 Encryption Client for Java to encrypt and decrypt Amazon S3 objects.

This example uses a Raw RSA wrapping key and instantiates the Amazon S3 Encryption Client with the default decryption mode.

  1. Specify your wrapping key by passing it to the Amazon S3 Encryption Client when you instantiate your client. The Amazon S3 Encryption Client for Java automatically configures a keyring based on the wrapping key you specify.

    // v3
                       
class v3RSAKeyPairExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .rsaKeyPair(rsaKeyPair)
                .build();
    }
}

  2. Encrypt your plaintext object by calling PutObject.

    1. The Amazon S3 Encryption Client provides the encryption materials: one plaintext data key and one copy of that data key encrypted by your wrapping key.

    2. The Amazon S3 Encryption Client uses the plaintext data key to encrypt your object, and then discards the plaintext data key.

    3. The Amazon S3 Encryption Client uploads the encrypted data key and the encrypted object to Amazon S3 as part of the PutObject call.

    // v3

class v3EncryptExample {
    public static void main(String[] args) {
        s3Client.putObject(PutObjectRequest.builder()
                        .bucket(bucket)
                        .key(objectKey)
                        .build(), RequestBody.fromString(objectContent));
    }
}

  3. Decrypt your encrypted object by calling GetObject.

    1. The Amazon S3 Encryption Client uses your wrapping key to decrypt the encrypted data key.

    2. The Amazon S3 Encryption Client uses the plaintext data key to decrypt the object, discards the plaintext data key, and returns the plaintext object as part of the GetObject call.

    // v3
  
class v3DecryptExample {
    public static void main(String[] args) {
        ResponseBytes<GetObjectResponse> objectResponse = s3Client.getObjectAsBytes(builder -> builder
                .bucket(bucket)
                .key(objectKey));
        String output = objectResponse.asUtf8String();
    }
}
    Note

    The default decryption mode cannot decrypt objects larger than 64 MB. This decryption mode automatically buffers stream contents into memory to prevent the release of unauthenticated objects. If you attempt to decrypt an object larger than 64 MB, you will receive an exception directing you to enable the delayed authentication decryption mode. For more information, see Decryption modes.

  4. Optional: verify that the decrypted object matches the original plaintext object that you uploaded.

    assert output.equals(objectContent);

  5. The Amazon S3 Encryption Client implements the AutoClosable interface, which automatically calls close() when you exit a try-with-resources block for which the object has been declared in the resource specification header. As a best practice, you should either use try-with-resources or explicitly call the close() method.

    s3Client.close();

Ranged GET requests

With Amazon S3, you can download a specific part of an object by performing a ranged GET request. In version 3.x of the Amazon S3 Encryption Client, you must explicitly enable the unauthenticated legacy decryption mode to perform ranged requests.

By default, version 3.x of the Amazon S3 Encryption Client encrypts and decrypts your objects using the AES-GCM algorithm suite. However, you can enable it to use the legacy AES-CTR algorithm to partially decrypt your object during a ranged GET request. The Amazon S3 Encryption Client cannot use AES-GCM for ranged gets because it is an authenticated scheme that appends an authentication tag to the encrypted object. When you request a partial object, the client cannot read the entire object stream to reach the authenticated tag. This means that the partial object is not authenticated.

Specifying a range

You can include the Range parameter in your GetObject request to download and decrypt a specific byte-range from an object. The start and end indices of the byte range are included in the partial object. The byte-range you specify should reflect to the following format:

range("bytes=startIndex–endIndex")

The following list details how the Amazon S3 Encryption Client responds to ranged requests that specify an invalid byte-range. For more detailed examples, see the amazon-s3-encryption-client-java GitHub repository.

  • When the start index is within object range but the end index is greater than the object's total length, the Amazon S3 Encryption Client returns the object from the start index to the end of the original plaintext object.

  • When the start index is greater than the end index, the Amazon S3 Encryption Client returns the entire object.

  • When the range is specified with an invalid format, the Amazon S3 Encryption Client returns the entire object.

    For example, if the range was specified as range("10-20"), instead of range("bytes=10-20"), then the Amazon S3 Encryption Client will return the entire object.

  • When both the start and end indicies are greater than the original plaintext object's total length, but still within the same cipher block, the Amazon S3 Encryption Client returns an empty object.

  • When both the start and end indicies are greater than the original plaintext object's total length, and are outside of the object's cipher block, the GetObject request fails.

Performing a ranged request

The following walkthrough explains how to perform a ranged request when using version 3.x of the Amazon S3 Encryption Client.

  1. Enable ranged gets by specifying the enableLegacyUnauthenticatedModes parameter when you instantiate your client.

    The following example specifies a raw AES key as the wrapping key.

    // v3
                       
class v3EnableRangedGetsExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .enableLegacyUnauthenticatedModes(true)
                .build();
    }
}

  2. Partially decrypt your encrypted object by specifying the byte-range in your GetObject request.

    The following example specifies a start index at byte 10 and end index at byte 20.

    // v3
                       
class v3RangedGetExample {
    public static void main(String[] args) {
        ResponseBytes<GetObjectResponse> objectResponse = v3Client.getObjectAsBytes(builder -> builder
                .bucket(bucket)
                .range("bytes=10-20")
                .key(objectKey));
        String output = objectResponse.asUtf8String();
    }
}

  3. Optional: verify that the decrypted partial object matches the original plaintext object that you uploaded at the same range.

    assert output.equals(objectContent);

  4. The Amazon S3 Encryption Client implements the AutoClosable interface, which automatically calls close() when you exit a try-with-resources block for which the object has been declared in the resource specification header. As a best practice, you should either use try-with-resources or explicitly call the close() method.

    s3Client.close();

Multipart upload

Amazon S3 allows you to upload a single object as a set of parts using multipart uploads. Amazon S3 recommends that when your object size reaches 100 MB, you should consider using multipart uploads. In version 3.x of the Amazon S3 Encryption Client, you can perform multipart uploads with the low-level API or the high-level API. Use the low-level API when you need to vary part sizes during the upload or require more control over the multipart upload process. Use the high-level API to simplify the multipart upload process by enabling the Amazon S3 Encryption Client to automatically perform multipart uploads.

Multipart Upload (high-level API)

When you use the high-level API, the Amazon S3 Encryption Client automatically performs multipart uploads for all objects larger than 5 MB. The Amazon S3 Encryption Client encrypts the object locally and then calls the AWS CRT-based Amazon S3 client to perform the multipart upload to Amazon S3.

Note

If your permissions to access required Amazon S3 resources or KMS keys are revoked during a multipart upload using the high-level API, the in-progress request may upload successfully. Subsequent multipart upload requests will fail.

To enable automatic multipart uploads with the high-level API, you must add dependencies for the AWS CRT-based Amazon S3 client to your Maven project file and specify the enableMultipartPutObject parameter when you instantiate your client.

Add dependencies

To use the AWS CRT-based Amazon S3 client with the Amazon S3 Encryption Client, add the following two dependencies. For more information on creating dependencies and installing the Amazon S3 Encryption Client, see Installing the Amazon S3 Encryption Client for Java.

<dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>s3</artifactId>
  <version>2.19.3
<dependency>
  <groupId>software.amazon.awssdk.crt</groupId>
  <artifactId>aws-crt</artifactId>
  <version>0.21.5</version>
</dependency>
Enable multipart upload

To enable the Amazon S3 Encryption Client to automatically perform multipart uploads, specify the enableMultipartPutObject parameter when you instantiate your client.

The following example specifies a raw AES key as the wrapping key.

// v3
                       
class v3EnableMultipartUploadExample {
    public static void main(String[] args) {
        S3Client v3Client = S3EncryptionClient.builder()
                .aesKey(aesKey)
                .enableMultipartPutObject(true)
                .build();
    }
}

Multipart Upload (low-level API)

The Amazon S3 Encryption Client does not require any additional configuration to use the low-level API. Use the following API calls to generate a multipart upload request with version 3.x of the Amazon S3 Encryption Client.

  1. Start the multipart upload process by calling CreateMultipartUpload.

  2. Call UploadPart to upload each part of your object. When you upload the final part, you must specify isLastPart for the Amazon S3 Encryption Client to be able to call cipher.doFinal()

    // v3
                       
class v3UploadFinalPartExample {
    public static void main(String[] args) {
         UploadPartRequest uploadPartRequest = UploadPartRequest.builder()
                    .bucket(bucket)
                    .key(objectKey)
                    .uploadId(initiateResult.uploadId())
                    .partNumber(partsSent)
                    .overrideConfiguration(isLastPart(true))
                    .build();        
    }
}

  3. Call CompleteMultipartUpload to finish the process.