com.emc.object.s3.jersey

Class S3EncryptionClient

java.lang.Object

com.emc.object.AbstractJerseyClient

com.emc.object.s3.jersey.S3JerseyClient

com.emc.object.s3.jersey.S3EncryptionClient

All Implemented Interfaces:

S3Client

public class S3EncryptionClient
extends S3JerseyClient

Implements client-side encryption on top of the S3 API. Encryption method uses "Envelope Encryption". With envelope encryption, a master asymmetric (RSA) key is used to encrypt and decrypt a per-object symmetric (AES) key. This means that every object is encrypted using a unique key so breaking any one object's key does not compromise the encryption on other objects. Key rotation can also be accomplished by creating a new asymmetric key and re-encrypting the object keys without re-encrypting the actual object content.
To use encryption, you will first need to create a keystore, set a password, and then create an RSA key to use as your master encryption key. This can be accomplished using the 'keytool' application that comes with Java In this example, we create a 2048-bit RSA key and call it "masterkey". If the keystore does not already exist, it will be created an you will be prompted for a keystore password.

 $ keytool -genkeypair -keystore keystore.jks -alias masterkey -keyalg RSA \
   -keysize 2048 -dname "CN=My Name, OU=My Division, O=My Company, L=My Location, ST=MA, C=US"
 Enter keystore password: changeit
 Re-enter new password: changeit
 Enter key password for <masterkey>
   (RETURN if same as keystore password):
 

Inside your application, you can then construct and load a Keystore object, KeyStore.load(InputStream, char[]) Once the keystore has been loaded, you then construct a EncryptionConfig object with the keystore:

 EncryptionConfig ec = new EncryptionConfig(keystore,
             keystorePassword.toCharArray(), "masterkey", provider, 128);
 

The "provider" argument is used to specify the security provider to be used for cryptographic operations. You can set it to null to use the default provider(s) as specified in your jre/lib/security/java.security file. The final argument is the AES encryption key size. Note that most JDKs only support 128-bit AES encryption by default and required the "unlimited strength jurisdiction policy files" to be installed to achieve 256-bit support. See your JRE/JDK download page for details.
Once you have your EncryptionConfig, simply pass this to the constructor of S3EncryptionClient:

 S3Client s3Client = new S3EncryptionClient(s3Config, ec);
 

After you have your S3EncryptionClient constructed, you may use it like any other S3Client instance with the following limitations:

• Byte range (partial) reads are not supported
• Byte range (partial) updates including appends are not supported.
• Pre-signed URLs are not supported because there is no way to decompress and/or decrypt the content for the receiver.

Field Summary

Fields inherited from class com.emc.object.s3.jersey.S3JerseyClient

client, loadBalancer, s3Config, signer

Fields inherited from class com.emc.object.AbstractJerseyClient

objectConfig

Constructor Summary

Constructors

Constructor and Description
S3EncryptionClient(S3Config s3Config, com.sun.jersey.api.client.ClientHandler clientHandler, EncryptionConfig encryptionConfig)
S3EncryptionClient(S3Config s3Config, EncryptionConfig encryptionConfig)

Method Summary

Modifier and Type	Method and Description
void	abortMultipartUpload(AbortMultipartUploadRequest request)
CompleteMultipartUploadResult	completeMultipartUpload(CompleteMultipartUploadRequest request)
CopyObjectResult	copyObject(CopyObjectRequest request) Remotely copies an object using the parameters specified in request
CopyPartResult	copyPart(CopyPartRequest request)
<T> GetObjectResult<T>	getObject(GetObjectRequest request, java.lang.Class<T> objectType) Gets an object using the parameters specified in request.
java.net.URL	getPresignedUrl(PresignedUrlRequest request) Generates a pre-signed URL using the parameters specified in request
InitiateMultipartUploadResult	initiateMultipartUpload(InitiateMultipartUploadRequest request)
PutObjectResult	putObject(PutObjectRequest request) Encrypted version of S3JerseyClient.putObject(PutObjectRequest).
boolean	rekey(java.lang.String bucketName, java.lang.String key) "Rekeys" an object.
void	setObjectMetadata(java.lang.String bucketName, java.lang.String key, S3ObjectMetadata objectMetadata) Sets metadata on object key in bucket bucketName
MultipartPartETag	uploadPart(UploadPartRequest request)

Methods inherited from class com.emc.object.s3.jersey.S3JerseyClient

