Category: AWS SDK for PHP*


Using Client-Side Encryption for Amazon S3 in the AWS SDK for PHP

The AWS SDK for PHP released an S3EncryptionClient in version 3.38.0. With client-side encryption, data is encrypted and decrypted directly in your environment. This means that this data is encrypted before it’s transferred to Amazon S3, and you don’t rely on an external service to handle encryption for you.

The AWS SDK for PHP implements envelope encryption and uses OpenSSL for its encrypting and decrypting. The implementation is interoperable with other SDKs that match its feature support. It’s also compatible with the SDK’s promise-based asynchronous workflow.

Setup

To get started with these client-side encryption examples, you need the following:

Encryption

Uploading an encrypted object through the PutObject operation takes a similar interface and requires two new parameters. Let’s take a look:

	
	// Let's construct our S3EncryptionClient using an S3Client
	$encryptionClient = new S3EncryptionClient(
		new S3Client([
			'region' => 'us-east-1',
			'version' => 'latest',
		])
	);

	$kmsKeyArn = 'arn-to-the-kms-key';
	// This materials provider handles generating a cipher key and initialization
	// vector, as well as encrypting your cipher key via AWS KMS
	$materialsProvider = new KmsMaterialsProvider(
		new KmsClient([
			'region' => 'us-east-1',
			'version' => 'latest',
		]),
		$kmsKeyArn
	);

	$bucket = 'the-bucket-name';
	$key = 'the-upload-key';
	$cipherOptions = [
		'Cipher' => 'gcm'
		'KeySize' => 256,
		// Additional configuration options
	];

	$result = $encryptionClient->putObject([
		'@MaterialsProvider' => $materialsProvider,
		'@CipherOptions' => $cipherOptions,
		'Bucket' => $bucket,
		'Key' => $key,
		'Body' => fopen('file-to-encrypt.txt'),
	]);
	

Decryption

Downloading and decrypting an object requires only one additional parameter on top of GetObject, and the client will detect the basic cipher options for you. Additional configuration options are passed through for decryption.

	
	$result = $encryptionClient->getObject([
		'@MaterialsProvider' => $materialsProvider,
		'@CipherOptions' => [
			// Additional configuration options
		], 
		'Bucket' => $bucket,
		'Key' => $key,
	]);
	

Going further

The S3EncryptionClient gives you access to other fields. These include an additional authentication data (‘Aad’) string to put in your $cipherOptions and the ability to define a MetadataStrategy. You can find more information about these topics in the service guide.

You can also check out other AWS SDKs that support the Amazon S3 encryption client:

Updated Composer Dependencies for AWS SDK for PHP Version 3

In version 3.34.0, the AWS SDK for PHP is updated to correctly communicate its dependencies on PHP extensions through Composer. Several extensions included in many common PHP distributions are not guaranteed to be installed or enabled. In earlier versions, the SDK silently required each of the following extensions, which would cause errors at runtime if not present:

After this update, when you install the SDK via Composer, you will be notified of the SDK’s reliance on these extensions. Updates via Composer will fail if you don’t have these extensions installed or enabled. You’ll receive a message similar to the following:

The compatibility-test.php file is also updated to reflect the correct dependencies.

Automated Changelog in AWS SDK for PHP

Starting with version 3.22.10 of the AWS SDK for PHP, released February 23, 2017, the Changelog Builder automatically processes all changelog entries. Each pull request is required to have a changelog JSON blob as part of the request. The system also calculates the next version for the SDK based on the type of the changes that are defined in the given changelog JSON blob.

The update simplifies the process of adding release notes to the CHANGELOG.md file for each pull request. Each merged pull request that was part of the release results in a new entry to the CHANGELOG.md file. The entry describes the change and provides the TAG number and release date.

The following is a sample changelog blob.

[
    {
        "type"       : "feature|enhancement|bugfix",
        "category"   : "Target of Update",
        "description": "English language simple description of your update."
    }
]

Each changelog blob is required to define the “type”, “category”, and “description” fields. The “category” explains the service that the change is associated with. For SDK changes that are not related to any service, the category field is left as an empty string. The “description” field should contain one or two sentences detailing the changes.

The “type” field describes the scope of the change being proposed. This field helps the Changelog Builder decide if a minor version bump is needed. The “type” field is assigned one of the following values:

  1. feature: A major change to the SDK that will cause a minor version bump. A feature will open a new use case or significantly improve upon an existing one. The update will result in a minor version bump. Example: a new AWS service.
  2. enhancement: A small update to the code. This should not cause any code to break and should only enhance given functionality of the SDK. The update will result in a patch version update. Example: Documentation Update.
  3. bugfix: A fix in the code that has caused some unwanted behavior. The update will result in a patch version update.

The changelog blob that will be included in the next release must be put inside the .changes/nextrelease folder. The changelog blob file name must be unique in that folder. A good practice is to give a descriptive name to the changelog blob file related to the request.

On each release, the SDK looks inside the .changes/nextrelease folder and consolidates all JSON blobs into a single JSON document. Then the SDK calculates the next version number, based on the full JSON document.

Example:

Current SDK Version: 1.2.3
Changelog Blob File 1: update-s3-client.json

[
    {
        "type"       : "enhancement",
        "category"   : "S3",
        "description": "Adds support for new feature in s3"
    }
]

Changelog Blob File 2: ec2-documentation-update.json

[
    {
        "type"       : "enhancement",
        "category"   : "EC2",
        "description": "Update Ec2 documentation for operation foo bar"
    }
]

Changelog Blob File 3: sdk-bugfix.json

[
    {
        "type"       : "bugfix",
        "category"   : "",
        "description": "Fixes a typo in Aws Client"
    }
]

Consolidated JSON document: .changes/1.2.4.json
Next SDK version: 1.2.4

[
  {
    "type": "enhancement",
    "category": "S3",
    "description": "Adds support for new feature in s3"
  },
  {
    "type": "enhancement",
    "category": "EC2",
    "description": "Update Ec2 documentation for operation foo bar"
  },
  {
    "type": "bugfix",
    "category": "",
    "description": "Fixes a typo in Aws Client"
  }
]

A new file, with the name VERSION_NUMBER.json, will be created in the .changes folder with the contents of the JSON blob for the changelog. You can see the previous changelog JSON blobs here. If needed, we can reconstruct the CHANGELOG.md file using the JSON documents in the .changes folder.

On a successful release, the changelog entries are written to the top of the CHANGELOG.md file. Then chag is used to tag the SDK and label the added release notes with the current version number.

For more information about Changelog Builder, see Class Aws\Build\ChangelogBuilder and CONTRIBUTING.md.