blib/lib/Paws/KMS.pm untested

filter: Statementstmt 0.0% 0 / 239 Branchbran 0.0% 0 / 16 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 59 Podpod 0.0% 0 / 58 totaltotal 0.0% 0 / 372 CC 9 SCAR 13.3
CC
9
Cov
0%
ListAllAliases
12.0
ListAllGrants
12.0
ListAllKeyPolicies
12.0
CRAP 3.8
1 package Paws::KMS;
2 use Moose;
3 sub service { 'kms' }
4 sub signing_name { 'kms' }
5 sub version { '2014-11-01' }
6 sub target_prefix { 'TrentService' }
7 sub json_version { "1.1" }
8 has max_attempts => (is => 'ro', isa => 'Int', default => 5);
9 has retry => (is => 'ro', isa => 'HashRef', default => sub {
10 { base => 'rand', type => 'exponential', growth_factor => 2 }
11 });
12 has retriables => (is => 'ro', isa => 'ArrayRef', default => sub { [
13 ] });
14  
15 with 'Paws::API::Caller', 'Paws::API::EndpointResolver', 'Paws::Net::V4Signature', 'Paws::Net::JsonCaller';
16  
17
18 sub CancelKeyDeletion {
19 my $self = shift;
20 my $call_object = $self->new_with_coercions('Paws::KMS::CancelKeyDeletion', @_);
21 return $self->caller->do_call($self, $call_object);
22 }
23 sub ConnectCustomKeyStore {
24 my $self = shift;
25 my $call_object = $self->new_with_coercions('Paws::KMS::ConnectCustomKeyStore', @_);
26 return $self->caller->do_call($self, $call_object);
27 }
28 sub CreateAlias {
29 my $self = shift;
30 my $call_object = $self->new_with_coercions('Paws::KMS::CreateAlias', @_);
31 return $self->caller->do_call($self, $call_object);
32 }
33 sub CreateCustomKeyStore {
34 my $self = shift;
35 my $call_object = $self->new_with_coercions('Paws::KMS::CreateCustomKeyStore', @_);
36 return $self->caller->do_call($self, $call_object);
37 }
38 sub CreateGrant {
39 my $self = shift;
40 my $call_object = $self->new_with_coercions('Paws::KMS::CreateGrant', @_);
41 return $self->caller->do_call($self, $call_object);
42 }
43 sub CreateKey {
44 my $self = shift;
45 my $call_object = $self->new_with_coercions('Paws::KMS::CreateKey', @_);
46 return $self->caller->do_call($self, $call_object);
47 }
48 sub Decrypt {
49 my $self = shift;
50 my $call_object = $self->new_with_coercions('Paws::KMS::Decrypt', @_);
51 return $self->caller->do_call($self, $call_object);
52 }
53 sub DeleteAlias {
54 my $self = shift;
55 my $call_object = $self->new_with_coercions('Paws::KMS::DeleteAlias', @_);
56 return $self->caller->do_call($self, $call_object);
57 }
58 sub DeleteCustomKeyStore {
59 my $self = shift;
60 my $call_object = $self->new_with_coercions('Paws::KMS::DeleteCustomKeyStore', @_);
61 return $self->caller->do_call($self, $call_object);
62 }
63 sub DeleteImportedKeyMaterial {
64 my $self = shift;
65 my $call_object = $self->new_with_coercions('Paws::KMS::DeleteImportedKeyMaterial', @_);
66 return $self->caller->do_call($self, $call_object);
67 }
68 sub DescribeCustomKeyStores {
69 my $self = shift;
70 my $call_object = $self->new_with_coercions('Paws::KMS::DescribeCustomKeyStores', @_);
71 return $self->caller->do_call($self, $call_object);
72 }
73 sub DescribeKey {
74 my $self = shift;
75 my $call_object = $self->new_with_coercions('Paws::KMS::DescribeKey', @_);
76 return $self->caller->do_call($self, $call_object);
77 }
78 sub DisableKey {
79 my $self = shift;
80 my $call_object = $self->new_with_coercions('Paws::KMS::DisableKey', @_);
81 return $self->caller->do_call($self, $call_object);
82 }
83 sub DisableKeyRotation {
84 my $self = shift;
85 my $call_object = $self->new_with_coercions('Paws::KMS::DisableKeyRotation', @_);
86 return $self->caller->do_call($self, $call_object);
87 }
88 sub DisconnectCustomKeyStore {
89 my $self = shift;
90 my $call_object = $self->new_with_coercions('Paws::KMS::DisconnectCustomKeyStore', @_);
91 return $self->caller->do_call($self, $call_object);
92 }
93 sub EnableKey {
94 my $self = shift;
95 my $call_object = $self->new_with_coercions('Paws::KMS::EnableKey', @_);
96 return $self->caller->do_call($self, $call_object);
97 }
98 sub EnableKeyRotation {
99 my $self = shift;
100 my $call_object = $self->new_with_coercions('Paws::KMS::EnableKeyRotation', @_);
101 return $self->caller->do_call($self, $call_object);
102 }
103 sub Encrypt {
104 my $self = shift;
105 my $call_object = $self->new_with_coercions('Paws::KMS::Encrypt', @_);
106 return $self->caller->do_call($self, $call_object);
107 }
108 sub GenerateDataKey {
109 my $self = shift;
110 my $call_object = $self->new_with_coercions('Paws::KMS::GenerateDataKey', @_);
111 return $self->caller->do_call($self, $call_object);
112 }
113 sub GenerateDataKeyPair {
114 my $self = shift;
115 my $call_object = $self->new_with_coercions('Paws::KMS::GenerateDataKeyPair', @_);
116 return $self->caller->do_call($self, $call_object);
117 }
118 sub GenerateDataKeyPairWithoutPlaintext {
119 my $self = shift;
120 my $call_object = $self->new_with_coercions('Paws::KMS::GenerateDataKeyPairWithoutPlaintext', @_);
121 return $self->caller->do_call($self, $call_object);
122 }
123 sub GenerateDataKeyWithoutPlaintext {
124 my $self = shift;
125 my $call_object = $self->new_with_coercions('Paws::KMS::GenerateDataKeyWithoutPlaintext', @_);
126 return $self->caller->do_call($self, $call_object);
127 }
128 sub GenerateRandom {
129 my $self = shift;
130 my $call_object = $self->new_with_coercions('Paws::KMS::GenerateRandom', @_);
131 return $self->caller->do_call($self, $call_object);
132 }
133 sub GetKeyPolicy {
134 my $self = shift;
135 my $call_object = $self->new_with_coercions('Paws::KMS::GetKeyPolicy', @_);
136 return $self->caller->do_call($self, $call_object);
137 }
138 sub GetKeyRotationStatus {
139 my $self = shift;
140 my $call_object = $self->new_with_coercions('Paws::KMS::GetKeyRotationStatus', @_);
141 return $self->caller->do_call($self, $call_object);
142 }
143 sub GetParametersForImport {
144 my $self = shift;
145 my $call_object = $self->new_with_coercions('Paws::KMS::GetParametersForImport', @_);
146 return $self->caller->do_call($self, $call_object);
147 }
148 sub GetPublicKey {
149 my $self = shift;
150 my $call_object = $self->new_with_coercions('Paws::KMS::GetPublicKey', @_);
151 return $self->caller->do_call($self, $call_object);
152 }
153 sub ImportKeyMaterial {
154 my $self = shift;
155 my $call_object = $self->new_with_coercions('Paws::KMS::ImportKeyMaterial', @_);
156 return $self->caller->do_call($self, $call_object);
157 }
158 sub ListAliases {
159 my $self = shift;
160 my $call_object = $self->new_with_coercions('Paws::KMS::ListAliases', @_);
161 return $self->caller->do_call($self, $call_object);
162 }
163 sub ListGrants {
164 my $self = shift;
165 my $call_object = $self->new_with_coercions('Paws::KMS::ListGrants', @_);
166 return $self->caller->do_call($self, $call_object);
167 }
168 sub ListKeyPolicies {
169 my $self = shift;
170 my $call_object = $self->new_with_coercions('Paws::KMS::ListKeyPolicies', @_);
171 return $self->caller->do_call($self, $call_object);
172 }
173 sub ListKeys {
174 my $self = shift;
175 my $call_object = $self->new_with_coercions('Paws::KMS::ListKeys', @_);
176 return $self->caller->do_call($self, $call_object);
177 }
178 sub ListResourceTags {
179 my $self = shift;
180 my $call_object = $self->new_with_coercions('Paws::KMS::ListResourceTags', @_);
181 return $self->caller->do_call($self, $call_object);
182 }
183 sub ListRetirableGrants {
184 my $self = shift;
185 my $call_object = $self->new_with_coercions('Paws::KMS::ListRetirableGrants', @_);
186 return $self->caller->do_call($self, $call_object);
187 }
188 sub PutKeyPolicy {
189 my $self = shift;
190 my $call_object = $self->new_with_coercions('Paws::KMS::PutKeyPolicy', @_);
191 return $self->caller->do_call($self, $call_object);
192 }
193 sub ReEncrypt {
194 my $self = shift;
195 my $call_object = $self->new_with_coercions('Paws::KMS::ReEncrypt', @_);
196 return $self->caller->do_call($self, $call_object);
197 }
198 sub ReplicateKey {
199 my $self = shift;
200 my $call_object = $self->new_with_coercions('Paws::KMS::ReplicateKey', @_);
201 return $self->caller->do_call($self, $call_object);
202 }
203 sub RetireGrant {
204 my $self = shift;
205 my $call_object = $self->new_with_coercions('Paws::KMS::RetireGrant', @_);
206 return $self->caller->do_call($self, $call_object);
207 }
208 sub RevokeGrant {
209 my $self = shift;
210 my $call_object = $self->new_with_coercions('Paws::KMS::RevokeGrant', @_);
211 return $self->caller->do_call($self, $call_object);
212 }
213 sub ScheduleKeyDeletion {
214 my $self = shift;
215 my $call_object = $self->new_with_coercions('Paws::KMS::ScheduleKeyDeletion', @_);
216 return $self->caller->do_call($self, $call_object);
217 }
218 sub Sign {
219 my $self = shift;
220 my $call_object = $self->new_with_coercions('Paws::KMS::Sign', @_);
221 return $self->caller->do_call($self, $call_object);
222 }
223 sub TagResource {
224 my $self = shift;
225 my $call_object = $self->new_with_coercions('Paws::KMS::TagResource', @_);
226 return $self->caller->do_call($self, $call_object);
227 }
228 sub UntagResource {
229 my $self = shift;
230 my $call_object = $self->new_with_coercions('Paws::KMS::UntagResource', @_);
231 return $self->caller->do_call($self, $call_object);
232 }
233 sub UpdateAlias {
234 my $self = shift;
235 my $call_object = $self->new_with_coercions('Paws::KMS::UpdateAlias', @_);
236 return $self->caller->do_call($self, $call_object);
237 }
238 sub UpdateCustomKeyStore {
239 my $self = shift;
240 my $call_object = $self->new_with_coercions('Paws::KMS::UpdateCustomKeyStore', @_);
241 return $self->caller->do_call($self, $call_object);
242 }
243 sub UpdateKeyDescription {
244 my $self = shift;
245 my $call_object = $self->new_with_coercions('Paws::KMS::UpdateKeyDescription', @_);
246 return $self->caller->do_call($self, $call_object);
247 }
248 sub UpdatePrimaryRegion {
249 my $self = shift;
250 my $call_object = $self->new_with_coercions('Paws::KMS::UpdatePrimaryRegion', @_);
251 return $self->caller->do_call($self, $call_object);
252 }
253 sub Verify {
254 my $self = shift;
255 my $call_object = $self->new_with_coercions('Paws::KMS::Verify', @_);
256 return $self->caller->do_call($self, $call_object);
257 }
258
259 sub ListAllAliases {
260 my $self = shift;
261  
262 my $callback = shift @_ if (ref($_[0]) eq 'CODE');
263 my $result = $self->ListAliases(@_);
264 my $next_result = $result;
265  
266 if (not defined $callback) {
267 while ($next_result->Truncated) {
268 $next_result = $self->ListAliases(@_, Marker => $next_result->NextMarker);
269 push @{ $result->Aliases }, @{ $next_result->Aliases };
270 }
271 return $result;
272 } else {
273 while ($result->Truncated) {
274 $callback->($_ => 'Aliases') foreach (@{ $result->Aliases });
275 $result = $self->ListAliases(@_, Marker => $result->NextMarker);
276 }
277 $callback->($_ => 'Aliases') foreach (@{ $result->Aliases });
278 }
279  
280 return undef
281 }
282 sub ListAllGrants {
283 my $self = shift;
284  
285 my $callback = shift @_ if (ref($_[0]) eq 'CODE');
286 my $result = $self->ListGrants(@_);
287 my $next_result = $result;
288  
289 if (not defined $callback) {
290 while ($next_result->Truncated) {
291 $next_result = $self->ListGrants(@_, Marker => $next_result->NextMarker);
292 push @{ $result->Grants }, @{ $next_result->Grants };
293 }
294 return $result;
295 } else {
296 while ($result->Truncated) {
297 $callback->($_ => 'Grants') foreach (@{ $result->Grants });
298 $result = $self->ListGrants(@_, Marker => $result->NextMarker);
299 }
300 $callback->($_ => 'Grants') foreach (@{ $result->Grants });
301 }
302  
303 return undef
304 }
305 sub ListAllKeyPolicies {
306 my $self = shift;
307  
308 my $callback = shift @_ if (ref($_[0]) eq 'CODE');
309 my $result = $self->ListKeyPolicies(@_);
310 my $next_result = $result;
311  
312 if (not defined $callback) {
313 while ($next_result->Truncated) {
314 $next_result = $self->ListKeyPolicies(@_, Marker => $next_result->NextMarker);
315 push @{ $result->PolicyNames }, @{ $next_result->PolicyNames };
316 }
317 return $result;
318 } else {
319 while ($result->Truncated) {
320 $callback->($_ => 'PolicyNames') foreach (@{ $result->PolicyNames });
321 $result = $self->ListKeyPolicies(@_, Marker => $result->NextMarker);
322 }
323 $callback->($_ => 'PolicyNames') foreach (@{ $result->PolicyNames });
324 }
325  
326 return undef
327 }
328 sub ListAllKeys {
329 my $self = shift;
330  
331 my $callback = shift @_ if (ref($_[0]) eq 'CODE');
332 my $result = $self->ListKeys(@_);
333 my $next_result = $result;
334  
335 if (not defined $callback) {
336 while ($next_result->Truncated) {
337 $next_result = $self->ListKeys(@_, Marker => $next_result->NextMarker);
338 push @{ $result->Keys }, @{ $next_result->Keys };
339 }
340 return $result;
341 } else {
342 while ($result->Truncated) {
343 $callback->($_ => 'Keys') foreach (@{ $result->Keys });
344 $result = $self->ListKeys(@_, Marker => $result->NextMarker);
345 }
346 $callback->($_ => 'Keys') foreach (@{ $result->Keys });
347 }
348  
349 return undef
350 }
351  
352  
353 sub operations { qw/CancelKeyDeletion ConnectCustomKeyStore CreateAlias CreateCustomKeyStore CreateGrant CreateKey Decrypt DeleteAlias DeleteCustomKeyStore DeleteImportedKeyMaterial DescribeCustomKeyStores DescribeKey DisableKey DisableKeyRotation DisconnectCustomKeyStore EnableKey EnableKeyRotation Encrypt GenerateDataKey GenerateDataKeyPair GenerateDataKeyPairWithoutPlaintext GenerateDataKeyWithoutPlaintext GenerateRandom GetKeyPolicy GetKeyRotationStatus GetParametersForImport GetPublicKey ImportKeyMaterial ListAliases ListGrants ListKeyPolicies ListKeys ListResourceTags ListRetirableGrants PutKeyPolicy ReEncrypt ReplicateKey RetireGrant RevokeGrant ScheduleKeyDeletion Sign TagResource UntagResource UpdateAlias UpdateCustomKeyStore UpdateKeyDescription UpdatePrimaryRegion Verify / }
354  
355 1;
356  
357 ### main pod documentation begin ###
358  
359 =head1 NAME
360  
361 Paws::KMS - Perl Interface to AWS AWS Key Management Service
362  
363 =head1 SYNOPSIS
364  
365 use Paws;
366  
367 my $obj = Paws->service('KMS');
368 my $res = $obj->Method(
369 Arg1 => $val1,
370 Arg2 => [ 'V1', 'V2' ],
371 # if Arg3 is an object, the HashRef will be used as arguments to the constructor
372 # of the arguments type
373 Arg3 => { Att1 => 'Val1' },
374 # if Arg4 is an array of objects, the HashRefs will be passed as arguments to
375 # the constructor of the arguments type
376 Arg4 => [ { Att1 => 'Val1' }, { Att1 => 'Val2' } ],
377 );
378  
379 =head1 DESCRIPTION
380  
381 AWS Key Management Service
382  
383 AWS Key Management Service (AWS KMS) is an encryption and key
384 management web service. This guide describes the AWS KMS operations
385 that you can call programmatically. For general information about AWS
386 KMS, see the I<AWS Key Management Service Developer Guide>
387 (https://docs.aws.amazon.com/kms/latest/developerguide/).
388  
389 AWS provides SDKs that consist of libraries and sample code for various
390 programming languages and platforms (Java, Ruby, .Net, macOS, Android,
391 etc.). The SDKs provide a convenient way to create programmatic access
392 to AWS KMS and other AWS services. For example, the SDKs take care of
393 tasks such as signing requests (see below), managing errors, and
394 retrying requests automatically. For more information about the AWS
395 SDKs, including how to download and install them, see Tools for Amazon
396 Web Services (http://aws.amazon.com/tools/).
397  
398 We recommend that you use the AWS SDKs to make programmatic API calls
399 to AWS KMS.
400  
401 Clients must support TLS (Transport Layer Security) 1.0. We recommend
402 TLS 1.2. Clients must also support cipher suites with Perfect Forward
403 Secrecy (PFS) such as Ephemeral Diffie-Hellman (DHE) or Elliptic Curve
404 Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7
405 and later support these modes.
406  
407 B<Signing Requests>
408  
409 Requests must be signed by using an access key ID and a secret access
410 key. We strongly recommend that you I<do not> use your AWS account
411 (root) access key ID and secret key for everyday work with AWS KMS.
412 Instead, use the access key ID and secret access key for an IAM user.
413 You can also use the AWS Security Token Service to generate temporary
414 security credentials that you can use to sign requests.
415  
416 All AWS KMS operations require Signature Version 4
417 (https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
418  
419 B<Logging API Requests>
420  
421 AWS KMS supports AWS CloudTrail, a service that logs AWS API calls and
422 related events for your AWS account and delivers them to an Amazon S3
423 bucket that you specify. By using the information collected by
424 CloudTrail, you can determine what requests were made to AWS KMS, who
425 made the request, when it was made, and so on. To learn more about
426 CloudTrail, including how to turn it on and find your log files, see
427 the AWS CloudTrail User Guide
428 (https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
429  
430 B<Additional Resources>
431  
432 For more information about credentials and request signing, see the
433 following:
434  
435 =over
436  
437 =item *
438  
439 AWS Security Credentials
440 (https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html)
441 - This topic provides general information about the types of
442 credentials used for accessing AWS.
443  
444 =item *
445  
446 Temporary Security Credentials
447 (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)
448 - This section of the I<IAM User Guide> describes how to create and use
449 temporary security credentials.
450  
451 =item *
452  
453 Signature Version 4 Signing Process
454 (https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
455 - This set of topics walks you through the process of signing a request
456 using an access key ID and a secret access key.
457  
458 =back
459  
460 B<Commonly Used API Operations>
461  
462 Of the API operations discussed in this guide, the following will prove
463 the most useful for most applications. You will likely perform
464 operations other than these, such as creating keys and assigning
465 policies, by using the console.
466  
467 =over
468  
469 =item *
470  
471 Encrypt
472  
473 =item *
474  
475 Decrypt
476  
477 =item *
478  
479 GenerateDataKey
480  
481 =item *
482  
483 GenerateDataKeyWithoutPlaintext
484  
485 =back
486  
487  
488 For the AWS API documentation, see L<https://docs.aws.amazon.com/goto/WebAPI/kms-2014-11-01>
489  
490  
491 =head1 METHODS
492  
493 =head2 CancelKeyDeletion
494  
495 =over
496  
497 =item KeyId => Str
498  
499  
500 =back
501  
502 Each argument is described in detail in: L<Paws::KMS::CancelKeyDeletion>
503  
504 Returns: a L<Paws::KMS::CancelKeyDeletionResponse> instance
505  
506 Cancels the deletion of a customer master key (CMK). When this
507 operation succeeds, the key state of the CMK is C<Disabled>. To enable
508 the CMK, use EnableKey.
509  
510 For more information about scheduling and canceling deletion of a CMK,
511 see Deleting Customer Master Keys
512 (https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html)
513 in the I<AWS Key Management Service Developer Guide>.
514  
515 The CMK that you use for this operation must be in a compatible key
516 state. For details, see Key state: Effect on your CMK
517 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
518 in the I<AWS Key Management Service Developer Guide>.
519  
520 B<Cross-account use>: No. You cannot perform this operation on a CMK in
521 a different AWS account.
522  
523 B<Required permissions>: kms:CancelKeyDeletion
524 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
525 (key policy)
526  
527 B<Related operations>: ScheduleKeyDeletion
528  
529  
530 =head2 ConnectCustomKeyStore
531  
532 =over
533  
534 =item CustomKeyStoreId => Str
535  
536  
537 =back
538  
539 Each argument is described in detail in: L<Paws::KMS::ConnectCustomKeyStore>
540  
541 Returns: a L<Paws::KMS::ConnectCustomKeyStoreResponse> instance
542  
543 Connects or reconnects a custom key store
544 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
545 to its associated AWS CloudHSM cluster.
546  
547 The custom key store must be connected before you can create customer
548 master keys (CMKs) in the key store or use the CMKs it contains. You
549 can disconnect and reconnect a custom key store at any time.
550  
551 To connect a custom key store, its associated AWS CloudHSM cluster must
552 have at least one active HSM. To get the number of active HSMs in a
553 cluster, use the DescribeClusters
554 (https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)
555 operation. To add HSMs to the cluster, use the CreateHsm
556 (https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html)
557 operation. Also, the C<kmsuser> crypto user
558 (https://docs.aws.amazon.com/kms/latest/developerguide/key-store-concepts.html#concept-kmsuser)
559 (CU) must not be logged into the cluster. This prevents AWS KMS from
560 using this account to log in.
561  
562 The connection process can take an extended amount of time to complete;
563 up to 20 minutes. This operation starts the connection process, but it
564 does not wait for it to complete. When it succeeds, this operation
565 quickly returns an HTTP 200 response and a JSON object with no
566 properties. However, this response does not indicate that the custom
567 key store is connected. To get the connection state of the custom key
568 store, use the DescribeCustomKeyStores operation.
569  
570 During the connection process, AWS KMS finds the AWS CloudHSM cluster
571 that is associated with the custom key store, creates the connection
572 infrastructure, connects to the cluster, logs into the AWS CloudHSM
573 client as the C<kmsuser> CU, and rotates its password.
574  
575 The C<ConnectCustomKeyStore> operation might fail for various reasons.
576 To find the reason, use the DescribeCustomKeyStores operation and see
577 the C<ConnectionErrorCode> in the response. For help interpreting the
578 C<ConnectionErrorCode>, see CustomKeyStoresListEntry.
579  
580 To fix the failure, use the DisconnectCustomKeyStore operation to
581 disconnect the custom key store, correct the error, use the
582 UpdateCustomKeyStore operation if necessary, and then use
583 C<ConnectCustomKeyStore> again.
584  
585 If you are having trouble connecting or disconnecting a custom key
586 store, see Troubleshooting a Custom Key Store
587 (https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html)
588 in the I<AWS Key Management Service Developer Guide>.
589  
590 B<Cross-account use>: No. You cannot perform this operation on a custom
591 key store in a different AWS account.
592  
593 B<Required permissions>: kms:ConnectCustomKeyStore
594 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
595 (IAM policy)
596  
597 B<Related operations>
598  
599 =over
600  
601 =item *
602  
603 CreateCustomKeyStore
604  
605 =item *
606  
607 DeleteCustomKeyStore
608  
609 =item *
610  
611 DescribeCustomKeyStores
612  
613 =item *
614  
615 DisconnectCustomKeyStore
616  
617 =item *
618  
619 UpdateCustomKeyStore
620  
621 =back
622  
623  
624  
625 =head2 CreateAlias
626  
627 =over
628  
629 =item AliasName => Str
630  
631 =item TargetKeyId => Str
632  
633  
634 =back
635  
636 Each argument is described in detail in: L<Paws::KMS::CreateAlias>
637  
638 Returns: nothing
639  
640 Creates a friendly name for a customer master key (CMK).
641  
642 Adding, deleting, or updating an alias can allow or deny permission to
643 the CMK. For details, see Using ABAC in AWS KMS
644 (https://docs.aws.amazon.com/kms/latest/developerguide/abac.html) in
645 the I<AWS Key Management Service Developer Guide>.
646  
647 You can use an alias to identify a CMK in the AWS KMS console, in the
648 DescribeKey operation and in cryptographic operations
649 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations),
650 such as Encrypt and GenerateDataKey. You can also change the CMK that's
651 associated with the alias (UpdateAlias) or delete the alias
652 (DeleteAlias) at any time. These operations don't affect the underlying
653 CMK.
654  
655 You can associate the alias with any customer managed CMK in the same
656 AWS Region. Each alias is associated with only one CMK at a time, but a
657 CMK can have multiple aliases. A valid CMK is required. You can't
658 create an alias without a CMK.
659  
660 The alias must be unique in the account and Region, but you can have
661 aliases with the same name in different Regions. For detailed
662 information about aliases, see Using aliases
663 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html)
664 in the I<AWS Key Management Service Developer Guide>.
665  
666 This operation does not return a response. To get the alias that you
667 created, use the ListAliases operation.
668  
669 The CMK that you use for this operation must be in a compatible key
670 state. For details, see Key state: Effect on your CMK
671 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
672 in the I<AWS Key Management Service Developer Guide>.
673  
674 B<Cross-account use>: No. You cannot perform this operation on an alias
675 in a different AWS account.
676  
677 B<Required permissions>
678  
679 =over
680  
681 =item *
682  
683 kms:CreateAlias
684 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
685 on the alias (IAM policy).
686  
687 =item *
688  
689 kms:CreateAlias
690 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
691 on the CMK (key policy).
692  
693 =back
694  
695 For details, see Controlling access to aliases
696 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html#alias-access)
697 in the I<AWS Key Management Service Developer Guide>.
698  
699 B<Related operations:>
700  
701 =over
702  
703 =item *
704  
705 DeleteAlias
706  
707 =item *
708  
709 ListAliases
710  
711 =item *
712  
713 UpdateAlias
714  
715 =back
716  
717  
718  
719 =head2 CreateCustomKeyStore
720  
721 =over
722  
723 =item CloudHsmClusterId => Str
724  
725 =item CustomKeyStoreName => Str
726  
727 =item KeyStorePassword => Str
728  
729 =item TrustAnchorCertificate => Str
730  
731  
732 =back
733  
734 Each argument is described in detail in: L<Paws::KMS::CreateCustomKeyStore>
735  
736 Returns: a L<Paws::KMS::CreateCustomKeyStoreResponse> instance
737  
738 Creates a custom key store
739 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
740 that is associated with an AWS CloudHSM cluster
741 (https://docs.aws.amazon.com/cloudhsm/latest/userguide/clusters.html)
742 that you own and manage.
743  
744 This operation is part of the Custom Key Store feature
745 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
746 feature in AWS KMS, which combines the convenience and extensive
747 integration of AWS KMS with the isolation and control of a
748 single-tenant key store.
749  
750 Before you create the custom key store, you must assemble the required
751 elements, including an AWS CloudHSM cluster that fulfills the
752 requirements for a custom key store. For details about the required
753 elements, see Assemble the Prerequisites
754 (https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#before-keystore)
755 in the I<AWS Key Management Service Developer Guide>.
756  
757 When the operation completes successfully, it returns the ID of the new
758 custom key store. Before you can use your new custom key store, you
759 need to use the ConnectCustomKeyStore operation to connect the new key
760 store to its AWS CloudHSM cluster. Even if you are not going to use
761 your custom key store immediately, you might want to connect it to
762 verify that all settings are correct and then disconnect it until you
763 are ready to use it.
764  
765 For help with failures, see Troubleshooting a Custom Key Store
766 (https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html)
767 in the I<AWS Key Management Service Developer Guide>.
768  
769 B<Cross-account use>: No. You cannot perform this operation on a custom
770 key store in a different AWS account.
771  
772 B<Required permissions>: kms:CreateCustomKeyStore
773 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
774 (IAM policy).
775  
776 B<Related operations:>
777  
778 =over
779  
780 =item *
781  
782 ConnectCustomKeyStore
783  
784 =item *
785  
786 DeleteCustomKeyStore
787  
788 =item *
789  
790 DescribeCustomKeyStores
791  
792 =item *
793  
794 DisconnectCustomKeyStore
795  
796 =item *
797  
798 UpdateCustomKeyStore
799  
800 =back
801  
802  
803  
804 =head2 CreateGrant
805  
806 =over
807  
808 =item GranteePrincipal => Str
809  
810 =item KeyId => Str
811  
812 =item Operations => ArrayRef[Str|Undef]
813  
814 =item [Constraints => L<Paws::KMS::GrantConstraints>]
815  
816 =item [GrantTokens => ArrayRef[Str|Undef]]
817  
818 =item [Name => Str]
819  
820 =item [RetiringPrincipal => Str]
821  
822  
823 =back
824  
825 Each argument is described in detail in: L<Paws::KMS::CreateGrant>
826  
827 Returns: a L<Paws::KMS::CreateGrantResponse> instance
828  
829 Adds a grant to a customer master key (CMK).
830  
831 A I<grant> is a policy instrument that allows AWS principals to use AWS
832 KMS customer master keys (CMKs) in cryptographic operations. It also
833 can allow them to view a CMK (DescribeKey) and create and manage
834 grants. When authorizing access to a CMK, grants are considered along
835 with key policies and IAM policies. Grants are often used for temporary
836 permissions because you can create one, use its permissions, and delete
837 it without changing your key policies or IAM policies.
838  
839 For detailed information about grants, including grant terminology, see
840 Using grants
841 (https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in
842 the I< I<AWS Key Management Service Developer Guide> >. For examples of
843 working with grants in several programming languages, see Programming
844 grants
845 (https://docs.aws.amazon.com/kms/latest/developerguide/programming-grants.html).
846  
847 The C<CreateGrant> operation returns a C<GrantToken> and a C<GrantId>.
848  
849 =over
850  
851 =item *
852  
853 When you create, retire, or revoke a grant, there might be a brief
854 delay, usually less than five minutes, until the grant is available
855 throughout AWS KMS. This state is known as I<eventual consistency>.
856 Once the grant has achieved eventual consistency, the grantee principal
857 can use the permissions in the grant without identifying the grant.
858  
859 However, to use the permissions in the grant immediately, use the
860 C<GrantToken> that C<CreateGrant> returns. For details, see Using a
861 grant token
862 (https://docs.aws.amazon.com/kms/latest/developerguide/using-grant-token.html)
863 in the I< I<AWS Key Management Service Developer Guide> >.
864  
865 =item *
866  
867 The C<CreateGrant> operation also returns a C<GrantId>. You can use the
868 C<GrantId> and a key identifier to identify the grant in the
869 RetireGrant and RevokeGrant operations. To find the grant ID, use the
870 ListGrants or ListRetirableGrants operations.
871  
872 =back
873  
874 For information about symmetric and asymmetric CMKs, see Using
875 Symmetric and Asymmetric CMKs
876 (https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)
877 in the I<AWS Key Management Service Developer Guide>. For more
878 information about grants, see Grants
879 (https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in
880 the I< I<AWS Key Management Service Developer Guide> >.
881  
882 The CMK that you use for this operation must be in a compatible key
883 state. For details, see Key state: Effect on your CMK
884 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
885 in the I<AWS Key Management Service Developer Guide>.
886  
887 B<Cross-account use>: Yes. To perform this operation on a CMK in a
888 different AWS account, specify the key ARN in the value of the C<KeyId>
889 parameter.
890  
891 B<Required permissions>: kms:CreateGrant
892 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
893 (key policy)
894  
895 B<Related operations:>
896  
897 =over
898  
899 =item *
900  
901 ListGrants
902  
903 =item *
904  
905 ListRetirableGrants
906  
907 =item *
908  
909 RetireGrant
910  
911 =item *
912  
913 RevokeGrant
914  
915 =back
916  
917  
918  
919 =head2 CreateKey
920  
921 =over
922  
923 =item [BypassPolicyLockoutSafetyCheck => Bool]
924  
925 =item [CustomerMasterKeySpec => Str]
926  
927 =item [CustomKeyStoreId => Str]
928  
929 =item [Description => Str]
930  
931 =item [KeyUsage => Str]
932  
933 =item [MultiRegion => Bool]
934  
935 =item [Origin => Str]
936  
937 =item [Policy => Str]
938  
939 =item [Tags => ArrayRef[L<Paws::KMS::Tag>]]
940  
941  
942 =back
943  
944 Each argument is described in detail in: L<Paws::KMS::CreateKey>
945  
946 Returns: a L<Paws::KMS::CreateKeyResponse> instance
947  
948 Creates a unique customer managed customer master key
949 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master-keys)
950 (CMK) in your AWS account and Region.
951  
952 You can use the C<CreateKey> operation to create symmetric or
953 asymmetric CMKs.
954  
955 =over
956  
957 =item *
958  
959 B<Symmetric CMKs> contain a 256-bit symmetric key that never leaves AWS
960 KMS unencrypted. To use the CMK, you must call AWS KMS. You can use a
961 symmetric CMK to encrypt and decrypt small amounts of data, but they
962 are typically used to generate data keys
963 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys)
964 and data keys pairs
965 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-key-pairs).
966 For details, see GenerateDataKey and GenerateDataKeyPair.
967  
968 =item *
969  
970 B<Asymmetric CMKs> can contain an RSA key pair or an Elliptic Curve
971 (ECC) key pair. The private key in an asymmetric CMK never leaves AWS
972 KMS unencrypted. However, you can use the GetPublicKey operation to
973 download the public key so it can be used outside of AWS KMS. CMKs with
974 RSA key pairs can be used to encrypt or decrypt data or sign and verify
975 messages (but not both). CMKs with ECC key pairs can be used only to
976 sign and verify messages.
977  
978 =back
979  
980 For information about symmetric and asymmetric CMKs, see Using
981 Symmetric and Asymmetric CMKs
982 (https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)
983 in the I<AWS Key Management Service Developer Guide>.
984  
985 To create different types of CMKs, use the following guidance:
986  
987 =over
988  
989 =item Asymmetric CMKs
990  
991 To create an asymmetric CMK, use the C<CustomerMasterKeySpec> parameter
992 to specify the type of key material in the CMK. Then, use the
993 C<KeyUsage> parameter to determine whether the CMK will be used to
994 encrypt and decrypt or sign and verify. You can't change these
995 properties after the CMK is created.
996  
997 =item Symmetric CMKs
998  
999 When creating a symmetric CMK, you don't need to specify the
1000 C<CustomerMasterKeySpec> or C<KeyUsage> parameters. The default value
1001 for C<CustomerMasterKeySpec>, C<SYMMETRIC_DEFAULT>, and the default
1002 value for C<KeyUsage>, C<ENCRYPT_DECRYPT>, are the only valid values
1003 for symmetric CMKs.
1004  
1005 =item Multi-Region primary keys
1006  
1007 =item Imported key material
1008  
1009 To create a multi-Region I<primary key> in the local AWS Region, use
1010 the C<MultiRegion> parameter with a value of C<True>. To create a
1011 multi-Region I<replica key>, that is, a CMK with the same key ID and
1012 key material as a primary key, but in a different AWS Region, use the
1013 ReplicateKey operation. To change a replica key to a primary key, and
1014 its primary key to a replica key, use the UpdatePrimaryRegion
1015 operation.
1016  
1017 This operation supports I<multi-Region keys>, an AWS KMS feature that
1018 lets you create multiple interoperable CMKs in different AWS Regions.
1019 Because these CMKs have the same key ID, key material, and other
1020 metadata, you can use them to encrypt data in one AWS Region and
1021 decrypt it in a different AWS Region without making a cross-Region call
1022 or exposing the plaintext data. For more information about multi-Region
1023 keys, see Using multi-Region keys
1024 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html)
1025 in the I<AWS Key Management Service Developer Guide>.
1026  
1027 You can create symmetric and asymmetric multi-Region keys and
1028 multi-Region keys with imported key material. You cannot create
1029 multi-Region keys in a custom key store.
1030  
1031 To import your own key material, begin by creating a symmetric CMK with
1032 no key material. To do this, use the C<Origin> parameter of
1033 C<CreateKey> with a value of C<EXTERNAL>. Next, use
1034 GetParametersForImport operation to get a public key and import token,
1035 and use the public key to encrypt your key material. Then, use
1036 ImportKeyMaterial with your import token to import the key material.
1037 For step-by-step instructions, see Importing Key Material
1038 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)
1039 in the I< I<AWS Key Management Service Developer Guide> >. You cannot
1040 import the key material into an asymmetric CMK.
1041  
1042 To create a multi-Region primary key with imported key material, use
1043 the C<Origin> parameter of C<CreateKey> with a value of C<EXTERNAL> and
1044 the C<MultiRegion> parameter with a value of C<True>. To create
1045 replicas of the multi-Region primary key, use the ReplicateKey
1046 operation. For more information about multi-Region keys, see Using
1047 multi-Region keys
1048 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html)
1049 in the I<AWS Key Management Service Developer Guide>.
1050  
1051 =item Custom key store
1052  
1053 To create a symmetric CMK in a custom key store
1054 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html),
1055 use the C<CustomKeyStoreId> parameter to specify the custom key store.
1056 You must also use the C<Origin> parameter with a value of
1057 C<AWS_CLOUDHSM>. The AWS CloudHSM cluster that is associated with the
1058 custom key store must have at least two active HSMs in different
1059 Availability Zones in the AWS Region.
1060  
1061 You cannot create an asymmetric CMK or a multi-Region CMK in a custom
1062 key store. For information about custom key stores in AWS KMS see Using
1063 Custom Key Stores
1064 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
1065 in the I< I<AWS Key Management Service Developer Guide> >.
1066  
1067 =back
1068  
1069 B<Cross-account use>: No. You cannot use this operation to create a CMK
1070 in a different AWS account.
1071  
1072 B<Required permissions>: kms:CreateKey
1073 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1074 (IAM policy). To use the C<Tags> parameter, kms:TagResource
1075 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1076 (IAM policy). For examples and information about related permissions,
1077 see Allow a user to create CMKs
1078 (https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html#iam-policy-example-create-key)
1079 in the I<AWS Key Management Service Developer Guide>.
1080  
1081 B<Related operations:>
1082  
1083 =over
1084  
1085 =item *
1086  
1087 DescribeKey
1088  
1089 =item *
1090  
1091 ListKeys
1092  
1093 =item *
1094  
1095 ScheduleKeyDeletion
1096  
1097 =back
1098  
1099  
1100  
1101 =head2 Decrypt
1102  
1103 =over
1104  
1105 =item CiphertextBlob => Str
1106  
1107 =item [EncryptionAlgorithm => Str]
1108  
1109 =item [EncryptionContext => L<Paws::KMS::EncryptionContextType>]
1110  
1111 =item [GrantTokens => ArrayRef[Str|Undef]]
1112  
1113 =item [KeyId => Str]
1114  
1115  
1116 =back
1117  
1118 Each argument is described in detail in: L<Paws::KMS::Decrypt>
1119  
1120 Returns: a L<Paws::KMS::DecryptResponse> instance
1121  
1122 Decrypts ciphertext that was encrypted by a AWS KMS customer master key
1123 (CMK) using any of the following operations:
1124  
1125 =over
1126  
1127 =item *
1128  
1129 Encrypt
1130  
1131 =item *
1132  
1133 GenerateDataKey
1134  
1135 =item *
1136  
1137 GenerateDataKeyPair
1138  
1139 =item *
1140  
1141 GenerateDataKeyWithoutPlaintext
1142  
1143 =item *
1144  
1145 GenerateDataKeyPairWithoutPlaintext
1146  
1147 =back
1148  
1149 You can use this operation to decrypt ciphertext that was encrypted
1150 under a symmetric or asymmetric CMK. When the CMK is asymmetric, you
1151 must specify the CMK and the encryption algorithm that was used to
1152 encrypt the ciphertext. For information about symmetric and asymmetric
1153 CMKs, see Using Symmetric and Asymmetric CMKs
1154 (https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)
1155 in the I<AWS Key Management Service Developer Guide>.
1156  
1157 The Decrypt operation also decrypts ciphertext that was encrypted
1158 outside of AWS KMS by the public key in an AWS KMS asymmetric CMK.
1159 However, it cannot decrypt ciphertext produced by other libraries, such
1160 as the AWS Encryption SDK
1161 (https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/) or
1162 Amazon S3 client-side encryption
1163 (https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html).
1164 These libraries return a ciphertext format that is incompatible with
1165 AWS KMS.
1166  
1167 If the ciphertext was encrypted under a symmetric CMK, the C<KeyId>
1168 parameter is optional. AWS KMS can get this information from metadata
1169 that it adds to the symmetric ciphertext blob. This feature adds
1170 durability to your implementation by ensuring that authorized users can
1171 decrypt ciphertext decades after it was encrypted, even if they've lost
1172 track of the CMK ID. However, specifying the CMK is always recommended
1173 as a best practice. When you use the C<KeyId> parameter to specify a
1174 CMK, AWS KMS only uses the CMK you specify. If the ciphertext was
1175 encrypted under a different CMK, the C<Decrypt> operation fails. This
1176 practice ensures that you use the CMK that you intend.
1177  
1178 Whenever possible, use key policies to give users permission to call
1179 the C<Decrypt> operation on a particular CMK, instead of using IAM
1180 policies. Otherwise, you might create an IAM user policy that gives the
1181 user C<Decrypt> permission on all CMKs. This user could decrypt
1182 ciphertext that was encrypted by CMKs in other accounts if the key
1183 policy for the cross-account CMK permits it. If you must use an IAM
1184 policy for C<Decrypt> permissions, limit the user to particular CMKs or
1185 particular trusted accounts. For details, see Best practices for IAM
1186 policies
1187 (https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html#iam-policies-best-practices)
1188 in the I<AWS Key Management Service Developer Guide>.
1189  
1190 The CMK that you use for this operation must be in a compatible key
1191 state. For details, see Key state: Effect on your CMK
1192 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1193 in the I<AWS Key Management Service Developer Guide>.
1194  
1195 B<Cross-account use>: Yes. You can decrypt a ciphertext using a CMK in
1196 a different AWS account.
1197  
1198 B<Required permissions>: kms:Decrypt
1199 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1200 (key policy)
1201  
1202 B<Related operations:>
1203  
1204 =over
1205  
1206 =item *
1207  
1208 Encrypt
1209  
1210 =item *
1211  
1212 GenerateDataKey
1213  
1214 =item *
1215  
1216 GenerateDataKeyPair
1217  
1218 =item *
1219  
1220 ReEncrypt
1221  
1222 =back
1223  
1224  
1225  
1226 =head2 DeleteAlias
1227  
1228 =over
1229  
1230 =item AliasName => Str
1231  
1232  
1233 =back
1234  
1235 Each argument is described in detail in: L<Paws::KMS::DeleteAlias>
1236  
1237 Returns: nothing
1238  
1239 Deletes the specified alias.
1240  
1241 Adding, deleting, or updating an alias can allow or deny permission to
1242 the CMK. For details, see Using ABAC in AWS KMS
1243 (https://docs.aws.amazon.com/kms/latest/developerguide/abac.html) in
1244 the I<AWS Key Management Service Developer Guide>.
1245  
1246 Because an alias is not a property of a CMK, you can delete and change
1247 the aliases of a CMK without affecting the CMK. Also, aliases do not
1248 appear in the response from the DescribeKey operation. To get the
1249 aliases of all CMKs, use the ListAliases operation.
1250  
1251 Each CMK can have multiple aliases. To change the alias of a CMK, use
1252 DeleteAlias to delete the current alias and CreateAlias to create a new
1253 alias. To associate an existing alias with a different customer master
1254 key (CMK), call UpdateAlias.
1255  
1256 B<Cross-account use>: No. You cannot perform this operation on an alias
1257 in a different AWS account.
1258  
1259 B<Required permissions>
1260  
1261 =over
1262  
1263 =item *
1264  
1265 kms:DeleteAlias
1266 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1267 on the alias (IAM policy).
1268  
1269 =item *
1270  
1271 kms:DeleteAlias
1272 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1273 on the CMK (key policy).
1274  
1275 =back
1276  
1277 For details, see Controlling access to aliases
1278 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html#alias-access)
1279 in the I<AWS Key Management Service Developer Guide>.
1280  
1281 B<Related operations:>
1282  
1283 =over
1284  
1285 =item *
1286  
1287 CreateAlias
1288  
1289 =item *
1290  
1291 ListAliases
1292  
1293 =item *
1294  
1295 UpdateAlias
1296  
1297 =back
1298  
1299  
1300  
1301 =head2 DeleteCustomKeyStore
1302  
1303 =over
1304  
1305 =item CustomKeyStoreId => Str
1306  
1307  
1308 =back
1309  
1310 Each argument is described in detail in: L<Paws::KMS::DeleteCustomKeyStore>
1311  
1312 Returns: a L<Paws::KMS::DeleteCustomKeyStoreResponse> instance
1313  
1314 Deletes a custom key store
1315 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html).
1316 This operation does not delete the AWS CloudHSM cluster that is
1317 associated with the custom key store, or affect any users or keys in
1318 the cluster.
1319  
1320 The custom key store that you delete cannot contain any AWS KMS
1321 customer master keys (CMKs)
1322 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys).
1323 Before deleting the key store, verify that you will never need to use
1324 any of the CMKs in the key store for any cryptographic operations
1325 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations).
1326 Then, use ScheduleKeyDeletion to delete the AWS KMS customer master
1327 keys (CMKs) from the key store. When the scheduled waiting period
1328 expires, the C<ScheduleKeyDeletion> operation deletes the CMKs. Then it
1329 makes a best effort to delete the key material from the associated
1330 cluster. However, you might need to manually delete the orphaned key
1331 material
1332 (https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html#fix-keystore-orphaned-key)
1333 from the cluster and its backups.
1334  
1335 After all CMKs are deleted from AWS KMS, use DisconnectCustomKeyStore
1336 to disconnect the key store from AWS KMS. Then, you can delete the
1337 custom key store.
1338  
1339 Instead of deleting the custom key store, consider using
1340 DisconnectCustomKeyStore to disconnect it from AWS KMS. While the key
1341 store is disconnected, you cannot create or use the CMKs in the key
1342 store. But, you do not need to delete CMKs and you can reconnect a
1343 disconnected custom key store at any time.
1344  
1345 If the operation succeeds, it returns a JSON object with no properties.
1346  
1347 This operation is part of the Custom Key Store feature
1348 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
1349 feature in AWS KMS, which combines the convenience and extensive
1350 integration of AWS KMS with the isolation and control of a
1351 single-tenant key store.
1352  
1353 B<Cross-account use>: No. You cannot perform this operation on a custom
1354 key store in a different AWS account.
1355  
1356 B<Required permissions>: kms:DeleteCustomKeyStore
1357 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1358 (IAM policy)
1359  
1360 B<Related operations:>
1361  
1362 =over
1363  
1364 =item *
1365  
1366 ConnectCustomKeyStore
1367  
1368 =item *
1369  
1370 CreateCustomKeyStore
1371  
1372 =item *
1373  
1374 DescribeCustomKeyStores
1375  
1376 =item *
1377  
1378 DisconnectCustomKeyStore
1379  
1380 =item *
1381  
1382 UpdateCustomKeyStore
1383  
1384 =back
1385  
1386  
1387  
1388 =head2 DeleteImportedKeyMaterial
1389  
1390 =over
1391  
1392 =item KeyId => Str
1393  
1394  
1395 =back
1396  
1397 Each argument is described in detail in: L<Paws::KMS::DeleteImportedKeyMaterial>
1398  
1399 Returns: nothing
1400  
1401 Deletes key material that you previously imported. This operation makes
1402 the specified customer master key (CMK) unusable. For more information
1403 about importing key material into AWS KMS, see Importing Key Material
1404 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)
1405 in the I<AWS Key Management Service Developer Guide>.
1406  
1407 When the specified CMK is in the C<PendingDeletion> state, this
1408 operation does not change the CMK's state. Otherwise, it changes the
1409 CMK's state to C<PendingImport>.
1410  
1411 After you delete key material, you can use ImportKeyMaterial to
1412 reimport the same key material into the CMK.
1413  
1414 The CMK that you use for this operation must be in a compatible key
1415 state. For details, see Key state: Effect on your CMK
1416 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1417 in the I<AWS Key Management Service Developer Guide>.
1418  
1419 B<Cross-account use>: No. You cannot perform this operation on a CMK in
1420 a different AWS account.
1421  
1422 B<Required permissions>: kms:DeleteImportedKeyMaterial
1423 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1424 (key policy)
1425  
1426 B<Related operations:>
1427  
1428 =over
1429  
1430 =item *
1431  
1432 GetParametersForImport
1433  
1434 =item *
1435  
1436 ImportKeyMaterial
1437  
1438 =back
1439  
1440  
1441  
1442 =head2 DescribeCustomKeyStores
1443  
1444 =over
1445  
1446 =item [CustomKeyStoreId => Str]
1447  
1448 =item [CustomKeyStoreName => Str]
1449  
1450 =item [Limit => Int]
1451  
1452 =item [Marker => Str]
1453  
1454  
1455 =back
1456  
1457 Each argument is described in detail in: L<Paws::KMS::DescribeCustomKeyStores>
1458  
1459 Returns: a L<Paws::KMS::DescribeCustomKeyStoresResponse> instance
1460  
1461 Gets information about custom key stores
1462 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
1463 in the account and Region.
1464  
1465 This operation is part of the Custom Key Store feature
1466 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
1467 feature in AWS KMS, which combines the convenience and extensive
1468 integration of AWS KMS with the isolation and control of a
1469 single-tenant key store.
1470  
1471 By default, this operation returns information about all custom key
1472 stores in the account and Region. To get only information about a
1473 particular custom key store, use either the C<CustomKeyStoreName> or
1474 C<CustomKeyStoreId> parameter (but not both).
1475  
1476 To determine whether the custom key store is connected to its AWS
1477 CloudHSM cluster, use the C<ConnectionState> element in the response.
1478 If an attempt to connect the custom key store failed, the
1479 C<ConnectionState> value is C<FAILED> and the C<ConnectionErrorCode>
1480 element in the response indicates the cause of the failure. For help
1481 interpreting the C<ConnectionErrorCode>, see CustomKeyStoresListEntry.
1482  
1483 Custom key stores have a C<DISCONNECTED> connection state if the key
1484 store has never been connected or you use the DisconnectCustomKeyStore
1485 operation to disconnect it. If your custom key store state is
1486 C<CONNECTED> but you are having trouble using it, make sure that its
1487 associated AWS CloudHSM cluster is active and contains the minimum
1488 number of HSMs required for the operation, if any.
1489  
1490 For help repairing your custom key store, see the Troubleshooting
1491 Custom Key Stores
1492 (https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html)
1493 topic in the I<AWS Key Management Service Developer Guide>.
1494  
1495 B<Cross-account use>: No. You cannot perform this operation on a custom
1496 key store in a different AWS account.
1497  
1498 B<Required permissions>: kms:DescribeCustomKeyStores
1499 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1500 (IAM policy)
1501  
1502 B<Related operations:>
1503  
1504 =over
1505  
1506 =item *
1507  
1508 ConnectCustomKeyStore
1509  
1510 =item *
1511  
1512 CreateCustomKeyStore
1513  
1514 =item *
1515  
1516 DeleteCustomKeyStore
1517  
1518 =item *
1519  
1520 DisconnectCustomKeyStore
1521  
1522 =item *
1523  
1524 UpdateCustomKeyStore
1525  
1526 =back
1527  
1528  
1529  
1530 =head2 DescribeKey
1531  
1532 =over
1533  
1534 =item KeyId => Str
1535  
1536 =item [GrantTokens => ArrayRef[Str|Undef]]
1537  
1538  
1539 =back
1540  
1541 Each argument is described in detail in: L<Paws::KMS::DescribeKey>
1542  
1543 Returns: a L<Paws::KMS::DescribeKeyResponse> instance
1544  
1545 Provides detailed information about a customer master key (CMK). You
1546 can run C<DescribeKey> on a customer managed CMK
1547 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)
1548 or an AWS managed CMK
1549 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk).
1550  
1551 This detailed information includes the key ARN, creation date (and
1552 deletion date, if applicable), the key state, and the origin and
1553 expiration date (if any) of the key material. For CMKs in custom key
1554 stores, it includes information about the custom key store, such as the
1555 key store ID and the AWS CloudHSM cluster ID. It includes fields, like
1556 C<KeySpec>, that help you distinguish symmetric from asymmetric CMKs.
1557 It also provides information that is particularly important to
1558 asymmetric CMKs, such as the key usage (encryption or signing) and the
1559 encryption algorithms or signing algorithms that the CMK supports.
1560  
1561 C<DescribeKey> does not return the following information:
1562  
1563 =over
1564  
1565 =item *
1566  
1567 Aliases associated with the CMK. To get this information, use
1568 ListAliases.
1569  
1570 =item *
1571  
1572 Whether automatic key rotation is enabled on the CMK. To get this
1573 information, use GetKeyRotationStatus. Also, some key states prevent a
1574 CMK from being automatically rotated. For details, see How Automatic
1575 Key Rotation Works
1576 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-how-it-works)
1577 in I<AWS Key Management Service Developer Guide>.
1578  
1579 =item *
1580  
1581 Tags on the CMK. To get this information, use ListResourceTags.
1582  
1583 =item *
1584  
1585 Key policies and grants on the CMK. To get this information, use
1586 GetKeyPolicy and ListGrants.
1587  
1588 =back
1589  
1590 If you call the C<DescribeKey> operation on a I<predefined AWS alias>,
1591 that is, an AWS alias with no key ID, AWS KMS creates an AWS managed
1592 CMK
1593 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys).
1594 Then, it associates the alias with the new CMK, and returns the
1595 C<KeyId> and C<Arn> of the new CMK in the response.
1596  
1597 B<Cross-account use>: Yes. To perform this operation with a CMK in a
1598 different AWS account, specify the key ARN or alias ARN in the value of
1599 the C<KeyId> parameter.
1600  
1601 B<Required permissions>: kms:DescribeKey
1602 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1603 (key policy)
1604  
1605 B<Related operations:>
1606  
1607 =over
1608  
1609 =item *
1610  
1611 GetKeyPolicy
1612  
1613 =item *
1614  
1615 GetKeyRotationStatus
1616  
1617 =item *
1618  
1619 ListAliases
1620  
1621 =item *
1622  
1623 ListGrants
1624  
1625 =item *
1626  
1627 ListKeys
1628  
1629 =item *
1630  
1631 ListResourceTags
1632  
1633 =item *
1634  
1635 ListRetirableGrants
1636  
1637 =back
1638  
1639  
1640  
1641 =head2 DisableKey
1642  
1643 =over
1644  
1645 =item KeyId => Str
1646  
1647  
1648 =back
1649  
1650 Each argument is described in detail in: L<Paws::KMS::DisableKey>
1651  
1652 Returns: nothing
1653  
1654 Sets the state of a customer master key (CMK) to disabled. This change
1655 temporarily prevents use of the CMK for cryptographic operations
1656 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations).
1657  
1658 For more information about how key state affects the use of a CMK, see
1659 Key state: Effect on your CMK
1660 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1661 in the I< I<AWS Key Management Service Developer Guide> >.
1662  
1663 The CMK that you use for this operation must be in a compatible key
1664 state. For details, see Key state: Effect on your CMK
1665 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1666 in the I<AWS Key Management Service Developer Guide>.
1667  
1668 B<Cross-account use>: No. You cannot perform this operation on a CMK in
1669 a different AWS account.
1670  
1671 B<Required permissions>: kms:DisableKey
1672 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1673 (key policy)
1674  
1675 B<Related operations>: EnableKey
1676  
1677  
1678 =head2 DisableKeyRotation
1679  
1680 =over
1681  
1682 =item KeyId => Str
1683  
1684  
1685 =back
1686  
1687 Each argument is described in detail in: L<Paws::KMS::DisableKeyRotation>
1688  
1689 Returns: nothing
1690  
1691 Disables automatic rotation of the key material
1692 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
1693 for the specified symmetric customer master key (CMK).
1694  
1695 You cannot enable automatic rotation of asymmetric CMKs
1696 (https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-concepts.html#asymmetric-cmks),
1697 CMKs with imported key material
1698 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html),
1699 or CMKs in a custom key store
1700 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html).
1701 To enable or disable automatic rotation of a set of related
1702 multi-Region keys
1703 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html#mrk-replica-key),
1704 set the property on the primary key.
1705  
1706 The CMK that you use for this operation must be in a compatible key
1707 state. For details, see Key state: Effect on your CMK
1708 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1709 in the I<AWS Key Management Service Developer Guide>.
1710  
1711 B<Cross-account use>: No. You cannot perform this operation on a CMK in
1712 a different AWS account.
1713  
1714 B<Required permissions>: kms:DisableKeyRotation
1715 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1716 (key policy)
1717  
1718 B<Related operations:>
1719  
1720 =over
1721  
1722 =item *
1723  
1724 EnableKeyRotation
1725  
1726 =item *
1727  
1728 GetKeyRotationStatus
1729  
1730 =back
1731  
1732  
1733  
1734 =head2 DisconnectCustomKeyStore
1735  
1736 =over
1737  
1738 =item CustomKeyStoreId => Str
1739  
1740  
1741 =back
1742  
1743 Each argument is described in detail in: L<Paws::KMS::DisconnectCustomKeyStore>
1744  
1745 Returns: a L<Paws::KMS::DisconnectCustomKeyStoreResponse> instance
1746  
1747 Disconnects the custom key store
1748 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
1749 from its associated AWS CloudHSM cluster. While a custom key store is
1750 disconnected, you can manage the custom key store and its customer
1751 master keys (CMKs), but you cannot create or use CMKs in the custom key
1752 store. You can reconnect the custom key store at any time.
1753  
1754 While a custom key store is disconnected, all attempts to create
1755 customer master keys (CMKs) in the custom key store or to use existing
1756 CMKs in cryptographic operations
1757 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations)
1758 will fail. This action can prevent users from storing and accessing
1759 sensitive data.
1760  
1761 To find the connection state of a custom key store, use the
1762 DescribeCustomKeyStores operation. To reconnect a custom key store, use
1763 the ConnectCustomKeyStore operation.
1764  
1765 If the operation succeeds, it returns a JSON object with no properties.
1766  
1767 This operation is part of the Custom Key Store feature
1768 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
1769 feature in AWS KMS, which combines the convenience and extensive
1770 integration of AWS KMS with the isolation and control of a
1771 single-tenant key store.
1772  
1773 B<Cross-account use>: No. You cannot perform this operation on a custom
1774 key store in a different AWS account.
1775  
1776 B<Required permissions>: kms:DisconnectCustomKeyStore
1777 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1778 (IAM policy)
1779  
1780 B<Related operations:>
1781  
1782 =over
1783  
1784 =item *
1785  
1786 ConnectCustomKeyStore
1787  
1788 =item *
1789  
1790 CreateCustomKeyStore
1791  
1792 =item *
1793  
1794 DeleteCustomKeyStore
1795  
1796 =item *
1797  
1798 DescribeCustomKeyStores
1799  
1800 =item *
1801  
1802 UpdateCustomKeyStore
1803  
1804 =back
1805  
1806  
1807  
1808 =head2 EnableKey
1809  
1810 =over
1811  
1812 =item KeyId => Str
1813  
1814  
1815 =back
1816  
1817 Each argument is described in detail in: L<Paws::KMS::EnableKey>
1818  
1819 Returns: nothing
1820  
1821 Sets the key state of a customer master key (CMK) to enabled. This
1822 allows you to use the CMK for cryptographic operations
1823 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations).
1824  
1825 The CMK that you use for this operation must be in a compatible key
1826 state. For details, see Key state: Effect on your CMK
1827 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1828 in the I<AWS Key Management Service Developer Guide>.
1829  
1830 B<Cross-account use>: No. You cannot perform this operation on a CMK in
1831 a different AWS account.
1832  
1833 B<Required permissions>: kms:EnableKey
1834 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1835 (key policy)
1836  
1837 B<Related operations>: DisableKey
1838  
1839  
1840 =head2 EnableKeyRotation
1841  
1842 =over
1843  
1844 =item KeyId => Str
1845  
1846  
1847 =back
1848  
1849 Each argument is described in detail in: L<Paws::KMS::EnableKeyRotation>
1850  
1851 Returns: nothing
1852  
1853 Enables automatic rotation of the key material
1854 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
1855 for the specified symmetric customer master key (CMK).
1856  
1857 You cannot enable automatic rotation of asymmetric CMKs
1858 (https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-concepts.html#asymmetric-cmks),
1859 CMKs with imported key material
1860 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html),
1861 or CMKs in a custom key store
1862 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html).
1863 To enable or disable automatic rotation of a set of related
1864 multi-Region keys
1865 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html#mrk-replica-key),
1866 set the property on the primary key.
1867  
1868 The CMK that you use for this operation must be in a compatible key
1869 state. For details, see Key state: Effect on your CMK
1870 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
1871 in the I<AWS Key Management Service Developer Guide>.
1872  
1873 B<Cross-account use>: No. You cannot perform this operation on a CMK in
1874 a different AWS account.
1875  
1876 B<Required permissions>: kms:EnableKeyRotation
1877 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
1878 (key policy)
1879  
1880 B<Related operations:>
1881  
1882 =over
1883  
1884 =item *
1885  
1886 DisableKeyRotation
1887  
1888 =item *
1889  
1890 GetKeyRotationStatus
1891  
1892 =back
1893  
1894  
1895  
1896 =head2 Encrypt
1897  
1898 =over
1899  
1900 =item KeyId => Str
1901  
1902 =item Plaintext => Str
1903  
1904 =item [EncryptionAlgorithm => Str]
1905  
1906 =item [EncryptionContext => L<Paws::KMS::EncryptionContextType>]
1907  
1908 =item [GrantTokens => ArrayRef[Str|Undef]]
1909  
1910  
1911 =back
1912  
1913 Each argument is described in detail in: L<Paws::KMS::Encrypt>
1914  
1915 Returns: a L<Paws::KMS::EncryptResponse> instance
1916  
1917 Encrypts plaintext into ciphertext by using a customer master key
1918 (CMK). The C<Encrypt> operation has two primary use cases:
1919  
1920 =over
1921  
1922 =item *
1923  
1924 You can encrypt small amounts of arbitrary data, such as a personal
1925 identifier or database password, or other sensitive information.
1926  
1927 =item *
1928  
1929 You can use the C<Encrypt> operation to move encrypted data from one
1930 AWS Region to another. For example, in Region A, generate a data key
1931 and use the plaintext key to encrypt your data. Then, in Region A, use
1932 the C<Encrypt> operation to encrypt the plaintext data key under a CMK
1933 in Region B. Now, you can move the encrypted data and the encrypted
1934 data key to Region B. When necessary, you can decrypt the encrypted
1935 data key and the encrypted data entirely within in Region B.
1936  
1937 =back
1938  
1939 You don't need to use the C<Encrypt> operation to encrypt a data key.
1940 The GenerateDataKey and GenerateDataKeyPair operations return a
1941 plaintext data key and an encrypted copy of that data key.
1942  
1943 When you encrypt data, you must specify a symmetric or asymmetric CMK
1944 to use in the encryption operation. The CMK must have a C<KeyUsage>
1945 value of C<ENCRYPT_DECRYPT.> To find the C<KeyUsage> of a CMK, use the
1946 DescribeKey operation.
1947  
1948 If you use a symmetric CMK, you can use an encryption context to add
1949 additional security to your encryption operation. If you specify an
1950 C<EncryptionContext> when encrypting data, you must specify the same
1951 encryption context (a case-sensitive exact match) when decrypting the
1952 data. Otherwise, the request to decrypt fails with an
1953 C<InvalidCiphertextException>. For more information, see Encryption
1954 Context
1955 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)
1956 in the I<AWS Key Management Service Developer Guide>.
1957  
1958 If you specify an asymmetric CMK, you must also specify the encryption
1959 algorithm. The algorithm must be compatible with the CMK type.
1960  
1961 When you use an asymmetric CMK to encrypt or reencrypt data, be sure to
1962 record the CMK and encryption algorithm that you choose. You will be
1963 required to provide the same CMK and encryption algorithm when you
1964 decrypt the data. If the CMK and algorithm do not match the values used
1965 to encrypt the data, the decrypt operation fails.
1966  
1967 You are not required to supply the CMK ID and encryption algorithm when
1968 you decrypt with symmetric CMKs because AWS KMS stores this information
1969 in the ciphertext blob. AWS KMS cannot store metadata in ciphertext
1970 generated with asymmetric keys. The standard format for asymmetric key
1971 ciphertext does not include configurable fields.
1972  
1973 The maximum size of the data that you can encrypt varies with the type
1974 of CMK and the encryption algorithm that you choose.
1975  
1976 =over
1977  
1978 =item *
1979  
1980 Symmetric CMKs
1981  
1982 =over
1983  
1984 =item *
1985  
1986 C<SYMMETRIC_DEFAULT>: 4096 bytes
1987  
1988 =back
1989  
1990 =item *
1991  
1992 C<RSA_2048>
1993  
1994 =over
1995  
1996 =item *
1997  
1998 C<RSAES_OAEP_SHA_1>: 214 bytes
1999  
2000 =item *
2001  
2002 C<RSAES_OAEP_SHA_256>: 190 bytes
2003  
2004 =back
2005  
2006 =item *
2007  
2008 C<RSA_3072>
2009  
2010 =over
2011  
2012 =item *
2013  
2014 C<RSAES_OAEP_SHA_1>: 342 bytes
2015  
2016 =item *
2017  
2018 C<RSAES_OAEP_SHA_256>: 318 bytes
2019  
2020 =back
2021  
2022 =item *
2023  
2024 C<RSA_4096>
2025  
2026 =over
2027  
2028 =item *
2029  
2030 C<RSAES_OAEP_SHA_1>: 470 bytes
2031  
2032 =item *
2033  
2034 C<RSAES_OAEP_SHA_256>: 446 bytes
2035  
2036 =back
2037  
2038 =back
2039  
2040 The CMK that you use for this operation must be in a compatible key
2041 state. For details, see Key state: Effect on your CMK
2042 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2043 in the I<AWS Key Management Service Developer Guide>.
2044  
2045 B<Cross-account use>: Yes. To perform this operation with a CMK in a
2046 different AWS account, specify the key ARN or alias ARN in the value of
2047 the C<KeyId> parameter.
2048  
2049 B<Required permissions>: kms:Encrypt
2050 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2051 (key policy)
2052  
2053 B<Related operations:>
2054  
2055 =over
2056  
2057 =item *
2058  
2059 Decrypt
2060  
2061 =item *
2062  
2063 GenerateDataKey
2064  
2065 =item *
2066  
2067 GenerateDataKeyPair
2068  
2069 =back
2070  
2071  
2072  
2073 =head2 GenerateDataKey
2074  
2075 =over
2076  
2077 =item KeyId => Str
2078  
2079 =item [EncryptionContext => L<Paws::KMS::EncryptionContextType>]
2080  
2081 =item [GrantTokens => ArrayRef[Str|Undef]]
2082  
2083 =item [KeySpec => Str]
2084  
2085 =item [NumberOfBytes => Int]
2086  
2087  
2088 =back
2089  
2090 Each argument is described in detail in: L<Paws::KMS::GenerateDataKey>
2091  
2092 Returns: a L<Paws::KMS::GenerateDataKeyResponse> instance
2093  
2094 Generates a unique symmetric data key for client-side encryption. This
2095 operation returns a plaintext copy of the data key and a copy that is
2096 encrypted under a customer master key (CMK) that you specify. You can
2097 use the plaintext key to encrypt your data outside of AWS KMS and store
2098 the encrypted data key with the encrypted data.
2099  
2100 C<GenerateDataKey> returns a unique data key for each request. The
2101 bytes in the plaintext key are not related to the caller or the CMK.
2102  
2103 To generate a data key, specify the symmetric CMK that will be used to
2104 encrypt the data key. You cannot use an asymmetric CMK to generate data
2105 keys. To get the type of your CMK, use the DescribeKey operation. You
2106 must also specify the length of the data key. Use either the C<KeySpec>
2107 or C<NumberOfBytes> parameters (but not both). For 128-bit and 256-bit
2108 data keys, use the C<KeySpec> parameter.
2109  
2110 To get only an encrypted copy of the data key, use
2111 GenerateDataKeyWithoutPlaintext. To generate an asymmetric data key
2112 pair, use the GenerateDataKeyPair or
2113 GenerateDataKeyPairWithoutPlaintext operation. To get a
2114 cryptographically secure random byte string, use GenerateRandom.
2115  
2116 You can use the optional encryption context to add additional security
2117 to the encryption operation. If you specify an C<EncryptionContext>,
2118 you must specify the same encryption context (a case-sensitive exact
2119 match) when decrypting the encrypted data key. Otherwise, the request
2120 to decrypt fails with an C<InvalidCiphertextException>. For more
2121 information, see Encryption Context
2122 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)
2123 in the I<AWS Key Management Service Developer Guide>.
2124  
2125 The CMK that you use for this operation must be in a compatible key
2126 state. For details, see Key state: Effect on your CMK
2127 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2128 in the I<AWS Key Management Service Developer Guide>.
2129  
2130 B<How to use your data key>
2131  
2132 We recommend that you use the following pattern to encrypt data locally
2133 in your application. You can write your own code or use a client-side
2134 encryption library, such as the AWS Encryption SDK
2135 (https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/),
2136 the Amazon DynamoDB Encryption Client
2137 (https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/),
2138 or Amazon S3 client-side encryption
2139 (https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html)
2140 to do these tasks for you.
2141  
2142 To encrypt data outside of AWS KMS:
2143  
2144 =over
2145  
2146 =item 1.
2147  
2148 Use the C<GenerateDataKey> operation to get a data key.
2149  
2150 =item 2.
2151  
2152 Use the plaintext data key (in the C<Plaintext> field of the response)
2153 to encrypt your data outside of AWS KMS. Then erase the plaintext data
2154 key from memory.
2155  
2156 =item 3.
2157  
2158 Store the encrypted data key (in the C<CiphertextBlob> field of the
2159 response) with the encrypted data.
2160  
2161 =back
2162  
2163 To decrypt data outside of AWS KMS:
2164  
2165 =over
2166  
2167 =item 1.
2168  
2169 Use the Decrypt operation to decrypt the encrypted data key. The
2170 operation returns a plaintext copy of the data key.
2171  
2172 =item 2.
2173  
2174 Use the plaintext data key to decrypt data outside of AWS KMS, then
2175 erase the plaintext data key from memory.
2176  
2177 =back
2178  
2179 B<Cross-account use>: Yes. To perform this operation with a CMK in a
2180 different AWS account, specify the key ARN or alias ARN in the value of
2181 the C<KeyId> parameter.
2182  
2183 B<Required permissions>: kms:GenerateDataKey
2184 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2185 (key policy)
2186  
2187 B<Related operations:>
2188  
2189 =over
2190  
2191 =item *
2192  
2193 Decrypt
2194  
2195 =item *
2196  
2197 Encrypt
2198  
2199 =item *
2200  
2201 GenerateDataKeyPair
2202  
2203 =item *
2204  
2205 GenerateDataKeyPairWithoutPlaintext
2206  
2207 =item *
2208  
2209 GenerateDataKeyWithoutPlaintext
2210  
2211 =back
2212  
2213  
2214  
2215 =head2 GenerateDataKeyPair
2216  
2217 =over
2218  
2219 =item KeyId => Str
2220  
2221 =item KeyPairSpec => Str
2222  
2223 =item [EncryptionContext => L<Paws::KMS::EncryptionContextType>]
2224  
2225 =item [GrantTokens => ArrayRef[Str|Undef]]
2226  
2227  
2228 =back
2229  
2230 Each argument is described in detail in: L<Paws::KMS::GenerateDataKeyPair>
2231  
2232 Returns: a L<Paws::KMS::GenerateDataKeyPairResponse> instance
2233  
2234 Generates a unique asymmetric data key pair. The C<GenerateDataKeyPair>
2235 operation returns a plaintext public key, a plaintext private key, and
2236 a copy of the private key that is encrypted under the symmetric CMK you
2237 specify. You can use the data key pair to perform asymmetric
2238 cryptography outside of AWS KMS.
2239  
2240 C<GenerateDataKeyPair> returns a unique data key pair for each request.
2241 The bytes in the keys are not related to the caller or the CMK that is
2242 used to encrypt the private key.
2243  
2244 You can use the public key that C<GenerateDataKeyPair> returns to
2245 encrypt data or verify a signature outside of AWS KMS. Then, store the
2246 encrypted private key with the data. When you are ready to decrypt data
2247 or sign a message, you can use the Decrypt operation to decrypt the
2248 encrypted private key.
2249  
2250 To generate a data key pair, you must specify a symmetric customer
2251 master key (CMK) to encrypt the private key in a data key pair. You
2252 cannot use an asymmetric CMK or a CMK in a custom key store. To get the
2253 type and origin of your CMK, use the DescribeKey operation.
2254  
2255 If you are using the data key pair to encrypt data, or for any
2256 operation where you don't immediately need a private key, consider
2257 using the GenerateDataKeyPairWithoutPlaintext operation.
2258 C<GenerateDataKeyPairWithoutPlaintext> returns a plaintext public key
2259 and an encrypted private key, but omits the plaintext private key that
2260 you need only to decrypt ciphertext or sign a message. Later, when you
2261 need to decrypt the data or sign a message, use the Decrypt operation
2262 to decrypt the encrypted private key in the data key pair.
2263  
2264 You can use the optional encryption context to add additional security
2265 to the encryption operation. If you specify an C<EncryptionContext>,
2266 you must specify the same encryption context (a case-sensitive exact
2267 match) when decrypting the encrypted data key. Otherwise, the request
2268 to decrypt fails with an C<InvalidCiphertextException>. For more
2269 information, see Encryption Context
2270 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)
2271 in the I<AWS Key Management Service Developer Guide>.
2272  
2273 The CMK that you use for this operation must be in a compatible key
2274 state. For details, see Key state: Effect on your CMK
2275 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2276 in the I<AWS Key Management Service Developer Guide>.
2277  
2278 B<Cross-account use>: Yes. To perform this operation with a CMK in a
2279 different AWS account, specify the key ARN or alias ARN in the value of
2280 the C<KeyId> parameter.
2281  
2282 B<Required permissions>: kms:GenerateDataKeyPair
2283 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2284 (key policy)
2285  
2286 B<Related operations:>
2287  
2288 =over
2289  
2290 =item *
2291  
2292 Decrypt
2293  
2294 =item *
2295  
2296 Encrypt
2297  
2298 =item *
2299  
2300 GenerateDataKey
2301  
2302 =item *
2303  
2304 GenerateDataKeyPairWithoutPlaintext
2305  
2306 =item *
2307  
2308 GenerateDataKeyWithoutPlaintext
2309  
2310 =back
2311  
2312  
2313  
2314 =head2 GenerateDataKeyPairWithoutPlaintext
2315  
2316 =over
2317  
2318 =item KeyId => Str
2319  
2320 =item KeyPairSpec => Str
2321  
2322 =item [EncryptionContext => L<Paws::KMS::EncryptionContextType>]
2323  
2324 =item [GrantTokens => ArrayRef[Str|Undef]]
2325  
2326  
2327 =back
2328  
2329 Each argument is described in detail in: L<Paws::KMS::GenerateDataKeyPairWithoutPlaintext>
2330  
2331 Returns: a L<Paws::KMS::GenerateDataKeyPairWithoutPlaintextResponse> instance
2332  
2333 Generates a unique asymmetric data key pair. The
2334 C<GenerateDataKeyPairWithoutPlaintext> operation returns a plaintext
2335 public key and a copy of the private key that is encrypted under the
2336 symmetric CMK you specify. Unlike GenerateDataKeyPair, this operation
2337 does not return a plaintext private key.
2338  
2339 To generate a data key pair, you must specify a symmetric customer
2340 master key (CMK) to encrypt the private key in the data key pair. You
2341 cannot use an asymmetric CMK or a CMK in a custom key store. To get the
2342 type and origin of your CMK, use the C<KeySpec> field in the
2343 DescribeKey response.
2344  
2345 You can use the public key that C<GenerateDataKeyPairWithoutPlaintext>
2346 returns to encrypt data or verify a signature outside of AWS KMS. Then,
2347 store the encrypted private key with the data. When you are ready to
2348 decrypt data or sign a message, you can use the Decrypt operation to
2349 decrypt the encrypted private key.
2350  
2351 C<GenerateDataKeyPairWithoutPlaintext> returns a unique data key pair
2352 for each request. The bytes in the key are not related to the caller or
2353 CMK that is used to encrypt the private key.
2354  
2355 You can use the optional encryption context to add additional security
2356 to the encryption operation. If you specify an C<EncryptionContext>,
2357 you must specify the same encryption context (a case-sensitive exact
2358 match) when decrypting the encrypted data key. Otherwise, the request
2359 to decrypt fails with an C<InvalidCiphertextException>. For more
2360 information, see Encryption Context
2361 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)
2362 in the I<AWS Key Management Service Developer Guide>.
2363  
2364 The CMK that you use for this operation must be in a compatible key
2365 state. For details, see Key state: Effect on your CMK
2366 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2367 in the I<AWS Key Management Service Developer Guide>.
2368  
2369 B<Cross-account use>: Yes. To perform this operation with a CMK in a
2370 different AWS account, specify the key ARN or alias ARN in the value of
2371 the C<KeyId> parameter.
2372  
2373 B<Required permissions>: kms:GenerateDataKeyPairWithoutPlaintext
2374 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2375 (key policy)
2376  
2377 B<Related operations:>
2378  
2379 =over
2380  
2381 =item *
2382  
2383 Decrypt
2384  
2385 =item *
2386  
2387 Encrypt
2388  
2389 =item *
2390  
2391 GenerateDataKey
2392  
2393 =item *
2394  
2395 GenerateDataKeyPair
2396  
2397 =item *
2398  
2399 GenerateDataKeyWithoutPlaintext
2400  
2401 =back
2402  
2403  
2404  
2405 =head2 GenerateDataKeyWithoutPlaintext
2406  
2407 =over
2408  
2409 =item KeyId => Str
2410  
2411 =item [EncryptionContext => L<Paws::KMS::EncryptionContextType>]
2412  
2413 =item [GrantTokens => ArrayRef[Str|Undef]]
2414  
2415 =item [KeySpec => Str]
2416  
2417 =item [NumberOfBytes => Int]
2418  
2419  
2420 =back
2421  
2422 Each argument is described in detail in: L<Paws::KMS::GenerateDataKeyWithoutPlaintext>
2423  
2424 Returns: a L<Paws::KMS::GenerateDataKeyWithoutPlaintextResponse> instance
2425  
2426 Generates a unique symmetric data key. This operation returns a data
2427 key that is encrypted under a customer master key (CMK) that you
2428 specify. To request an asymmetric data key pair, use the
2429 GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext operations.
2430  
2431 C<GenerateDataKeyWithoutPlaintext> is identical to the GenerateDataKey
2432 operation except that returns only the encrypted copy of the data key.
2433 This operation is useful for systems that need to encrypt data at some
2434 point, but not immediately. When you need to encrypt the data, you call
2435 the Decrypt operation on the encrypted copy of the key.
2436  
2437 It's also useful in distributed systems with different levels of trust.
2438 For example, you might store encrypted data in containers. One
2439 component of your system creates new containers and stores an encrypted
2440 data key with each container. Then, a different component puts the data
2441 into the containers. That component first decrypts the data key, uses
2442 the plaintext data key to encrypt data, puts the encrypted data into
2443 the container, and then destroys the plaintext data key. In this
2444 system, the component that creates the containers never sees the
2445 plaintext data key.
2446  
2447 C<GenerateDataKeyWithoutPlaintext> returns a unique data key for each
2448 request. The bytes in the keys are not related to the caller or CMK
2449 that is used to encrypt the private key.
2450  
2451 To generate a data key, you must specify the symmetric customer master
2452 key (CMK) that is used to encrypt the data key. You cannot use an
2453 asymmetric CMK to generate a data key. To get the type of your CMK, use
2454 the DescribeKey operation.
2455  
2456 If the operation succeeds, you will find the encrypted copy of the data
2457 key in the C<CiphertextBlob> field.
2458  
2459 You can use the optional encryption context to add additional security
2460 to the encryption operation. If you specify an C<EncryptionContext>,
2461 you must specify the same encryption context (a case-sensitive exact
2462 match) when decrypting the encrypted data key. Otherwise, the request
2463 to decrypt fails with an C<InvalidCiphertextException>. For more
2464 information, see Encryption Context
2465 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)
2466 in the I<AWS Key Management Service Developer Guide>.
2467  
2468 The CMK that you use for this operation must be in a compatible key
2469 state. For details, see Key state: Effect on your CMK
2470 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2471 in the I<AWS Key Management Service Developer Guide>.
2472  
2473 B<Cross-account use>: Yes. To perform this operation with a CMK in a
2474 different AWS account, specify the key ARN or alias ARN in the value of
2475 the C<KeyId> parameter.
2476  
2477 B<Required permissions>: kms:GenerateDataKeyWithoutPlaintext
2478 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2479 (key policy)
2480  
2481 B<Related operations:>
2482  
2483 =over
2484  
2485 =item *
2486  
2487 Decrypt
2488  
2489 =item *
2490  
2491 Encrypt
2492  
2493 =item *
2494  
2495 GenerateDataKey
2496  
2497 =item *
2498  
2499 GenerateDataKeyPair
2500  
2501 =item *
2502  
2503 GenerateDataKeyPairWithoutPlaintext
2504  
2505 =back
2506  
2507  
2508  
2509 =head2 GenerateRandom
2510  
2511 =over
2512  
2513 =item [CustomKeyStoreId => Str]
2514  
2515 =item [NumberOfBytes => Int]
2516  
2517  
2518 =back
2519  
2520 Each argument is described in detail in: L<Paws::KMS::GenerateRandom>
2521  
2522 Returns: a L<Paws::KMS::GenerateRandomResponse> instance
2523  
2524 Returns a random byte string that is cryptographically secure.
2525  
2526 By default, the random byte string is generated in AWS KMS. To generate
2527 the byte string in the AWS CloudHSM cluster that is associated with a
2528 custom key store
2529 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html),
2530 specify the custom key store ID.
2531  
2532 For more information about entropy and random number generation, see
2533 AWS Key Management Service Cryptographic Details
2534 (https://docs.aws.amazon.com/kms/latest/cryptographic-details/).
2535  
2536 B<Required permissions>: kms:GenerateRandom
2537 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2538 (IAM policy)
2539  
2540  
2541 =head2 GetKeyPolicy
2542  
2543 =over
2544  
2545 =item KeyId => Str
2546  
2547 =item PolicyName => Str
2548  
2549  
2550 =back
2551  
2552 Each argument is described in detail in: L<Paws::KMS::GetKeyPolicy>
2553  
2554 Returns: a L<Paws::KMS::GetKeyPolicyResponse> instance
2555  
2556 Gets a key policy attached to the specified customer master key (CMK).
2557  
2558 B<Cross-account use>: No. You cannot perform this operation on a CMK in
2559 a different AWS account.
2560  
2561 B<Required permissions>: kms:GetKeyPolicy
2562 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2563 (key policy)
2564  
2565 B<Related operations>: PutKeyPolicy
2566  
2567  
2568 =head2 GetKeyRotationStatus
2569  
2570 =over
2571  
2572 =item KeyId => Str
2573  
2574  
2575 =back
2576  
2577 Each argument is described in detail in: L<Paws::KMS::GetKeyRotationStatus>
2578  
2579 Returns: a L<Paws::KMS::GetKeyRotationStatusResponse> instance
2580  
2581 Gets a Boolean value that indicates whether automatic rotation of the
2582 key material
2583 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
2584 is enabled for the specified customer master key (CMK).
2585  
2586 You cannot enable automatic rotation of asymmetric CMKs
2587 (https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-concepts.html#asymmetric-cmks),
2588 CMKs with imported key material
2589 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html),
2590 or CMKs in a custom key store
2591 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html).
2592 To enable or disable automatic rotation of a set of related
2593 multi-Region keys
2594 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html#mrk-replica-key),
2595 set the property on the primary key. The key rotation status for these
2596 CMKs is always C<false>.
2597  
2598 The CMK that you use for this operation must be in a compatible key
2599 state. For details, see Key state: Effect on your CMK
2600 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2601 in the I<AWS Key Management Service Developer Guide>.
2602  
2603 =over
2604  
2605 =item *
2606  
2607 Disabled: The key rotation status does not change when you disable a
2608 CMK. However, while the CMK is disabled, AWS KMS does not rotate the
2609 backing key.
2610  
2611 =item *
2612  
2613 Pending deletion: While a CMK is pending deletion, its key rotation
2614 status is C<false> and AWS KMS does not rotate the backing key. If you
2615 cancel the deletion, the original key rotation status is restored.
2616  
2617 =back
2618  
2619 B<Cross-account use>: Yes. To perform this operation on a CMK in a
2620 different AWS account, specify the key ARN in the value of the C<KeyId>
2621 parameter.
2622  
2623 B<Required permissions>: kms:GetKeyRotationStatus
2624 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2625 (key policy)
2626  
2627 B<Related operations:>
2628  
2629 =over
2630  
2631 =item *
2632  
2633 DisableKeyRotation
2634  
2635 =item *
2636  
2637 EnableKeyRotation
2638  
2639 =back
2640  
2641  
2642  
2643 =head2 GetParametersForImport
2644  
2645 =over
2646  
2647 =item KeyId => Str
2648  
2649 =item WrappingAlgorithm => Str
2650  
2651 =item WrappingKeySpec => Str
2652  
2653  
2654 =back
2655  
2656 Each argument is described in detail in: L<Paws::KMS::GetParametersForImport>
2657  
2658 Returns: a L<Paws::KMS::GetParametersForImportResponse> instance
2659  
2660 Returns the items you need to import key material into a symmetric,
2661 customer managed customer master key (CMK). For more information about
2662 importing key material into AWS KMS, see Importing Key Material
2663 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)
2664 in the I<AWS Key Management Service Developer Guide>.
2665  
2666 This operation returns a public key and an import token. Use the public
2667 key to encrypt the symmetric key material. Store the import token to
2668 send with a subsequent ImportKeyMaterial request.
2669  
2670 You must specify the key ID of the symmetric CMK into which you will
2671 import key material. This CMK's C<Origin> must be C<EXTERNAL>. You must
2672 also specify the wrapping algorithm and type of wrapping key (public
2673 key) that you will use to encrypt the key material. You cannot perform
2674 this operation on an asymmetric CMK or on any CMK in a different AWS
2675 account.
2676  
2677 To import key material, you must use the public key and import token
2678 from the same response. These items are valid for 24 hours. The
2679 expiration date and time appear in the C<GetParametersForImport>
2680 response. You cannot use an expired token in an ImportKeyMaterial
2681 request. If your key and token expire, send another
2682 C<GetParametersForImport> request.
2683  
2684 The CMK that you use for this operation must be in a compatible key
2685 state. For details, see Key state: Effect on your CMK
2686 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2687 in the I<AWS Key Management Service Developer Guide>.
2688  
2689 B<Cross-account use>: No. You cannot perform this operation on a CMK in
2690 a different AWS account.
2691  
2692 B<Required permissions>: kms:GetParametersForImport
2693 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2694 (key policy)
2695  
2696 B<Related operations:>
2697  
2698 =over
2699  
2700 =item *
2701  
2702 ImportKeyMaterial
2703  
2704 =item *
2705  
2706 DeleteImportedKeyMaterial
2707  
2708 =back
2709  
2710  
2711  
2712 =head2 GetPublicKey
2713  
2714 =over
2715  
2716 =item KeyId => Str
2717  
2718 =item [GrantTokens => ArrayRef[Str|Undef]]
2719  
2720  
2721 =back
2722  
2723 Each argument is described in detail in: L<Paws::KMS::GetPublicKey>
2724  
2725 Returns: a L<Paws::KMS::GetPublicKeyResponse> instance
2726  
2727 Returns the public key of an asymmetric CMK. Unlike the private key of
2728 a asymmetric CMK, which never leaves AWS KMS unencrypted, callers with
2729 C<kms:GetPublicKey> permission can download the public key of an
2730 asymmetric CMK. You can share the public key to allow others to encrypt
2731 messages and verify signatures outside of AWS KMS. For information
2732 about symmetric and asymmetric CMKs, see Using Symmetric and Asymmetric
2733 CMKs
2734 (https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)
2735 in the I<AWS Key Management Service Developer Guide>.
2736  
2737 You do not need to download the public key. Instead, you can use the
2738 public key within AWS KMS by calling the Encrypt, ReEncrypt, or Verify
2739 operations with the identifier of an asymmetric CMK. When you use the
2740 public key within AWS KMS, you benefit from the authentication,
2741 authorization, and logging that are part of every AWS KMS operation.
2742 You also reduce of risk of encrypting data that cannot be decrypted.
2743 These features are not effective outside of AWS KMS. For details, see
2744 Special Considerations for Downloading Public Keys
2745 (https://docs.aws.amazon.com/kms/latest/developerguide/download-public-key.html#download-public-key-considerations).
2746  
2747 To help you use the public key safely outside of AWS KMS,
2748 C<GetPublicKey> returns important information about the public key in
2749 the response, including:
2750  
2751 =over
2752  
2753 =item *
2754  
2755 CustomerMasterKeySpec
2756 (https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html#KMS-GetPublicKey-response-CustomerMasterKeySpec):
2757 The type of key material in the public key, such as C<RSA_4096> or
2758 C<ECC_NIST_P521>.
2759  
2760 =item *
2761  
2762 KeyUsage
2763 (https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html#KMS-GetPublicKey-response-KeyUsage):
2764 Whether the key is used for encryption or signing.
2765  
2766 =item *
2767  
2768 EncryptionAlgorithms
2769 (https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html#KMS-GetPublicKey-response-EncryptionAlgorithms)
2770 or SigningAlgorithms
2771 (https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html#KMS-GetPublicKey-response-SigningAlgorithms):
2772 A list of the encryption algorithms or the signing algorithms for the
2773 key.
2774  
2775 =back
2776  
2777 Although AWS KMS cannot enforce these restrictions on external
2778 operations, it is crucial that you use this information to prevent the
2779 public key from being used improperly. For example, you can prevent a
2780 public signing key from being used encrypt data, or prevent a public
2781 key from being used with an encryption algorithm that is not supported
2782 by AWS KMS. You can also avoid errors, such as using the wrong signing
2783 algorithm in a verification operation.
2784  
2785 The CMK that you use for this operation must be in a compatible key
2786 state. For details, see Key state: Effect on your CMK
2787 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2788 in the I<AWS Key Management Service Developer Guide>.
2789  
2790 B<Cross-account use>: Yes. To perform this operation with a CMK in a
2791 different AWS account, specify the key ARN or alias ARN in the value of
2792 the C<KeyId> parameter.
2793  
2794 B<Required permissions>: kms:GetPublicKey
2795 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2796 (key policy)
2797  
2798 B<Related operations>: CreateKey
2799  
2800  
2801 =head2 ImportKeyMaterial
2802  
2803 =over
2804  
2805 =item EncryptedKeyMaterial => Str
2806  
2807 =item ImportToken => Str
2808  
2809 =item KeyId => Str
2810  
2811 =item [ExpirationModel => Str]
2812  
2813 =item [ValidTo => Str]
2814  
2815  
2816 =back
2817  
2818 Each argument is described in detail in: L<Paws::KMS::ImportKeyMaterial>
2819  
2820 Returns: a L<Paws::KMS::ImportKeyMaterialResponse> instance
2821  
2822 Imports key material into an existing symmetric AWS KMS customer master
2823 key (CMK) that was created without key material. After you successfully
2824 import key material into a CMK, you can reimport the same key material
2825 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html#reimport-key-material)
2826 into that CMK, but you cannot import different key material.
2827  
2828 You cannot perform this operation on an asymmetric CMK or on any CMK in
2829 a different AWS account. For more information about creating CMKs with
2830 no key material and then importing key material, see Importing Key
2831 Material
2832 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html)
2833 in the I<AWS Key Management Service Developer Guide>.
2834  
2835 Before using this operation, call GetParametersForImport. Its response
2836 includes a public key and an import token. Use the public key to
2837 encrypt the key material. Then, submit the import token from the same
2838 C<GetParametersForImport> response.
2839  
2840 When calling this operation, you must specify the following values:
2841  
2842 =over
2843  
2844 =item *
2845  
2846 The key ID or key ARN of a CMK with no key material. Its C<Origin> must
2847 be C<EXTERNAL>.
2848  
2849 To create a CMK with no key material, call CreateKey and set the value
2850 of its C<Origin> parameter to C<EXTERNAL>. To get the C<Origin> of a
2851 CMK, call DescribeKey.)
2852  
2853 =item *
2854  
2855 The encrypted key material. To get the public key to encrypt the key
2856 material, call GetParametersForImport.
2857  
2858 =item *
2859  
2860 The import token that GetParametersForImport returned. You must use a
2861 public key and token from the same C<GetParametersForImport> response.
2862  
2863 =item *
2864  
2865 Whether the key material expires and if so, when. If you set an
2866 expiration date, AWS KMS deletes the key material from the CMK on the
2867 specified date, and the CMK becomes unusable. To use the CMK again, you
2868 must reimport the same key material. The only way to change an
2869 expiration date is by reimporting the same key material and specifying
2870 a new expiration date.
2871  
2872 =back
2873  
2874 When this operation is successful, the key state of the CMK changes
2875 from C<PendingImport> to C<Enabled>, and you can use the CMK.
2876  
2877 If this operation fails, use the exception to help determine the
2878 problem. If the error is related to the key material, the import token,
2879 or wrapping key, use GetParametersForImport to get a new public key and
2880 import token for the CMK and repeat the import procedure. For help, see
2881 How To Import Key Material
2882 (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html#importing-keys-overview)
2883 in the I<AWS Key Management Service Developer Guide>.
2884  
2885 The CMK that you use for this operation must be in a compatible key
2886 state. For details, see Key state: Effect on your CMK
2887 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
2888 in the I<AWS Key Management Service Developer Guide>.
2889  
2890 B<Cross-account use>: No. You cannot perform this operation on a CMK in
2891 a different AWS account.
2892  
2893 B<Required permissions>: kms:ImportKeyMaterial
2894 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2895 (key policy)
2896  
2897 B<Related operations:>
2898  
2899 =over
2900  
2901 =item *
2902  
2903 DeleteImportedKeyMaterial
2904  
2905 =item *
2906  
2907 GetParametersForImport
2908  
2909 =back
2910  
2911  
2912  
2913 =head2 ListAliases
2914  
2915 =over
2916  
2917 =item [KeyId => Str]
2918  
2919 =item [Limit => Int]
2920  
2921 =item [Marker => Str]
2922  
2923  
2924 =back
2925  
2926 Each argument is described in detail in: L<Paws::KMS::ListAliases>
2927  
2928 Returns: a L<Paws::KMS::ListAliasesResponse> instance
2929  
2930 Gets a list of aliases in the caller's AWS account and region. For more
2931 information about aliases, see CreateAlias.
2932  
2933 By default, the C<ListAliases> operation returns all aliases in the
2934 account and region. To get only the aliases associated with a
2935 particular customer master key (CMK), use the C<KeyId> parameter.
2936  
2937 The C<ListAliases> response can include aliases that you created and
2938 associated with your customer managed CMKs, and aliases that AWS
2939 created and associated with AWS managed CMKs in your account. You can
2940 recognize AWS aliases because their names have the format
2941 C<aws/E<lt>service-nameE<gt>>, such as C<aws/dynamodb>.
2942  
2943 The response might also include aliases that have no C<TargetKeyId>
2944 field. These are predefined aliases that AWS has created but has not
2945 yet associated with a CMK. Aliases that AWS creates in your account,
2946 including predefined aliases, do not count against your AWS KMS aliases
2947 quota
2948 (https://docs.aws.amazon.com/kms/latest/developerguide/limits.html#aliases-limit).
2949  
2950 B<Cross-account use>: No. C<ListAliases> does not return aliases in
2951 other AWS accounts.
2952  
2953 B<Required permissions>: kms:ListAliases
2954 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
2955 (IAM policy)
2956  
2957 For details, see Controlling access to aliases
2958 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html#alias-access)
2959 in the I<AWS Key Management Service Developer Guide>.
2960  
2961 B<Related operations:>
2962  
2963 =over
2964  
2965 =item *
2966  
2967 CreateAlias
2968  
2969 =item *
2970  
2971 DeleteAlias
2972  
2973 =item *
2974  
2975 UpdateAlias
2976  
2977 =back
2978  
2979  
2980  
2981 =head2 ListGrants
2982  
2983 =over
2984  
2985 =item KeyId => Str
2986  
2987 =item [GranteePrincipal => Str]
2988  
2989 =item [GrantId => Str]
2990  
2991 =item [Limit => Int]
2992  
2993 =item [Marker => Str]
2994  
2995  
2996 =back
2997  
2998 Each argument is described in detail in: L<Paws::KMS::ListGrants>
2999  
3000 Returns: a L<Paws::KMS::ListGrantsResponse> instance
3001  
3002 Gets a list of all grants for the specified customer master key (CMK).
3003  
3004 You must specify the CMK in all requests. You can filter the grant list
3005 by grant ID or grantee principal.
3006  
3007 The C<GranteePrincipal> field in the C<ListGrants> response usually
3008 contains the user or role designated as the grantee principal in the
3009 grant. However, when the grantee principal in the grant is an AWS
3010 service, the C<GranteePrincipal> field contains the service principal
3011 (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-services),
3012 which might represent several different grantee principals.
3013  
3014 B<Cross-account use>: Yes. To perform this operation on a CMK in a
3015 different AWS account, specify the key ARN in the value of the C<KeyId>
3016 parameter.
3017  
3018 B<Required permissions>: kms:ListGrants
3019 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3020 (key policy)
3021  
3022 B<Related operations:>
3023  
3024 =over
3025  
3026 =item *
3027  
3028 CreateGrant
3029  
3030 =item *
3031  
3032 ListRetirableGrants
3033  
3034 =item *
3035  
3036 RetireGrant
3037  
3038 =item *
3039  
3040 RevokeGrant
3041  
3042 =back
3043  
3044  
3045  
3046 =head2 ListKeyPolicies
3047  
3048 =over
3049  
3050 =item KeyId => Str
3051  
3052 =item [Limit => Int]
3053  
3054 =item [Marker => Str]
3055  
3056  
3057 =back
3058  
3059 Each argument is described in detail in: L<Paws::KMS::ListKeyPolicies>
3060  
3061 Returns: a L<Paws::KMS::ListKeyPoliciesResponse> instance
3062  
3063 Gets the names of the key policies that are attached to a customer
3064 master key (CMK). This operation is designed to get policy names that
3065 you can use in a GetKeyPolicy operation. However, the only valid policy
3066 name is C<default>.
3067  
3068 B<Cross-account use>: No. You cannot perform this operation on a CMK in
3069 a different AWS account.
3070  
3071 B<Required permissions>: kms:ListKeyPolicies
3072 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3073 (key policy)
3074  
3075 B<Related operations:>
3076  
3077 =over
3078  
3079 =item *
3080  
3081 GetKeyPolicy
3082  
3083 =item *
3084  
3085 PutKeyPolicy
3086  
3087 =back
3088  
3089  
3090  
3091 =head2 ListKeys
3092  
3093 =over
3094  
3095 =item [Limit => Int]
3096  
3097 =item [Marker => Str]
3098  
3099  
3100 =back
3101  
3102 Each argument is described in detail in: L<Paws::KMS::ListKeys>
3103  
3104 Returns: a L<Paws::KMS::ListKeysResponse> instance
3105  
3106 Gets a list of all customer master keys (CMKs) in the caller's AWS
3107 account and Region.
3108  
3109 B<Cross-account use>: No. You cannot perform this operation on a CMK in
3110 a different AWS account.
3111  
3112 B<Required permissions>: kms:ListKeys
3113 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3114 (IAM policy)
3115  
3116 B<Related operations:>
3117  
3118 =over
3119  
3120 =item *
3121  
3122 CreateKey
3123  
3124 =item *
3125  
3126 DescribeKey
3127  
3128 =item *
3129  
3130 ListAliases
3131  
3132 =item *
3133  
3134 ListResourceTags
3135  
3136 =back
3137  
3138  
3139  
3140 =head2 ListResourceTags
3141  
3142 =over
3143  
3144 =item KeyId => Str
3145  
3146 =item [Limit => Int]
3147  
3148 =item [Marker => Str]
3149  
3150  
3151 =back
3152  
3153 Each argument is described in detail in: L<Paws::KMS::ListResourceTags>
3154  
3155 Returns: a L<Paws::KMS::ListResourceTagsResponse> instance
3156  
3157 Returns all tags on the specified customer master key (CMK).
3158  
3159 For general information about tags, including the format and syntax,
3160 see Tagging AWS resources
3161 (https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the
3162 I<Amazon Web Services General Reference>. For information about using
3163 tags in AWS KMS, see Tagging keys
3164 (https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html).
3165  
3166 B<Cross-account use>: No. You cannot perform this operation on a CMK in
3167 a different AWS account.
3168  
3169 B<Required permissions>: kms:ListResourceTags
3170 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3171 (key policy)
3172  
3173 B<Related operations:>
3174  
3175 =over
3176  
3177 =item *
3178  
3179 CreateKey
3180  
3181 =item *
3182  
3183 ReplicateKey
3184  
3185 =item *
3186  
3187 TagResource
3188  
3189 =item *
3190  
3191 UntagResource
3192  
3193 =back
3194  
3195  
3196  
3197 =head2 ListRetirableGrants
3198  
3199 =over
3200  
3201 =item RetiringPrincipal => Str
3202  
3203 =item [Limit => Int]
3204  
3205 =item [Marker => Str]
3206  
3207  
3208 =back
3209  
3210 Each argument is described in detail in: L<Paws::KMS::ListRetirableGrants>
3211  
3212 Returns: a L<Paws::KMS::ListGrantsResponse> instance
3213  
3214 Returns information about all grants in the AWS account and Region that
3215 have the specified retiring principal. For more information about
3216 grants, see Grants
3217 (https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in
3218 the I< I<AWS Key Management Service Developer Guide> >.
3219  
3220 You can specify any principal in your AWS account. The grants that are
3221 returned include grants for CMKs in your AWS account and other AWS
3222 accounts.
3223  
3224 You might use this operation to determine which grants you may retire.
3225 To retire a grant, use the RetireGrant operation.
3226  
3227 B<Cross-account use>: You must specify a principal in your AWS account.
3228 However, this operation can return grants in any AWS account. You do
3229 not need C<kms:ListRetirableGrants> permission (or any other additional
3230 permission) in any AWS account other than your own.
3231  
3232 B<Required permissions>: kms:ListRetirableGrants
3233 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3234 (IAM policy) in your AWS account.
3235  
3236 B<Related operations:>
3237  
3238 =over
3239  
3240 =item *
3241  
3242 CreateGrant
3243  
3244 =item *
3245  
3246 ListGrants
3247  
3248 =item *
3249  
3250 RetireGrant
3251  
3252 =item *
3253  
3254 RevokeGrant
3255  
3256 =back
3257  
3258  
3259  
3260 =head2 PutKeyPolicy
3261  
3262 =over
3263  
3264 =item KeyId => Str
3265  
3266 =item Policy => Str
3267  
3268 =item PolicyName => Str
3269  
3270 =item [BypassPolicyLockoutSafetyCheck => Bool]
3271  
3272  
3273 =back
3274  
3275 Each argument is described in detail in: L<Paws::KMS::PutKeyPolicy>
3276  
3277 Returns: nothing
3278  
3279 Attaches a key policy to the specified customer master key (CMK).
3280  
3281 For more information about key policies, see Key Policies
3282 (https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)
3283 in the I<AWS Key Management Service Developer Guide>. For help writing
3284 and formatting a JSON policy document, see the IAM JSON Policy
3285 Reference
3286 (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html)
3287 in the I< I<IAM User Guide> >. For examples of adding a key policy in
3288 multiple programming languages, see Setting a key policy
3289 (https://docs.aws.amazon.com/kms/latest/developerguide/programming-key-policies.html#put-policy)
3290 in the I<AWS Key Management Service Developer Guide>.
3291  
3292 B<Cross-account use>: No. You cannot perform this operation on a CMK in
3293 a different AWS account.
3294  
3295 B<Required permissions>: kms:PutKeyPolicy
3296 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3297 (key policy)
3298  
3299 B<Related operations>: GetKeyPolicy
3300  
3301  
3302 =head2 ReEncrypt
3303  
3304 =over
3305  
3306 =item CiphertextBlob => Str
3307  
3308 =item DestinationKeyId => Str
3309  
3310 =item [DestinationEncryptionAlgorithm => Str]
3311  
3312 =item [DestinationEncryptionContext => L<Paws::KMS::EncryptionContextType>]
3313  
3314 =item [GrantTokens => ArrayRef[Str|Undef]]
3315  
3316 =item [SourceEncryptionAlgorithm => Str]
3317  
3318 =item [SourceEncryptionContext => L<Paws::KMS::EncryptionContextType>]
3319  
3320 =item [SourceKeyId => Str]
3321  
3322  
3323 =back
3324  
3325 Each argument is described in detail in: L<Paws::KMS::ReEncrypt>
3326  
3327 Returns: a L<Paws::KMS::ReEncryptResponse> instance
3328  
3329 Decrypts ciphertext and then reencrypts it entirely within AWS KMS. You
3330 can use this operation to change the customer master key (CMK) under
3331 which data is encrypted, such as when you manually rotate
3332 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually)
3333 a CMK or change the CMK that protects a ciphertext. You can also use it
3334 to reencrypt ciphertext under the same CMK, such as to change the
3335 encryption context
3336 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context)
3337 of a ciphertext.
3338  
3339 The C<ReEncrypt> operation can decrypt ciphertext that was encrypted by
3340 using an AWS KMS CMK in an AWS KMS operation, such as Encrypt or
3341 GenerateDataKey. It can also decrypt ciphertext that was encrypted by
3342 using the public key of an asymmetric CMK
3343 (https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-concepts.html#asymmetric-cmks)
3344 outside of AWS KMS. However, it cannot decrypt ciphertext produced by
3345 other libraries, such as the AWS Encryption SDK
3346 (https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/) or
3347 Amazon S3 client-side encryption
3348 (https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html).
3349 These libraries return a ciphertext format that is incompatible with
3350 AWS KMS.
3351  
3352 When you use the C<ReEncrypt> operation, you need to provide
3353 information for the decrypt operation and the subsequent encrypt
3354 operation.
3355  
3356 =over
3357  
3358 =item *
3359  
3360 If your ciphertext was encrypted under an asymmetric CMK, you must use
3361 the C<SourceKeyId> parameter to identify the CMK that encrypted the
3362 ciphertext. You must also supply the encryption algorithm that was
3363 used. This information is required to decrypt the data.
3364  
3365 =item *
3366  
3367 If your ciphertext was encrypted under a symmetric CMK, the
3368 C<SourceKeyId> parameter is optional. AWS KMS can get this information
3369 from metadata that it adds to the symmetric ciphertext blob. This
3370 feature adds durability to your implementation by ensuring that
3371 authorized users can decrypt ciphertext decades after it was encrypted,
3372 even if they've lost track of the CMK ID. However, specifying the
3373 source CMK is always recommended as a best practice. When you use the
3374 C<SourceKeyId> parameter to specify a CMK, AWS KMS uses only the CMK
3375 you specify. If the ciphertext was encrypted under a different CMK, the
3376 C<ReEncrypt> operation fails. This practice ensures that you use the
3377 CMK that you intend.
3378  
3379 =item *
3380  
3381 To reencrypt the data, you must use the C<DestinationKeyId> parameter
3382 specify the CMK that re-encrypts the data after it is decrypted. You
3383 can select a symmetric or asymmetric CMK. If the destination CMK is an
3384 asymmetric CMK, you must also provide the encryption algorithm. The
3385 algorithm that you choose must be compatible with the CMK.
3386  
3387 When you use an asymmetric CMK to encrypt or reencrypt data, be sure to
3388 record the CMK and encryption algorithm that you choose. You will be
3389 required to provide the same CMK and encryption algorithm when you
3390 decrypt the data. If the CMK and algorithm do not match the values used
3391 to encrypt the data, the decrypt operation fails.
3392  
3393 You are not required to supply the CMK ID and encryption algorithm when
3394 you decrypt with symmetric CMKs because AWS KMS stores this information
3395 in the ciphertext blob. AWS KMS cannot store metadata in ciphertext
3396 generated with asymmetric keys. The standard format for asymmetric key
3397 ciphertext does not include configurable fields.
3398  
3399 =back
3400  
3401 The CMK that you use for this operation must be in a compatible key
3402 state. For details, see Key state: Effect on your CMK
3403 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
3404 in the I<AWS Key Management Service Developer Guide>.
3405  
3406 B<Cross-account use>: Yes. The source CMK and destination CMK can be in
3407 different AWS accounts. Either or both CMKs can be in a different
3408 account than the caller.
3409  
3410 B<Required permissions>:
3411  
3412 =over
3413  
3414 =item *
3415  
3416 kms:ReEncryptFrom
3417 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3418 permission on the source CMK (key policy)
3419  
3420 =item *
3421  
3422 kms:ReEncryptTo
3423 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3424 permission on the destination CMK (key policy)
3425  
3426 =back
3427  
3428 To permit reencryption from or to a CMK, include the
3429 C<"kms:ReEncrypt*"> permission in your key policy
3430 (https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html).
3431 This permission is automatically included in the key policy when you
3432 use the console to create a CMK. But you must include it manually when
3433 you create a CMK programmatically or when you use the PutKeyPolicy
3434 operation to set a key policy.
3435  
3436 B<Related operations:>
3437  
3438 =over
3439  
3440 =item *
3441  
3442 Decrypt
3443  
3444 =item *
3445  
3446 Encrypt
3447  
3448 =item *
3449  
3450 GenerateDataKey
3451  
3452 =item *
3453  
3454 GenerateDataKeyPair
3455  
3456 =back
3457  
3458  
3459  
3460 =head2 ReplicateKey
3461  
3462 =over
3463  
3464 =item KeyId => Str
3465  
3466 =item ReplicaRegion => Str
3467  
3468 =item [BypassPolicyLockoutSafetyCheck => Bool]
3469  
3470 =item [Description => Str]
3471  
3472 =item [Policy => Str]
3473  
3474 =item [Tags => ArrayRef[L<Paws::KMS::Tag>]]
3475  
3476  
3477 =back
3478  
3479 Each argument is described in detail in: L<Paws::KMS::ReplicateKey>
3480  
3481 Returns: a L<Paws::KMS::ReplicateKeyResponse> instance
3482  
3483 Replicates a multi-Region key into the specified Region. This operation
3484 creates a multi-Region replica key based on a multi-Region primary key
3485 in a different Region of the same AWS partition. You can create
3486 multiple replicas of a primary key, but each must be in a different
3487 Region. To create a multi-Region primary key, use the CreateKey
3488 operation.
3489  
3490 This operation supports I<multi-Region keys>, an AWS KMS feature that
3491 lets you create multiple interoperable CMKs in different AWS Regions.
3492 Because these CMKs have the same key ID, key material, and other
3493 metadata, you can use them to encrypt data in one AWS Region and
3494 decrypt it in a different AWS Region without making a cross-Region call
3495 or exposing the plaintext data. For more information about multi-Region
3496 keys, see Using multi-Region keys
3497 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html)
3498 in the I<AWS Key Management Service Developer Guide>.
3499  
3500 A I<replica key> is a fully-functional CMK that can be used
3501 independently of its primary and peer replica keys. A primary key and
3502 its replica keys share properties that make them interoperable. They
3503 have the same key ID
3504 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id)
3505 and key material. They also have the same key spec
3506 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-spec),
3507 key usage
3508 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-usage),
3509 key material origin
3510 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-origin),
3511 and automatic key rotation status
3512 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html).
3513 AWS KMS automatically synchronizes these shared properties among
3514 related multi-Region keys. All other properties of a replica key can
3515 differ, including its key policy
3516 (https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html),
3517 tags
3518 (https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html),
3519 aliases
3520 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html),
3521 and key state
3522 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html).
3523 AWS KMS pricing and quotas for CMKs apply to each primary key and
3524 replica key.
3525  
3526 When this operation completes, the new replica key has a transient key
3527 state of C<Creating>. This key state changes to C<Enabled> (or
3528 C<PendingImport>) after a few seconds when the process of creating the
3529 new replica key is complete. While the key state is C<Creating>, you
3530 can manage key, but you cannot yet use it in cryptographic operations.
3531 If you are creating and using the replica key programmatically, retry
3532 on C<KMSInvalidStateException> or call C<DescribeKey> to check its
3533 C<KeyState> value before using it. For details about the C<Creating>
3534 key state, see Key state: Effect on your CMK in the I<AWS Key
3535 Management Service Developer Guide>.
3536  
3537 The AWS CloudTrail log of a C<ReplicateKey> operation records a
3538 C<ReplicateKey> operation in the primary key's Region and a CreateKey
3539 operation in the replica key's Region.
3540  
3541 If you replicate a multi-Region primary key with imported key material,
3542 the replica key is created with no key material. You must import the
3543 same key material that you imported into the primary key. For details,
3544 see Importing key material into multi-Region keys in the I<AWS Key
3545 Management Service Developer Guide>.
3546  
3547 To convert a replica key to a primary key, use the UpdatePrimaryRegion
3548 operation.
3549  
3550 C<ReplicateKey> uses different default values for the C<KeyPolicy> and
3551 C<Tags> parameters than those used in the AWS KMS console. For details,
3552 see the parameter descriptions.
3553  
3554 B<Cross-account use>: No. You cannot use this operation to create a CMK
3555 in a different AWS account.
3556  
3557 B<Required permissions>:
3558  
3559 =over
3560  
3561 =item *
3562  
3563 C<kms:ReplicateKey> on the primary CMK (in the primary CMK's Region).
3564 Include this permission in the primary CMK's key policy.
3565  
3566 =item *
3567  
3568 C<kms:CreateKey> in an IAM policy in the replica Region.
3569  
3570 =item *
3571  
3572 To use the C<Tags> parameter, C<kms:TagResource> in an IAM policy in
3573 the replica Region.
3574  
3575 =back
3576  
3577 B<Related operations>
3578  
3579 =over
3580  
3581 =item *
3582  
3583 CreateKey
3584  
3585 =item *
3586  
3587 UpdatePrimaryRegion
3588  
3589 =back
3590  
3591  
3592  
3593 =head2 RetireGrant
3594  
3595 =over
3596  
3597 =item [GrantId => Str]
3598  
3599 =item [GrantToken => Str]
3600  
3601 =item [KeyId => Str]
3602  
3603  
3604 =back
3605  
3606 Each argument is described in detail in: L<Paws::KMS::RetireGrant>
3607  
3608 Returns: nothing
3609  
3610 Deletes a grant. Typically, you retire a grant when you no longer need
3611 its permissions. To identify the grant to retire, use a grant token
3612 (https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#grant_token),
3613 or both the grant ID and a key identifier (key ID or key ARN) of the
3614 customer master key (CMK). The CreateGrant operation returns both
3615 values.
3616  
3617 This operation can be called by the I<retiring principal> for a grant,
3618 by the I<grantee principal> if the grant allows the C<RetireGrant>
3619 operation, and by the AWS account (root user) in which the grant is
3620 created. It can also be called by principals to whom permission for
3621 retiring a grant is delegated. For details, see Retiring and revoking
3622 grants
3623 (https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete)
3624 in the I<AWS Key Management Service Developer Guide>.
3625  
3626 For detailed information about grants, including grant terminology, see
3627 Using grants
3628 (https://docs.aws.amazon.com/kms/latest/developerguide/grants.html) in
3629 the I< I<AWS Key Management Service Developer Guide> >. For examples of
3630 working with grants in several programming languages, see Programming
3631 grants
3632 (https://docs.aws.amazon.com/kms/latest/developerguide/programming-grants.html).
3633  
3634 B<Cross-account use>: Yes. You can retire a grant on a CMK in a
3635 different AWS account.
3636  
3637 B<Required permissions:>:Permission to retire a grant is determined
3638 primarily by the grant. For details, see Retiring and revoking grants
3639 (https://docs.aws.amazon.com/kms/latest/developerguide/grant-manage.html#grant-delete)
3640 in the I<AWS Key Management Service Developer Guide>.
3641  
3642 B<Related operations:>
3643  
3644 =over
3645  
3646 =item *
3647  
3648 CreateGrant
3649  
3650 =item *
3651  
3652 ListGrants
3653  
3654 =item *
3655  
3656 ListRetirableGrants
3657  
3658 =item *
3659  
3660 RevokeGrant
3661  
3662 =back
3663  
3664  
3665  
3666 =head2 RevokeGrant
3667  
3668 =over
3669  
3670 =item GrantId => Str
3671  
3672 =item KeyId => Str
3673  
3674  
3675 =back
3676  
3677 Each argument is described in detail in: L<Paws::KMS::RevokeGrant>
3678  
3679 Returns: nothing
3680  
3681 Deletes the specified grant. You revoke a grant to terminate the
3682 permissions that the grant allows. For more information, see Retiring
3683 and revoking grants
3684 (https://docs.aws.amazon.com/kms/latest/developerguide/managing-grants.html#grant-delete)
3685 in the I< I<AWS Key Management Service Developer Guide> >.
3686  
3687 When you create, retire, or revoke a grant, there might be a brief
3688 delay, usually less than five minutes, until the grant is available
3689 throughout AWS KMS. This state is known as I<eventual consistency>. For
3690 details, see Eventual consistency
3691 (https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-eventual-consistency)
3692 in the I< I<AWS Key Management Service Developer Guide> >.
3693  
3694 B<Cross-account use>: Yes. To perform this operation on a CMK in a
3695 different AWS account, specify the key ARN in the value of the C<KeyId>
3696 parameter.
3697  
3698 B<Required permissions>: kms:RevokeGrant
3699 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3700 (key policy).
3701  
3702 B<Related operations:>
3703  
3704 =over
3705  
3706 =item *
3707  
3708 CreateGrant
3709  
3710 =item *
3711  
3712 ListGrants
3713  
3714 =item *
3715  
3716 ListRetirableGrants
3717  
3718 =item *
3719  
3720 RetireGrant
3721  
3722 =back
3723  
3724  
3725  
3726 =head2 ScheduleKeyDeletion
3727  
3728 =over
3729  
3730 =item KeyId => Str
3731  
3732 =item [PendingWindowInDays => Int]
3733  
3734  
3735 =back
3736  
3737 Each argument is described in detail in: L<Paws::KMS::ScheduleKeyDeletion>
3738  
3739 Returns: a L<Paws::KMS::ScheduleKeyDeletionResponse> instance
3740  
3741 Schedules the deletion of a customer master key (CMK). By default, AWS
3742 KMS applies a waiting period of 30 days, but you can specify a waiting
3743 period of 7-30 days. When this operation is successful, the key state
3744 of the CMK changes to C<PendingDeletion> and the key can't be used in
3745 any cryptographic operations. It remains in this state for the duration
3746 of the waiting period. Before the waiting period ends, you can use
3747 CancelKeyDeletion to cancel the deletion of the CMK. After the waiting
3748 period ends, AWS KMS deletes the CMK, its key material, and all AWS KMS
3749 data associated with it, including all aliases that refer to it.
3750  
3751 Deleting a CMK is a destructive and potentially dangerous operation.
3752 When a CMK is deleted, all data that was encrypted under the CMK is
3753 unrecoverable. (The only exception is a multi-Region replica key.) To
3754 prevent the use of a CMK without deleting it, use DisableKey.
3755  
3756 If you schedule deletion of a CMK from a custom key store
3757 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html),
3758 when the waiting period expires, C<ScheduleKeyDeletion> deletes the CMK
3759 from AWS KMS. Then AWS KMS makes a best effort to delete the key
3760 material from the associated AWS CloudHSM cluster. However, you might
3761 need to manually delete the orphaned key material
3762 (https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html#fix-keystore-orphaned-key)
3763 from the cluster and its backups.
3764  
3765 You can schedule the deletion of a multi-Region primary key and its
3766 replica keys at any time. However, AWS KMS will not delete a
3767 multi-Region primary key with existing replica keys. If you schedule
3768 the deletion of a primary key with replicas, its key state changes to
3769 C<PendingReplicaDeletion> and it cannot be replicated or used in
3770 cryptographic operations. This status can continue indefinitely. When
3771 the last of its replicas keys is deleted (not just scheduled), the key
3772 state of the primary key changes to C<PendingDeletion> and its waiting
3773 period (C<PendingWindowInDays>) begins. For details, see Deleting
3774 multi-Region keys
3775 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-delete.html)
3776 in the I<AWS Key Management Service Developer Guide>.
3777  
3778 For more information about scheduling a CMK for deletion, see Deleting
3779 Customer Master Keys
3780 (https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html)
3781 in the I<AWS Key Management Service Developer Guide>.
3782  
3783 The CMK that you use for this operation must be in a compatible key
3784 state. For details, see Key state: Effect on your CMK
3785 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
3786 in the I<AWS Key Management Service Developer Guide>.
3787  
3788 B<Cross-account use>: No. You cannot perform this operation on a CMK in
3789 a different AWS account.
3790  
3791 B<Required permissions>: kms:ScheduleKeyDeletion (key policy)
3792  
3793 B<Related operations>
3794  
3795 =over
3796  
3797 =item *
3798  
3799 CancelKeyDeletion
3800  
3801 =item *
3802  
3803 DisableKey
3804  
3805 =back
3806  
3807  
3808  
3809 =head2 Sign
3810  
3811 =over
3812  
3813 =item KeyId => Str
3814  
3815 =item Message => Str
3816  
3817 =item SigningAlgorithm => Str
3818  
3819 =item [GrantTokens => ArrayRef[Str|Undef]]
3820  
3821 =item [MessageType => Str]
3822  
3823  
3824 =back
3825  
3826 Each argument is described in detail in: L<Paws::KMS::Sign>
3827  
3828 Returns: a L<Paws::KMS::SignResponse> instance
3829  
3830 Creates a digital signature
3831 (https://en.wikipedia.org/wiki/Digital_signature) for a message or
3832 message digest by using the private key in an asymmetric CMK. To verify
3833 the signature, use the Verify operation, or use the public key in the
3834 same asymmetric CMK outside of AWS KMS. For information about symmetric
3835 and asymmetric CMKs, see Using Symmetric and Asymmetric CMKs
3836 (https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)
3837 in the I<AWS Key Management Service Developer Guide>.
3838  
3839 Digital signatures are generated and verified by using asymmetric key
3840 pair, such as an RSA or ECC pair that is represented by an asymmetric
3841 customer master key (CMK). The key owner (or an authorized user) uses
3842 their private key to sign a message. Anyone with the public key can
3843 verify that the message was signed with that particular private key and
3844 that the message hasn't changed since it was signed.
3845  
3846 To use the C<Sign> operation, provide the following information:
3847  
3848 =over
3849  
3850 =item *
3851  
3852 Use the C<KeyId> parameter to identify an asymmetric CMK with a
3853 C<KeyUsage> value of C<SIGN_VERIFY>. To get the C<KeyUsage> value of a
3854 CMK, use the DescribeKey operation. The caller must have C<kms:Sign>
3855 permission on the CMK.
3856  
3857 =item *
3858  
3859 Use the C<Message> parameter to specify the message or message digest
3860 to sign. You can submit messages of up to 4096 bytes. To sign a larger
3861 message, generate a hash digest of the message, and then provide the
3862 hash digest in the C<Message> parameter. To indicate whether the
3863 message is a full message or a digest, use the C<MessageType>
3864 parameter.
3865  
3866 =item *
3867  
3868 Choose a signing algorithm that is compatible with the CMK.
3869  
3870 =back
3871  
3872 When signing a message, be sure to record the CMK and the signing
3873 algorithm. This information is required to verify the signature.
3874  
3875 To verify the signature that this operation generates, use the Verify
3876 operation. Or use the GetPublicKey operation to download the public key
3877 and then use the public key to verify the signature outside of AWS KMS.
3878  
3879 The CMK that you use for this operation must be in a compatible key
3880 state. For details, see Key state: Effect on your CMK
3881 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
3882 in the I<AWS Key Management Service Developer Guide>.
3883  
3884 B<Cross-account use>: Yes. To perform this operation with a CMK in a
3885 different AWS account, specify the key ARN or alias ARN in the value of
3886 the C<KeyId> parameter.
3887  
3888 B<Required permissions>: kms:Sign
3889 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3890 (key policy)
3891  
3892 B<Related operations>: Verify
3893  
3894  
3895 =head2 TagResource
3896  
3897 =over
3898  
3899 =item KeyId => Str
3900  
3901 =item Tags => ArrayRef[L<Paws::KMS::Tag>]
3902  
3903  
3904 =back
3905  
3906 Each argument is described in detail in: L<Paws::KMS::TagResource>
3907  
3908 Returns: nothing
3909  
3910 Adds or edits tags on a customer managed CMK
3911 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk).
3912  
3913 Tagging or untagging a CMK can allow or deny permission to the CMK. For
3914 details, see Using ABAC in AWS KMS
3915 (https://docs.aws.amazon.com/kms/latest/developerguide/abac.html) in
3916 the I<AWS Key Management Service Developer Guide>.
3917  
3918 Each tag consists of a tag key and a tag value, both of which are
3919 case-sensitive strings. The tag value can be an empty (null) string. To
3920 add a tag, specify a new tag key and a tag value. To edit a tag,
3921 specify an existing tag key and a new tag value.
3922  
3923 You can use this operation to tag a customer managed CMK
3924 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk),
3925 but you cannot tag an AWS managed CMK
3926 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk),
3927 an AWS owned CMK
3928 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk),
3929 a custom key store
3930 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#keystore-concept),
3931 or an alias
3932 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#alias-concept).
3933  
3934 You can also add tags to a CMK while creating it (CreateKey) or
3935 replicating it (ReplicateKey).
3936  
3937 For information about using tags in AWS KMS, see Tagging keys
3938 (https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html).
3939 For general information about tags, including the format and syntax,
3940 see Tagging AWS resources
3941 (https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the
3942 I<Amazon Web Services General Reference>.
3943  
3944 The CMK that you use for this operation must be in a compatible key
3945 state. For details, see Key state: Effect on your CMK
3946 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
3947 in the I<AWS Key Management Service Developer Guide>.
3948  
3949 B<Cross-account use>: No. You cannot perform this operation on a CMK in
3950 a different AWS account.
3951  
3952 B<Required permissions>: kms:TagResource
3953 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
3954 (key policy)
3955  
3956 B<Related operations>
3957  
3958 =over
3959  
3960 =item *
3961  
3962 CreateKey
3963  
3964 =item *
3965  
3966 ListResourceTags
3967  
3968 =item *
3969  
3970 ReplicateKey
3971  
3972 =item *
3973  
3974 UntagResource
3975  
3976 =back
3977  
3978  
3979  
3980 =head2 UntagResource
3981  
3982 =over
3983  
3984 =item KeyId => Str
3985  
3986 =item TagKeys => ArrayRef[Str|Undef]
3987  
3988  
3989 =back
3990  
3991 Each argument is described in detail in: L<Paws::KMS::UntagResource>
3992  
3993 Returns: nothing
3994  
3995 Deletes tags from a customer managed CMK
3996 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk).
3997 To delete a tag, specify the tag key and the CMK.
3998  
3999 Tagging or untagging a CMK can allow or deny permission to the CMK. For
4000 details, see Using ABAC in AWS KMS
4001 (https://docs.aws.amazon.com/kms/latest/developerguide/abac.html) in
4002 the I<AWS Key Management Service Developer Guide>.
4003  
4004 When it succeeds, the C<UntagResource> operation doesn't return any
4005 output. Also, if the specified tag key isn't found on the CMK, it
4006 doesn't throw an exception or return a response. To confirm that the
4007 operation worked, use the ListResourceTags operation.
4008  
4009 For information about using tags in AWS KMS, see Tagging keys
4010 (https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html).
4011 For general information about tags, including the format and syntax,
4012 see Tagging AWS resources
4013 (https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the
4014 I<Amazon Web Services General Reference>.
4015  
4016 The CMK that you use for this operation must be in a compatible key
4017 state. For details, see Key state: Effect on your CMK
4018 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
4019 in the I<AWS Key Management Service Developer Guide>.
4020  
4021 B<Cross-account use>: No. You cannot perform this operation on a CMK in
4022 a different AWS account.
4023  
4024 B<Required permissions>: kms:UntagResource
4025 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4026 (key policy)
4027  
4028 B<Related operations>
4029  
4030 =over
4031  
4032 =item *
4033  
4034 CreateKey
4035  
4036 =item *
4037  
4038 ListResourceTags
4039  
4040 =item *
4041  
4042 ReplicateKey
4043  
4044 =item *
4045  
4046 TagResource
4047  
4048 =back
4049  
4050  
4051  
4052 =head2 UpdateAlias
4053  
4054 =over
4055  
4056 =item AliasName => Str
4057  
4058 =item TargetKeyId => Str
4059  
4060  
4061 =back
4062  
4063 Each argument is described in detail in: L<Paws::KMS::UpdateAlias>
4064  
4065 Returns: nothing
4066  
4067 Associates an existing AWS KMS alias with a different customer master
4068 key (CMK). Each alias is associated with only one CMK at a time,
4069 although a CMK can have multiple aliases. The alias and the CMK must be
4070 in the same AWS account and Region.
4071  
4072 Adding, deleting, or updating an alias can allow or deny permission to
4073 the CMK. For details, see Using ABAC in AWS KMS
4074 (https://docs.aws.amazon.com/kms/latest/developerguide/abac.html) in
4075 the I<AWS Key Management Service Developer Guide>.
4076  
4077 The current and new CMK must be the same type (both symmetric or both
4078 asymmetric), and they must have the same key usage (C<ENCRYPT_DECRYPT>
4079 or C<SIGN_VERIFY>). This restriction prevents errors in code that uses
4080 aliases. If you must assign an alias to a different type of CMK, use
4081 DeleteAlias to delete the old alias and CreateAlias to create a new
4082 alias.
4083  
4084 You cannot use C<UpdateAlias> to change an alias name. To change an
4085 alias name, use DeleteAlias to delete the old alias and CreateAlias to
4086 create a new alias.
4087  
4088 Because an alias is not a property of a CMK, you can create, update,
4089 and delete the aliases of a CMK without affecting the CMK. Also,
4090 aliases do not appear in the response from the DescribeKey operation.
4091 To get the aliases of all CMKs in the account, use the ListAliases
4092 operation.
4093  
4094 The CMK that you use for this operation must be in a compatible key
4095 state. For details, see Key state: Effect on your CMK
4096 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
4097 in the I<AWS Key Management Service Developer Guide>.
4098  
4099 B<Cross-account use>: No. You cannot perform this operation on a CMK in
4100 a different AWS account.
4101  
4102 B<Required permissions>
4103  
4104 =over
4105  
4106 =item *
4107  
4108 kms:UpdateAlias
4109 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4110 on the alias (IAM policy).
4111  
4112 =item *
4113  
4114 kms:UpdateAlias
4115 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4116 on the current CMK (key policy).
4117  
4118 =item *
4119  
4120 kms:UpdateAlias
4121 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4122 on the new CMK (key policy).
4123  
4124 =back
4125  
4126 For details, see Controlling access to aliases
4127 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html#alias-access)
4128 in the I<AWS Key Management Service Developer Guide>.
4129  
4130 B<Related operations:>
4131  
4132 =over
4133  
4134 =item *
4135  
4136 CreateAlias
4137  
4138 =item *
4139  
4140 DeleteAlias
4141  
4142 =item *
4143  
4144 ListAliases
4145  
4146 =back
4147  
4148  
4149  
4150 =head2 UpdateCustomKeyStore
4151  
4152 =over
4153  
4154 =item CustomKeyStoreId => Str
4155  
4156 =item [CloudHsmClusterId => Str]
4157  
4158 =item [KeyStorePassword => Str]
4159  
4160 =item [NewCustomKeyStoreName => Str]
4161  
4162  
4163 =back
4164  
4165 Each argument is described in detail in: L<Paws::KMS::UpdateCustomKeyStore>
4166  
4167 Returns: a L<Paws::KMS::UpdateCustomKeyStoreResponse> instance
4168  
4169 Changes the properties of a custom key store. Use the
4170 C<CustomKeyStoreId> parameter to identify the custom key store you want
4171 to edit. Use the remaining parameters to change the properties of the
4172 custom key store.
4173  
4174 You can only update a custom key store that is disconnected. To
4175 disconnect the custom key store, use DisconnectCustomKeyStore. To
4176 reconnect the custom key store after the update completes, use
4177 ConnectCustomKeyStore. To find the connection state of a custom key
4178 store, use the DescribeCustomKeyStores operation.
4179  
4180 Use the parameters of C<UpdateCustomKeyStore> to edit your keystore
4181 settings.
4182  
4183 =over
4184  
4185 =item *
4186  
4187 Use the B<NewCustomKeyStoreName> parameter to change the friendly name
4188 of the custom key store to the value that you specify.
4189  
4190 =item *
4191  
4192 Use the B<KeyStorePassword> parameter tell AWS KMS the current password
4193 of the C<kmsuser> crypto user (CU)
4194 (https://docs.aws.amazon.com/kms/latest/developerguide/key-store-concepts.html#concept-kmsuser)
4195 in the associated AWS CloudHSM cluster. You can use this parameter to
4196 fix connection failures
4197 (https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html#fix-keystore-password)
4198 that occur when AWS KMS cannot log into the associated cluster because
4199 the C<kmsuser> password has changed. This value does not change the
4200 password in the AWS CloudHSM cluster.
4201  
4202 =item *
4203  
4204 Use the B<CloudHsmClusterId> parameter to associate the custom key
4205 store with a different, but related, AWS CloudHSM cluster. You can use
4206 this parameter to repair a custom key store if its AWS CloudHSM cluster
4207 becomes corrupted or is deleted, or when you need to create or restore
4208 a cluster from a backup.
4209  
4210 =back
4211  
4212 If the operation succeeds, it returns a JSON object with no properties.
4213  
4214 This operation is part of the Custom Key Store feature
4215 (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html)
4216 feature in AWS KMS, which combines the convenience and extensive
4217 integration of AWS KMS with the isolation and control of a
4218 single-tenant key store.
4219  
4220 B<Cross-account use>: No. You cannot perform this operation on a custom
4221 key store in a different AWS account.
4222  
4223 B<Required permissions>: kms:UpdateCustomKeyStore
4224 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4225 (IAM policy)
4226  
4227 B<Related operations:>
4228  
4229 =over
4230  
4231 =item *
4232  
4233 ConnectCustomKeyStore
4234  
4235 =item *
4236  
4237 CreateCustomKeyStore
4238  
4239 =item *
4240  
4241 DeleteCustomKeyStore
4242  
4243 =item *
4244  
4245 DescribeCustomKeyStores
4246  
4247 =item *
4248  
4249 DisconnectCustomKeyStore
4250  
4251 =back
4252  
4253  
4254  
4255 =head2 UpdateKeyDescription
4256  
4257 =over
4258  
4259 =item Description => Str
4260  
4261 =item KeyId => Str
4262  
4263  
4264 =back
4265  
4266 Each argument is described in detail in: L<Paws::KMS::UpdateKeyDescription>
4267  
4268 Returns: nothing
4269  
4270 Updates the description of a customer master key (CMK). To see the
4271 description of a CMK, use DescribeKey.
4272  
4273 The CMK that you use for this operation must be in a compatible key
4274 state. For details, see Key state: Effect on your CMK
4275 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
4276 in the I<AWS Key Management Service Developer Guide>.
4277  
4278 B<Cross-account use>: No. You cannot perform this operation on a CMK in
4279 a different AWS account.
4280  
4281 B<Required permissions>: kms:UpdateKeyDescription
4282 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4283 (key policy)
4284  
4285 B<Related operations>
4286  
4287 =over
4288  
4289 =item *
4290  
4291 CreateKey
4292  
4293 =item *
4294  
4295 DescribeKey
4296  
4297 =back
4298  
4299  
4300  
4301 =head2 UpdatePrimaryRegion
4302  
4303 =over
4304  
4305 =item KeyId => Str
4306  
4307 =item PrimaryRegion => Str
4308  
4309  
4310 =back
4311  
4312 Each argument is described in detail in: L<Paws::KMS::UpdatePrimaryRegion>
4313  
4314 Returns: nothing
4315  
4316 Changes the primary key of a multi-Region key.
4317  
4318 This operation changes the replica key in the specified Region to a
4319 primary key and changes the former primary key to a replica key. For
4320 example, suppose you have a primary key in C<us-east-1> and a replica
4321 key in C<eu-west-2>. If you run C<UpdatePrimaryRegion> with a
4322 C<PrimaryRegion> value of C<eu-west-2>, the primary key is now the key
4323 in C<eu-west-2>, and the key in C<us-east-1> becomes a replica key. For
4324 details, see
4325  
4326 This operation supports I<multi-Region keys>, an AWS KMS feature that
4327 lets you create multiple interoperable CMKs in different AWS Regions.
4328 Because these CMKs have the same key ID, key material, and other
4329 metadata, you can use them to encrypt data in one AWS Region and
4330 decrypt it in a different AWS Region without making a cross-Region call
4331 or exposing the plaintext data. For more information about multi-Region
4332 keys, see Using multi-Region keys
4333 (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html)
4334 in the I<AWS Key Management Service Developer Guide>.
4335  
4336 The I<primary key> of a multi-Region key is the source for properties
4337 that are always shared by primary and replica keys, including the key
4338 material, key ID
4339 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-id),
4340 key spec
4341 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-spec),
4342 key usage
4343 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-usage),
4344 key material origin
4345 (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-origin),
4346 and automatic key rotation
4347 (https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html).
4348 It's the only key that can be replicated. You cannot delete the primary
4349 key
4350 (https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html)
4351 until all replicas are deleted.
4352  
4353 The key ID and primary Region that you specify uniquely identify the
4354 replica key that will become the primary key. The primary Region must
4355 already have a replica key. This operation does not create a CMK in the
4356 specified Region. To find the replica keys, use the DescribeKey
4357 operation on the primary key or any replica key. To create a replica
4358 key, use the ReplicateKey operation.
4359  
4360 You can run this operation while using the affected multi-Region keys
4361 in cryptographic operations. This operation should not delay,
4362 interrupt, or cause failures in cryptographic operations.
4363  
4364 Even after this operation completes, the process of updating the
4365 primary Region might still be in progress for a few more seconds.
4366 Operations such as C<DescribeKey> might display both the old and new
4367 primary keys as replicas. The old and new primary keys have a transient
4368 key state of C<Updating>. The original key state is restored when the
4369 update is complete. While the key state is C<Updating>, you can use the
4370 keys in cryptographic operations, but you cannot replicate the new
4371 primary key or perform certain management operations, such as enabling
4372 or disabling these keys. For details about the C<Updating> key state,
4373 see Key state: Effect on your CMK in the I<AWS Key Management Service
4374 Developer Guide>.
4375  
4376 This operation does not return any output. To verify that primary key
4377 is changed, use the DescribeKey operation.
4378  
4379 B<Cross-account use>: No. You cannot use this operation in a different
4380 AWS account.
4381  
4382 B<Required permissions>:
4383  
4384 =over
4385  
4386 =item *
4387  
4388 C<kms:UpdatePrimaryRegion> on the current primary CMK (in the primary
4389 CMK's Region). Include this permission primary CMK's key policy.
4390  
4391 =item *
4392  
4393 C<kms:UpdatePrimaryRegion> on the current replica CMK (in the replica
4394 CMK's Region). Include this permission in the replica CMK's key policy.
4395  
4396 =back
4397  
4398 B<Related operations>
4399  
4400 =over
4401  
4402 =item *
4403  
4404 CreateKey
4405  
4406 =item *
4407  
4408 ReplicateKey
4409  
4410 =back
4411  
4412  
4413  
4414 =head2 Verify
4415  
4416 =over
4417  
4418 =item KeyId => Str
4419  
4420 =item Message => Str
4421  
4422 =item Signature => Str
4423  
4424 =item SigningAlgorithm => Str
4425  
4426 =item [GrantTokens => ArrayRef[Str|Undef]]
4427  
4428 =item [MessageType => Str]
4429  
4430  
4431 =back
4432  
4433 Each argument is described in detail in: L<Paws::KMS::Verify>
4434  
4435 Returns: a L<Paws::KMS::VerifyResponse> instance
4436  
4437 Verifies a digital signature that was generated by the Sign operation.
4438  
4439 Verification confirms that an authorized user signed the message with
4440 the specified CMK and signing algorithm, and the message hasn't changed
4441 since it was signed. If the signature is verified, the value of the
4442 C<SignatureValid> field in the response is C<True>. If the signature
4443 verification fails, the C<Verify> operation fails with an
4444 C<KMSInvalidSignatureException> exception.
4445  
4446 A digital signature is generated by using the private key in an
4447 asymmetric CMK. The signature is verified by using the public key in
4448 the same asymmetric CMK. For information about symmetric and asymmetric
4449 CMKs, see Using Symmetric and Asymmetric CMKs
4450 (https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html)
4451 in the I<AWS Key Management Service Developer Guide>.
4452  
4453 To verify a digital signature, you can use the C<Verify> operation.
4454 Specify the same asymmetric CMK, message, and signing algorithm that
4455 were used to produce the signature.
4456  
4457 You can also verify the digital signature by using the public key of
4458 the CMK outside of AWS KMS. Use the GetPublicKey operation to download
4459 the public key in the asymmetric CMK and then use the public key to
4460 verify the signature outside of AWS KMS. The advantage of using the
4461 C<Verify> operation is that it is performed within AWS KMS. As a
4462 result, it's easy to call, the operation is performed within the FIPS
4463 boundary, it is logged in AWS CloudTrail, and you can use key policy
4464 and IAM policy to determine who is authorized to use the CMK to verify
4465 signatures.
4466  
4467 The CMK that you use for this operation must be in a compatible key
4468 state. For details, see Key state: Effect on your CMK
4469 (https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html)
4470 in the I<AWS Key Management Service Developer Guide>.
4471  
4472 B<Cross-account use>: Yes. To perform this operation with a CMK in a
4473 different AWS account, specify the key ARN or alias ARN in the value of
4474 the C<KeyId> parameter.
4475  
4476 B<Required permissions>: kms:Verify
4477 (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html)
4478 (key policy)
4479  
4480 B<Related operations>: Sign
4481  
4482  
4483  
4484  
4485 =head1 PAGINATORS
4486  
4487 Paginator methods are helpers that repetively call methods that return partial results
4488  
4489 =head2 ListAllAliases(sub { },[KeyId => Str, Limit => Int, Marker => Str])
4490  
4491 =head2 ListAllAliases([KeyId => Str, Limit => Int, Marker => Str])
4492  
4493  
4494 If passed a sub as first parameter, it will call the sub for each element found in :
4495  
4496 - Aliases, passing the object as the first parameter, and the string 'Aliases' as the second parameter
4497  
4498 If not, it will return a a L<Paws::KMS::ListAliasesResponse> instance with all the C<param>s; from all the responses. Please take into account that this mode can potentially consume vasts ammounts of memory.
4499  
4500  
4501 =head2 ListAllGrants(sub { },KeyId => Str, [GranteePrincipal => Str, GrantId => Str, Limit => Int, Marker => Str])
4502  
4503 =head2 ListAllGrants(KeyId => Str, [GranteePrincipal => Str, GrantId => Str, Limit => Int, Marker => Str])
4504  
4505  
4506 If passed a sub as first parameter, it will call the sub for each element found in :
4507  
4508 - Grants, passing the object as the first parameter, and the string 'Grants' as the second parameter
4509  
4510 If not, it will return a a L<Paws::KMS::ListGrantsResponse> instance with all the C<param>s; from all the responses. Please take into account that this mode can potentially consume vasts ammounts of memory.
4511  
4512  
4513 =head2 ListAllKeyPolicies(sub { },KeyId => Str, [Limit => Int, Marker => Str])
4514  
4515 =head2 ListAllKeyPolicies(KeyId => Str, [Limit => Int, Marker => Str])
4516  
4517  
4518 If passed a sub as first parameter, it will call the sub for each element found in :
4519  
4520 - PolicyNames, passing the object as the first parameter, and the string 'PolicyNames' as the second parameter
4521  
4522 If not, it will return a a L<Paws::KMS::ListKeyPoliciesResponse> instance with all the C<param>s; from all the responses. Please take into account that this mode can potentially consume vasts ammounts of memory.
4523  
4524  
4525 =head2 ListAllKeys(sub { },[Limit => Int, Marker => Str])
4526  
4527 =head2 ListAllKeys([Limit => Int, Marker => Str])
4528  
4529  
4530 If passed a sub as first parameter, it will call the sub for each element found in :
4531  
4532 - Keys, passing the object as the first parameter, and the string 'Keys' as the second parameter
4533  
4534 If not, it will return a a L<Paws::KMS::ListKeysResponse> instance with all the C<param>s; from all the responses. Please take into account that this mode can potentially consume vasts ammounts of memory.
4535  
4536  
4537  
4538  
4539  
4540 =head1 SEE ALSO
4541  
4542 This service class forms part of L<Paws>
4543  
4544 =head1 BUGS and CONTRIBUTIONS
4545  
4546 The source code is located here: L<https://github.com/pplu/aws-sdk-perl>
4547  
4548 Please report bugs to: L<https://github.com/pplu/aws-sdk-perl/issues>
4549  
4550 =cut
4551