| 1 | |||
| 2 | package Paws::KMS::CreateKey; | ||
| 3 | use Moose; | ||
| 4 | has BypassPolicyLockoutSafetyCheck => (is => 'ro', isa => 'Bool'); | ||
| 5 | has CustomerMasterKeySpec => (is => 'ro', isa => 'Str'); | ||
| 6 | has CustomKeyStoreId => (is => 'ro', isa => 'Str'); | ||
| 7 | has Description => (is => 'ro', isa => 'Str'); | ||
| 8 | has KeyUsage => (is => 'ro', isa => 'Str'); | ||
| 9 | has MultiRegion => (is => 'ro', isa => 'Bool'); | ||
| 10 | has Origin => (is => 'ro', isa => 'Str'); | ||
| 11 | has Policy => (is => 'ro', isa => 'Str'); | ||
| 12 | has Tags => (is => 'ro', isa => 'ArrayRef[Paws::KMS::Tag]'); | ||
| 13 | |||
| 14 | use MooseX::ClassAttribute; | ||
| 15 | |||
| 16 | class_has _api_call => (isa => 'Str', is => 'ro', default => 'CreateKey'); | ||
| 17 | class_has _returns => (isa => 'Str', is => 'ro', default => 'Paws::KMS::CreateKeyResponse'); | ||
| 18 | class_has _result_key => (isa => 'Str', is => 'ro'); | ||
| 19 | 1; | ||
| 20 | |||
| 21 | ### main pod documentation begin ### | ||
| 22 | |||
| 23 | =head1 NAME | ||
| 24 | |||
| 25 | Paws::KMS::CreateKey - Arguments for method CreateKey on L<Paws::KMS> | ||
| 26 | |||
| 27 | =head1 DESCRIPTION | ||
| 28 | |||
| 29 | This class represents the parameters used for calling the method CreateKey on the | ||
| 30 | L<AWS Key Management Service|Paws::KMS> service. Use the attributes of this class | ||
| 31 | as arguments to method CreateKey. | ||
| 32 | |||
| 33 | You shouldn't make instances of this class. Each attribute should be used as a named argument in the call to CreateKey. | ||
| 34 | |||
| 35 | =head1 SYNOPSIS | ||
| 36 | |||
| 37 | my $kms = Paws->service('KMS'); | ||
| 38 | # To create a customer master key (CMK) | ||
| 39 | # The following example creates a CMK. | ||
| 40 | my $CreateKeyResponse = $kms->CreateKey( | ||
| 41 | 'Tags' => [ | ||
| 42 | |||
| 43 | { | ||
| 44 | 'TagKey' => 'CreatedBy', | ||
| 45 | 'TagValue' => 'ExampleUser' | ||
| 46 | } | ||
| 47 | ] | ||
| 48 | ); | ||
| 49 | |||
| 50 | # Results: | ||
| 51 | my $KeyMetadata = $CreateKeyResponse->KeyMetadata; | ||
| 52 | |||
| 53 | # Returns a L<Paws::KMS::CreateKeyResponse> object. | ||
| 54 | |||
| 55 | Values for attributes that are native types (Int, String, Float, etc) can passed as-is (scalar values). Values for complex Types (objects) can be passed as a HashRef. The keys and values of the hashref will be used to instance the underlying object. | ||
| 56 | For the AWS API documentation, see L<https://docs.aws.amazon.com/goto/WebAPI/kms/CreateKey> | ||
| 57 | |||
| 58 | =head1 ATTRIBUTES | ||
| 59 | |||
| 60 | |||
| 61 | =head2 BypassPolicyLockoutSafetyCheck => Bool | ||
| 62 | |||
| 63 | A flag to indicate whether to bypass the key policy lockout safety | ||
| 64 | check. | ||
| 65 | |||
| 66 | Setting this value to true increases the risk that the CMK becomes | ||
| 67 | unmanageable. Do not set this value to true indiscriminately. | ||
| 68 | |||
| 69 | For more information, refer to the scenario in the Default Key Policy | ||
| 70 | (https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-root-enable-iam) | ||
| 71 | section in the I< I<AWS Key Management Service Developer Guide> >. | ||
| 72 | |||
| 73 | Use this parameter only when you include a policy in the request and | ||
| 74 | you intend to prevent the principal that is making the request from | ||
| 75 | making a subsequent PutKeyPolicy request on the CMK. | ||
| 76 | |||
| 77 | The default value is false. | ||
| 78 | |||
| 79 | |||
| 80 | |||
| 81 | =head2 CustomerMasterKeySpec => Str | ||
| 82 | |||
| 83 | Specifies the type of CMK to create. The default value, | ||
| 84 | C<SYMMETRIC_DEFAULT>, creates a CMK with a 256-bit symmetric key for | ||
| 85 | encryption and decryption. For help choosing a key spec for your CMK, | ||
| 86 | see How to Choose Your CMK Configuration | ||
| 87 | (https://docs.aws.amazon.com/kms/latest/developerguide/symm-asymm-choose.html) | ||
| 88 | in the I<AWS Key Management Service Developer Guide>. | ||
| 89 | |||
| 90 | The C<CustomerMasterKeySpec> determines whether the CMK contains a | ||
| 91 | symmetric key or an asymmetric key pair. It also determines the | ||
| 92 | encryption algorithms or signing algorithms that the CMK supports. You | ||
| 93 | can't change the C<CustomerMasterKeySpec> after the CMK is created. To | ||
| 94 | further restrict the algorithms that can be used with the CMK, use a | ||
| 95 | condition key in its key policy or IAM policy. For more information, | ||
| 96 | see kms:EncryptionAlgorithm | ||
| 97 | (https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-encryption-algorithm) | ||
| 98 | or kms:Signing Algorithm | ||
| 99 | (https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-signing-algorithm) | ||
| 100 | in the I<AWS Key Management Service Developer Guide>. | ||
| 101 | |||
| 102 | AWS services that are integrated with AWS KMS | ||
| 103 | (http://aws.amazon.com/kms/features/#AWS_Service_Integration) use | ||
| 104 | symmetric CMKs to protect your data. These services do not support | ||
| 105 | asymmetric CMKs. For help determining whether a CMK is symmetric or | ||
| 106 | asymmetric, see Identifying Symmetric and Asymmetric CMKs | ||
| 107 | (https://docs.aws.amazon.com/kms/latest/developerguide/find-symm-asymm.html) | ||
| 108 | in the I<AWS Key Management Service Developer Guide>. | ||
| 109 | |||
| 110 | AWS KMS supports the following key specs for CMKs: | ||
| 111 | |||
| 112 | =over | ||
| 113 | |||
| 114 | =item * | ||
| 115 | |||
| 116 | Symmetric key (default) | ||
| 117 | |||
| 118 | =over | ||
| 119 | |||
| 120 | =item * | ||
| 121 | |||
| 122 | C<SYMMETRIC_DEFAULT> (AES-256-GCM) | ||
| 123 | |||
| 124 | =back | ||
| 125 | |||
| 126 | =item * | ||
| 127 | |||
| 128 | Asymmetric RSA key pairs | ||
| 129 | |||
| 130 | =over | ||
| 131 | |||
| 132 | =item * | ||
| 133 | |||
| 134 | C<RSA_2048> | ||
| 135 | |||
| 136 | =item * | ||
| 137 | |||
| 138 | C<RSA_3072> | ||
| 139 | |||
| 140 | =item * | ||
| 141 | |||
| 142 | C<RSA_4096> | ||
| 143 | |||
| 144 | =back | ||
| 145 | |||
| 146 | =item * | ||
| 147 | |||
| 148 | Asymmetric NIST-recommended elliptic curve key pairs | ||
| 149 | |||
| 150 | =over | ||
| 151 | |||
| 152 | =item * | ||
| 153 | |||
| 154 | C<ECC_NIST_P256> (secp256r1) | ||
| 155 | |||
| 156 | =item * | ||
| 157 | |||
| 158 | C<ECC_NIST_P384> (secp384r1) | ||
| 159 | |||
| 160 | =item * | ||
| 161 | |||
| 162 | C<ECC_NIST_P521> (secp521r1) | ||
| 163 | |||
| 164 | =back | ||
| 165 | |||
| 166 | =item * | ||
| 167 | |||
| 168 | Other asymmetric elliptic curve key pairs | ||
| 169 | |||
| 170 | =over | ||
| 171 | |||
| 172 | =item * | ||
| 173 | |||
| 174 | C<ECC_SECG_P256K1> (secp256k1), commonly used for cryptocurrencies. | ||
| 175 | |||
| 176 | =back | ||
| 177 | |||
| 178 | =back | ||
| 179 | |||
| 180 | |||
| 181 | Valid values are: C<"RSA_2048">, C<"RSA_3072">, C<"RSA_4096">, C<"ECC_NIST_P256">, C<"ECC_NIST_P384">, C<"ECC_NIST_P521">, C<"ECC_SECG_P256K1">, C<"SYMMETRIC_DEFAULT"> | ||
| 182 | |||
| 183 | =head2 CustomKeyStoreId => Str | ||
| 184 | |||
| 185 | Creates the CMK in the specified custom key store | ||
| 186 | (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html) | ||
| 187 | and the key material in its associated AWS CloudHSM cluster. To create | ||
| 188 | a CMK in a custom key store, you must also specify the C<Origin> | ||
| 189 | parameter with a value of C<AWS_CLOUDHSM>. The AWS CloudHSM cluster | ||
| 190 | that is associated with the custom key store must have at least two | ||
| 191 | active HSMs, each in a different Availability Zone in the Region. | ||
| 192 | |||
| 193 | This parameter is valid only for symmetric CMKs and regional CMKs. You | ||
| 194 | cannot create an asymmetric CMK or a multi-Region CMK in a custom key | ||
| 195 | store. | ||
| 196 | |||
| 197 | To find the ID of a custom key store, use the DescribeCustomKeyStores | ||
| 198 | operation. | ||
| 199 | |||
| 200 | The response includes the custom key store ID and the ID of the AWS | ||
| 201 | CloudHSM cluster. | ||
| 202 | |||
| 203 | This operation is part of the Custom Key Store feature | ||
| 204 | (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html) | ||
| 205 | feature in AWS KMS, which combines the convenience and extensive | ||
| 206 | integration of AWS KMS with the isolation and control of a | ||
| 207 | single-tenant key store. | ||
| 208 | |||
| 209 | |||
| 210 | |||
| 211 | =head2 Description => Str | ||
| 212 | |||
| 213 | A description of the CMK. | ||
| 214 | |||
| 215 | Use a description that helps you decide whether the CMK is appropriate | ||
| 216 | for a task. The default value is an empty string (no description). | ||
| 217 | |||
| 218 | |||
| 219 | |||
| 220 | =head2 KeyUsage => Str | ||
| 221 | |||
| 222 | Determines the cryptographic operations | ||
| 223 | (https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations) | ||
| 224 | for which you can use the CMK. The default value is C<ENCRYPT_DECRYPT>. | ||
| 225 | This parameter is required only for asymmetric CMKs. You can't change | ||
| 226 | the C<KeyUsage> value after the CMK is created. | ||
| 227 | |||
| 228 | Select only one valid value. | ||
| 229 | |||
| 230 | =over | ||
| 231 | |||
| 232 | =item * | ||
| 233 | |||
| 234 | For symmetric CMKs, omit the parameter or specify C<ENCRYPT_DECRYPT>. | ||
| 235 | |||
| 236 | =item * | ||
| 237 | |||
| 238 | For asymmetric CMKs with RSA key material, specify C<ENCRYPT_DECRYPT> | ||
| 239 | or C<SIGN_VERIFY>. | ||
| 240 | |||
| 241 | =item * | ||
| 242 | |||
| 243 | For asymmetric CMKs with ECC key material, specify C<SIGN_VERIFY>. | ||
| 244 | |||
| 245 | =back | ||
| 246 | |||
| 247 | |||
| 248 | Valid values are: C<"SIGN_VERIFY">, C<"ENCRYPT_DECRYPT"> | ||
| 249 | |||
| 250 | =head2 MultiRegion => Bool | ||
| 251 | |||
| 252 | Creates a multi-Region primary key that you can replicate into other | ||
| 253 | AWS Regions. You cannot change this value after you create the CMK. | ||
| 254 | |||
| 255 | For a multi-Region key, set this parameter to C<True>. For a | ||
| 256 | single-Region CMK, omit this parameter or set it to C<False>. The | ||
| 257 | default value is C<False>. | ||
| 258 | |||
| 259 | This operation supports I<multi-Region keys>, an AWS KMS feature that | ||
| 260 | lets you create multiple interoperable CMKs in different AWS Regions. | ||
| 261 | Because these CMKs have the same key ID, key material, and other | ||
| 262 | metadata, you can use them to encrypt data in one AWS Region and | ||
| 263 | decrypt it in a different AWS Region without making a cross-Region call | ||
| 264 | or exposing the plaintext data. For more information about multi-Region | ||
| 265 | keys, see Using multi-Region keys | ||
| 266 | (https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) | ||
| 267 | in the I<AWS Key Management Service Developer Guide>. | ||
| 268 | |||
| 269 | This value creates a I<primary key>, not a replica. To create a | ||
| 270 | I<replica key>, use the ReplicateKey operation. | ||
| 271 | |||
| 272 | You can create a symmetric or asymmetric multi-Region CMK, and you can | ||
| 273 | create a multi-Region CMK with imported key material. However, you | ||
| 274 | cannot create a multi-Region CMK in a custom key store. | ||
| 275 | |||
| 276 | |||
| 277 | |||
| 278 | =head2 Origin => Str | ||
| 279 | |||
| 280 | The source of the key material for the CMK. You cannot change the | ||
| 281 | origin after you create the CMK. The default is C<AWS_KMS>, which means | ||
| 282 | that AWS KMS creates the key material. | ||
| 283 | |||
| 284 | To create a CMK with no key material (for imported key material), set | ||
| 285 | the value to C<EXTERNAL>. For more information about importing key | ||
| 286 | material into AWS KMS, see Importing Key Material | ||
| 287 | (https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html) | ||
| 288 | in the I<AWS Key Management Service Developer Guide>. This value is | ||
| 289 | valid only for symmetric CMKs. | ||
| 290 | |||
| 291 | To create a CMK in an AWS KMS custom key store | ||
| 292 | (https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html) | ||
| 293 | and create its key material in the associated AWS CloudHSM cluster, set | ||
| 294 | this value to C<AWS_CLOUDHSM>. You must also use the | ||
| 295 | C<CustomKeyStoreId> parameter to identify the custom key store. This | ||
| 296 | value is valid only for symmetric CMKs. | ||
| 297 | |||
| 298 | Valid values are: C<"AWS_KMS">, C<"EXTERNAL">, C<"AWS_CLOUDHSM"> | ||
| 299 | |||
| 300 | =head2 Policy => Str | ||
| 301 | |||
| 302 | The key policy to attach to the CMK. | ||
| 303 | |||
| 304 | If you provide a key policy, it must meet the following criteria: | ||
| 305 | |||
| 306 | =over | ||
| 307 | |||
| 308 | =item * | ||
| 309 | |||
| 310 | If you don't set C<BypassPolicyLockoutSafetyCheck> to true, the key | ||
| 311 | policy must allow the principal that is making the C<CreateKey> request | ||
| 312 | to make a subsequent PutKeyPolicy request on the CMK. This reduces the | ||
| 313 | risk that the CMK becomes unmanageable. For more information, refer to | ||
| 314 | the scenario in the Default Key Policy | ||
| 315 | (https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-root-enable-iam) | ||
| 316 | section of the I< I<AWS Key Management Service Developer Guide> >. | ||
| 317 | |||
| 318 | =item * | ||
| 319 | |||
| 320 | Each statement in the key policy must contain one or more principals. | ||
| 321 | The principals in the key policy must exist and be visible to AWS KMS. | ||
| 322 | When you create a new AWS principal (for example, an IAM user or role), | ||
| 323 | you might need to enforce a delay before including the new principal in | ||
| 324 | a key policy because the new principal might not be immediately visible | ||
| 325 | to AWS KMS. For more information, see Changes that I make are not | ||
| 326 | always immediately visible | ||
| 327 | (https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_general.html#troubleshoot_general_eventual-consistency) | ||
| 328 | in the I<AWS Identity and Access Management User Guide>. | ||
| 329 | |||
| 330 | =back | ||
| 331 | |||
| 332 | If you do not provide a key policy, AWS KMS attaches a default key | ||
| 333 | policy to the CMK. For more information, see Default Key Policy | ||
| 334 | (https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default) | ||
| 335 | in the I<AWS Key Management Service Developer Guide>. | ||
| 336 | |||
| 337 | The key policy size quota is 32 kilobytes (32768 bytes). | ||
| 338 | |||
| 339 | For help writing and formatting a JSON policy document, see the IAM | ||
| 340 | JSON Policy Reference | ||
| 341 | (https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) | ||
| 342 | in the I< I<IAM User Guide> >. | ||
| 343 | |||
| 344 | |||
| 345 | |||
| 346 | =head2 Tags => ArrayRef[L<Paws::KMS::Tag>] | ||
| 347 | |||
| 348 | Assigns one or more tags to the CMK. Use this parameter to tag the CMK | ||
| 349 | when it is created. To tag an existing CMK, use the TagResource | ||
| 350 | operation. | ||
| 351 | |||
| 352 | Tagging or untagging a CMK can allow or deny permission to the CMK. For | ||
| 353 | details, see Using ABAC in AWS KMS | ||
| 354 | (https://docs.aws.amazon.com/kms/latest/developerguide/abac.html) in | ||
| 355 | the I<AWS Key Management Service Developer Guide>. | ||
| 356 | |||
| 357 | To use this parameter, you must have kms:TagResource | ||
| 358 | (https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html) | ||
| 359 | permission in an IAM policy. | ||
| 360 | |||
| 361 | Each tag consists of a tag key and a tag value. Both the tag key and | ||
| 362 | the tag value are required, but the tag value can be an empty (null) | ||
| 363 | string. You cannot have more than one tag on a CMK with the same tag | ||
| 364 | key. If you specify an existing tag key with a different tag value, AWS | ||
| 365 | KMS replaces the current tag value with the specified one. | ||
| 366 | |||
| 367 | When you assign tags to an AWS resource, AWS generates a cost | ||
| 368 | allocation report with usage and costs aggregated by tags. Tags can | ||
| 369 | also be used to control access to a CMK. For details, see Tagging Keys | ||
| 370 | (https://docs.aws.amazon.com/kms/latest/developerguide/tagging-keys.html). | ||
| 371 | |||
| 372 | |||
| 373 | |||
| 374 | |||
| 375 | =head1 SEE ALSO | ||
| 376 | |||
| 377 | This class forms part of L<Paws>, documenting arguments for method CreateKey in L<Paws::KMS> | ||
| 378 | |||
| 379 | =head1 BUGS and CONTRIBUTIONS | ||
| 380 | |||
| 381 | The source code is located here: L<https://github.com/pplu/aws-sdk-perl> | ||
| 382 | |||
| 383 | Please report bugs to: L<https://github.com/pplu/aws-sdk-perl/issues> | ||
| 384 | |||
| 385 | =cut | ||
| 386 |