appendObject, bucketExists, copyObject, copyRange, createBucket, createBucket, deleteBucket, deleteBucket, deleteBucketCors, deleteBucketLifecycle, deleteBucketPolicy, deleteObject, deleteObject, deleteObjects, deleteObjectTagging, deleteVersion, destroy, enableObjectLock, executeRequest, extendRetentionPeriod, finalize, getBucketAcl, getBucketCors, getBucketDeletionStatus, getBucketInfo, getBucketLifecycle, getBucketLocation, getBucketPolicy, getBucketVersioning, getLoadBalancer, getObject, getObjectAcl, getObjectAcl, getObjectLegalHold, getObjectLockConfiguration, getObjectMetadata, getObjectMetadata, getObjectRetention, getObjectTagging, getPresignedUrl, getS3Config, initiateMultipartUpload, listBucketMetadataSearchKeys, listBuckets, listBuckets, listDataNodes, listMoreObjects, listMoreVersions, listMultipartUploads, listMultipartUploads, listObjects, listObjects, listObjects, listParts, listParts, listSystemMetadataSearchKeys, listVersions, listVersions, pingNode, pingNode, putObject, putObject, putObjectTagging, queryMoreObjects, queryObjects, readObject, readObject, readObjectStream, setBucketAcl, setBucketAcl, setBucketAcl, setBucketCors, setBucketLifecycle, setBucketPolicy, setBucketStaleReadAllowed, setBucketVersioning, setObjectAcl, setObjectAcl, setObjectAcl, setObjectLegalHold, setObjectLockConfiguration, setObjectRetention, shutdown

Methods inherited from class com.emc.object.AbstractJerseyClient

buildRequest, executeAndClose, executeRequest, fillResponseEntity, getObjectConfig

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

S3EncryptionClient

public S3EncryptionClient(S3Config s3Config,
                          EncryptionConfig encryptionConfig)

S3EncryptionClient

public S3EncryptionClient(S3Config s3Config,
                          com.sun.jersey.api.client.ClientHandler clientHandler,
                          EncryptionConfig encryptionConfig)

Method Detail

rekey

public boolean rekey(java.lang.String bucketName,
                     java.lang.String key)

"Rekeys" an object. This operation re-encrypts the object's key with the most current master key and is used to implement key rotation. Note that when you create a new master key, your EncryptionConfig should keep all of the old master key(s) until you have rekeyed all of the objects so you can decrypt the old objects.

Parameters:

bucketName - the name of the bucket that holds the object to rekey.

key - the name of the object to rekey.

Returns:

true if the object was successfully rekeyed, false if the object already uses the new key

Throws:

java.lang.IllegalArgumentException - if the object is not encrypted

putObject

public PutObjectResult putObject(PutObjectRequest request)

Encrypted version of S3JerseyClient.putObject(PutObjectRequest).

Note: this method will write the encrypted object first, then update the metadata to finalize encryption properties (including original SHA1 and metadata signature). For version-enabled buckets, this will create 2 versions.

Specified by:

putObject in interface S3Client

Overrides:

putObject in class S3JerseyClient

getObject

public <T> GetObjectResult<T> getObject(GetObjectRequest request,
                                        java.lang.Class<T> objectType)

Description copied from interface: S3Client

Gets an object using the parameters specified in request. Object details as well as the translated data (converted to objectType) are contained in the GetObjectResult instance.

Note: this method will return null for 304 and 412 responses (failed preconditions). This method will open a stream for the object data. Be sure to call getObject() and, if requesting an InputStream, properly close the stream to release the connection.

Specified by:

getObject in interface S3Client

Overrides:

getObject in class S3JerseyClient

copyObject

public CopyObjectResult copyObject(CopyObjectRequest request)

Description copied from interface: S3Client

Remotely copies an object using the parameters specified in request

Specified by:

copyObject in interface S3Client

Overrides:

copyObject in class S3JerseyClient

getPresignedUrl

public java.net.URL getPresignedUrl(PresignedUrlRequest request)

Description copied from interface: S3Client

Generates a pre-signed URL using the parameters specified in request

Specified by:

getPresignedUrl in interface S3Client

Overrides:

getPresignedUrl in class S3JerseyClient

setObjectMetadata

public void setObjectMetadata(java.lang.String bucketName,
                              java.lang.String key,
                              S3ObjectMetadata objectMetadata)

Description copied from interface: S3Client

Sets metadata on object key in bucket bucketName

Specified by:

setObjectMetadata in interface S3Client

Overrides:

setObjectMetadata in class S3JerseyClient

initiateMultipartUpload

public InitiateMultipartUploadResult initiateMultipartUpload(InitiateMultipartUploadRequest request)

Specified by:

initiateMultipartUpload in interface S3Client

Overrides:

initiateMultipartUpload in class S3JerseyClient

uploadPart

public MultipartPartETag uploadPart(UploadPartRequest request)

Specified by:

uploadPart in interface S3Client

Overrides:

uploadPart in class S3JerseyClient

copyPart

public CopyPartResult copyPart(CopyPartRequest request)

Specified by:

copyPart in interface S3Client

Overrides:

copyPart in class S3JerseyClient

completeMultipartUpload

public CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request)

Specified by:

completeMultipartUpload in interface S3Client

Overrides:

completeMultipartUpload in class S3JerseyClient

abortMultipartUpload

public void abortMultipartUpload(AbortMultipartUploadRequest request)

Specified by:

abortMultipartUpload in interface S3Client

Overrides:

abortMultipartUpload in class S3JerseyClient