AWS Encryption SDK Developer Guide
User Manual:
Open the PDF directly: View PDF .
Page Count: 104
Download | ![]() |
Open PDF In Browser | View PDF |
AWS Encryption SDK Developer Guide AWS Encryption SDK Developer Guide AWS Encryption SDK: Developer Guide Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon. AWS Encryption SDK Developer Guide Table of Contents What Is the AWS Encryption SDK? ....................................................................................................... 1 Where to find more information .................................................................................................. 2 How the SDK Works ................................................................................................................... 2 Symmetric Key Encryption .................................................................................................. 2 Envelope Encryption ........................................................................................................... 3 AWS Encryption SDK Encryption Workflows .......................................................................... 4 Concepts ................................................................................................................................... 5 Data Keys .......................................................................................................................... 6 Master key ........................................................................................................................ 6 Master key operations: Generate, Encrypt, Decrypt ................................................................. 6 Master key provider ............................................................................................................ 7 Cryptographic Materials Manager ......................................................................................... 7 Algorithm Suite ................................................................................................................. 7 Encryption Context ............................................................................................................. 8 Encrypted Message ............................................................................................................. 8 Getting Started .................................................................................................................................. 9 Supported Algorithm Suites .............................................................................................................. 10 Recommended: AES-GCM with Key Derivation and Signing ............................................................ 10 Other Supported Algorithm Suites ............................................................................................. 11 Programming Languages ................................................................................................................... 12 Java ........................................................................................................................................ 12 Prerequisites .................................................................................................................... 12 Installation ...................................................................................................................... 13 Example Code .................................................................................................................. 13 Python .................................................................................................................................... 20 Prerequisites .................................................................................................................... 20 Installation ...................................................................................................................... 20 Example Code .................................................................................................................. 21 Command Line Interface ........................................................................................................... 26 Installing the CLI .............................................................................................................. 27 How to Use the CLI .......................................................................................................... 29 Examples ......................................................................................................................... 36 Syntax and Parameter Reference ........................................................................................ 49 Data Key Caching ............................................................................................................................. 55 How to Implement Data Key Caching ......................................................................................... 55 Implement Data Key Caching: Step-by-Step ......................................................................... 56 Data Key Caching Example: Encrypt a String ........................................................................ 58 Setting Cache Security Thresholds .............................................................................................. 60 Data Key Caching Details .......................................................................................................... 61 How Data Key Caching Works ............................................................................................ 62 Creating a Cryptographic Materials Cache ............................................................................ 64 Creating a Caching Cryptographic Materials Manager ............................................................ 65 What Is in a Data Key Cache Entry? .................................................................................... 65 Encryption Context: How to Select Cache Entries ................................................................. 66 Data Key Caching Example ........................................................................................................ 66 LocalCryptoMaterialsCache Results ..................................................................................... 67 Java Example ................................................................................................................... 68 Python Example ............................................................................................................... 72 AWS CloudFormation Template .......................................................................................... 75 Frequently Asked Questions ............................................................................................................... 79 Reference ........................................................................................................................................ 82 Message Format Reference ........................................................................................................ 82 Header Structure .............................................................................................................. 83 Body Structure ................................................................................................................. 87 iii AWS Encryption SDK Developer Guide Footer Structure ............................................................................................................... Body AAD Reference ................................................................................................................. Message Format Examples ......................................................................................................... Non-Framed Data ............................................................................................................. Framed Data .................................................................................................................... Algorithms Reference ................................................................................................................ Initialization Vector Reference .................................................................................................... Document History ............................................................................................................................ Recent Updates ........................................................................................................................ Earlier Updates ........................................................................................................................ iv 89 90 91 91 93 96 98 99 99 99 AWS Encryption SDK Developer Guide What Is the AWS Encryption SDK? The AWS Encryption SDK is an encryption library that helps make it easier for you to implement encryption best practices in your application. It enables you to focus on the core functionality of your application, rather than on how to best encrypt and decrypt your data. The AWS Encryption SDK answers questions like the following for you: • Which encryption algorithm should I use? • How, or in which mode, should I use that algorithm? • How do I generate the encryption key? • How do I protect the encryption key, and where should I store it? • How can I make my encrypted data portable? • How do I ensure that the intended recipient can read my encrypted data? • How can I ensure my encrypted data is not modified between the time it is written and when it is read? Without the AWS Encryption SDK, you might spend more effort on building an encryption solution than on the core functionality of your application. The AWS Encryption SDK answers these questions by providing the following things. A Default Implementation that Adheres to Cryptography Best Practices By default, the AWS Encryption SDK generates a unique data key for each data object that it encrypts. This follows the cryptography best practice of using unique data keys for each encryption operation. The AWS Encryption SDK encrypts your data using a secure, authenticated, symmetric key algorithm. For more information, see Supported Algorithm Suites (p. 10). A Framework for Protecting Data Keys with Master Keys The AWS Encryption SDK protects the data keys that encrypt your data by encrypting them under one or more master keys. By providing a framework to encrypt data keys with more than one master key, the AWS Encryption SDK helps make your encrypted data portable. For example, you can encrypt data under multiple AWS Key Management Service (AWS KMS) customer master keys (CMKs), each in a different AWS Region. Then you can copy the encrypted data to any of the regions and use the CMK in that region to decrypt it. You can also encrypt data under a CMK in AWS KMS and a master key in an on-premises HSM, enabling you to later decrypt the data even if one of the options is unavailable. A Formatted Message that Stores Encrypted Data Keys with the Encrypted Data The AWS Encryption SDK stores the encrypted data and encrypted data key together in an encrypted message (p. 8) that uses a defined data format. This means you don't need to keep track of or protect the data keys that encrypt your data because the AWS Encryption SDK does it for you. With the AWS Encryption SDK, you define a master key provider (p. 7) that returns one or more master keys (p. 6). Then you encrypt and decrypt your data using straightforward methods provided by the AWS Encryption SDK. The AWS Encryption SDK does the rest. 1 AWS Encryption SDK Developer Guide Where to find more information Where to find more information If you're looking for more information about the AWS Encryption SDK and client-side encryption, try these sources. • To get started quickly, see Getting Started (p. 9). • For information about how this SDK works, see How the SDK Works (p. 2). • For help with the terms and concepts used in this SDK, see Concepts in the AWS Encryption SDK (p. 5). • For detailed technical information, see the Reference (p. 82). • For answers to your questions about using the AWS Encryption SDK, read and post on the AWS Crypto Tools Discussion Forum. For information about implementations of the AWS Encryption SDK in different programming languages. • Java: See AWS Encryption SDK for Java (p. 12), the AWS Encryption SDK Javadoc, and the awsencryption-sdk-java repository on GitHub. • Python: See AWS Encryption SDK for Python (p. 20), the AWS Encryption SDK Python documentation, and the aws-encryption-sdk-python repository on GitHub. • Command Line Interface: See AWS Encryption SDK Command Line Interface (p. 26), Read the Docs for the AWS Encryption CLI, and the aws-encryption-sdk-cli repository on GitHub. If you have questions or comments about this guide, let us know! Choose the feedback link in the lowerright corner of the page or the GitHub link in the upper-right corner of the page. You can also file an issue in the aws-encryption-sdk-docs GitHub repository for this guide. The AWS Encryption SDK is provided free of charge under the Apache license. How the AWS Encryption SDK Works The AWS Encryption SDK uses envelope encryption to protect your data and the corresponding data keys. For more information, see the following topics. Topics • Symmetric Key Encryption (p. 2) • Envelope Encryption (p. 3) • AWS Encryption SDK Encryption Workflows (p. 4) Symmetric Key Encryption To encrypt data, the AWS Encryption SDK provides raw data, known as plaintext data, and a data key to an encryption algorithm. The encryption algorithm uses those inputs to encrypt the data. Then, the AWS Encryption SDK returns an encrypted message (p. 8) that includes the encrypted data and an encrypted copy of the data key. To decrypt the encrypted message, the AWS Encryption SDK provides the encrypted message to a decryption algorithm that uses those inputs to return the plaintext data. Because the same data key is used to encrypt and decrypt the data, the operations are known as symmetric key encryption and decryption. The following figure shows symmetric key encryption and decryption in the AWS Encryption SDK. 2 AWS Encryption SDK Developer Guide Envelope Encryption Envelope Encryption The security of your encrypted data depends on protecting the data key that can decrypt it. One accepted best practice for protecting the data key is to encrypt it. To do this, you need another encryption key, known as a master key (p. 6). This practice of using a master key to encrypt data keys is known as envelope encryption. Some of the benefits of envelope encryption include the following. Protecting Data Keys When you encrypt a data key, you don't have to worry about where to store it because the data key is inherently protected by encryption. You can safely store the encrypted data key with the encrypted data. The AWS Encryption SDK does this for you. It saves the encrypted data and the encrypted data key together in an encrypted message (p. 8). Encrypting the Same Data Under Multiple Master Keys Encryption operations can be time-consuming, particularly when the data being encrypted are large objects. Instead of reencrypting raw data multiple times with different keys, you can reencrypt only the data keys that protect the raw data. Combining the Strengths of Multiple Algorithms In general, symmetric key encryption algorithms are faster and produce smaller ciphertexts than assymetric or public key encryption. But, public key algorithms provide inherent separation of roles and easier key management. You might want to combine the strengths of each. For example, you might encrypt raw data with symmetric key encryption, and then encrypt the data key with public key encryption. The AWS Encryption SDK uses envelope encryption. It encrypts your data with a data key. Then, it encrypts the data key with a master key. The AWS Encryption SDK returns the encrypted data and the encrypted data keys in a single encrypted message, as shown in the following diagram. 3 AWS Encryption SDK Developer Guide AWS Encryption SDK Encryption Workflows If you have multiple master keys, each of them can encrypt the plaintext data key. Then, the AWS Encryption SDK returns an encrypted message that contains the encrypted data and the collection of encrypted data keys. Any one of the master keys can decrypt one of the encrypted data keys, which can then decrypt the data. When you use envelope encryption, you must protect your master keys from unauthorized access. You can do this in one of the following ways: • Use a web service designed for this purpose, such as AWS Key Management Service (AWS KMS). • Use a hardware security module (HSM) such as those offered by AWS CloudHSM. • Use your existing key management tools. If you don't have a key management system, we recommend AWS KMS. The AWS Encryption SDK integrates with AWS KMS to help you protect and use your master keys. You can also use the AWS Encryption SDK with other master key providers, including custom ones that you define. Even if you don't use AWS, you can still use this AWS Encryption SDK. AWS Encryption SDK Encryption Workflows The workflows in this section explain how the SDK encrypts data and decrypts encrypted messages (p. 8). They show how the SDK uses the components that you create, including the cryptographic materials manager (p. 7) (CMM), master key provider (p. 7), and master key (p. 6), to respond to encryption and decryption requests from your application. How the SDK Encrypts Data The SDK provides methods that encrypt strings, byte arrays, and byte streams. For code examples showing calls to encrypt and decrypt strings and byte streams in each supported programming languages, see the examples in the Programming Languages (p. 12) section. 1. Your application passes plaintext data to one of the encryption methods. To indicate the source of the data keys (p. 6) that you want to use to encrypt your data, your request specifies a cryptographic materials manager (CMM) or a master key provider. (If you specify a master key provider, the AWS Encryption SDK creates a default CMM that interacts with your chosen master key provider.) 2. The encryption method asks the CMM for data keys (and related cryptographic material). 4 AWS Encryption SDK Developer Guide Concepts 3. The CMM gets a master key (p. 6) from its master key provider. Note If you are using AWS Key Management Service (AWS KMS), the KMS master key object that is returned identifies the CMK, but the actual CMK never leaves the AWS KMS service. 4. The CMM asks the master key to generate a data key. The master key returns two copies of the data key, one in plaintext and one encrypted under the master key. 5. The CMM returns the plaintext and encrypted data keys to the encryption method. 6. The encryption method uses the plaintext data key to encrypt the data, and then discards the plaintext data key. 7. The encryption method returns an encrypted message (p. 8) that contains the encrypted data and the encrypted data key. How the SDK Decrypts an Encrypted Message The SDK provides methods that decrypt an encrypted message and return plaintext strings, byte arrays, or byte streams. For code examples in each supported programming languages, see the examples in the Programming Languages (p. 12) section. 1. Your application passes an encrypted message to a decryption method. To indicate the source of the data keys (p. 6) that were used to encrypt your data, your request specifies a cryptographic materials manager (CMM) or a master key provider. (If you specify a master key provider, the AWS Encryption SDK creates a default CMM that interacts with the specified master key provider.) 2. The decryption method asks the CMM for cryptographic materials to decrypt the encrypted message. It passes in information from the message header, including the encrypted data keys. 3. To get decryption materials, the Default CMM asks its master key provider for a master key that can decrypt the encrypted data key. It uses the master key to decrypt the encrypted data key. Then, it returns the decryption materials (including the plaintext data key) to the decryption method. Other CMMs might use different techniques to get the decryption materials. 4. The decryption method uses the plaintext data key to decrypt the data, then discards the plaintext data key. 5. The decryption method returns the plaintext data. Concepts in the AWS Encryption SDK This section introduces the concepts used in the AWS Encryption SDK. The AWS Encryption SDK is designed so that you can use the default implementations of the components without detailed knowledge about their functionality. This section is provided as a glossary and reference. Topics • Data Keys (p. 6) • Master key (p. 6) • Master key operations: Generate, Encrypt, Decrypt (p. 6) • Master key provider (p. 7) • Cryptographic Materials Manager (p. 7) • Algorithm Suite (p. 7) • Encryption Context (p. 8) • Encrypted Message (p. 8) 5 AWS Encryption SDK Developer Guide Data Keys Data Keys A data key consists of cryptographic material. It is the secret key that protects the data that you encrypt. Data keys are generated by master keys (p. 6). You do not need to implement or extend data keys to use the AWS Encryption SDK. When a master key generates a data key, it returns two copies of the data key; one in plaintext and one that is encrypted by the master key that generated it. The plaintext data key can be encrypted by multiple master keys, each of which returns an encrypted copy of the data key. Every encrypted data key is associated with the master key that encrypted it and the master key provider (p. 7) that supplied the master key. When you encrypt data in the AWS Encryption SDK, the encrypted data keys are stored in an encrypted message (p. 8) along with the encrypted data. In the AWS Encryption SDK, we distinguish data keys from data encryption keys. Several of the supported algorithm suites (p. 7), including the default suite, use a key derivation function that prevents the data key from hitting its cryptographic limits. The key derivation function takes the data key as input and returns a data encryption key that is actually used to encrypt the data. For this reason, we often say that data is encrypted "under" a data key rather than "by" the data key. Master key A master key encrypts, decrypts, and generates data keys (p. 2). The AWS Encryption SDK represents master keys as abstract classes or interfaces so you can implement the master key operations in the way that best meets the security requirements of your organization. For example, although they are called "keys," master keys might not have their own cryptographic material. Also, unlike data keys, whose use and algorithm suite (p. 7) are strictly defined by AWS Encryption SDK, master keys can use any algorithm suite or implementation. Master keys are instrumental to envelope encryption (p. 3). In envelope encryption, one master key generates and encrypts a data key that is used to encrypt data. Other master keys then re-encrypt the plaintext data key. As a result, any master key is sufficient to decrypt the data. Each master key is associated with one master key provider (p. 7) that returns one or more master keys to the caller. The AWS Encryption SDK provides several commonly used master keys, such as AWS Key Management Service (AWS KMS) customer master keys (CMKs), raw AES-GCM (Advanced Encryption Standard / Galois Counter Mode) keys, and RSA keys. You can implement your own master keys for other cryptographic algorithms and services. For example, you could implement master keys backed by implementations of Elliptical Curve Integrated Encryption Scheme (ECIES), Key Management Interoperability Program (KMIP), tokenization services, or other proprietary systems. Master key operations: Generate, Encrypt, Decrypt Master keys in the AWS Encryption SDK generate, encrypt, and decrypt data keys (p. 6). You write methods to perform these operations when you create a master key, but your application does not call the methods directly. The SDK calls them when you ask it to encrypt or decrypt data. You can implement the master key methods in the way that works best for your organization. For example, when asked to generate a data key, a master key can create or return a key in any way that fulfills the requirements of the algorithm suite that they use. Master keys can generate data keys locally or remotely. They can derive the keys algorithmically, call a service that generates the cryptographic material, or return previously-generated data keys. The SDK requires only that they return a valid data key object. 6 AWS Encryption SDK Developer Guide Master key provider Also, although master keys must implement all three methods, you can create master keys that actually perform only one or two of the three operations. Calls to the remaining methods just fail or return errors. These limited master keys might be useful in a system with strict access controls that do not let the same users encrypt and decrypt data. All master key operations take an encryption context (p. 8) as input. For optimal security, master key operations that encrypt data keys should cryptographically bind the encryption context to the encrypted data so that changing any key or value in the encryption context invalidates the encryption. Master key operations that decrypt should verify the encryption context and fail unless they include the same encryption context used to encrypt. The encryption context is most useful when there are users who have permission to decrypt, but not encrypt. Master key provider A master key provider returns objects that represent master keys. Each master key is associated with one master key provider, but a master key provider typically provides multiple master keys. The simplest master key provider always returns the same master key (p. 6). In fact, master keys are implemented as master keys providers that only return themselves. More complex master key providers might use key rotation, the encryption context, application permissions, and other factors to select master keys from among the set they can provide. Many master keys providers wrap or extend other master key providers to customize their behavior and functionality. For example, a custom master key provider might select a master key provider from a collection, delegate requests, and combine their results. Cryptographic Materials Manager The cryptographic materials manager (CMM) gets the cryptographic materials that are used to encrypt and decrypt data. The cryptographic materials include plaintext and encrypted data keys, and an optional message signing key. You can use the Default CMM that the AWS Encryption SDK provides (DefaultCryptoMaterialsManager) or write a custom CMM. Each Default CMM is associated with a master key provider (p. 7). When it gets a materials request, the Default CMM gets master keys from its master key provider and uses them to generate the requested cryptographic material. This might involve a call to a cryptographic service, such as AWS Key Management Service (AWS KMS). In each call to encrypt or decrypt data, you specify a CMM or a master key provider. This lets you choose a particular set of master keys for the operation. You can create a CMM explicitly and specify its master key provider, but that is not required. If you specify a master key provider in an encryption request, the SDK creates a Default CMM for the master key provider. Because the CMM acts as a liaison between the SDK and a master key provider, it is an ideal point for customization and extension, such as support for policy enforcement and caching. Algorithm Suite The AWS Encryption SDK supports several (p. 12) algorithm suites (p. 10), all of which use Advanced Encryption Standard (AES) as the primary algorithm, and combine it with other algorithm and values. The AWS Encryption SDK establishes a recommended algorithm suite as the default for all encryption operations. The default might change as standards and best practices improve. You can specify an alternate algorithm suite in requests to encrypt data or when creating a cryptographic materials manager (CMM) (p. 7), but unless an alternate is required for your situation, it is best to use the default. The current default is AES-GCM with an HMAC-based extract-and-expand key derivation 7 AWS Encryption SDK Developer Guide Encryption Context function (HKDF), Elliptic Curve Digital Signature Algorithm (ECDSA) signing, and a 256-bit encryption key. If you specify an algorithm suite, we recommend an algorithm suite that uses a key derivation function and a message signing algorithm. Algorithm suites that have neither feature are supported only for backward compatibility. Encryption Context To improve the security of your cryptographic operations, use an encryption context in all requests to encrypt data. The encryption context is optional, but recommended. An encryption context is a set of key–value pairs that contain arbitrary nonsecret data. The encryption context can contain any data you choose, but it typically consists of data that is useful in logging and tracking, such as data about the file type, purpose, or ownership. In requests to encrypt data, you can include an encryption context along with the plaintext data and a master key provider. The AWS Encryption SDK cryptographically binds the encryption context to the encrypted data so that the same encryption context is required to decrypt the data. The AWS Encryption SDK also includes the encryption context in the encrypted message (p. 8) that it returns, along with the encrypted data and data keys. The encryption context in the encrypted message always includes the encryption context that you specified in the encryption request, along with elements that the operation might add, such as a public signing key. To decrypt the data, you pass in the encrypted message. Because the AWS Encryption SDK can extract the encryption context from the message, you do not need to pass it in separately. After decrypting the data, the AWS Encryption SDK returns a result that includes that encryption context along with the plaintext data. The functions in your application that decrypt data should always verify that the encryption context in the decrypt result includes the values that you expect before it returns the plaintext data. When choosing an encryption context, remember that it is not a secret. The encryption context is displayed in plaintext in the header of the encrypted message (p. 8) that the SDK returns. If you are using AWS Key Management Service, the encryption context also might appear in plaintext in audit records and logs, such as AWS CloudTrail. Encrypted Message Encrypt operations in the AWS Encryption SDK return an encrypted message and decrypt operations take an encrypted message as input. An encrypted message, a formatted data structure (p. 82) that includes the encrypted data along with encrypted copies of the data keys, the algorithm ID, and, optionally, an encryption context and a message signature. Combining the encrypted data and its encrypted data keys streamlines the decryption operation and frees you from having to store and manage encrypted data keys independently of the data that they encrypt. For technical information about the encrypted message, see Encrypted Message Format (p. 82). 8 AWS Encryption SDK Developer Guide Getting Started with the AWS Encryption SDK To use the AWS Encryption SDK, you need a master key provider (p. 7). If you don't have one, we recommend using AWS Key Management Service (AWS KMS). Many of the code samples in the AWS Encryption SDK require an AWS KMS customer master key (CMK). To interact with AWS KMS, you need to use the AWS SDK for your preferred programming language, such as the AWS SDK for Java or the AWS SDK for Python (Boto). The AWS Encryption SDK client library works with the AWS SDKs to support master keys stored in AWS KMS. To prepare to use the AWS Encryption SDK with AWS KMS 1. 2. Create an AWS account. To learn how, see How do I create and activate a new Amazon Web Services account? in the AWS Knowledge Center. Create a customer master key (CMK) in AWS KMS. To learn how, see Creating Keys in the AWS Key Management Service Developer Guide. Tip 3. To use the CMK programmatically, you will need the ID or Amazon Resource Name (ARN) of the CMK. For help finding the ID or ARN of a CMK, see Viewing Keys in the AWS Key Management Service Developer Guide. Create an IAM user with an access key. To learn how, see Creating IAM Users in the IAM User Guide. When you create the user, for Access type, choose Programmatic access. After you create the user, choose Download.csv to save the AWS access key that represents your user credentials. Store the file in a secure location. We recommend that you use AWS Identity and Access Management (IAM) access keys instead of AWS (root) account access keys. IAM lets you securely control access to AWS services and resources in your AWS account. For detailed best practice guidance, see Best Practices for Managing AWS Access Keys The Download.csv file contains an AWS access key ID and a secret access key that represents the AWS credentials of the user that you created. When you write code without using an AWS SDK, you use your access key to sign your requests to AWS. The signature assures AWS that the request came from you unchanged. However, when you use an AWS SDK, such as the AWS SDK for Java, the SDK signs all requests to AWS for you. 4. 5. Set your AWS credentials using the instructions for Java or Python and the AWS access key in the Download.csv file that you downloaded in Step 3. This procedure allows AWS SDKs to sign requests to AWS for you. Code samples in the AWS Encryption SDK that interact with AWS KMS assume that you have completed this step. Download and install the AWS Encryption SDK. To learn how, see the installation instructions for the programming language (p. 12) that you want to use. 9 AWS Encryption SDK Developer Guide Recommended: AES-GCM with Key Derivation and Signing Supported Algorithm Suites in the AWS Encryption SDK An algorithm suite is a collection of cryptographic algorithms and related values. Cryptographic systems use the algorithm implemenation to generate the ciphertext message. The AWS Encryption SDK algorithm suite uses the Advanced Encryption Standard (AES) algorithm in Galois/Counter Mode (GCM), known as AES-GCM, to encrypt raw data. The SDK supports 256-bit, 192bit, and 128-bit encryption keys. The length of the initialization vector (IV) is always 12 bytes; the length of the authentication tag is always 16 bytes. The SDK implements AES-GCM in one of three ways. By default, the SDK uses AES-GCM with an HMACbased extract-and-expand key derivation function (HKDF), signing, and a 256-bit encryption key. Recommended: AES-GCM with Key Derivation and Signing In the recommended algorithm suite, the SDK uses the data encryption key as an input to the HMACbased extract-and-expand key derivation function (HKDF) to derive the AES-GCM encryption key. The SDK also adds an Elliptic Curve Digital Signature Algorithm (ECDSA) signature. By default, the SDK uses this algorithm suite with a 256-bit encryption key. The HKDF helps you avoid accidental reuse of a data encryption key. This algorithm suite uses ECDSA and a message signing algorithm (SHA-384 or SHA-256). ECDSA is used by default, even when it is not specified by the policy for the underlying master key. Message signing verifies the identity of the message sender and adds message authenticity to the envelope encrypted data. It is particularly useful when the authorization policy for a master key allows one set of users to encrypt data and a different set of users to decrypt data. The following table lists the variations of the recommended algorithm suites. AWS Encryption SDK Algorithm Suites Algorithm Name Data Encryption Key Length (in bits) Algorithm Mode Key Derivation Algorithm Signature Algorithm AES 256 GCM HKDF with SHA-384 ECDSA with P-384 and SHA-384 AES 192 GCM HKDF with SHA-384 ECDSA with P-384 and SHA-384 AES 128 GCM HKDF with SHA-256 ECDSA with P-256 and SHA-256 10 AWS Encryption SDK Developer Guide Other Supported Algorithm Suites Other Supported Algorithm Suites The AWS Encryption SDK supports the alternate algorithm suites for backward compatibility, although we do not recommend them. If you cannot use an algorithm suite with HKDF and signing, we recommend an algorithm suite with HKDF over one that lacks both elements. AES-GCM with Key Derivation Only This algorithm suite uses a key derivation function, but lacks the ECDSA signature that provides authenticity and nonrepudiation. Use this suite when the users who encrypt data and those who decrypt it are equally trusted. AES-GCM without Key Derivation or Signing This algorithm suite uses the data encryption key as the AES-GCM encryption key, instead of using a key derivation function to derive a unique key. We discourage using this suite to generate ciphertext, but the SDK supports it for compatibility reasons. For more information about how these suites are represented and used in the library, see the section called “Algorithms Reference” (p. 96). 11 AWS Encryption SDK Developer Guide Java AWS Encryption SDK Programming Languages The AWS Encryption SDK is available for the following programming languages. For more information, see the corresponding topic. Topics • AWS Encryption SDK for Java (p. 12) • AWS Encryption SDK for Python (p. 20) • AWS Encryption SDK Command Line Interface (p. 26) AWS Encryption SDK for Java This topic explains how to install and use the AWS Encryption SDK for Java. For details about programming with the SDK, see the aws-encryption-sdk-java repository on GitHub and the Javadoc for the AWS Encryption SDK. Topics • Prerequisites (p. 12) • Installation (p. 13) • AWS Encryption SDK for Java Example Code (p. 13) Prerequisites Before you install the AWS Encryption SDK for Java, be sure you have the following prerequisites. A Java development environment You will need Java 8 or later. On the Oracle website, go to Java SE Downloads, and then download and install the Java SE Development Kit (JDK). If you use the Oracle JDK, you must also download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. Bouncy Castle Bouncy Castle provides a cryptography API for Java. If you don't have Bouncy Castle, go to Bouncy Castle latest releases to download the provider file that corresponds to your JDK. If you use Apache Maven, Bouncy Castle is available with the following dependency definition.12 AWS Encryption SDK Developer Guide Installation AWS SDK for Java (Optional) Although you don't need the AWS SDK for Java to use the AWS Encryption SDK for Java, you do need it to use AWS Key Management Service (AWS KMS) as a master key provider, and to use some of the example Java code (p. 13) in this guide. For more information about installing and configuring the AWS SDK for Java, see AWS SDK for Java. Installation You can install the AWS Encryption SDK for Java in the following ways. Manually To install the AWS Encryption SDK for Java, clone or download the aws-encryption-sdk-java GitHub repository. Using Apache Maven The AWS Encryption SDK for Java is available through Apache Maven with the following dependency definition. org.bouncycastle bcprov-ext-jdk15on 1.58 After you install the SDK, get started by looking at the example Java code (p. 13) in this guide and the Javadoc on GitHub. AWS Encryption SDK for Java Example Code The following examples show you how to use the AWS Encryption SDK for Java to encrypt and decrypt data. Topics • Encrypting and Decrypting Strings (p. 13) • Encrypting and Decrypting Byte Streams (p. 15) • Encrypting and Decrypting Byte Streams with Multiple Master Key Providers (p. 17) Encrypting and Decrypting Strings The following example shows you how to use the AWS Encryption SDK to encrypt and decrypt strings. This example uses an AWS Key Management Service (AWS KMS) customer master key (CMK) as the master key. For help creating a key, see Creating Keys in the AWS Key Management Service Developer Guide. To find the Amazon Resource name (ARN) of an existing CMK, go to the Encryption keys section of the AWS Management Console, select the region, and then click the CMK alias. You can also use the AWS KMS ListKeys operation. For details, see Viewing Keys in the AWS Key Management Service Developer Guide. /* 13 AWS Encryption SDK Developer Guide Example Code * Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except * in compliance with the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. */ package com.amazonaws.crypto.examples; import java.util.Collections; import java.util.Map; import import import import com.amazonaws.encryptionsdk.AwsCrypto; com.amazonaws.encryptionsdk.CryptoResult; com.amazonaws.encryptionsdk.kms.KmsMasterKey; com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider; /** * com.amazonaws aws-encryption-sdk-java 1.3.1 * Encrypts and then decrypts a string under a KMS key * *
* Arguments: *
*
*/ public class StringExample { private static String keyArn; private static String data; public static void main(final String[] args) { keyArn = args[0]; data = args[1]; // Instantiate the SDK final AwsCrypto crypto = new AwsCrypto(); // Set up the KmsMasterKeyProvider backed by the default credentials final KmsMasterKeyProvider prov = new KmsMasterKeyProvider(keyArn); // Encrypt the data // // Most encrypted data should have an associated encryption context // to protect integrity. This sample uses placeholder values. // // For more information see: // blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrityof-Your-Encrypted-Data-by-Using-AWS-Key-Management final Map- Key ARN: For help finding the Amazon Resource Name (ARN) of your KMS customer master * key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/ developerguide/viewing-keys.html *
- String to encrypt *
context = Collections.singletonMap("Example", "String"); final String ciphertext = crypto.encryptString(prov, data, context).getResult(); System.out.println("Ciphertext: " + ciphertext); 14 AWS Encryption SDK Developer Guide Example Code // Decrypt the data final CryptoResult decryptResult = crypto.decryptString(prov, ciphertext); // Before returning the plaintext, verify that the customer master key that // was used in the encryption operation was the one supplied to the master key provider. if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) { throw new IllegalStateException("Wrong key ID!"); } // Also, verify that the encryption context in the result contains the // encryption context supplied to the encryptString method. Because the // SDK can add values to the encryption context, don't require that // the entire context matches. for (final Map.Entry e : context.entrySet()) { if (!e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey()))) { } } } } throw new IllegalStateException("Wrong Encryption Context!"); // Now we can return the plaintext data System.out.println("Decrypted: " + decryptResult.getResult()); Encrypting and Decrypting Byte Streams The following example shows you how to use the AWS Encryption SDK to encrypt and decrypt byte streams. This example does not use AWS. It uses the Java Cryptography Extension (JCE) to protect the master key. /* * Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except * in compliance with the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. */ package com.amazonaws.crypto.examples; import import import import import import java.io.FileInputStream; java.io.FileOutputStream; java.io.IOException; java.security.SecureRandom; java.util.Collections; java.util.Map; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CryptoInputStream; import com.amazonaws.encryptionsdk.MasterKey; 15 AWS Encryption SDK Developer Guide Example Code import com.amazonaws.encryptionsdk.jce.JceMasterKey; import com.amazonaws.util.IOUtils; /** * * Encrypts and then decrypts a file under a random key. * *
* Arguments: *
*
* *- Name of file containing plaintext data to encrypt *
* This program demonstrates using a standard Java {@link SecretKey} object as a {@link MasterKey} to * encrypt and decrypt streaming data. */ public class FileStreamingExample { private static String srcFile; public static void main(String[] args) throws IOException { srcFile = args[0]; // In this example, we generate a random key. In practice, // you would get a key from an existing store SecretKey cryptoKey = retrieveEncryptionKey(); // Create a JCE master key provider using the random key and an AES-GCM encryption algorithm JceMasterKey masterKey = JceMasterKey.getInstance(cryptoKey, "Example", "RandomKey", "AES/GCM/NoPadding"); // Instantiate the SDK AwsCrypto crypto = new AwsCrypto(); // Create an encryption context to identify this ciphertext Map
context = Collections.singletonMap("Example", "FileStreaming"); // Because the file might be to large to load into memory, we stream the data, instead of //loading it all at once. FileInputStream in = new FileInputStream(srcFile); CryptoInputStream encryptingStream = crypto.createEncryptingStream(masterKey, in, context); FileOutputStream out = new FileOutputStream(srcFile + ".encrypted"); IOUtils.copy(encryptingStream, out); encryptingStream.close(); out.close(); // Decrypt the file. Verify the encryption context before returning the plaintext. in = new FileInputStream(srcFile + ".encrypted"); CryptoInputStream decryptingStream = crypto.createDecryptingStream(masterKey, in); // Does it contain the expected encryption context? if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) { throw new IllegalStateException("Bad encryption context"); } // Return the plaintext data out = new FileOutputStream(srcFile + ".decrypted"); IOUtils.copy(decryptingStream, out); decryptingStream.close(); 16 AWS Encryption SDK Developer Guide Example Code } } out.close(); /** * In practice, this key would be saved in a secure location. * For this demo, we generate a new random key for each operation. */ private static SecretKey retrieveEncryptionKey() { SecureRandom rnd = new SecureRandom(); byte[] rawKey = new byte[16]; // 128 bits rnd.nextBytes(rawKey); return new SecretKeySpec(rawKey, "AES"); } Encrypting and Decrypting Byte Streams with Multiple Master Key Providers The following example shows you how to use the AWS Encryption SDK with more than one master key provider. Using more than one master key provider creates redundancy if one master key provider is unavailable for decryption. This example uses a CMK in AWS KMS and an RSA key pair as the master keys. /* * Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except * in compliance with the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. */ package com.amazonaws.crypto.examples; import import import import import import import java.io.FileInputStream; java.io.FileOutputStream; java.security.GeneralSecurityException; java.security.KeyPair; java.security.KeyPairGenerator; java.security.PrivateKey; java.security.PublicKey; import import import import import import import com.amazonaws.encryptionsdk.AwsCrypto; com.amazonaws.encryptionsdk.CryptoOutputStream; com.amazonaws.encryptionsdk.MasterKeyProvider; com.amazonaws.encryptionsdk.jce.JceMasterKey; com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider; com.amazonaws.encryptionsdk.multi.MultipleProviderFactory; com.amazonaws.util.IOUtils; /** * * Encrypts a file using both KMS and an asymmetric key pair. * *
* Arguments: *
17 AWS Encryption SDK Developer Guide Example Code *
* * You might use AWS Key Management Service (KMS) for most encryption and decryption operations, but * still want the option of decrypting your data offline independently of KMS. This sample * demonstrates one way to do this. * * The sample encrypts data under both a KMS customer master key (CMK) and an "escrowed" RSA key pair * so that either key alone can decrypt it. You might commonly use the KMS CMK for decryption. However, * at any time, you can use the private RSA key to decrypt the ciphertext independent of KMS. * * This sample uses the JCEMasterKey class to generate a RSA public-private key pair * and saves the key pair in memory. In practice, you would store the private key in a secure offline * location, such as an offline HSM, and distribute the public key to your development team. * */ public class EscrowedEncryptExample { private static PublicKey publicEscrowKey; private static PrivateKey privateEscrowKey; public static void main(final String[] args) throws Exception { // This sample generates a new random key for each operation. // In practice, you would distribute the public key and save the private key in secure // storage. generateEscrowKeyPair(); final String kmsArn = args[0]; final String fileName = args[1]; standardEncrypt(kmsArn, fileName); standardDecrypt(kmsArn, fileName); } escrowDecrypt(fileName); private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception { // Encrypt with the KMS CMK and the escrowed public key // 1. Instantiate the SDK final AwsCrypto crypto = new AwsCrypto(); // 2. Instantiate a KMS master key provider final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn); // 3. Instantiate a JCE master key provider // Because the user does not have access to the private escrow key, // they pass in "null" for the private key parameter. final JceMasterKey escrowPub = JceMasterKey.getInstance(publicEscrowKey, null, "Escrow", "Escrow", "RSA/ECB/OAEPWithSHA-512AndMGF1Padding"); // 4. Combine the providers into a single master key provider final MasterKeyProvider provider = MultipleProviderFactory.buildMultiProvider(kms, escrowPub); 18 AWS Encryption SDK Developer Guide Example Code always // 5. Encrypt the file // To simplify the code, we omit the encryption context. Production code should // use an encryption context. For an example, see the other SDK samples. final FileInputStream in = new FileInputStream(fileName); final FileOutputStream out = new FileOutputStream(fileName + ".encrypted"); final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(provider, out); } IOUtils.copy(in, encryptingStream); in.close(); encryptingStream.close(); private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception { // Decrypt with the KMS CMK and the escrow public key. You can use a combined provider, // as shown here, or just the KMS master key provider. // 1. Instantiate the SDK final AwsCrypto crypto = new AwsCrypto(); // 2. Instantiate a KMS master key provider final KmsMasterKeyProvider kms = new KmsMasterKeyProvider(kmsArn); // 3. Instantiate a JCE master key provider // Because the user does not have access to the private escrow // key, they pass in "null" for the private key parameter. final JceMasterKey escrowPub = JceMasterKey.getInstance(publicEscrowKey, null, "Escrow", "Escrow", "RSA/ECB/OAEPWithSHA-512AndMGF1Padding"); // 4. Combine the providers into a single master key provider final MasterKeyProvider provider = MultipleProviderFactory.buildMultiProvider(kms, escrowPub); always // 5. Decrypt the file // To simplify the code, we omit the encryption context. Production code should // use an encryption context. For an example, see the other SDK samples. final FileInputStream in = new FileInputStream(fileName + ".encrypted"); final FileOutputStream out = new FileOutputStream(fileName + ".decrypted"); final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(provider, out); IOUtils.copy(in, decryptingStream); in.close(); decryptingStream.close(); } private static void escrowDecrypt(final String fileName) throws Exception { // You can decrypt the stream using only the private key. // This method does not call KMS. // 1. Instantiate the SDK final AwsCrypto crypto = new AwsCrypto(); // 2. Instantiate a JCE master key // This method call uses the escrowed private key, not null final JceMasterKey escrowPriv = JceMasterKey.getInstance(publicEscrowKey, privateEscrowKey, "Escrow", "Escrow", "RSA/ECB/OAEPWithSHA-512AndMGF1Padding"); always // 3. Decrypt the file // To simplify the code, we omit the encryption context. Production code should 19 AWS Encryption SDK Developer Guide Python // use an encryption context. For an example, see the other SDK samples. final FileInputStream in = new FileInputStream(fileName + ".encrypted"); final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed"); final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPriv, out); IOUtils.copy(in, decryptingStream); in.close(); decryptingStream.close(); } private static void generateEscrowKeyPair() throws GeneralSecurityException { final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA"); kg.initialize(4096); // Escrow keys should be very strong final KeyPair keyPair = kg.generateKeyPair(); publicEscrowKey = keyPair.getPublic(); privateEscrowKey = keyPair.getPrivate(); } } AWS Encryption SDK for Python This topic explains how to install and use the AWS Encryption SDK for Python. For details about programming with the SDK, see the aws-encryption-sdk-python repository on GitHub and the Python documentation for the AWS Encryption SDK for Python. Topics • Prerequisites (p. 20) • Installation (p. 20) • AWS Encryption SDK for Python Example Code (p. 21) Prerequisites Before you install the AWS Encryption SDK for Python, be sure you have the following prerequisites. A supported version of Python To use this SDK, you need Python 2.7, or Python 3.4 or later. To download Python, see Python downloads. The pip installation tool for Python If you have Python 2.7.9 or later, or Python 3.4 or later, you already have pip, although you might want to upgrade it. For more information about upgrading or installing pip, see Installation in the pip documentation. Installation Use pip to install the AWS Encryption SDK for Python, as shown in the following examples. To install the latest version pip install aws-encryption-sdk 20 AWS Encryption SDK Developer Guide Example Code For more details about using pip to install and upgrade packages, see Installing Packages. The SDK requires the cryptography library on all platforms. All versions of pip install and build the cryptography library on Windows. pip 8.1 and later installs and builds cryptography on Linux. If you are using an earlier version of pip and your Linux environment doesn't have the tools needed to build the cryptography library, you need to install them. For more information, see Building cryptography on Linux. For the latest development version of this SDK, go to the aws-encryption-sdk-python GitHub repository. After you install the SDK, get started by looking at the example Python code (p. 21) in this guide. AWS Encryption SDK for Python Example Code The following examples show you how to use the AWS Encryption SDK for Python to encrypt and decrypt data. Topics • Encrypting and Decrypting Strings (p. 21) • Encrypting and Decrypting Byte Streams (p. 22) • Encrypting and Decrypting Byte Streams with Multiple Master Key Providers (p. 24) Encrypting and Decrypting Strings The following example shows you how to use the AWS Encryption SDK to encrypt and decrypt strings. This example uses a customer master key (CMK) in AWS Key Management Service (AWS KMS) as the master key. """ Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache-2-0/ or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. """ from __future__ import print_function import aws_encryption_sdk def cycle_string(key_arn, source_plaintext, botocore_session=None): """Encrypts and then decrypts a string using a KMS customer master key (CMK) :param str key_arn: Amazon Resource Name (ARN) of the KMS CMK (http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) :param bytes source_plaintext: Data to encrypt :param botocore_session: Existing Botocore session instance :type botocore_session: botocore.session.Session """ 21 AWS Encryption SDK Developer Guide Example Code # Create a KMS master key provider kms_kwargs = dict(key_ids=[key_arn]) if botocore_session is not None: kms_kwargs['botocore_session'] = botocore_session master_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(**kms_kwargs) # Encrypt the plaintext source data ciphertext, encryptor_header = aws_encryption_sdk.encrypt( source=source_plaintext, key_provider=master_key_provider ) print('Ciphertext: ', ciphertext) # Decrypt the ciphertext cycled_plaintext, decrypted_header = aws_encryption_sdk.decrypt( source=ciphertext, key_provider=master_key_provider ) # Verify that the "cycled" (encrypted, then decrypted) plaintext is identical to the source # plaintext assert cycled_plaintext == source_plaintext # Verify that the encryption context used in the decrypt operation includes all key pairs from # the encrypt operation. (The SDK can add pairs, so don't require an exact match.) # # In production, always use a meaningful encryption context. In this sample, we omit the # encryption context (no key pairs). assert all( pair in decrypted_header.encryption_context.items() for pair in encryptor_header.encryption_context.items() ) print('Decrypted: ', cycled_plaintext) Encrypting and Decrypting Byte Streams The following example shows you how to use the AWS Encryption SDK to encrypt and decrypt byte streams. This example doesn't use AWS. It uses a static, ephemeral master key provider. """ Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache-2-0/ or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. """ import filecmp import os import aws_encryption_sdk 22 AWS Encryption SDK Developer Guide Example Code from aws_encryption_sdk.internal.crypto import WrappingKey from aws_encryption_sdk.key_providers.raw import RawMasterKeyProvider from aws_encryption_sdk.identifiers import WrappingAlgorithm, EncryptionKeyType class StaticRandomMasterKeyProvider(RawMasterKeyProvider): """Randomly and consistently generates 256-bit keys for each unique key ID.""" provider_id = 'static-random' def __init__(self, **kwargs): self._static_keys = {} def _get_raw_key(self, key_id): """Returns a static, randomly-generated symmetric key for the specified key ID. :param str key_id: Key ID :returns: Wrapping key that contains the specified static key :rtype: :class:`aws_encryption_sdk.internal.crypto.WrappingKey` """ try: static_key = self._static_keys[key_id] except KeyError: static_key = os.urandom(32) self._static_keys[key_id] = static_key return WrappingKey( wrapping_algorithm=WrappingAlgorithm.AES_256_GCM_IV12_TAG16_NO_PADDING, wrapping_key=static_key, wrapping_key_type=EncryptionKeyType.SYMMETRIC ) def cycle_file(source_plaintext_filename): """Encrypts and then decrypts a file under a custom static master key provider. :param str source_plaintext_filename: Filename of file to encrypt """ # Create a static random master key provider key_id = os.urandom(8) master_key_provider = StaticRandomMasterKeyProvider() master_key_provider.add_master_key(key_id) ciphertext_filename = source_plaintext_filename + '.encrypted' cycled_plaintext_filename = source_plaintext_filename + '.decrypted' # Encrypt the plaintext source data with open(source_plaintext_filename, 'rb') as plaintext, open(ciphertext_filename, 'wb') as ciphertext: with aws_encryption_sdk.stream( mode='e', source=plaintext, key_provider=master_key_provider ) as encryptor: for chunk in encryptor: ciphertext.write(chunk) # Decrypt the ciphertext with open(ciphertext_filename, 'rb') as ciphertext, open(cycled_plaintext_filename, 'wb') as plaintext: with aws_encryption_sdk.stream( mode='d', source=ciphertext, key_provider=master_key_provider ) as decryptor: for chunk in decryptor: plaintext.write(chunk) 23 AWS Encryption SDK Developer Guide Example Code # Verify that the "cycled" (encrypted, then decrypted) plaintext is identical to the source # plaintext assert filecmp.cmp(source_plaintext_filename, cycled_plaintext_filename) # Verify that the encryption context used in the decrypt operation includes all key pairs from # the encrypt operation # # In production, always use a meaningful encryption context. In this sample, we omit the # encryption context (no key pairs). assert all( pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items() ) return ciphertext_filename, cycled_plaintext_filename Encrypting and Decrypting Byte Streams with Multiple Master Key Providers The following example shows you how to use the AWS Encryption SDK with more than one master key provider. Using more than one master key provider creates redundancy if one master key provider is unavailable for decryption. This example uses a CMK in AWS KMS and an RSA key pair as the master keys. """ Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache-2-0/ or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. """ import filecmp import os import aws_encryption_sdk from aws_encryption_sdk.internal.crypto import WrappingKey from aws_encryption_sdk.key_providers.raw import RawMasterKeyProvider from aws_encryption_sdk.identifiers import WrappingAlgorithm, EncryptionKeyType from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives import serialization from cryptography.hazmat.primitives.asymmetric import rsa class StaticRandomMasterKeyProvider(RawMasterKeyProvider): provider_id = 'static-random' def __init__(self, **kwargs): self._static_keys = {} def _get_raw_key(self, key_id): """Returns a static, randomly generated, RSA key for the specified key ID. 24 AWS Encryption SDK Developer Guide Example Code :param str key_id: User-defined ID for the static key :returns: Wrapping key that contains the specified static key :rtype: :class:`aws_encryption_sdk.internal.crypto.WrappingKey` """ try: static_key = self._static_keys[key_id] except KeyError: private_key = rsa.generate_private_key( public_exponent=65537, key_size=4096, backend=default_backend() ) static_key = private_key.private_bytes( encoding=serialization.Encoding.PEM, format=serialization.PrivateFormat.PKCS8, encryption_algorithm=serialization.NoEncryption() ) self._static_keys[key_id] = static_key return WrappingKey( wrapping_algorithm=WrappingAlgorithm.RSA_OAEP_SHA1_MGF1, wrapping_key=static_key, wrapping_key_type=EncryptionKeyType.PRIVATE ) def cycle_file(key_arn, source_plaintext_filename, botocore_session=None): """Encrypts and then decrypts a file using a KMS master key provider and a custom static master key provider. Both master key providers are used to encrypt the plaintext file, so either one alone can decrypt it. :param str key_arn: Amazon Resource Name (ARN) of the KMS Customer Master Key (CMK) (http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html) :param str source_plaintext_filename: Filename of file to encrypt :param botocore_session: existing botocore session instance :type botocore_session: botocore.session.Session """ # "Cycled" means encrypted and then decrypted ciphertext_filename = source_plaintext_filename + '.encrypted' cycled_kms_plaintext_filename = source_plaintext_filename + '.kms.decrypted' cycled_static_plaintext_filename = source_plaintext_filename + '.static.decrypted' # Create a KMS master key provider kms_kwargs = dict(key_ids=[key_arn]) if botocore_session is not None: kms_kwargs['botocore_session'] = botocore_session kms_master_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(**kms_kwargs) # Create a static master key provider and add a master key to it static_key_id = os.urandom(8) static_master_key_provider = StaticRandomMasterKeyProvider() static_master_key_provider.add_master_key(static_key_id) # Create a master key provider that includes the KMS and static master key providers kms_master_key_provider.add_master_key_provider(static_master_key_provider) # Encrypt plaintext with both KMS and static master keys with open(source_plaintext_filename, 'rb') as plaintext, open(ciphertext_filename, 'wb') as ciphertext: with aws_encryption_sdk.stream( source=plaintext, mode='e', key_provider=kms_master_key_provider ) as encryptor: 25 AWS Encryption SDK Developer Guide Command Line Interface for chunk in encryptor: ciphertext.write(chunk) # Decrypt the ciphertext with only the KMS master key with open(ciphertext_filename, 'rb') as ciphertext, open(cycled_kms_plaintext_filename, 'wb') as plaintext: with aws_encryption_sdk.stream( source=ciphertext, mode='d', key_provider=aws_encryption_sdk.KMSMasterKeyProvider(**kms_kwargs) ) as kms_decryptor: for chunk in kms_decryptor: plaintext.write(chunk) # Decrypt the ciphertext with only the static master key with open(ciphertext_filename, 'rb') as ciphertext, open(cycled_static_plaintext_filename, 'wb') as plaintext: with aws_encryption_sdk.stream( source=ciphertext, mode='d', key_provider=static_master_key_provider ) as static_decryptor: for chunk in static_decryptor: plaintext.write(chunk) # Verify that the "cycled" (encrypted, then decrypted) plaintext is identical to the source # plaintext assert filecmp.cmp(source_plaintext_filename, cycled_kms_plaintext_filename) assert filecmp.cmp(source_plaintext_filename, cycled_static_plaintext_filename) # Verify that the encryption context in the decrypt operation includes all key pairs from the # encrypt operation. # # In production, always use a meaningful encryption context. In this sample, we omit the # encryption context (no key pairs). assert all( pair in kms_decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items() ) assert all( pair in static_decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items() ) return ciphertext_filename, cycled_kms_plaintext_filename, cycled_static_plaintext_filename AWS Encryption SDK Command Line Interface The AWS Encryption SDK Command Line Interface (AWS Encryption CLI) enables you to use the AWS Encryption SDK to encrypt and decrypt data interactively at the command line and in scripts. You don't need cryptography or programming expertise. Like all implementations of the AWS Encryption SDK, the AWS Encryption CLI offers advanced data protection features. These include envelope encryption, additional authenticated data (AAD), and secure, authenticated, symmetric key algorithm suites, such as 256-bit AES-GCM with key derivation and signing. The AWS Encryption CLI is built on the AWS Encryption SDK for Python and is supported on Linux, macOS, and Windows. You can run commands and scripts to encrypt and decrypt your data in your 26 AWS Encryption SDK Developer Guide Installing the CLI preferred shell on Linux or macOS, in a Command Prompt window (cmd.exe) on Windows, and in a PowerShell console on any system. All language-specific implementations of the AWS Encryption SDK, including the AWS Encryption CLI, are interoperable. For example, you can encrypt data with the AWS Encryption SDK for Java (p. 12) and decrypt it with the AWS Encryption CLI. This topic introduces the AWS Encryption CLI, explains how to install and use it, and provides several examples to help you get started. For a quick start, see How to Encrypt and Decrypt Your Data with the AWS Encryption CLI in the AWS Security Blog. For more detailed information, see Read The Docs, and join us in developing the AWS Encryption CLI in the aws-encryption-sdk-cli repository on GitHub. Topics • Installing the AWS Encryption SDK Command Line Interface (p. 27) • How to Use the AWS Encryption SDK Command Line Interface (p. 29) • Examples of the AWS Encryption SDK Command Line Interface (p. 36) • AWS Encryption SDK CLI Syntax and Parameter Reference (p. 49) Installing the AWS Encryption SDK Command Line Interface This topic explains how to install the AWS Encryption CLI. For detailed information, see the awsencryption-sdk-cli repository on GitHub and Read the Docs. Topics • Installing the Prerequisites (p. 27) • Installing the AWS Encryption CLI (p. 28) Installing the Prerequisites The AWS Encryption CLI is built on the AWS Encryption SDK for Python. To use the AWS Encryption CLI, you need Python and pip, the Python package management tool. Python and pip are available on all supported platforms. Before you install the AWS Encryption CLI, be sure that you have the following prerequisites. Python The AWS Encryption CLI requires Python 2.7, or Python 3.4 or later. Python is included in most Linux and macOS installations, although you might need to upgrade to one of the required versions. However, you have to install Python on Windows, if it is not already installed. To download Python, see Python downloads. To determine whether Python is installed, at the command line, type: python To check the Python version, use the -V (uppercase V) parameter. python -V 27 AWS Encryption SDK Developer Guide Installing the CLI On Windows, you need to install Python. Then, add the path to the Python.exe file to the value of the Path environment variable. By default, Python is installed in the all users directory or in a user profile directory ($home or %userprofile%) in the AppData\Local\Programs\Python subdirectory. To find the location of the Python.exe file on your system, check one of the following registry keys. You can use PowerShell to search the registry. PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath # -orPS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath pip pip is the Python package manager. To install the AWS Encryption CLI and its dependencies, you need pip 8.1 or later. For help installing or upgrading pip, see Installation in the pip documentation. AWS Command Line Interface The AWS Command Line Interface (AWS CLI) is required only if you are using AWS Key Management Service (AWS KMS) customer master keys (CMKs) with the AWS Encryption CLI. If you are using a different master key provider (p. 7), the AWS CLI is not required. To use AWS KMS CMKs with the AWS Encryption CLI, you need to install and configure the AWS CLI. The configuration makes the credentials that you use to authenticate to AWS KMS available to the AWS Encryption CLI. Installing the AWS Encryption CLI Use pip to install the AWS Encryption CLI and the Python cryptography library that it requires. The AWS Encryption CLI requires the cryptography library on all platforms. All versions of pip install and build the cryptography library on Windows and OS X. On Linux, pip 8.1 and later installs and builds the cryptography library. If you are using an earlier version of pip and your Linux environment doesn't have the tools needed to build the cryptography library, you must install them. For more information, see Building cryptography on Linux. To install the latest version pip install aws-encryption-sdk-cli To upgrade to the latest version pip install --upgrade aws-encryption-sdk-cli To find the version number of your AWS Encryption CLI and AWS Encryption SDK aws-encryption-cli --version aws-encryption-sdk-cli/1.1.0 aws-encryption-sdk/1.3.2 To install the version of the AWS Encryption CLI currently in development, see the aws-encryption-sdk-cli repository on GitHub. 28 AWS Encryption SDK Developer Guide How to Use the CLI For more details about using pip to install and upgrade Python packages, see the pip documentation. How to Use the AWS Encryption SDK Command Line Interface This topic explains how to use the parameters in the AWS Encryption CLI. For examples, see Examples of the AWS Encryption SDK Command Line Interface (p. 36). For complete documentation, see Read the Docs. Topics • How to Encrypt and Decrypt Data (p. 29) • How to Specify a Master Key (p. 30) • How to Provide Input (p. 32) • How to Specify the Output Location (p. 32) • How to Use an Encryption Context (p. 33) • How to Store Parameters in a Configuration File (p. 34) How to Encrypt and Decrypt Data The AWS Encryption CLI uses the features of the AWS Encryption SDK to make it easy to encrypt and decrypt data securely. • When you encrypt data in the AWS Encryption CLI, you specify your plaintext data and a master key (p. 6), such as an AWS Key Management Service (AWS KMS) customer master key (CMK). If you are using a custom master key provider, you need to specify the provider. You also specify output locations for the encrypted message (p. 8) and for metadata about the encryption operation. An encryption context (p. 8) is optional, but recommended. aws-encryption-cli --encrypt --input myPlaintextData \ --master-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \ --output myEncryptedMessage \ --metadata-output ~/metadata \ --encryption-context purpose=test The AWS Encryption CLI gets a unique data key from the master key and encrypts your data. It returns an encrypted message (p. 8) and metadata about the operation. The encrypted message contains your encrypted data (ciphertext) and an encrypted copy of the data key. You don't have to worry about storing, managing, or losing the data key. • When you decrypt data, you pass in your encrypted message, the optional encryption context, and location for the plaintext output and the metadata. If you are using a custom master key provider, you also supply the master key. If you are using an AWS KMS CMK, AWS KMS derives the master key from the encrypted message. aws-encryption-cli --decrypt --input myEncryptedMessage \ --output myPlaintextData \ --metadata-output ~/metadata \ --encryption-context purpose=test The AWS Encryption CLI uses the master key to decrypt the data key in the encrypted message. Then it uses the data key to decrypt your data. It returns your plaintext data and metadata about the operation. 29 AWS Encryption SDK Developer Guide How to Use the CLI How to Specify a Master Key When you encrypt data in the AWS Encryption CLI, you need to specify a master key (p. 6). You can use an AWS KMS customer master key (CMK) or a master key from a custom master key provider (p. 7). The custom master key provider can be any compatible Python master key provider. To specify a master key, use the --master-keys parameter (-m). Its value is a collection of attributes (p. 30) with the attribute=value format. The attributes that you use depend on the master key provider and the command. • AWS KMS. In encrypt commands, you must specify a --master-keys parameter with a key attribute. The other attributes are optional. In decrypt commands, the --master-keys parameter is optional and it can only have a profile attribute. • Custom master key provider. You must specify the --master-keys parameter in every command. The parameter value must have key and provider attributes. You can include multiple --master-keys parameters (p. 31) in the same command. Master Key Parameter Attributes The value of the --master-keys parameter consists of the following attributes and their values. If an attribute name or value includes spaces or special characters, enclose both the name and value in quotation marks. For example, --master-keys key=12345 "provider=my cool provider". Key: Specify a Master Key Use the key attribute to identify a master key. The value can be any key identifier that the master key provider recognizes. --master-keys key=1234abcd-12ab-34cd-56ef-1234567890ab In an encrypt command, each --master-keys parameter value must include at least one key attribute and value. You can use multiple key attributes (p. 31) in each --master-keys parameter value. aws-encryption-cli --encrypt --master-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d In encrypt commands that use AWS KMS CMKs, the value of key can be the CMK ID, its Amazon Resource Name (ARN), an alias name, or alias ARN. For example, this encrypt command uses an alias ARN in the value of the key attribute. aws-encryption-cli --encrypt --master-keys key=arn:aws:kms:uswest-2:111122223333:alias/ExampleAlias In decrypt commands that use a custom master key provider, key and provider attributes are required. The key attribute is not permitted in decrypt commands that use an AWS KMS CMK. aws-encryption-cli --decrypt --master-keys provider='myProvider' key='100101' Provider: Specify the Master Key Provider The provider attribute identifies the master key provider (p. 7). The default value is aws-kms, which represents AWS KMS. If you are using a different master key provider, the provider attribute is required. 30 AWS Encryption SDK Developer Guide How to Use the CLI --master-keys key=12345 provider=my_custom_provider For more information about using custom (non-AWS KMS) master key providers, see the Advanced Configuration topic in the README file for the AWS Encryption SDK CLI repository. Region: Specify an AWS Region Use the region attribute to specify the AWS Region of an AWS KMS CMK. This attribute is valid only in encrypt commands and only when the master key provider is AWS KMS. --encrypt --master-keys key=alias/primary-key region=us-east-2 AWS Encryption CLI commands use the AWS Region that is specified in the key attribute value if it includes a region, such as an ARN. if the key value specifies a AWS Region, the region attribute is ignored. The region attribute takes precedence over other region specifications. If you don't use a region attribute, AWS Encryption CLI commands uses the AWS Region specified in your AWS CLI named profile, if any, or your default profile. Profile: Specify a Named Profile Use the profile attribute to specify an AWS CLI named profile. Named profiles can include credentials and an AWS Region. This attribute is valid only when the master key provider is AWS KMS. --master-keys key=alias/primary-key profile=admin-1 You can use the profile attribute to specify alternate credentials in encrypt and decrypt commands. In an encrypt command, the AWS Encryption CLI uses the AWS Region in the named profile only when the key value does not include a region and there is no region attribute. In a decrypt command, the AWS Region in the name profile is ignored. How to Specify Multiple Master Keys You can specify multiple master keys in each command. If you specify more than one master key, the first master key generates (and encrypts) the data key that is used to encrypt your data. The other master keys only encrypt the data key. The resulting encrypted message (p. 8) contains the encrypted data ("ciphertext") and a collection of encrypted data keys, one encrypted by each master key. Any of the master keys can decrypt one data key and then decrypt the data. There are two ways to specify multiple master keys: • Include multiple key attributes in a --master-keys parameter value. $cmk_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $cmk_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef --master-keys key=$cmk_oregon key=$cmk_ohio • Include multiple --master-keys parameters in the same command. Use this syntax when the attribute values that you specify do not apply to all of the master keys in the command. --master-keys region=us-east-2 key=alias/primary_CMK \ 31 AWS Encryption SDK Developer Guide How to Use the CLI --master-keys region=us-west-1 key=alias/primary_CMK How to Provide Input The encrypt operation in the AWS Encryption CLI takes plaintext data as input and returns an encrypted message (p. 8). The decrypt operation takes an encrypted message as input and returns plaintext data. The --input parameter (-i) , which tells the AWS Encryption CLI where to find the input, is required in all AWS Encryption CLI commands. You can provide input in any of the following ways: • Use a file. --input myData.txt • Use a file name pattern. --input testdir/*.xml • Use a directory or directory name pattern. When the input is a directory, the --recursive parameter (-r, -R) is required. --input testdir --recursive • Pipe input to the command (stdin). Use a value of - for the --input parameter. (The --input parameter is always required.) echo 'Hello World' | aws-encryption-cli --encrypt --input - How to Specify the Output Location The --output parameter tells the AWS Encryption CLI where to write the results of the encryption or decryption operation. It is required in every AWS Encryption CLI command. The AWS Encryption CLI creates a new output file for every input file in the operation. If an output file already exists, by default, the AWS Encryption CLI prints a warning, then overwrites the file. To prevent overwriting, use the --interactive parameter, which prompts you for confirmation before overwriting, or --no-overwrite, which skips the input if the output would cause an overwrite. To suppress the overwrite warning, use --quiet. To capture errors and warnings from the AWS Encryption CLI, use the 2>&1 redirection operator to write them to the output stream. Note Commands that overwrite output files begin by deleting the output file. If the command fails, the output file might already be deleted. You can the output location in several ways. • Specify a file name. If you specify a path to the file, all directories in the path must exist before the command runs. --output myEncryptedData.txt • Specify a directory. The output directory must exist before the command runs. 32 AWS Encryption SDK Developer Guide How to Use the CLI If the input contains subdirectories, the command reproduces the subdirectories under the specified directory. --output Test When the output location is a directory (without file names), the AWS Encryption CLI creates output file names based on the input file names plus a suffix. Encrypt operations append .encrypted to the input file name and the decrypt operations append .decrypted. To change the suffix, use the -suffix parameter. For example, if you encrypt file.txt, the encrypt command creates file.txt.encrypted. If you decrypt file.txt.encrypted, the decrypt command creates file.txt.encrypted.decrypted. • Write to the command line (stdout). Enter a value of - for the --output parameter. You can use -output - to pipe output to another command or program. --output - How to Use an Encryption Context The AWS Encryption CLI lets you provide an encryption context in encrypt and decrypt commands. It is not required, but it is a cryptographic best practice that we recommend. An encryption context is a type of arbitrary, non-secret additional authenticated data. In the AWS Encryption CLI, the encryption context consists of a collection of name=value pairs. You can use any content in the pairs, including information about the files, data that helps you to find the encryption operation in logs, or data that your grants or policies require. In an Encrypt Command The encryption context that you specify in an encrypt command, along with any additional encryption context that the encryption components add, is cryptographically bound to the encrypted data. It is also included (in plaintext) in the encrypted message (p. 8) that the command returns. If you are using an AWS KMS customer master key (CMK), the encryption context also might appear in plaintext in audit records and logs, such as AWS CloudTrail. The following example shows a encryption context with three name=value pairs. --encryption-context purpose=test dept=IT class=confidential In a Decrypt Command In a decrypt command, the encryption context helps you to confirm that you are decrypting the right encrypted message. You are not required to provide an encryption context in a decrypt command, even if an encryption context was used on encrypt. However, if you do, the AWS Encryption CLI verifies that every element in the encryption context of the decrypt command matches an element in the encryption context of the encrypted message. If any element does not match, the decrypt command fails. For example, the following command decrypts the encrypted message only if its encryption context includes dept=IT. 33 AWS Encryption SDK Developer Guide How to Use the CLI aws-encryption-cli --decrypt --encryption-context dept=IT ... An encryption context is an important part of your security strategy. However, when choosing an encryption context, remember that its values are not secret. Do not include any confidential data in the encryption context. To specify an encryption context: • In an encrypt command, use the --encryption-context parameter with one or more name=value pairs. Use a space to separate each pair. --encryption-context name=value [name=value] ... • In a decrypt command, the --encryption-context parameter value can include name=value pairs, name elements (with no values), or a combination of both. --encryption-context name[=value] [name] [name=value] ... If the name or value in a name=value pair includes spaces or special characters, enclose the entire pair in quotation marks. --encryption-context "department=software engineering" "AWS Region=us-west-2" For example, this encrypt command includes an encryption context with two pairs, purpose=test and dept=23. aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ... These decrypt command would succeed. The encryption context in each commands is a subset of the original encryption context. \\ Any one or both of the encryption context pairs aws-encryption-cli --decrypt --encryption-context dept=23 ... \\ Any one or both of the encryption context names aws-encryption-cli --decrypt --encryption-context purpose ... \\ Any combination of names and pairs aws-encryption-cli --decrypt --encryption-context dept purpose=test ... However, these decrypt commands would fail. The encryption context in the encrypted message does not contain the specified elements. aws-encryption-cli --decrypt --encryption-context dept=Finance ... aws-encryption-cli --decrypt --encryption-context scope ... How to Store Parameters in a Configuration File You can save time and avoid typing errors by saving frequently used AWS Encryption CLI parameters and values in configuration files. A configuration file is a text file that contains parameters and values for an AWS Encryption CLI command. When you refer to a configuration file in a AWS Encryption CLI command, the reference is 34 AWS Encryption SDK Developer Guide How to Use the CLI replaced by the parameters and values in the configuration file. The effect is the same is if you typed the file content at the command line. A configuration file can have any name and it can be located in any directory that the current user can access. The following example configuration file, cmk.conf, specifies two AWS KMS CMKs in different regions. --master-keys key=arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab --master-keys key=arn:aws:kms:useast-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef To use the configuration file in a command, prefix the file name with an at sign (@). In a PowerShell console, use a backtick character to escape the at sign (`@). This example command uses the cmk.conf file in an encrypt command. Bash $ aws-encryption-cli -e @cmk.conf -i hello.txt -o testdir PowerShell PS C:\> aws-encryption-cli -e `@cmk.conf -i .\Hello.txt -o .\TestDir Configuration File Rules The rules for using configuration files are as follows: • You can include multiple parameters in each configuration file and list them in any order. List each parameter with its values (if any) on a separate line. • Use # to add a comment to all or part of a line. • You can include references to other configuration files. Do not use a backtick to escape the @ sign, even in PowerShell. • If you use quotes in a configuration file, the quoted text cannot span multiple lines. For example, this is the contents of an example encrypt.conf file. # Archive Files --encrypt --output /archive/logs --recursive --interactive --encryption-context class=unclassified dept=IT --suffix # No suffix --metadata-output ~/metadata @caching.conf # Use limited caching You can also include multiple configuration files in a command. This example command uses both the encrypt.conf and master-keys.conf configurations files. Bash $ aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf 35 AWS Encryption SDK Developer Guide Examples PowerShell PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf Next: Try the AWS Encryption CLI examples (p. 36) Examples of the AWS Encryption SDK Command Line Interface Use the following examples to try the AWS Encryption CLI on the platform you prefer. For help with master keys and other parameters, see How to Use the AWS Encryption SDK Command Line Interface (p. 29). For a quick reference, see AWS Encryption SDK CLI Syntax and Parameter Reference (p. 49). Topics • Encrypting a File (p. 36) • Decrypting a File (p. 38) • Encrypting All Files in a Directory (p. 39) • Decrypting All Files in a Directory (p. 40) • Encrypting and Decrypting on the Command Line (p. 42) • Using Multiple Master Keys (p. 43) • Encrypting and Decrypting in Scripts (p. 45) • Using Data Key Caching (p. 47) Encrypting a File This example uses the AWS Encryption CLI to encrypt the contents of the hello.txt file, which contains a "Hello World" string. When you run an encrypt command on a file, the AWS Encryption CLI gets the contents of the file, generates a unique data key (p. 6), encrypts the file contents under the data key, and then writes the encrypted message (p. 8) to a new file. The first command saves the Amazon Resource Name (ARN) of an AWS KMS customer master key (CMK) in the $cmkArn variable. The second command encrypts the file contents. The command uses the --encrypt parameter to specify the operation and the --input parameter to indicate the file to encrypt. The --master-keys parameter (p. 30), and its required key attribute, tell the command to use the master key represented by the CMK ARN. The command uses the --metadata-output parameter to specify a text file for the metadata about the encryption operation. As a best practice, the command uses the --encryption-context parameter to specify an encryption context (p. 33). The value of the --output parameter, a dot (.), tells the command to write the output file to the current directory. Bash \\ To run this example, replace the fictitious CMK ARN with a valid value. 36 AWS Encryption SDK Developer Guide Examples $ cmkArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --encrypt \ --input hello.txt \ --master-keys key=$cmkArn \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --output . PowerShell # To run this example, replace the fictitious CMK ARN with a valid value. PS C:\> $CmkArn = arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PS C:\> aws-encryption-cli --encrypt ` --input Hello.txt ` --master-keys key=$CmkArn ` --metadata-output $home\Metadata.txt ` --encryption-context purpose=test ` --output . When the encrypt command succeeds, it does not return any output. To determine whether the command succeeded, check the Boolean value in the $? variable. When the command succeeds, the value of $? is 0 (Bash) or True (PowerShell). When the command fails, the value of $? is non-zero (Bash) or False (PowerShell). Bash $ echo $? 0 PowerShell PS C:\> $? True You can also use a directory listing command to see that the encrypt command created a new file, hello.txt.encrypted. Because the encrypt command did not specify a file name for the output, the AWS Encryption CLI wrote the output to a file with the same name as the input file plus a .encrypted suffix. To use a different suffix, or suppress the suffix, use the --suffix parameter. The hello.txt.encrypted file contains an encrypted message (p. 8) that includes the ciphertext of the hello.txt file, an encrypted copy of the data key, and additional metadata, including the encryption context. Bash $ ls hello.txt hello.txt.encrypted PowerShell PS C:\> dir 37 AWS Encryption SDK Developer Guide Examples Directory: C:\TestCLI Mode ----a----a---- LastWriteTime ------------9/15/2017 5:57 PM 9/17/2017 1:06 PM Length -----11 585 Name ---Hello.txt Hello.txt.encrypted Decrypting a File This example uses the AWS Encryption CLI to decrypt the contents of the Hello.txt.encrypted file that was encrypted in the previous example. The decrypt command uses the --decrypt parameter to indicate the operation and --input parameter to identify the file to decrypt. The value of the --output parameter is a dot that represents the current directory. This command does not have a --master-keys parameter. A --master-keys parameter is required in decrypt commands only when you are using a custom master key provider. If you are using an AWS KMS CMK, you cannot specify a master key, because AWS KMS derives it from the encrypted message. The --encryption-context parameter is optional in the decrypt command, even when an encryption context (p. 33) is provided in the encrypt command. In this case, the decrypt command uses the same encryption context that was provided in the encrypt command. Before decrypting, the AWS Encryption CLI verifies that the encryption context in the encrypted message includes a purpose=test pair. If it does not, the decrypt command fails. The --metadata-output parameter specifies a file for metadata about the decryption operation. The value of the --output parameter, a dot (.), writes the output file to the current directory. Bash $ aws-encryption-cli --decrypt \ --input hello.txt.encrypted \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --output . PowerShell PS C:\> aws-encryption-cli --decrypt ` --input Hello.txt.encrypted ` --encryption-context purpose=test ` --metadata-output $home\Metadata.txt ` --output . When a decrypt command succeeds, it does not return any output. To determine whether the command succeeded, get the value of the $? variable. You can also use a directory listing command to see that the command created a new file with a .decrypted suffix. To see the plaintext content, use a command to get the file content, such as cat or Get-Content. Bash $ ls hello.txt $ hello.txt.encrypted hello.txt.encrypted.decrypted cat hello.txt.encrypted.decrypted 38 AWS Encryption SDK Developer Guide Examples Hello World PowerShell PS C:\> dir Directory: C:\TestCLI Mode ----a----a----a---- LastWriteTime ------------9/17/2017 1:01 PM 9/17/2017 1:06 PM 9/17/2017 1:08 PM Length -----11 585 11 Name ---Hello.txt Hello.txt.encrypted Hello.txt.encrypted.decrypted PS C:\> Get-Content Hello.txt.encrypted.decrypted Hello World Encrypting All Files in a Directory This example uses the AWS Encryption CLI to encrypt the contents of all of the files in a directory. When a command affects multiple files, the AWS Encryption CLI processes each file individually. It gets the file contents, gets a unique data key (p. 6) for the file from the master key, encrypts the file contents under the data key, and writes the results to a new file in the output directory. As a result, you can decrypt the output files independently. This listing of the TestDir directory shows the plaintext files that we want to encrypt. Bash $ ls testdir cool-new-thing.py hello.txt employees.csv PowerShell PS C:\> dir C:\TestDir Directory: C:\TestDir Mode ----a----a----a---- LastWriteTime ------------9/12/2017 3:11 PM 9/15/2017 5:57 PM 9/17/2017 1:44 PM Length -----2139 11 46 Name ---cool-new-thing.py Hello.txt Employees.csv The first command saves the Amazon Resource Name (ARN) of an AWS KMS customer master key (CMK) in the $cmkArn variable. The second command encrypts the content of files in the TestDir directory and writes the files of encrypted content to the TestEnc directory. If the TestEnc directory doesn't exist, the command fails. Because the input location is a directory, the --recursive parameter is required. The --master-keys parameter (p. 30), and its required key attribute, specify the master key. The encrypt command includes an encryption context (p. 33), dept=IT. When you specify an encryption context in a command that encrypts multiple files, the same encryption context is used for all of the files. 39 AWS Encryption SDK Developer Guide Examples The command also has a --metadata-output parameter to tell the AWS Encryption CLI where to write the metadata about the encryption operations. The AWS Encryption CLI writes one metadata record for each file that was encrypted. When the command completes, the AWS Encryption CLI writes the encrypted files to the TestEnc directory, but it does not return any output. The final command lists the files in the TestEnc directory. There is one output file of encrypted content for each input file of plaintext content. Because the command did not specify an alternate suffix, the encrypt command appended .encrypted to each of the input file names. Bash # To run this example, replace the fictitious CMK ARN with a valid master key identifier. $ cmkArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --encrypt \ --input testdir --recursive\ --master-keys key=$cmkArn \ --encryption-context dept=IT \ --metadata-output ~/metadata \ --output testenc $ ls testenc cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted PowerShell # To run this example, replace the fictitious CMK ARN with a valid master key identifier. PS C:\> $cmkArn = arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PS C:\> aws-encryption-cli --encrypt ` --input .\TestDir --recursive ` --master-keys key=$cmkArn ` --encryption-context dept=IT ` --metadata-output .\Metadata\Metadata.txt ` --output .\TestEnc PS C:\> dir .\TestEnc Directory: C:\TestEnc Mode ----a----a----a---- LastWriteTime ------------9/17/2017 2:32 PM 9/17/2017 2:32 PM 9/17/2017 2:32 PM Length -----2713 620 585 Name ---cool-new-thing.py.encrypted Hello.txt.encrypted Employees.csv.encrypted Decrypting All Files in a Directory This example decrypts all files in a directory. It starts with the files in the TestEnc directory that were encrypted in the previous example. Bash $ ls testenc 40 AWS Encryption SDK Developer Guide Examples cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted PowerShell PS C:\> dir C:\TestEnc Directory: C:\TestEnc Mode ----a----a----a---- LastWriteTime ------------9/17/2017 2:32 PM 9/17/2017 2:32 PM 9/17/2017 2:32 PM Length -----2713 620 585 Name ---cool-new-thing.py.encrypted Hello.txt.encrypted Employees.csv.encrypted This decrypt command decrypts all of the files in the TestEnc directory and writes the plaintext files to the TestDec directory. Because the encrypted files were encrypted under an AWS KMS CMK, there is no --master-keys parameter in the command. The command uses the --interactive parameter to tell the AWS Encryption CLI to prompt you before overwriting a file with the same name. This command also uses the encryption context that was provided when the files were encrypted. When decrypting multiple files, the AWS Encryption CLI checks the encryption context of every file. If the encryption context check on any file fails, the AWS Encryption CLI rejects the file, writes a warning, records the failure in the metadata, and then continues checking the remaining files. If the AWS Encryption CLI fails to decrypt a file for any other reason, the entire decrypt command fails immediately. In this example, the encrypted messages in all of the input files contain the dept=IT encryption context element. However, if you were decrypting messages with different encryption contexts, you might still be able to verify part of the encryption context. For example, if some messages had an encryption context of dept=finance and others had dept=IT, you could verify that the encryption context always contains a dept name without specifying the value. If you wanted to be more specific, you could decrypt the files in separate commands. The decrypt command does not return any output, but you can use a directory listing command to see that it created new files with the .decrypted suffix. To see the plaintext content, use a command to get the file content. Bash $ aws-encryption-cli --decrypt --input testenc --recursive \ --encryption-context dept=IT \ --metadata-output ~/metadata \ --output testdec --interactive $ ls testdec cool-new-thing.py.encrypted.decrypted employees.csv.encrypted.decrypted hello.txt.encrypted.decrypted PowerShell PS C:\> aws-encryption-cli --decrypt ` --input C:\TestEnc --recursive ` --encryption-context dept=IT ` --metadata-output $home\Metadata.txt ` --output C:\TestDec --interactive PS C:\> dir .\TestDec 41 AWS Encryption SDK Developer Guide Examples Mode ----a----a----a---- LastWriteTime ------------10/8/2017 4:57 PM 10/8/2017 4:57 PM 10/8/2017 4:57 PM Length Name ------ ---2139 cool-new-thing.py.encrypted.decrypted 46 Employees.csv.encrypted.decrypted 11 Hello.txt.encrypted.decrypted Encrypting and Decrypting on the Command Line These examples show you how to pipe input to commands (stdin) and write output to the command line (stdout). They explain how to represent stdin and stdout in a command and how to use the built-in Base64 encoding tools to prevent the shell from misinterpreting non-ASCII characters. This example pipes a plaintext string to an encrypt command and saves the encrypted message in a variable. Then, it pipes the encrypted message in the variable to a decrypt command, which writes its output to the pipeline (stdout). The example consists of three commands: • The first command saves the Amazon Resource Name (ARN) of an AWS KMS customer master key (CMK) in the $cmkArn variable. Bash $ cmkArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PowerShell PS C:\> $cmkArn = arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab • The second command pipes the Hello World string to the encrypt command and saves the result in the $encrypted variable. The --input and --output parameters are required in all AWS Encryption CLI commands. To indicate that input is being piped to the command (stdin), use a hyphen (-) for the value of the -input parameter. To send the output to the command line (stdout), use a hyphen for the value of the --output parameter. The --encode parameter Base64-encodes the output before returning it. This prevents the shell from misinterpreting the non-ASCII characters in the encrypted message. Because this command is just a proof of concept, we omit the encryption context and suppress the metadata (-S). Bash $ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \ --input - --output - --encode \ --master-keys key=$cmkArn ) PowerShell PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S ` --input - --output - --encode ` --master-keys key=$cmkArn 42 AWS Encryption SDK Developer Guide Examples • The third command pipes the encrypted message in the $encrypted variable to the decrypt command. This decrypt command uses --input - to indicate that input is coming from the pipeline (stdin) and --output - to send the output to the pipeline (stdout). (The input parameter takes the location of the input, not the actual input bytes, so you cannot use the $encrypted variable as the value of the --input parameter.) Because the output was encrypted and then encoded, the decrypt command uses the --decode parameter to decode Base64-encoded input before decrypting it. You can also use the --decode parameter to decode Base64-encoded input before encrypting it. Again, the command omits the encryption context and suppresses the metadata (-S). Bash $ echo $encrypted | aws-encryption-cli --decrypt --input - --output - --decode -S Hello World PowerShell PS C:\> $encrypted | aws-encryption-cli --decrypt --input - --output - --decode -S Hello World You can also perform the encrypt and decrypt operations in a single command without the intervening variable. As in the previous example, the --input and --output parameters have a - value and the command uses the --encode parameter to encode the output and the --decode parameter to decode the input. Bash $ cmkArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ echo 'Hello World' | aws-encryption-cli --encrypt --master-keys key=$cmkArn --input - --output --encode -S | aws-encryption-cli --decrypt --input - --output - --decode -S Hello World PowerShell PS C:\> $cmkArn = arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PS C:\> 'Hello World' | aws-encryption-cli --encrypt --master-keys key=$cmkArn --input - -output - --encode -S | aws-encryption-cli --decrypt --input - --output - --decode -S Hello World Using Multiple Master Keys This example shows how to use multiple master keys when encrypting and decrypting data in the AWS Encryption CLI. 43 AWS Encryption SDK Developer Guide Examples When you use multiple master keys to encrypt data, any one of the master keys can be used to decrypt the data. This strategy assures that you can decrypt the data even if one of the master keys is unavailable. If you are storing the encrypted data in multiple AWS Regions, this strategy lets you use a master key in the same Region to decrypt the data. When you encrypt with multiple master keys, the first master key plays a special role. It generates the data key that is used to encrypt the data. The remaining master keys encrypt the plaintext data key. The resulting encrypted message (p. 8) includes the encrypted data and a collection of encrypted data keys, one for each master key. Although the first master key generated the data key, any of the master keys can decrypt one of the data keys, which can be used to decrypt the data. Encrypting with Three Master Keys This example command uses three master keys to encrypt the Finance.log file, one in each of three AWS Regions. It writes the encrypted message to the Archive directory. The command uses the --suffix parameter with no value to suppress the suffix, so the input and output files names will be the same. The command uses the --master-keys parameter with three key attributes. You can also use multiple --master-keys parameters in the same command. To encrypt the log file, the AWS Encryption CLI asks the first master key in the list, $cmk1, to generate the data key that it uses to encrypt the data. Then, it uses each of the other master keys to encrypt the plaintext copy of the data key. The encrypted message in the output file includes all three of the encrypted data keys. Bash $ cmk1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ cmk2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef $ cmk3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d $ aws-encryption-cli --encrypt --input /logs/finance.log \ --output /archive --suffix \ --encryption-context class=log \ --metadata-output ~/metadata \ --master-keys key=$cmk1 key=$cmk2 key=$cmk3 PowerShell PS C:\> $cmk1 = arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PS C:\> $cmk2 = arn:aws:kms:useast-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef PS C:\> $cmk3 = arn:aws:kms:apsoutheast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log ` --output D:\Archive --suffix ` --encryption-context class=log ` --metadata-output $home\Metadata.txt ` --master-keys key=$cmk1 key=$cmk2 key=$cmk3 This command decrypts the encrypted copy of the Finance.log file and writes it to a Finance.log.clear file in the Finance directory. When you decrypt data that was encrypted under AWS KMS CMKs, you cannot tell AWS KMS to use a particular CMK to decrypt the data. The key attribute of the --master-keys parameter is not valid in a decrypt command with the aws-kms provider. The AWS Encryption CLI can use any of the CMKs that 44 AWS Encryption SDK Developer Guide Examples were used to encrypt the data, provided that the AWS credentials you are using have permission to call the Decrypt API on the master key. For more information, see Authentication and Access Control for AWS KMS. Bash $ aws-encryption-cli --decrypt --input /archive/finance.log \ --output /finance --suffix '.clear' \ --metadata-output ~/metadata \ --encryption-context class=log PowerShell PS C:\> aws-encryption-cli --decrypt ` --input D:\Archive\Finance.log ` --output D:\Finance --suffix '.clear' ` --metadata-output .\Metadata\Metadata.txt ` --encryption-context class=log Encrypting and Decrypting in Scripts This example shows how to use the AWS Encryption CLI in scripts. You can write scripts that just encrypt and decrypt data, or scripts that encrypt or decrypt as part of a data management process. In this example, the script gets a collection of log files, compresses them, encrypts them, and then copies the encrypted files to an Amazon S3 bucket. This script processes each file separately, so that you can decrypt and expand them independently. When you compress and encrypt files, be sure to compress before you encrypt. Properly encrypted data is not compressible. Warning Be careful when compressing data that includes both secrets and data that might be controlled by a malicious actor. The final size of the compressed data might inadvertently reveal sensitive information about its contents. You can find the complete scripts in the Examples directory of the aws-encryption-sdk-cli repository in GitHub. PowerShell #Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive Param ( [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String[]] $FilePath, [Parameter()] [Switch] $Recurse, [Parameter(Mandatory=$true)] [String] $masterKeyID, [Parameter()] [String] $masterKeyProvider = 'aws-kms', 45 AWS Encryption SDK Developer Guide Examples [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String] $ZipDirectory, [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String] $EncryptDirectory, [Parameter()] [String] $EncryptionContext, [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String] $MetadataDirectory, [Parameter(Mandatory)] [ValidateScript({Test-S3Bucket -BucketName $_})] [String] $S3Bucket, ) [Parameter()] [String] $S3BucketFolder BEGIN {} PROCESS { if ($files = dir $FilePath -Recurse:$Recurse) { # Step 1: Compress foreach ($file in $files) { $fileName = $file.Name try { Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName DestinationPath $ZipDirectory\$filename.zip } catch { Write-Error "Zip failed on $file.FullName" } # Step 2: Encrypt if (-not (Test-Path "$ZipDirectory\$filename.zip")) { Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip" } else { # 2>&1 captures command output $err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" ` -o $EncryptDirectory ` -m key=$masterKeyID provider= $masterKeyProvider ` -c $EncryptionContext ` --metadata-output $MetadataDirectory ` -v) 2>&1 # Check error status 46 AWS Encryption SDK Developer Guide Examples if ($? -eq $false) { # Write the error $err } elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted") { # Step 3: Write to S3 bucket if ($S3BucketFolder) { Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\ $fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted" } else { Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\ $fileName.zip.encrypted" } } } } } } Using Data Key Caching This example uses data key caching (p. 55) in a command that encrypts a large number of files. By default, the AWS Encryption CLI (and other versions of the AWS Encryption SDK) generates a unique data key for each file that it encrypts. Although using a unique data key for each operation is a cryptographic best practice, limited reuse of data keys is acceptable for some situations. If you are considering data key caching, consult with a security engineer to understand the security requirements of your application and determine security thresholds that are right for you. In this example, data key caching speeds up the encryption operation by reducing the frequency of requests to the master key provider. The command in this example encrypts a large directory with multiple subdirectories that contain a total of approximately 800 small log files. The first command saves the ARN of the CMK in a cmkARN variable. The second command encrypts all of the files in the input directory (recursively) and writes them to an archive directory. The command uses the --suffix parameter to specify the .archive suffix. The --caching parameter enables data key caching. The capacity attribute, which limits the number of data keys in the cache, is set to 1, because serial file processing never uses more than one data key at a time. The max_age attribute, which determines how long the cached data key can used, is set to 10 seconds. The optional max_messages_encrypted attribute is set to 10 messages, so a single data key is never used to encrypt more than 10 files. Limiting the number of files encrypted by each data key reduces the number of files that would be affected in the unlikely event that a data key was compromised. To run this command on log files that your operating system generates, you might need administrator permissions (sudo in Linux; Run as Administrator in Windows). Bash $ cmkArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab 47 AWS Encryption SDK Developer Guide Examples $ aws-encryption-cli --encrypt \ --input /var/log/httpd --recursive \ --output ~/archive --suffix .archive \ --master-keys key=$cmkArn \ --encryption-context class=log \ --suppress-metadata \ --caching capacity=1 max_age=10 max_messages_encrypted=10 PowerShell PS C:\> $cmkArn = arn:aws:kms:uswest-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PS C:\> aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --master-keys key=$cmkARN ` --encryption-context class=log ` --suppress-metadata ` --caching capacity=1 max_age=10 max_messages_encrypted=10 To test the effect of data key caching, this example uses the Measure-Command cmdlet in PowerShell. When you run this example without data key caching, it takes about 25 seconds to complete. This process generates a new data key for each file in the directory. PS C:\> Measure-Command {aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --master-keys key=$cmkARN ` --encryption-context class=log ` --suppress-metadata } Days Hours Minutes Seconds Milliseconds Ticks TotalDays TotalHours TotalMinutes TotalSeconds TotalMilliseconds : : : : : : : : : : : 0 0 0 25 453 254531202 0.000294596298611111 0.00707031116666667 0.42421867 25.4531202 25453.1202 Data key caching makes the process quicker, even when you limit each data key to a maximum of 10 files. The command now takes less than 12 seconds to complete and reduces the number of calls to the master key provider to 1/10 of the original value. PS C:\> Measure-Command {aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --master-keys key=$cmkARN ` --encryption-context class=log ` --suppress-metadata ` --caching capacity=1 max_age=10 max_messages_encrypted=10} Days Hours : 0 : 0 48 AWS Encryption SDK Developer Guide Syntax and Parameter Reference Minutes Seconds Milliseconds Ticks TotalDays TotalHours TotalMinutes TotalSeconds TotalMilliseconds : : : : : : : : : 0 11 813 118132640 0.000136727592592593 0.00328146222222222 0.196887733333333 11.813264 11813.264 If you eliminate the max_messages_encrypted restriction, all files are encrypted under the same data key. This change increases the risk of reusing data keys without making the process much faster. However, it reduces the number of calls to the master key provider to 1. PS C:\> Measure-Command {aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --master-keys key=$cmkARN ` --encryption-context class=log ` --suppress-metadata ` --caching capacity=1 max_age=10} Days Hours Minutes Seconds Milliseconds Ticks TotalDays TotalHours TotalMinutes TotalSeconds TotalMilliseconds : : : : : : : : : : : 0 0 0 10 252 102523367 0.000118661304398148 0.00284787130555556 0.170872278333333 10.2523367 10252.3367 AWS Encryption SDK CLI Syntax and Parameter Reference This topic provides syntax diagrams and brief parameter descriptions to help you use the AWS Encryption SDK Command Line Interface (CLI). For help with master keys and other parameters, see How to Use the AWS Encryption SDK Command Line Interface (p. 29). For example, see Examples of the AWS Encryption SDK Command Line Interface (p. 36). For complete documentation, see Read the Docs. Topics • AWS Encryption CLI Syntax (p. 49) • AWS Encryption CLI Command Line Parameters (p. 51) • Advanced Parameters (p. 54) AWS Encryption CLI Syntax These AWS Encryption CLI syntax diagrams show the syntax for each task that you perform with the AWS Encryption CLI. Get Help To get the full AWS Encryption CLI syntax with parameter descriptions, use --help or -h. 49 AWS Encryption SDK Developer Guide Syntax and Parameter Reference aws-encryption-cli (--help | -h) Get the Version To get the version number of your AWS Encryption CLI installation, use --version. Be sure to include the version when you ask questions, report problems, or share tips about using the AWS Encryption CLI. aws-encryption-cli --version Encrypt Data The following syntax diagram shows the parameters that an encrypt command uses. aws-encryption-cli --encrypt --input [--recursive] [--decode] --output- Key ARN: For help finding the Amazon Resource Name (ARN) of your KMS customer master * key (CMK), see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/ developerguide/viewing-keys.html *
- Name of file containing plaintext data to encrypt *
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf Linearized : No Page Count : 104 Profile CMM Type : Little CMS Profile Version : 2.1.0 Profile Class : Display Device Profile Color Space Data : RGB Profile Connection Space : XYZ Profile Date Time : 1998:02:09 06:49:00 Profile File Signature : acsp Primary Platform : Apple Computer Inc. CMM Flags : Not Embedded, Independent Device Manufacturer : Hewlett-Packard Device Model : sRGB Device Attributes : Reflective, Glossy, Positive, Color Rendering Intent : Perceptual Connection Space Illuminant : 0.9642 1 0.82491 Profile Creator : Little CMS Profile ID : 0 Profile Copyright : Copyright (c) 1998 Hewlett-Packard Company Profile Description : sRGB IEC61966-2.1 Media White Point : 0.95045 1 1.08905 Media Black Point : 0 0 0 Red Matrix Column : 0.43607 0.22249 0.01392 Green Matrix Column : 0.38515 0.71687 0.09708 Blue Matrix Column : 0.14307 0.06061 0.7141 Device Mfg Desc : IEC http://www.iec.ch Device Model Desc : IEC 61966-2.1 Default RGB colour space - sRGB Viewing Cond Desc : Reference Viewing Condition in IEC61966-2.1 Viewing Cond Illuminant : 19.6445 20.3718 16.8089 Viewing Cond Surround : 3.92889 4.07439 3.36179 Viewing Cond Illuminant Type : D50 Luminance : 76.03647 80 87.12462 Measurement Observer : CIE 1931 Measurement Backing : 0 0 0 Measurement Geometry : Unknown Measurement Flare : 0.999% Measurement Illuminant : D65 Technology : Cathode Ray Tube Display Red Tone Reproduction Curve : (Binary data 2060 bytes, use -b option to extract) Green Tone Reproduction Curve : (Binary data 2060 bytes, use -b option to extract) Blue Tone Reproduction Curve : (Binary data 2060 bytes, use -b option to extract) Producer : Apache FOP Version 2.1 PDF Version : 1.4 Creator : AWS Format : application/pdf Title : AWS Encryption SDK - Developer Guide Language : en Date : 2018:11:19 08:51:12Z Creator Tool : ZonBook XSL Stylesheets with Apache FOP Metadata Date : 2018:11:19 08:51:12Z Create Date : 2018:11:19 08:51:12Z Page Mode : UseOutlines Author : AWS Keywords : client-side encryption, encryption client, encryption SDKEXIF Metadata provided by EXIF.tools