generated from amazon-archives/__template_Apache-2.0
-
Notifications
You must be signed in to change notification settings - Fork 237
Expand file tree
/
Copy pathkms.json
More file actions
9981 lines (9981 loc) · 832 KB
/
kms.json
File metadata and controls
9981 lines (9981 loc) · 832 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"smithy": "2.0",
"metadata": {
"suppressions": [
{
"id": "HttpMethodSemantics",
"namespace": "*"
},
{
"id": "HttpResponseCodeSemantics",
"namespace": "*"
},
{
"id": "PaginatedTrait",
"namespace": "*"
},
{
"id": "HttpHeaderTrait",
"namespace": "*"
},
{
"id": "HttpUriConflict",
"namespace": "*"
},
{
"id": "Service",
"namespace": "*"
}
]
},
"shapes": {
"com.amazonaws.kms#AWSAccountIdType": {
"type": "string"
},
"com.amazonaws.kms#AlgorithmSpec": {
"type": "enum",
"members": {
"RSAES_PKCS1_V1_5": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "RSAES_PKCS1_V1_5"
}
},
"RSAES_OAEP_SHA_1": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "RSAES_OAEP_SHA_1"
}
},
"RSAES_OAEP_SHA_256": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "RSAES_OAEP_SHA_256"
}
},
"RSA_AES_KEY_WRAP_SHA_1": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "RSA_AES_KEY_WRAP_SHA_1"
}
},
"RSA_AES_KEY_WRAP_SHA_256": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "RSA_AES_KEY_WRAP_SHA_256"
}
},
"SM2PKE": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "SM2PKE"
}
}
}
},
"com.amazonaws.kms#AliasList": {
"type": "list",
"member": {
"target": "com.amazonaws.kms#AliasListEntry"
}
},
"com.amazonaws.kms#AliasListEntry": {
"type": "structure",
"members": {
"AliasName": {
"target": "com.amazonaws.kms#AliasNameType",
"traits": {
"smithy.api#documentation": "<p>String that contains the alias. This value begins with <code>alias/</code>.</p>"
}
},
"AliasArn": {
"target": "com.amazonaws.kms#ArnType",
"traits": {
"smithy.api#documentation": "<p>String that contains the key ARN.</p>"
}
},
"TargetKeyId": {
"target": "com.amazonaws.kms#KeyIdType",
"traits": {
"smithy.api#documentation": "<p>String that contains the key identifier of the KMS key associated with the alias.</p>"
}
},
"CreationDate": {
"target": "com.amazonaws.kms#DateType",
"traits": {
"smithy.api#documentation": "<p>Date and time that the alias was most recently created in the account and Region.\n Formatted as Unix time.</p>"
}
},
"LastUpdatedDate": {
"target": "com.amazonaws.kms#DateType",
"traits": {
"smithy.api#documentation": "<p>Date and time that the alias was most recently associated with a KMS key in the account\n and Region. Formatted as Unix time.</p>"
}
}
},
"traits": {
"smithy.api#documentation": "<p>Contains information about an alias.</p>"
}
},
"com.amazonaws.kms#AliasNameType": {
"type": "string",
"traits": {
"smithy.api#length": {
"min": 1,
"max": 256
},
"smithy.api#pattern": "^[a-zA-Z0-9:/_-]+$"
}
},
"com.amazonaws.kms#AlreadyExistsException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "AlreadyExists",
"httpResponseCode": 409
},
"smithy.api#documentation": "<p>The request was rejected because it attempted to create a resource that already\n exists.</p>",
"smithy.api#error": "client",
"smithy.api#httpError": 409
}
},
"com.amazonaws.kms#ArnType": {
"type": "string",
"traits": {
"smithy.api#length": {
"min": 20,
"max": 2048
}
}
},
"com.amazonaws.kms#AttestationDocumentType": {
"type": "blob",
"traits": {
"smithy.api#length": {
"min": 1,
"max": 262144
}
}
},
"com.amazonaws.kms#BackingKeyIdResponseType": {
"type": "string",
"traits": {
"smithy.api#length": {
"min": 0,
"max": 64
},
"smithy.api#pattern": "^[a-f0-9]+$"
}
},
"com.amazonaws.kms#BackingKeyIdType": {
"type": "string",
"traits": {
"smithy.api#length": {
"min": 64,
"max": 64
},
"smithy.api#pattern": "^[a-f0-9]+$"
}
},
"com.amazonaws.kms#BooleanType": {
"type": "boolean",
"traits": {
"smithy.api#default": false
}
},
"com.amazonaws.kms#CancelKeyDeletion": {
"type": "operation",
"input": {
"target": "com.amazonaws.kms#CancelKeyDeletionRequest"
},
"output": {
"target": "com.amazonaws.kms#CancelKeyDeletionResponse"
},
"errors": [
{
"target": "com.amazonaws.kms#DependencyTimeoutException"
},
{
"target": "com.amazonaws.kms#InvalidArnException"
},
{
"target": "com.amazonaws.kms#KMSInternalException"
},
{
"target": "com.amazonaws.kms#KMSInvalidStateException"
},
{
"target": "com.amazonaws.kms#NotFoundException"
}
],
"traits": {
"smithy.api#documentation": "<p>Cancels the deletion of a KMS key. When this operation succeeds, the key state of the KMS\n key is <code>Disabled</code>. To enable the KMS key, use <a>EnableKey</a>. </p>\n <p>For more information about scheduling and canceling deletion of a KMS key, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html\">Deleting KMS keys</a> in the\n <i>Key Management Service Developer Guide</i>.</p>\n <p>The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html\">Key states of KMS keys</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>\n <b>Cross-account use</b>: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.</p>\n <p>\n <b>Required permissions</b>: <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html\">kms:CancelKeyDeletion</a> (key policy)</p>\n <p>\n <b>Related operations</b>: <a>ScheduleKeyDeletion</a>\n </p>\n <p>\n <b>Eventual consistency</b>: The KMS API follows an eventual consistency model. \n For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency\">KMS eventual consistency</a>.</p>",
"smithy.api#examples": [
{
"title": "To cancel deletion of a KMS key",
"documentation": "The following example cancels deletion of the specified KMS key.",
"input": {
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
"output": {
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
]
}
},
"com.amazonaws.kms#CancelKeyDeletionRequest": {
"type": "structure",
"members": {
"KeyId": {
"target": "com.amazonaws.kms#KeyIdType",
"traits": {
"smithy.api#documentation": "<p>Identifies the KMS key whose deletion is being canceled.</p>\n <p>Specify the key ID or key ARN of the KMS key.</p>\n <p>For example:</p>\n <ul>\n <li>\n <p>Key ID: <code>1234abcd-12ab-34cd-56ef-1234567890ab</code>\n </p>\n </li>\n <li>\n <p>Key ARN: <code>arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</code>\n </p>\n </li>\n </ul>\n <p>To get the key ID and key ARN for a KMS key, use <a>ListKeys</a> or <a>DescribeKey</a>.</p>",
"smithy.api#required": {}
}
}
},
"traits": {
"smithy.api#input": {}
}
},
"com.amazonaws.kms#CancelKeyDeletionResponse": {
"type": "structure",
"members": {
"KeyId": {
"target": "com.amazonaws.kms#KeyIdType",
"traits": {
"smithy.api#documentation": "<p>The Amazon Resource Name (<a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN\">key ARN</a>) of the KMS key whose deletion is canceled.</p>"
}
}
},
"traits": {
"smithy.api#output": {}
}
},
"com.amazonaws.kms#CiphertextType": {
"type": "blob",
"traits": {
"smithy.api#length": {
"min": 1,
"max": 6144
}
}
},
"com.amazonaws.kms#CloudHsmClusterIdType": {
"type": "string",
"traits": {
"smithy.api#length": {
"min": 19,
"max": 24
},
"smithy.api#pattern": "^cluster-[2-7a-zA-Z]{11,16}$"
}
},
"com.amazonaws.kms#CloudHsmClusterInUseException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "CloudHsmClusterInUseException",
"httpResponseCode": 400
},
"smithy.api#documentation": "<p>The request was rejected because the specified CloudHSM cluster is already associated with an\n CloudHSM key store in the account, or it shares a backup history with an CloudHSM key store in the\n account. Each CloudHSM key store in the account must be associated with a different CloudHSM\n cluster.</p>\n <p>CloudHSM clusters that share a backup history have the same cluster certificate. To view the\n cluster certificate of an CloudHSM cluster, use the <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html\">DescribeClusters</a> operation.</p>",
"smithy.api#error": "client",
"smithy.api#httpError": 400
}
},
"com.amazonaws.kms#CloudHsmClusterInvalidConfigurationException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "CloudHsmClusterInvalidConfigurationException",
"httpResponseCode": 400
},
"smithy.api#documentation": "<p>The request was rejected because the associated CloudHSM cluster did not meet the\n configuration requirements for an CloudHSM key store.</p>\n <ul>\n <li>\n <p>The CloudHSM cluster must be configured with private subnets in at least two different\n Availability Zones in the Region.</p>\n </li>\n <li>\n <p>The <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sg.html\">security group for\n the cluster</a> (cloudhsm-cluster-<i><cluster-id></i>-sg) must\n include inbound rules and outbound rules that allow TCP traffic on ports 2223-2225. The\n <b>Source</b> in the inbound rules and the <b>Destination</b> in the outbound rules must match the security group\n ID. These rules are set by default when you create the CloudHSM cluster. Do not delete or\n change them. To get information about a particular security group, use the <a href=\"https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html\">DescribeSecurityGroups</a> operation.</p>\n </li>\n <li>\n <p>The CloudHSM cluster must contain at least as many HSMs as the operation requires. To add\n HSMs, use the CloudHSM <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html\">CreateHsm</a> operation.</p>\n <p>For the <a>CreateCustomKeyStore</a>, <a>UpdateCustomKeyStore</a>, and <a>CreateKey</a> operations, the CloudHSM cluster must have at least two\n active HSMs, each in a different Availability Zone. For the <a>ConnectCustomKeyStore</a> operation, the CloudHSM must contain at least one active\n HSM.</p>\n </li>\n </ul>\n <p>For information about the requirements for an CloudHSM cluster that is associated with an\n CloudHSM key store, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#before-keystore\">Assemble the Prerequisites</a>\n in the <i>Key Management Service Developer Guide</i>. For information about creating a private subnet for an CloudHSM cluster,\n see <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-subnets.html\">Create a Private\n Subnet</a> in the <i>CloudHSM User Guide</i>. For information about cluster security groups, see\n <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sg.html\">Configure a Default Security\n Group</a> in the <i>\n <i>CloudHSM User Guide</i>\n </i>. </p>",
"smithy.api#error": "client",
"smithy.api#httpError": 400
}
},
"com.amazonaws.kms#CloudHsmClusterNotActiveException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "CloudHsmClusterNotActiveException",
"httpResponseCode": 400
},
"smithy.api#documentation": "<p>The request was rejected because the CloudHSM cluster associated with the CloudHSM key store is\n not active. Initialize and activate the cluster and try the command again. For detailed\n instructions, see <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html\">Getting\n Started</a> in the <i>CloudHSM User Guide</i>.</p>",
"smithy.api#error": "client",
"smithy.api#httpError": 400
}
},
"com.amazonaws.kms#CloudHsmClusterNotFoundException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "CloudHsmClusterNotFoundException",
"httpResponseCode": 400
},
"smithy.api#documentation": "<p>The request was rejected because KMS cannot find the CloudHSM cluster with the specified\n cluster ID. Retry the request with a different cluster ID.</p>",
"smithy.api#error": "client",
"smithy.api#httpError": 400
}
},
"com.amazonaws.kms#CloudHsmClusterNotRelatedException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "CloudHsmClusterNotRelatedException",
"httpResponseCode": 400
},
"smithy.api#documentation": "<p>The request was rejected because the specified CloudHSM cluster has a different cluster\n certificate than the original cluster. You cannot use the operation to specify an unrelated\n cluster for an CloudHSM key store.</p>\n <p>Specify an CloudHSM cluster that shares a backup history with the original cluster. This\n includes clusters that were created from a backup of the current cluster, and clusters that\n were created from the same backup that produced the current cluster.</p>\n <p>CloudHSM clusters that share a backup history have the same cluster certificate. To view the\n cluster certificate of an CloudHSM cluster, use the <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html\">DescribeClusters</a> operation.</p>",
"smithy.api#error": "client",
"smithy.api#httpError": 400
}
},
"com.amazonaws.kms#ConflictException": {
"type": "structure",
"members": {
"message": {
"target": "com.amazonaws.kms#ErrorMessageType"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "ConflictException",
"httpResponseCode": 409
},
"smithy.api#documentation": "<p>The request was rejected because an automatic rotation of this key is currently in\n progress or scheduled to begin within the next 20 minutes. </p>",
"smithy.api#error": "client",
"smithy.api#httpError": 409
}
},
"com.amazonaws.kms#ConnectCustomKeyStore": {
"type": "operation",
"input": {
"target": "com.amazonaws.kms#ConnectCustomKeyStoreRequest"
},
"output": {
"target": "com.amazonaws.kms#ConnectCustomKeyStoreResponse"
},
"errors": [
{
"target": "com.amazonaws.kms#CloudHsmClusterInvalidConfigurationException"
},
{
"target": "com.amazonaws.kms#CloudHsmClusterNotActiveException"
},
{
"target": "com.amazonaws.kms#CustomKeyStoreInvalidStateException"
},
{
"target": "com.amazonaws.kms#CustomKeyStoreNotFoundException"
},
{
"target": "com.amazonaws.kms#KMSInternalException"
}
],
"traits": {
"smithy.api#documentation": "<p>Connects or reconnects a <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/key-store-overview.html\">custom key store</a> to its backing key store. For an CloudHSM key\n store, <code>ConnectCustomKeyStore</code> connects the key store to its associated CloudHSM\n cluster. For an external key store, <code>ConnectCustomKeyStore</code> connects the key store\n to the external key store proxy that communicates with your external key manager.</p>\n <p>The custom key store must be connected before you can create KMS keys in the key store or\n use the KMS keys it contains. You can disconnect and reconnect a custom key store at any\n time.</p>\n <p>The connection process for a custom key store can take an extended amount of time to\n complete. This operation starts the connection process, but it does not wait for it to\n complete. When it succeeds, this operation quickly returns an HTTP 200 response and a JSON\n object with no properties. However, this response does not indicate that the custom key store\n is connected. To get the connection state of the custom key store, use the <a>DescribeCustomKeyStores</a> operation.</p>\n <p> This operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.</p>\n <p>The <code>ConnectCustomKeyStore</code> operation might fail for various reasons. To find\n the reason, use the <a>DescribeCustomKeyStores</a> operation and see the\n <code>ConnectionErrorCode</code> in the response. For help interpreting the\n <code>ConnectionErrorCode</code>, see <a>CustomKeyStoresListEntry</a>.</p>\n <p>To fix the failure, use the <a>DisconnectCustomKeyStore</a> operation to\n disconnect the custom key store, correct the error, use the <a>UpdateCustomKeyStore</a> operation if necessary, and then use\n <code>ConnectCustomKeyStore</code> again.</p>\n <p>\n <b>CloudHSM key store</b>\n </p>\n <p>During the connection process for an CloudHSM key store, KMS finds the CloudHSM cluster that\n is associated with the custom key store, creates the connection infrastructure, connects to\n the cluster, logs into the CloudHSM client as the <code>kmsuser</code> CU, and rotates its\n password.</p>\n <p>To connect an CloudHSM key store, its associated CloudHSM cluster must have at least one active\n HSM. To get the number of active HSMs in a cluster, use the <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html\">DescribeClusters</a> operation. To add HSMs\n to the cluster, use the <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html\">CreateHsm</a> operation. Also, the <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html#concept-kmsuser\">\n <code>kmsuser</code> crypto\n user</a> (CU) must not be logged into the cluster. This prevents KMS from using this\n account to log in.</p>\n <p>If you are having trouble connecting or disconnecting a CloudHSM key store, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html\">Troubleshooting an CloudHSM key\n store</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>\n <b>External key store</b>\n </p>\n <p>When you connect an external key store that uses public endpoint connectivity, KMS tests\n its ability to communicate with your external key manager by sending a request via the\n external key store proxy.</p>\n <p>When you connect to an external key store that uses VPC endpoint service connectivity,\n KMS establishes the networking elements that it needs to communicate with your external key\n manager via the external key store proxy. This includes creating an interface endpoint to the\n VPC endpoint service and a private hosted zone for traffic between KMS and the VPC endpoint\n service.</p>\n <p>To connect an external key store, KMS must be able to connect to the external key store\n proxy, the external key store proxy must be able to communicate with your external key\n manager, and the external key manager must be available for cryptographic operations.</p>\n <p>If you are having trouble connecting or disconnecting an external key store, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/xks-troubleshooting.html\">Troubleshooting an external\n key store</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>\n <b>Cross-account use</b>: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.</p>\n <p>\n <b>Required permissions</b>: <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html\">kms:ConnectCustomKeyStore</a> (IAM policy)</p>\n <p>\n <b>Related operations</b>\n </p>\n <ul>\n <li>\n <p>\n <a>CreateCustomKeyStore</a>\n </p>\n </li>\n <li>\n <p>\n <a>DeleteCustomKeyStore</a>\n </p>\n </li>\n <li>\n <p>\n <a>DescribeCustomKeyStores</a>\n </p>\n </li>\n <li>\n <p>\n <a>DisconnectCustomKeyStore</a>\n </p>\n </li>\n <li>\n <p>\n <a>UpdateCustomKeyStore</a>\n </p>\n </li>\n </ul>\n <p>\n <b>Eventual consistency</b>: The KMS API follows an eventual consistency model. \n For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency\">KMS eventual consistency</a>.</p>",
"smithy.api#examples": [
{
"title": "To connect a custom key store",
"documentation": "This example connects an AWS KMS custom key store to its backing key store. For an AWS CloudHSM key store, it connects the key store to its AWS CloudHSM cluster. For an external key store, it connects the key store to the external key store proxy that communicates with your external key manager. This operation does not return any data. To verify that the custom key store is connected, use the <code>DescribeCustomKeyStores</code> operation.",
"input": {
"CustomKeyStoreId": "cks-1234567890abcdef0"
},
"output": {}
}
]
}
},
"com.amazonaws.kms#ConnectCustomKeyStoreRequest": {
"type": "structure",
"members": {
"CustomKeyStoreId": {
"target": "com.amazonaws.kms#CustomKeyStoreIdType",
"traits": {
"smithy.api#documentation": "<p>Enter the key store ID of the custom key store that you want to connect.\n To find the ID of a custom key store, use the <a>DescribeCustomKeyStores</a> operation.</p>",
"smithy.api#required": {}
}
}
},
"traits": {
"smithy.api#input": {}
}
},
"com.amazonaws.kms#ConnectCustomKeyStoreResponse": {
"type": "structure",
"members": {},
"traits": {
"smithy.api#output": {}
}
},
"com.amazonaws.kms#ConnectionErrorCodeType": {
"type": "enum",
"members": {
"INVALID_CREDENTIALS": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "INVALID_CREDENTIALS"
}
},
"CLUSTER_NOT_FOUND": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "CLUSTER_NOT_FOUND"
}
},
"NETWORK_ERRORS": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "NETWORK_ERRORS"
}
},
"INTERNAL_ERROR": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "INTERNAL_ERROR"
}
},
"INSUFFICIENT_CLOUDHSM_HSMS": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "INSUFFICIENT_CLOUDHSM_HSMS"
}
},
"USER_LOCKED_OUT": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "USER_LOCKED_OUT"
}
},
"USER_NOT_FOUND": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "USER_NOT_FOUND"
}
},
"USER_LOGGED_IN": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "USER_LOGGED_IN"
}
},
"SUBNET_NOT_FOUND": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "SUBNET_NOT_FOUND"
}
},
"INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET"
}
},
"XKS_PROXY_ACCESS_DENIED": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_PROXY_ACCESS_DENIED"
}
},
"XKS_PROXY_NOT_REACHABLE": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_PROXY_NOT_REACHABLE"
}
},
"XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND"
}
},
"XKS_PROXY_INVALID_RESPONSE": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_PROXY_INVALID_RESPONSE"
}
},
"XKS_PROXY_INVALID_CONFIGURATION": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_PROXY_INVALID_CONFIGURATION"
}
},
"XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION"
}
},
"XKS_PROXY_TIMED_OUT": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_PROXY_TIMED_OUT"
}
},
"XKS_PROXY_INVALID_TLS_CONFIGURATION": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "XKS_PROXY_INVALID_TLS_CONFIGURATION"
}
}
}
},
"com.amazonaws.kms#ConnectionStateType": {
"type": "enum",
"members": {
"CONNECTED": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "CONNECTED"
}
},
"CONNECTING": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "CONNECTING"
}
},
"FAILED": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "FAILED"
}
},
"DISCONNECTED": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "DISCONNECTED"
}
},
"DISCONNECTING": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "DISCONNECTING"
}
}
}
},
"com.amazonaws.kms#CreateAlias": {
"type": "operation",
"input": {
"target": "com.amazonaws.kms#CreateAliasRequest"
},
"output": {
"target": "smithy.api#Unit"
},
"errors": [
{
"target": "com.amazonaws.kms#AlreadyExistsException"
},
{
"target": "com.amazonaws.kms#DependencyTimeoutException"
},
{
"target": "com.amazonaws.kms#InvalidAliasNameException"
},
{
"target": "com.amazonaws.kms#KMSInternalException"
},
{
"target": "com.amazonaws.kms#KMSInvalidStateException"
},
{
"target": "com.amazonaws.kms#LimitExceededException"
},
{
"target": "com.amazonaws.kms#NotFoundException"
}
],
"traits": {
"smithy.api#documentation": "<p>Creates a friendly name for a KMS key. </p>\n <note>\n <p>Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/abac.html\">ABAC for KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>\n </note>\n <p>You can use an alias to identify a KMS key in the KMS console, in the <a>DescribeKey</a> operation and in <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-cryptography.html#cryptographic-operations\">cryptographic operations</a>, such as <a>Encrypt</a> and\n <a>GenerateDataKey</a>. You can also change the KMS key that's associated with\n the alias (<a>UpdateAlias</a>) or delete the alias (<a>DeleteAlias</a>)\n at any time. These operations don't affect the underlying KMS key. </p>\n <p>You can associate the alias with any customer managed key in the same Amazon Web Services Region. Each\n alias is associated with only one KMS key at a time, but a KMS key can have multiple aliases.\n A valid KMS key is required. You can't create an alias without a KMS key.</p>\n <p>The alias must be unique in the account and Region, but you can have aliases with the same\n name in different Regions. For detailed information about aliases, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html\">Aliases in KMS</a> in the\n <i>Key Management Service Developer Guide</i>.</p>\n <p>This operation does not return a response. To get the alias that you created, use the\n <a>ListAliases</a> operation.</p>\n <p>The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html\">Key states of KMS keys</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>\n <b>Cross-account use</b>: No. You cannot perform this operation on an alias in a different Amazon Web Services account.</p>\n <p>\n <b>Required permissions</b>\n </p>\n <ul>\n <li>\n <p>\n <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html\">kms:CreateAlias</a> on\n the alias (IAM policy).</p>\n </li>\n <li>\n <p>\n <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html\">kms:CreateAlias</a> on\n the KMS key (key policy).</p>\n </li>\n </ul>\n <p>For details, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/alias-access.html\">Controlling access to aliases</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>\n <b>Related operations:</b>\n </p>\n <ul>\n <li>\n <p>\n <a>DeleteAlias</a>\n </p>\n </li>\n <li>\n <p>\n <a>ListAliases</a>\n </p>\n </li>\n <li>\n <p>\n <a>UpdateAlias</a>\n </p>\n </li>\n </ul>\n <p>\n <b>Eventual consistency</b>: The KMS API follows an eventual consistency model. \n For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency\">KMS eventual consistency</a>.</p>",
"smithy.api#examples": [
{
"title": "To create an alias",
"documentation": "The following example creates an alias for the specified KMS key.",
"input": {
"AliasName": "alias/ExampleAlias",
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
]
}
},
"com.amazonaws.kms#CreateAliasRequest": {
"type": "structure",
"members": {
"AliasName": {
"target": "com.amazonaws.kms#AliasNameType",
"traits": {
"smithy.api#documentation": "<p>Specifies the alias name. This value must begin with <code>alias/</code> followed by a\n name, such as <code>alias/ExampleAlias</code>. </p>\n <important>\n <p>Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.</p>\n </important>\n <p>The <code>AliasName</code> value must be string of 1-256 characters. It can contain only\n alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). The alias name\n cannot begin with <code>alias/aws/</code>. The <code>alias/aws/</code> prefix is reserved for\n <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-key\">Amazon Web Services managed\n keys</a>.</p>",
"smithy.api#required": {}
}
},
"TargetKeyId": {
"target": "com.amazonaws.kms#KeyIdType",
"traits": {
"smithy.api#documentation": "<p>Associates the alias with the specified <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key\">customer managed key</a>. The KMS key\n must be in the same Amazon Web Services Region. </p>\n <p>A valid key ID is required. If you supply a null or empty string value, this operation\n returns an error.</p>\n <p>For help finding the key ID and ARN, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html\">Find the key ID and key ARN</a> in\n the <i>\n <i>Key Management Service Developer Guide</i>\n </i>.</p>\n <p>Specify the key ID or key ARN of the KMS key.</p>\n <p>For example:</p>\n <ul>\n <li>\n <p>Key ID: <code>1234abcd-12ab-34cd-56ef-1234567890ab</code>\n </p>\n </li>\n <li>\n <p>Key ARN: <code>arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</code>\n </p>\n </li>\n </ul>\n <p>To get the key ID and key ARN for a KMS key, use <a>ListKeys</a> or <a>DescribeKey</a>.</p>",
"smithy.api#required": {}
}
}
},
"traits": {
"smithy.api#input": {}
}
},
"com.amazonaws.kms#CreateCustomKeyStore": {
"type": "operation",
"input": {
"target": "com.amazonaws.kms#CreateCustomKeyStoreRequest"
},
"output": {
"target": "com.amazonaws.kms#CreateCustomKeyStoreResponse"
},
"errors": [
{
"target": "com.amazonaws.kms#CloudHsmClusterInUseException"
},
{
"target": "com.amazonaws.kms#CloudHsmClusterInvalidConfigurationException"
},
{
"target": "com.amazonaws.kms#CloudHsmClusterNotActiveException"
},
{
"target": "com.amazonaws.kms#CloudHsmClusterNotFoundException"
},
{
"target": "com.amazonaws.kms#CustomKeyStoreNameInUseException"
},
{
"target": "com.amazonaws.kms#IncorrectTrustAnchorException"
},
{
"target": "com.amazonaws.kms#KMSInternalException"
},
{
"target": "com.amazonaws.kms#LimitExceededException"
},
{
"target": "com.amazonaws.kms#XksProxyIncorrectAuthenticationCredentialException"
},
{
"target": "com.amazonaws.kms#XksProxyInvalidConfigurationException"
},
{
"target": "com.amazonaws.kms#XksProxyInvalidResponseException"
},
{
"target": "com.amazonaws.kms#XksProxyUriEndpointInUseException"
},
{
"target": "com.amazonaws.kms#XksProxyUriInUseException"
},
{
"target": "com.amazonaws.kms#XksProxyUriUnreachableException"
},
{
"target": "com.amazonaws.kms#XksProxyVpcEndpointServiceInUseException"
},
{
"target": "com.amazonaws.kms#XksProxyVpcEndpointServiceInvalidConfigurationException"
},
{
"target": "com.amazonaws.kms#XksProxyVpcEndpointServiceNotFoundException"
}
],
"traits": {
"smithy.api#documentation": "<p>Creates a <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/key-store-overview.html\">custom key store</a> backed by a key store that you own and manage. When you use a\n KMS key in a custom key store for a cryptographic operation, the cryptographic operation is\n actually performed in your key store using your keys. KMS supports <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html\">CloudHSM key stores</a>\n backed by an <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/userguide/clusters.html\">CloudHSM cluster</a>\n and <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html\">external key\n stores</a> backed by an external key store proxy and external key manager outside of\n Amazon Web Services.</p>\n <p> This operation is part of the custom key stores feature in KMS, which\ncombines the convenience and extensive integration of KMS with the isolation and control of a\nkey store that you own and manage.</p>\n <p>Before you create the custom key store, the required elements must be in place and\n operational. We recommend that you use the test tools that KMS provides to verify the\n configuration your external key store proxy. For details about the required elements and\n verification tests, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#before-keystore\">Assemble the prerequisites (for\n CloudHSM key stores)</a> or <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/create-xks-keystore.html#xks-requirements\">Assemble the prerequisites (for\n external key stores)</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>To create a custom key store, use the following parameters.</p>\n <ul>\n <li>\n <p>To create an CloudHSM key store, specify the <code>CustomKeyStoreName</code>,\n <code>CloudHsmClusterId</code>, <code>KeyStorePassword</code>, and\n <code>TrustAnchorCertificate</code>. The <code>CustomKeyStoreType</code> parameter is\n optional for CloudHSM key stores. If you include it, set it to the default value,\n <code>AWS_CLOUDHSM</code>. For help with failures, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html\">Troubleshooting an CloudHSM key store</a> in the\n <i>Key Management Service Developer Guide</i>.</p>\n </li>\n <li>\n <p>To create an external key store, specify the <code>CustomKeyStoreName</code> and a\n <code>CustomKeyStoreType</code> of <code>EXTERNAL_KEY_STORE</code>. Also, specify values\n for <code>XksProxyConnectivity</code>, <code>XksProxyAuthenticationCredential</code>,\n <code>XksProxyUriEndpoint</code>, and <code>XksProxyUriPath</code>. If your\n <code>XksProxyConnectivity</code> value is <code>VPC_ENDPOINT_SERVICE</code>, specify\n the <code>XksProxyVpcEndpointServiceName</code> parameter. For help with failures, see\n <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/xks-troubleshooting.html\">Troubleshooting\n an external key store</a> in the <i>Key Management Service Developer Guide</i>.</p>\n </li>\n </ul>\n <note>\n <p>For external key stores:</p>\n <p>Some external key managers provide a simpler method for creating an external key store.\n For details, see your external key manager documentation.</p>\n <p>When creating an external key store in the KMS console, you can upload a JSON-based\n proxy configuration file with the desired values. You cannot use a proxy configuration with\n the <code>CreateCustomKeyStore</code> operation. However, you can use the values in the file\n to help you determine the correct values for the <code>CreateCustomKeyStore</code>\n parameters.</p>\n </note>\n <p>When the operation completes successfully, it returns the ID of the new custom key store.\n Before you can use your new custom key store, you need to use the <a>ConnectCustomKeyStore</a> operation to connect a new CloudHSM key store to its CloudHSM\n cluster, or to connect a new external key store to the external key store proxy for your\n external key manager. Even if you are not going to use your custom key store immediately, you\n might want to connect it to verify that all settings are correct and then disconnect it until\n you are ready to use it.</p>\n <p>\n <b>Cross-account use</b>: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.</p>\n <p>\n <b>Required permissions</b>: <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html\">kms:CreateCustomKeyStore</a> (IAM policy).</p>\n <p>\n <b>Related operations:</b>\n </p>\n <ul>\n <li>\n <p>\n <a>ConnectCustomKeyStore</a>\n </p>\n </li>\n <li>\n <p>\n <a>DeleteCustomKeyStore</a>\n </p>\n </li>\n <li>\n <p>\n <a>DescribeCustomKeyStores</a>\n </p>\n </li>\n <li>\n <p>\n <a>DisconnectCustomKeyStore</a>\n </p>\n </li>\n <li>\n <p>\n <a>UpdateCustomKeyStore</a>\n </p>\n </li>\n </ul>\n <p>\n <b>Eventual consistency</b>: The KMS API follows an eventual consistency model. \n For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency\">KMS eventual consistency</a>.</p>",
"smithy.api#examples": [
{
"title": "To create an AWS CloudHSM key store",
"documentation": "This example creates a custom key store that is associated with an AWS CloudHSM cluster.",
"input": {
"CustomKeyStoreName": "ExampleKeyStore",
"CloudHsmClusterId": "cluster-234abcdefABC",
"TrustAnchorCertificate": "<certificate-goes-here>",
"KeyStorePassword": "kmsPswd"
},
"output": {
"CustomKeyStoreId": "cks-1234567890abcdef0"
}
}
]
}
},
"com.amazonaws.kms#CreateCustomKeyStoreRequest": {
"type": "structure",
"members": {
"CustomKeyStoreName": {
"target": "com.amazonaws.kms#CustomKeyStoreNameType",
"traits": {
"smithy.api#documentation": "<p>Specifies a friendly name for the custom key store. The name must be unique in your\n Amazon Web Services account and Region. This parameter is required for all custom key stores.</p>\n <important>\n <p>Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.</p>\n </important>",
"smithy.api#required": {}
}
},
"CloudHsmClusterId": {
"target": "com.amazonaws.kms#CloudHsmClusterIdType",
"traits": {
"smithy.api#documentation": "<p>Identifies the CloudHSM cluster for an CloudHSM key store. This parameter is required for custom\n key stores with <code>CustomKeyStoreType</code> of <code>AWS_CLOUDHSM</code>.</p>\n <p>Enter the cluster ID of any active CloudHSM cluster that is not already associated with a\n custom key store. To find the cluster ID, use the <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html\">DescribeClusters</a> operation.</p>"
}
},
"TrustAnchorCertificate": {
"target": "com.amazonaws.kms#TrustAnchorCertificateType",
"traits": {
"smithy.api#documentation": "<p>Specifies the certificate for an CloudHSM key store. This parameter is required for custom\n key stores with a <code>CustomKeyStoreType</code> of <code>AWS_CLOUDHSM</code>.</p>\n <p>Enter the content of the trust anchor certificate for the CloudHSM cluster. This is the\n content of the <code>customerCA.crt</code> file that you created when you <a href=\"https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html\">initialized the\n cluster</a>.</p>"
}
},
"KeyStorePassword": {
"target": "com.amazonaws.kms#KeyStorePasswordType",
"traits": {
"smithy.api#documentation": "<p>Specifies the <code>kmsuser</code> password for an CloudHSM key store. This parameter is\n required for custom key stores with a <code>CustomKeyStoreType</code> of\n <code>AWS_CLOUDHSM</code>.</p>\n <p>Enter the password of the <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html#concept-kmsuser\">\n <code>kmsuser</code> crypto user\n (CU) account</a> in the specified CloudHSM cluster. KMS logs into the cluster as this\n user to manage key material on your behalf.</p>\n <p>The password must be a string of 7 to 32 characters. Its value is case sensitive.</p>\n <p>This parameter tells KMS the <code>kmsuser</code> account password; it does not change\n the password in the CloudHSM cluster.</p>"
}
},
"CustomKeyStoreType": {
"target": "com.amazonaws.kms#CustomKeyStoreType",
"traits": {
"smithy.api#documentation": "<p>Specifies the type of custom key store. The default value is\n <code>AWS_CLOUDHSM</code>.</p>\n <p>For a custom key store backed by an CloudHSM cluster, omit the parameter or enter\n <code>AWS_CLOUDHSM</code>. For a custom key store backed by an external key manager outside\n of Amazon Web Services, enter <code>EXTERNAL_KEY_STORE</code>. You cannot change this property after the key\n store is created.</p>"
}
},
"XksProxyUriEndpoint": {
"target": "com.amazonaws.kms#XksProxyUriEndpointType",
"traits": {
"smithy.api#documentation": "<p>Specifies the endpoint that KMS uses to send requests to the external key store proxy\n (XKS proxy). This parameter is required for custom key stores with a\n <code>CustomKeyStoreType</code> of <code>EXTERNAL_KEY_STORE</code>.</p>\n <p>The protocol must be HTTPS. KMS communicates on port 443. Do not specify the port in the\n <code>XksProxyUriEndpoint</code> value.</p>\n <p>For external key stores with <code>XksProxyConnectivity</code> value of\n <code>VPC_ENDPOINT_SERVICE</code>, specify <code>https://</code> followed by the private DNS\n name of the VPC endpoint service.</p>\n <p>For external key stores with <code>PUBLIC_ENDPOINT</code> connectivity, this endpoint must\n be reachable before you create the custom key store. KMS connects to the external key store\n proxy while creating the custom key store. For external key stores with\n <code>VPC_ENDPOINT_SERVICE</code> connectivity, KMS connects when you call the <a>ConnectCustomKeyStore</a> operation.</p>\n <p>The value of this parameter must begin with <code>https://</code>. The remainder can\n contain upper and lower case letters (A-Z and a-z), numbers (0-9), dots (<code>.</code>), and\n hyphens (<code>-</code>). Additional slashes (<code>/</code> and <code>\\</code>) are not\n permitted.</p>\n <p>\n <b>Uniqueness requirements: </b>\n </p>\n <ul>\n <li>\n <p>The combined <code>XksProxyUriEndpoint</code> and <code>XksProxyUriPath</code> values\n must be unique in the Amazon Web Services account and Region.</p>\n </li>\n <li>\n <p>An external key store with <code>PUBLIC_ENDPOINT</code> connectivity cannot use the\n same <code>XksProxyUriEndpoint</code> value as an external key store with\n <code>VPC_ENDPOINT_SERVICE</code> connectivity in this Amazon Web Services Region.</p>\n </li>\n <li>\n <p>Each external key store with <code>VPC_ENDPOINT_SERVICE</code> connectivity must have\n its own private DNS name. The <code>XksProxyUriEndpoint</code> value for external key\n stores with <code>VPC_ENDPOINT_SERVICE</code> connectivity (private DNS name) must be\n unique in the Amazon Web Services account and Region.</p>\n </li>\n </ul>"
}
},
"XksProxyUriPath": {
"target": "com.amazonaws.kms#XksProxyUriPathType",
"traits": {
"smithy.api#documentation": "<p>Specifies the base path to the proxy APIs for this external key store. To find this value,\n see the documentation for your external key store proxy. This parameter is required for all\n custom key stores with a <code>CustomKeyStoreType</code> of\n <code>EXTERNAL_KEY_STORE</code>.</p>\n <p>The value must start with <code>/</code> and must end with <code>/kms/xks/v1</code> where\n <code>v1</code> represents the version of the KMS external key store proxy API. This path\n can include an optional prefix between the required elements such as\n <code>/<i>prefix</i>/kms/xks/v1</code>.</p>\n <p>\n <b>Uniqueness requirements: </b>\n </p>\n <ul>\n <li>\n <p>The combined <code>XksProxyUriEndpoint</code> and <code>XksProxyUriPath</code> values\n must be unique in the Amazon Web Services account and Region.</p>\n </li>\n </ul>"
}
},
"XksProxyVpcEndpointServiceName": {
"target": "com.amazonaws.kms#XksProxyVpcEndpointServiceNameType",
"traits": {
"smithy.api#documentation": "<p>Specifies the name of the Amazon VPC endpoint service for interface endpoints that is used to\n communicate with your external key store proxy (XKS proxy). This parameter is required when\n the value of <code>CustomKeyStoreType</code> is <code>EXTERNAL_KEY_STORE</code> and the value\n of <code>XksProxyConnectivity</code> is <code>VPC_ENDPOINT_SERVICE</code>.</p>\n <p>The Amazon VPC endpoint service must <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/create-xks-keystore.html#xks-requirements\">fulfill all\n requirements</a> for use with an external key store. </p>\n <p>\n <b>Uniqueness requirements:</b>\n </p>\n <ul>\n <li>\n <p>External key stores with <code>VPC_ENDPOINT_SERVICE</code> connectivity can share an\n Amazon VPC, but each external key store must have its own VPC endpoint service and private DNS\n name.</p>\n </li>\n </ul>"
}
},
"XksProxyAuthenticationCredential": {
"target": "com.amazonaws.kms#XksProxyAuthenticationCredentialType",
"traits": {
"smithy.api#documentation": "<p>Specifies an authentication credential for the external key store proxy (XKS proxy). This\n parameter is required for all custom key stores with a <code>CustomKeyStoreType</code> of\n <code>EXTERNAL_KEY_STORE</code>.</p>\n <p>The <code>XksProxyAuthenticationCredential</code> has two required elements:\n <code>RawSecretAccessKey</code>, a secret key, and <code>AccessKeyId</code>, a unique\n identifier for the <code>RawSecretAccessKey</code>. For character requirements, see <a href=\"API_XksProxyAuthenticationCredentialType.html\">XksProxyAuthenticationCredentialType</a>.</p>\n <p>KMS uses this authentication credential to sign requests to the external key store proxy\n on your behalf. This credential is unrelated to Identity and Access Management (IAM) and Amazon Web Services credentials.</p>\n <p>This parameter doesn't set or change the authentication credentials on the XKS proxy. It\n just tells KMS the credential that you established on your external key store proxy. If you\n rotate your proxy authentication credential, use the <a>UpdateCustomKeyStore</a>\n operation to provide the new credential to KMS.</p>"
}
},
"XksProxyConnectivity": {
"target": "com.amazonaws.kms#XksProxyConnectivityType",
"traits": {
"smithy.api#documentation": "<p>Indicates how KMS communicates with the external key store proxy. This parameter is\n required for custom key stores with a <code>CustomKeyStoreType</code> of\n <code>EXTERNAL_KEY_STORE</code>.</p>\n <p>If the external key store proxy uses a public endpoint, specify\n <code>PUBLIC_ENDPOINT</code>. If the external key store proxy uses a Amazon VPC\n endpoint service for communication with KMS, specify <code>VPC_ENDPOINT_SERVICE</code>. For\n help making this choice, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/choose-xks-connectivity.html\">Choosing a connectivity option</a> in\n the <i>Key Management Service Developer Guide</i>.</p>\n <p>An Amazon VPC endpoint service keeps your communication with KMS in a private address space\n entirely within Amazon Web Services, but it requires more configuration, including establishing a Amazon VPC with multiple subnets, a VPC endpoint service, a network load balancer, and a\n verified private DNS name. A public endpoint is simpler to set up, but it might be slower and\n might not fulfill your security requirements. You might consider testing with a public\n endpoint, and then establishing a VPC endpoint service for production tasks. Note that this\n choice does not determine the location of the external key store proxy. Even if you choose a\n VPC endpoint service, the proxy can be hosted within the VPC or outside of Amazon Web Services such as in\n your corporate data center.</p>"
}
}
},
"traits": {
"smithy.api#input": {}
}
},
"com.amazonaws.kms#CreateCustomKeyStoreResponse": {
"type": "structure",
"members": {
"CustomKeyStoreId": {
"target": "com.amazonaws.kms#CustomKeyStoreIdType",
"traits": {
"smithy.api#documentation": "<p>A unique identifier for the new custom key store.</p>"
}
}
},
"traits": {
"smithy.api#output": {}
}
},
"com.amazonaws.kms#CreateGrant": {
"type": "operation",
"input": {
"target": "com.amazonaws.kms#CreateGrantRequest"
},
"output": {
"target": "com.amazonaws.kms#CreateGrantResponse"
},
"errors": [
{
"target": "com.amazonaws.kms#DependencyTimeoutException"
},
{
"target": "com.amazonaws.kms#DisabledException"
},
{
"target": "com.amazonaws.kms#DryRunOperationException"
},
{
"target": "com.amazonaws.kms#InvalidArnException"
},
{
"target": "com.amazonaws.kms#InvalidGrantTokenException"
},
{
"target": "com.amazonaws.kms#KMSInternalException"
},
{
"target": "com.amazonaws.kms#KMSInvalidStateException"
},
{
"target": "com.amazonaws.kms#LimitExceededException"
},
{
"target": "com.amazonaws.kms#NotFoundException"
}
],
"traits": {
"smithy.api#documentation": "<p>Adds a grant to a KMS key. </p>\n <p>A <i>grant</i> is a policy instrument that allows Amazon Web Services principals to use\n KMS keys in cryptographic operations. It also can allow them to view a KMS key (<a>DescribeKey</a>) and create and manage grants. When authorizing access to a KMS key,\n grants are considered along with key policies and IAM policies. Grants are often used for\n temporary permissions because you can create one, use its permissions, and delete it without\n changing your key policies or IAM policies. </p>\n <p>For detailed information about grants, including grant terminology, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/grants.html\">Grants in KMS</a> in the\n <i>\n <i>Key Management Service Developer Guide</i>\n </i>. For examples of creating grants in several\n programming languages, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/example_kms_CreateGrant_section.html\">Use CreateGrant with an Amazon Web Services SDK or CLI</a>. </p>\n <p>The <code>CreateGrant</code> operation returns a <code>GrantToken</code> and a\n <code>GrantId</code>.</p>\n <ul>\n <li>\n <p>When you create, retire, or revoke a grant, there might be a brief delay, usually less than five minutes, until the grant is available throughout KMS. This state is known as <i>eventual consistency</i>. Once the grant has achieved eventual consistency, the grantee\n principal can use the permissions in the grant without identifying the grant. </p>\n <p>However, to use the permissions in the grant immediately, use the\n <code>GrantToken</code> that <code>CreateGrant</code> returns. For details, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/using-grant-token.html\">Using a grant\n token</a> in the <i>\n <i>Key Management Service Developer Guide</i>\n </i>.</p>\n </li>\n <li>\n <p>The <code>CreateGrant</code> operation also returns a <code>GrantId</code>. You can\n use the <code>GrantId</code> and a key identifier to identify the grant in the <a>RetireGrant</a> and <a>RevokeGrant</a> operations. To find the grant\n ID, use the <a>ListGrants</a> or <a>ListRetirableGrants</a>\n operations.</p>\n </li>\n </ul>\n <p>The KMS key that you use for this operation must be in a compatible key state. For\ndetails, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html\">Key states of KMS keys</a> in the <i>Key Management Service Developer Guide</i>.</p>\n <p>\n <b>Cross-account use</b>: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key\n ARN in the value of the <code>KeyId</code> parameter. </p>\n <p>\n <b>Required permissions</b>: <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html\">kms:CreateGrant</a> (key policy)</p>\n <p>\n <b>Related operations:</b>\n </p>\n <ul>\n <li>\n <p>\n <a>ListGrants</a>\n </p>\n </li>\n <li>\n <p>\n <a>ListRetirableGrants</a>\n </p>\n </li>\n <li>\n <p>\n <a>RetireGrant</a>\n </p>\n </li>\n <li>\n <p>\n <a>RevokeGrant</a>\n </p>\n </li>\n </ul>\n <p>\n <b>Eventual consistency</b>: The KMS API follows an eventual consistency model. \n For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency\">KMS eventual consistency</a>.</p>",
"smithy.api#examples": [
{
"title": "To create a grant",
"documentation": "The following example creates a grant that allows the specified IAM role to encrypt data with the specified KMS key.",
"input": {
"KeyId": "arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"Operations": [
"Encrypt",
"Decrypt"
]
},
"output": {
"GrantToken": "AQpAM2RhZTk1MGMyNTk2ZmZmMzEyYWVhOWViN2I1MWM4Mzc0MWFiYjc0ZDE1ODkyNGFlNTIzODZhMzgyZjBlNGY3NiKIAgEBAgB4Pa6VDCWW__MSrqnre1HIN0Grt00ViSSuUjhqOC8OT3YAAADfMIHcBgkqhkiG9w0BBwaggc4wgcsCAQAwgcUGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMmqLyBTAegIn9XlK5AgEQgIGXZQjkBcl1dykDdqZBUQ6L1OfUivQy7JVYO2-ZJP7m6f1g8GzV47HX5phdtONAP7K_HQIflcgpkoCqd_fUnE114mSmiagWkbQ5sqAVV3ov-VeqgrvMe5ZFEWLMSluvBAqdjHEdMIkHMlhlj4ENZbzBfo9Wxk8b8SnwP4kc4gGivedzFXo-dwN8fxjjq_ZZ9JFOj2ijIbj5FyogDCN0drOfi8RORSEuCEmPvjFRMFAwcmwFkN2NPp89amA",
"GrantId": "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60"
}
}
]
}
},
"com.amazonaws.kms#CreateGrantRequest": {
"type": "structure",
"members": {
"KeyId": {
"target": "com.amazonaws.kms#KeyIdType",
"traits": {
"smithy.api#documentation": "<p>Identifies the KMS key for the grant. The grant gives principals permission to use this\n KMS key.</p>\n <p>Specify the key ID or key ARN of the KMS key. To specify a KMS key in a\ndifferent Amazon Web Services account, you must use the key ARN.</p>\n <p>For example:</p>\n <ul>\n <li>\n <p>Key ID: <code>1234abcd-12ab-34cd-56ef-1234567890ab</code>\n </p>\n </li>\n <li>\n <p>Key ARN: <code>arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</code>\n </p>\n </li>\n </ul>\n <p>To get the key ID and key ARN for a KMS key, use <a>ListKeys</a> or <a>DescribeKey</a>.</p>",
"smithy.api#required": {}
}
},
"GranteePrincipal": {
"target": "com.amazonaws.kms#PrincipalIdType",
"traits": {
"smithy.api#documentation": "<p>The identity that gets the permissions specified in the grant.</p>\n <p>To specify the grantee principal, use the Amazon Resource Name (ARN) of an Amazon Web Services\n principal. Valid principals include Amazon Web Services accounts, IAM users, IAM roles,\n federated users, and assumed role users. For help with the ARN syntax for a principal, see\n <a href=\"https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns\">IAM ARNs</a> in the <i>\n <i>Identity and Access Management User Guide</i>\n </i>.</p>",
"smithy.api#required": {}
}
},
"RetiringPrincipal": {
"target": "com.amazonaws.kms#PrincipalIdType",
"traits": {
"smithy.api#documentation": "<p>The principal that has permission to use the <a>RetireGrant</a> operation to\n retire the grant. </p>\n <p>To specify the principal, use the <a href=\"https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html\">Amazon Resource Name (ARN)</a> of an\n Amazon Web Services principal. Valid principals include Amazon Web Services accounts, IAM users, IAM roles,\n federated users, and assumed role users. For help with the ARN syntax for a principal, see\n <a href=\"https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns\">IAM ARNs</a> in the <i>\n <i>Identity and Access Management User Guide</i>\n </i>.</p>\n <p>The grant determines the retiring principal. Other principals might have permission to\n retire the grant or revoke the grant. For details, see <a>RevokeGrant</a> and\n <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/grant-delete.html\">Retiring and revoking\n grants</a> in the <i>Key Management Service Developer Guide</i>. </p>"
}
},
"Operations": {
"target": "com.amazonaws.kms#GrantOperationList",
"traits": {
"smithy.api#documentation": "<p>A list of operations that the grant permits. </p>\n <p>This list must include only operations that are permitted in a grant. Also, the operation\n must be supported on the KMS key. For example, you cannot create a grant for a symmetric\n encryption KMS key that allows the <a>Sign</a> operation, or a grant for an\n asymmetric KMS key that allows the <a>GenerateDataKey</a> operation. If you try,\n KMS returns a <code>ValidationError</code> exception. For details, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations\">Grant\n operations</a> in the <i>Key Management Service Developer Guide</i>.</p>",
"smithy.api#required": {}
}
},
"Constraints": {
"target": "com.amazonaws.kms#GrantConstraints",
"traits": {
"smithy.api#documentation": "<p>Specifies a grant constraint.</p>\n <important>\n <p>Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.</p>\n </important>\n <p>KMS supports the <code>EncryptionContextEquals</code> and\n <code>EncryptionContextSubset</code> grant constraints, which allow the permissions in the\n grant only when the encryption context in the request matches\n (<code>EncryptionContextEquals</code>) or includes (<code>EncryptionContextSubset</code>)\n the encryption context specified in the constraint. </p>\n <p>The encryption context grant constraints are supported only on <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations\">grant operations</a> that include\n an <code>EncryptionContext</code> parameter, such as cryptographic operations on symmetric\n encryption KMS keys. Grants with grant constraints can include the <a>DescribeKey</a> and <a>RetireGrant</a> operations, but the constraint doesn't apply to these\n operations. If a grant with a grant constraint includes the <code>CreateGrant</code>\n operation, the constraint requires that any grants created with the <code>CreateGrant</code>\n permission have an equally strict or stricter encryption context constraint.</p>\n <p>You cannot use an encryption context grant constraint for cryptographic operations with\n asymmetric KMS keys or HMAC KMS keys. Operations with these keys don't support an encryption\n context.</p>\n <p>Each constraint value can include up to 8 encryption context pairs. The encryption context\n value in each constraint cannot exceed 384 characters. For information about grant\n constraints, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/create-grant-overview.html#grant-constraints\">Using grant\n constraints</a> in the <i>Key Management Service Developer Guide</i>. For more information about encryption context,\n see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context\">Encryption\n context</a> in the <i>\n <i>Key Management Service Developer Guide</i>\n </i>. </p>"
}
},
"GrantTokens": {
"target": "com.amazonaws.kms#GrantTokenList",
"traits": {
"smithy.api#documentation": "<p>A list of grant tokens. </p>\n <p>Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved <i>eventual consistency</i>. For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#grant_token\">Grant token</a> and <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/using-grant-token.html\">Using a grant token</a> in the\n <i>Key Management Service Developer Guide</i>.</p>"
}
},
"Name": {
"target": "com.amazonaws.kms#GrantNameType",
"traits": {
"smithy.api#documentation": "<p>A friendly name for the grant. Use this value to prevent the unintended creation of\n duplicate grants when retrying this request.</p>\n <important>\n <p>Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.</p>\n </important>\n <p>When this value is absent, all <code>CreateGrant</code> requests result in a new grant\n with a unique <code>GrantId</code> even if all the supplied parameters are identical. This can\n result in unintended duplicates when you retry the <code>CreateGrant</code> request.</p>\n <p>When this value is present, you can retry a <code>CreateGrant</code> request with\n identical parameters; if the grant already exists, the original <code>GrantId</code> is\n returned without creating a new grant. Note that the returned grant token is unique with every\n <code>CreateGrant</code> request, even when a duplicate <code>GrantId</code> is returned.\n All grant tokens for the same grant ID can be used interchangeably.</p>"
}
},
"DryRun": {
"target": "com.amazonaws.kms#NullableBooleanType",
"traits": {
"smithy.api#documentation": "<p>Checks if your request will succeed. <code>DryRun</code> is an optional parameter. </p>\n <p>To learn more about how to use this parameter, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/testing-permissions.html\">Testing your permissions</a> in the <i>Key Management Service Developer Guide</i>.</p>"
}
}
},
"traits": {
"smithy.api#input": {}
}
},
"com.amazonaws.kms#CreateGrantResponse": {
"type": "structure",
"members": {
"GrantToken": {
"target": "com.amazonaws.kms#GrantTokenType",
"traits": {
"smithy.api#documentation": "<p>The grant token.</p>\n <p>Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved <i>eventual consistency</i>. For more information, see <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#grant_token\">Grant token</a> and <a href=\"https://docs.aws.amazon.com/kms/latest/developerguide/using-grant-token.html\">Using a grant token</a> in the\n <i>Key Management Service Developer Guide</i>.</p>"
}
},
"GrantId": {
"target": "com.amazonaws.kms#GrantIdType",
"traits": {
"smithy.api#documentation": "<p>The unique identifier for the grant.</p>\n <p>You can use the <code>GrantId</code> in a <a>ListGrants</a>, <a>RetireGrant</a>, or <a>RevokeGrant</a> operation.</p>"
}
}
},
"traits": {
"smithy.api#output": {}
}
},
"com.amazonaws.kms#CreateKey": {
"type": "operation",
"input": {
"target": "com.amazonaws.kms#CreateKeyRequest"
},
"output": {
"target": "com.amazonaws.kms#CreateKeyResponse"
},
"errors": [
{
"target": "com.amazonaws.kms#CloudHsmClusterInvalidConfigurationException"
},
{
"target": "com.amazonaws.kms#CustomKeyStoreInvalidStateException"
},
{
"target": "com.amazonaws.kms#CustomKeyStoreNotFoundException"
},
{
"target": "com.amazonaws.kms#DependencyTimeoutException"
},
{
"target": "com.amazonaws.kms#InvalidArnException"
},
{
"target": "com.amazonaws.kms#KMSInternalException"
},
{
"target": "com.amazonaws.kms#LimitExceededException"
},
{
"target": "com.amazonaws.kms#MalformedPolicyDocumentException"
},
{
"target": "com.amazonaws.kms#TagException"
},
{
"target": "com.amazonaws.kms#UnsupportedOperationException"
},
{
"target": "com.amazonaws.kms#XksKeyAlreadyInUseException"
},