:doc:`KMS <../../kms>` / Client / put_key_policy

**************
put_key_policy
**************



.. py:method:: KMS.Client.put_key_policy(**kwargs)

  

  Attaches a key policy to the specified KMS key.

   

  For more information about key policies, see `Key Policies <https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html>`__ in the *Key Management Service Developer Guide*. For help writing and formatting a JSON policy document, see the `IAM JSON Policy Reference <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html>`__ in the *Identity and Access Management User Guide* . For examples of adding a key policy in multiple programming languages, see `Use PutKeyPolicy with an Amazon Web Services SDK or CLI <https://docs.aws.amazon.com/kms/latest/developerguide/example_kms_PutKeyPolicy_section.html>`__ in the *Key Management Service Developer Guide*.

   

  **Cross-account use**: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.

   

  **Required permissions**: `kms\:PutKeyPolicy <https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html>`__ (key policy)

   

  **Related operations**:  GetKeyPolicy

   

  **Eventual consistency**: The KMS API follows an eventual consistency model. For more information, see `KMS eventual consistency <https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/kms-2014-11-01/PutKeyPolicy>`_  


  **Request Syntax**
  ::

    response = client.put_key_policy(
        KeyId='string',
        PolicyName='string',
        Policy='string',
        BypassPolicyLockoutSafetyCheck=True|False
    )
    
  :type KeyId: string
  :param KeyId: **[REQUIRED]** 

    Sets the key policy on the specified KMS key.

     

    Specify the key ID or key ARN of the KMS key.

     

    For example:

     

    
    * Key ID: ``1234abcd-12ab-34cd-56ef-1234567890ab``
     
    * Key ARN: ``arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab``
    

     

    To get the key ID and key ARN for a KMS key, use  ListKeys or  DescribeKey.

    

  
  :type PolicyName: string
  :param PolicyName: 

    The name of the key policy. If no policy name is specified, the default value is ``default``. The only valid value is ``default``.

    

  
  :type Policy: string
  :param Policy: **[REQUIRED]** 

    The key policy to attach to the KMS key.

     

    The key policy must meet the following criteria:

     

    
    * The key policy must allow the calling principal to make a subsequent ``PutKeyPolicy`` request on the KMS key. This reduces the risk that the KMS key becomes unmanageable. For more information, see `Default key policy <https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#prevent-unmanageable-key>`__ in the *Key Management Service Developer Guide*. (To omit this condition, set ``BypassPolicyLockoutSafetyCheck`` to true.)
     
    * Each statement in the key policy must contain one or more principals. The principals in the key policy must exist and be visible to KMS. When you create a new Amazon Web Services principal, you might need to enforce a delay before including the new principal in a key policy because the new principal might not be immediately visible to KMS. For more information, see `Changes that I make are not always immediately visible <https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_general.html#troubleshoot_general_eventual-consistency>`__ in the *Amazon Web Services Identity and Access Management User Guide*.
    

     

    .. note::

      

      If either of the required ``Resource`` or ``Action`` elements are missing from a key policy statement, the policy statement has no effect. When a key policy statement is missing one of these elements, the KMS console correctly reports an error, but the ``PutKeyPolicy`` API request succeeds, even though the policy statement is ineffective.

       

      For more information on required key policy elements, see `Elements in a key policy <https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-overview.html#key-policy-elements>`__ in the *Key Management Service Developer Guide*.

      

     

    A key policy document can include only the following characters:

     

    
    * Printable ASCII characters from the space character ( ``\u0020``) through the end of the ASCII character range.
     
    * Printable characters in the Basic Latin and Latin-1 Supplement character set (through ``\u00FF``).
     
    * The tab ( ``\u0009``), line feed ( ``\u000A``), and carriage return ( ``\u000D``) special characters
    

     

    .. note::

      

      If the key policy exceeds the length constraint, KMS returns a ``LimitExceededException``.

      

     

    For information about key policies, see `Key policies in KMS <https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html>`__ in the *Key Management Service Developer Guide*.For help writing and formatting a JSON policy document, see the `IAM JSON Policy Reference <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html>`__ in the *Identity and Access Management User Guide* .

    

  
  :type BypassPolicyLockoutSafetyCheck: boolean
  :param BypassPolicyLockoutSafetyCheck: 

    Skips ("bypasses") the key policy lockout safety check. The default value is false.

     

    .. warning::

       

      Setting this value to true increases the risk that the KMS key becomes unmanageable. Do not set this value to true indiscriminately.

       

      For more information, see `Default key policy <https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#prevent-unmanageable-key>`__ in the *Key Management Service Developer Guide*.

       

     

    Use this parameter only when you intend to prevent the principal that is making the request from making a subsequent `PutKeyPolicy <https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html>`__ request on the KMS key.

    

  
  
  :returns: None
  **Exceptions**
  
  *   :py:class:`KMS.Client.exceptions.NotFoundException`

  
  *   :py:class:`KMS.Client.exceptions.InvalidArnException`

  
  *   :py:class:`KMS.Client.exceptions.MalformedPolicyDocumentException`

  
  *   :py:class:`KMS.Client.exceptions.DependencyTimeoutException`

  
  *   :py:class:`KMS.Client.exceptions.UnsupportedOperationException`

  
  *   :py:class:`KMS.Client.exceptions.KMSInternalException`

  
  *   :py:class:`KMS.Client.exceptions.LimitExceededException`

  
  *   :py:class:`KMS.Client.exceptions.KMSInvalidStateException`

  

  **Examples**

  The following example attaches a key policy to the specified KMS key.
  ::

    response = client.put_key_policy(
        # The identifier of the KMS key to attach the key policy to. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
        KeyId='1234abcd-12ab-34cd-56ef-1234567890ab',
        # The key policy document.
        Policy='{\n    "Version": "2012-10-17",\n    "Id": "custom-policy-2016-12-07",\n    "Statement": [\n        {\n            "Sid": "Enable IAM User Permissions",\n            "Effect": "Allow",\n            "Principal": {\n                "AWS": "arn:aws:iam::111122223333:root"\n            },\n            "Action": "kms:*",\n            "Resource": "*"\n        },\n        {\n            "Sid": "Allow access for Key Administrators",\n            "Effect": "Allow",\n            "Principal": {\n                "AWS": [\n                    "arn:aws:iam::111122223333:user/ExampleAdminUser",\n                    "arn:aws:iam::111122223333:role/ExampleAdminRole"\n                ]\n            },\n            "Action": [\n                "kms:Create*",\n                "kms:Describe*",\n                "kms:Enable*",\n                "kms:List*",\n                "kms:Put*",\n                "kms:Update*",\n                "kms:Revoke*",\n                "kms:Disable*",\n                "kms:Get*",\n                "kms:Delete*",\n                "kms:ScheduleKeyDeletion",\n                "kms:CancelKeyDeletion"\n            ],\n            "Resource": "*"\n        },\n        {\n            "Sid": "Allow use of the key",\n            "Effect": "Allow",\n            "Principal": {\n                "AWS": "arn:aws:iam::111122223333:role/ExamplePowerUserRole"\n            },\n            "Action": [\n                "kms:Encrypt",\n                "kms:Decrypt",\n                "kms:ReEncrypt*",\n                "kms:GenerateDataKey*",\n                "kms:DescribeKey"\n            ],\n            "Resource": "*"\n        },\n        {\n            "Sid": "Allow attachment of persistent resources",\n            "Effect": "Allow",\n            "Principal": {\n                "AWS": "arn:aws:iam::111122223333:role/ExamplePowerUserRole"\n            },\n            "Action": [\n                "kms:CreateGrant",\n                "kms:ListGrants",\n                "kms:RevokeGrant"\n            ],\n            "Resource": "*",\n            "Condition": {\n                "Bool": {\n                    "kms:GrantIsForAWSResource": "true"\n                }\n            }\n        }\n    ]\n}\n',
        # The name of the key policy.
        PolicyName='default',
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'ResponseMetadata': {
            '...': '...',
        },
    }

  