Debian Codegraph @

docs/source/guide/kms-example-encrypt-decrypt-file.rst

raw
1 .. Copyright 2010-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2
3 This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
4 International License (the "License"). You may not use this file except in compliance with the
5 License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
6
7 This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
8 either express or implied. See the License for the specific language governing permissions and
9 limitations under the License.
10
11 .. _aws-boto3-kms-examples-encrypt-decrypt-file:
12
13 **************************
14 Encrypt and decrypt a file
15 **************************
16
17 The example program uses AWS KMS keys to encrypt and decrypt a file.
18
19 A master key, also called a Customer Master Key or CMK, is created and used to generate a data key.
20 The data key is then used to encrypt a disk file. The encrypted data key is stored within
21 the encrypted file. To decrypt the file, the data key is decrypted and then used to decrypt
22 the rest of the file. This manner of using master and data keys is called envelope encryption.
23
24 To encrypt and decrypt data, the example uses the well-known Python ``cryptography`` package.
25 This package is not part of the Python standard library and must be installed separately, for
26 example, with the ``pip`` command.
27
28 ::
29
30 pip install cryptography
31
32
33 Retrieve an existing master key
34 ===============================
35
36 Master keys are created, managed, and stored within AWS KMS. A KMS master key is also referred to
37 as a customer master key or CMK. An AWS storage cost is incurred for each CMK, therefore, one CMK is
38 often used to manage multiple data keys.
39
40 The example ``retrieve_cmk`` function searches for an existing CMK. A key description is specified
41 when a CMK is created, and this description is used to identify and retrieve the desired key. If
42 many CMKs exist, they are processed in batches until either the desired key is found or all keys are
43 examined.
44
45 If the example function finds the desired CMK, it returns both the CMK's ID and its ARN (Amazon
46 Resource Name). Either of these identifiers can be used to reference the CMK in subsequent calls
47 to AWS KMS methods.
48
49 .. code-block:: python
50
51 def retrieve_cmk(desc):
52 """Retrieve an existing KMS CMK based on its description
53
54 :param desc: Description of CMK specified when the CMK was created
55 :return Tuple(KeyId, KeyArn) where:
56 KeyId: CMK ID
57 KeyArn: Amazon Resource Name of CMK
58 :return Tuple(None, None) if a CMK with the specified description was
59 not found
60 """
61
62 # Retrieve a list of existing CMKs
63 # If more than 100 keys exist, retrieve and process them in batches
64 kms_client = boto3.client('kms')
65 try:
66 response = kms_client.list_keys()
67 except ClientError as e:
68 logging.error(e)
69 return None, None
70
71 done = False
72 while not done:
73 for cmk in response['Keys']:
74 # Get info about the key, including its description
75 try:
76 key_info = kms_client.describe_key(KeyId=cmk['KeyArn'])
77 except ClientError as e:
78 logging.error(e)
79 return None, None
80
81 # Is this the key we're looking for?
82 if key_info['KeyMetadata']['Description'] == desc:
83 return cmk['KeyId'], cmk['KeyArn']
84
85 # Are there more keys to retrieve?
86 if not response['Truncated']:
87 # No, the CMK was not found
88 logging.debug('A CMK with the specified description was not found')
89 done = True
90 else:
91 # Yes, retrieve another batch
92 try:
93 response = kms_client.list_keys(Marker=response['NextMarker'])
94 except ClientError as e:
95 logging.error(e)
96 return None, None
97
98 # All existing CMKs were checked and the desired key was not found
99 return None, None
100
101
102 Create a customer master key
103 ============================
104
105 If the example does not find an existing CMK, it creates a new one and returns its ID and ARN.
106
107 .. code-block:: python
108
109 def create_cmk(desc='Customer Master Key'):
110 """Create a KMS Customer Master Key
111
112 The created CMK is a Customer-managed key stored in AWS KMS.
113
114 :param desc: key description
115 :return Tuple(KeyId, KeyArn) where:
116 KeyId: AWS globally-unique string ID
117 KeyArn: Amazon Resource Name of the CMK
118 :return Tuple(None, None) if error
119 """
120
121 # Create CMK
122 kms_client = boto3.client('kms')
123 try:
124 response = kms_client.create_key(Description=desc)
125 except ClientError as e:
126 logging.error(e)
127 return None, None
128
129 # Return the key ID and ARN
130 return response['KeyMetadata']['KeyId'], response['KeyMetadata']['Arn']
131
132
133 Create a data key
134 =================
135
136 To encrypt a file, the example ``create_data_key`` function creates a data key. The data key is
137 customer managed and does not incur an AWS storage cost. The example creates a data key for
138 each file it encrypts, but it's possible to use a single data key to encrypt multiple files.
139
140 The example function returns the data key in both its plaintext and encrypted forms. The
141 plaintext form is used to encrypt the data. The encrypted form will be stored with the encrypted
142 file. The data key is associated with a CMK which is capable of decrypting the encrypted data key
143 when necessary.
144
145
146 .. code-block:: python
147
148 def create_data_key(cmk_id, key_spec='AES_256'):
149 """Generate a data key to use when encrypting and decrypting data
150
151 :param cmk_id: KMS CMK ID or ARN under which to generate and encrypt the
152 data key.
153 :param key_spec: Length of the data encryption key. Supported values:
154 'AES_128': Generate a 128-bit symmetric key
155 'AES_256': Generate a 256-bit symmetric key
156 :return Tuple(EncryptedDataKey, PlaintextDataKey) where:
157 EncryptedDataKey: Encrypted CiphertextBlob data key as binary string
158 PlaintextDataKey: Plaintext base64-encoded data key as binary string
159 :return Tuple(None, None) if error
160 """
161
162 # Create data key
163 kms_client = boto3.client('kms')
164 try:
165 response = kms_client.generate_data_key(KeyId=cmk_id, KeySpec=key_spec)
166 except ClientError as e:
167 logging.error(e)
168 return None, None
169
170 # Return the encrypted and plaintext data key
171 return response['CiphertextBlob'], base64.b64encode(response['Plaintext'])
172
173
174 Encrypt a file
175 ==============
176
177 The ``encrypt_file`` function creates a data key and uses it to encrypt the contents of a disk file.
178
179 The encryption operation is performed by a ``Fernet`` object created by the Python ``cryptography``
180 package.
181
182 The encrypted form of the data key is saved within the encrypted file and will be used in the future
183 to decrypt the file. The encrypted file can be decrypted by any program with the credentials to
184 decrypt the encrypted data key.
185
186 .. code-block:: python
187
188 def encrypt_file(filename, cmk_id):
189 """Encrypt a file using an AWS KMS CMK
190
191 A data key is generated and associated with the CMK.
192 The encrypted data key is saved with the encrypted file. This enables the
193 file to be decrypted at any time in the future and by any program that
194 has the credentials to decrypt the data key.
195 The encrypted file is saved to <filename>.encrypted
196 Limitation: The contents of filename must fit in memory.
197
198 :param filename: File to encrypt
199 :param cmk_id: AWS KMS CMK ID or ARN
200 :return: True if file was encrypted. Otherwise, False.
201 """
202
203 # Read the entire file into memory
204 try:
205 with open(filename, 'rb') as file:
206 file_contents = file.read()
207 except IOError as e:
208 logging.error(e)
209 return False
210
211 # Generate a data key associated with the CMK
212 # The data key is used to encrypt the file. Each file can use its own
213 # data key or data keys can be shared among files.
214 # Specify either the CMK ID or ARN
215 data_key_encrypted, data_key_plaintext = create_data_key(cmk_id)
216 if data_key_encrypted is None:
217 return False
218 logging.info('Created new AWS KMS data key')
219
220 # Encrypt the file
221 f = Fernet(data_key_plaintext)
222 file_contents_encrypted = f.encrypt(file_contents)
223
224 # Write the encrypted data key and encrypted file contents together
225 try:
226 with open(filename + '.encrypted', 'wb') as file_encrypted:
227 file_encrypted.write(len(data_key_encrypted).to_bytes(NUM_BYTES_FOR_LEN,
228 byteorder='big'))
229 file_encrypted.write(data_key_encrypted)
230 file_encrypted.write(file_contents_encrypted)
231 except IOError as e:
232 logging.error(e)
233 return False
234
235 # For the highest security, the data_key_plaintext value should be wiped
236 # from memory. Unfortunately, this is not possible in Python. However,
237 # storing the value in a local variable makes it available for garbage
238 # collection.
239 return True
240
241
242 Decrypt a data key
243 ==================
244
245 To decrypt an encrypted file, the encrypted data key used to perform the encryption must first
246 be decrypted. This operation is performed by the example ``decrypt_data_key`` function which returns
247 the plaintext form of the key.
248
249 .. code-block:: python
250
251 def decrypt_data_key(data_key_encrypted):
252 """Decrypt an encrypted data key
253
254 :param data_key_encrypted: Encrypted ciphertext data key.
255 :return Plaintext base64-encoded binary data key as binary string
256 :return None if error
257 """
258
259 # Decrypt the data key
260 kms_client = boto3.client('kms')
261 try:
262 response = kms_client.decrypt(CiphertextBlob=data_key_encrypted)
263 except ClientError as e:
264 logging.error(e)
265 return None
266
267 # Return plaintext base64-encoded binary data key
268 return base64.b64encode((response['Plaintext']))
269
270
271 Decrypt a file
272 ==============
273
274 The example ``decrypt_file`` function first extracts the encrypted data key from the encrypted file. It
275 then decrypts the key to get its plaintext form and uses that to decrypt the file contents.
276
277 The decryption operation is performed by a ``Fernet`` object created by the Python ``cryptography``
278 package.
279
280 .. code-block:: python
281
282 def decrypt_file(filename):
283 """Decrypt a file encrypted by encrypt_file()
284
285 The encrypted file is read from <filename>.encrypted
286 The decrypted file is written to <filename>.decrypted
287
288 :param filename: File to decrypt
289 :return: True if file was decrypted. Otherwise, False.
290 """
291
292 # Read the encrypted file into memory
293 try:
294 with open(filename + '.encrypted', 'rb') as file:
295 file_contents = file.read()
296 except IOError as e:
297 logging.error(e)
298 return False
299
300 # The first NUM_BYTES_FOR_LEN bytes contain the integer length of the
301 # encrypted data key.
302 # Add NUM_BYTES_FOR_LEN to get index of end of encrypted data key/start
303 # of encrypted data.
304 data_key_encrypted_len = int.from_bytes(file_contents[:NUM_BYTES_FOR_LEN],
305 byteorder='big') \
306 + NUM_BYTES_FOR_LEN
307 data_key_encrypted = file_contents[NUM_BYTES_FOR_LEN:data_key_encrypted_len]
308
309 # Decrypt the data key before using it
310 data_key_plaintext = decrypt_data_key(data_key_encrypted)
311 if data_key_plaintext is None:
312 return False
313
314 # Decrypt the rest of the file
315 f = Fernet(data_key_plaintext)
316 file_contents_decrypted = f.decrypt(file_contents[data_key_encrypted_len:])
317
318 # Write the decrypted file contents
319 try:
320 with open(filename + '.decrypted', 'wb') as file_decrypted:
321 file_decrypted.write(file_contents_decrypted)
322 except IOError as e:
323 logging.error(e)
324 return False
325
326 # The same security issue described at the end of encrypt_file() exists
327 # here, too, i.e., the wish to wipe the data_key_plaintext value from
328 # memory.
329 return True