AWS KMS ejemplos que utilizan AWS CLI

Para cancelar la eliminación programada de una clave de KMS administrada por el cliente

En el siguiente ejemplo de cancel-key-deletion se cancela la eliminación programada de una clave de KMS administrada por el cliente.

aws kms cancel-key-deletion \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}

Cuando el comando cancel-key-deletion se ejecuta correctamente, se cancela la eliminación programada. Sin embargo, el estado de la clave de KMS es Disabled, por lo que no puede usar la clave de KMS en operaciones criptográficas. Para restaurar su funcionalidad, utilice el comando enable-key.

Para obtener más información, consulte Scheduling and canceling key deletion en la Guía para desarrolladores de AWS Key Management Service.

Para conectar un almacén de claves personalizado

En el siguiente ejemplo de connect-custom-key-store se vuelve a conectar el almacén de claves personalizado especificado. Puede utilizar un comando como este para conectar un almacén de claves personalizado por primera vez o para volver a conectar un almacén de claves que estaba desconectado.

Puede usar este comando para conectar un almacén de claves de AWS CloudHSM o un almacén de claves externo.

aws kms connect-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

El comando no devuelve ningún resultado. Para comprobar que se aplicó el comando, utilice el comando describe-custom-key-stores.

Para obtener información sobre cómo conectar un almacén de claves de AWS CloudHSM, consulte Conexión y desconexión de un almacén de claves de AWS CloudHSM en la Guía para desarrolladores de Key Management Service.AWS

Para obtener información sobre cómo conectar un almacén de claves externo, consulte Connecting and disconnecting an external key store en la Guía para desarrolladores de AWS Key Management Service.

Creación de un alias de una clave de KMS

El siguiente comando create-alias crea un alias llamado example-alias de la clave de KMS identificada por el ID de clave 1234abcd-12ab-34cd-56ef-1234567890ab.

Los nombres del alias no debe empezar por alias/. No utilice nombres de alias que comiencen poralias/aws; están reservados para su uso exclusivo AWS.

aws kms create-alias \
    --alias-name alias/example-alias \
    --target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no devuelve ningún resultado. Para ver el nuevo alias, utilice el comando list-aliases.

Para obtener más información, consulte Uso de alias en la AWS Guía para desarrolladores de Key Management Service.

Ejemplo 1: Para crear un almacén de AWS claves CloudHSM

En el siguiente create-custom-key-store ejemplo, se crea un almacén de claves de AWS CloudHSM respaldado por un clúster de AWS CloudHSM con los parámetros necesarios. También puede añadir el custom-key-store-type``parameter with the default value: ``AWS_CLOUDHSM.

Para especificar la entrada de archivo para el trust-anchor-certificate comando en la AWS CLI, se requiere el file:// prefijo.

aws kms create-custom-key-store \
    --custom-key-store-name ExampleCloudHSMKeyStore \
    --cloud-hsm-cluster-id cluster-1a23b4cdefg \
    --key-store-password kmsPswd \
    --trust-anchor-certificate file://customerCA.crt

Salida:

{
    "CustomKeyStoreId": cks-1234567890abcdef0
}

Para obtener más información, consulte Creación de un almacén de claves de AWS CloudHSM en AWS la Guía para desarrolladores de Key Management Service.

Ejemplo 2: crear un almacén de claves externo con conectividad a puntos de conexión públicos

En el siguiente create-custom-key-store ejemplo, se crea un almacén de claves externo (XKS) que se comunica con AWS KMS a través de Internet.

En este ejemplo, la XksProxyUriPath utiliza un prefijo opcional de example-prefix.

NOTA: Si utiliza la versión 1.0 de AWS CLI, ejecute el siguiente comando antes de especificar un parámetro con un valor HTTP o HTTPS, como el XksProxyUriEndpoint parámetro.

aws configure set cli_follow_urlparam false

De lo contrario, la versión 1.0 de AWS CLI reemplaza el valor del parámetro por el contenido que se encuentra en esa dirección URI.

aws kms create-custom-key-store \
    --custom-key-store-name ExamplePublicEndpointXKS \
    --custom-key-store-type EXTERNAL_KEY_STORE \
    --xks-proxy-connectivity PUBLIC_ENDPOINT \
    --xks-proxy-uri-endpoint "https://myproxy.xks.example.com" \
    --xks-proxy-uri-path "/example-prefix/kms/xks/v1" \
    --xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="

Salida:

{
    "CustomKeyStoreId": cks-2234567890abcdef0
}

Para obtener más información, consulte Creating an external key store en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 3: crear un almacén de claves externo con conectividad a servicio de puntos de conexión de VPC

En el siguiente create-custom-key-store ejemplo, se crea un almacén de claves externo (XKS) que utiliza un servicio de punto final de Amazon VPC para comunicarse con AWS KMS.

NOTA: Si utiliza la versión 1.0 de AWS CLI, ejecute el siguiente comando antes de especificar un parámetro con un valor HTTP o HTTPS, como el XksProxyUriEndpoint parámetro.

aws configure set cli_follow_urlparam false

De lo contrario, la versión 1.0 de AWS CLI reemplaza el valor del parámetro por el contenido que se encuentra en esa dirección URI.

aws kms create-custom-key-store \
    --custom-key-store-name ExampleVPCEndpointXKS \
    --custom-key-store-type EXTERNAL_KEY_STORE \
    --xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
    --xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
    --xks-proxy-uri-path "/kms/xks/v1" \
    --xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example1" \
    --xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="

Salida:

{
    "CustomKeyStoreId": cks-3234567890abcdef0
}

Para obtener más información, consulte Creating an external key store en la Guía para desarrolladores de AWS Key Management Service.

Creación de una concesión

En el siguiente ejemplo de create-grant se crea una concesión que permite al usuario exampleUser utilizar el comando decrypt de la clave de KMS del ejemplo 1234abcd-12ab-34cd-56ef-1234567890ab. La entidad principal que se va a dar de baja es el rol adminRole. La concesión utiliza la limitación de concesión EncryptionContextSubset para permitir este permiso solo cuando el contexto de cifrado de la solicitud decrypt incluye un par clave-valor "Department": "IT".

aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::123456789012:user/exampleUser \
    --operations Decrypt \
    --constraints EncryptionContextSubset={Department=IT} \
    --retiring-principal arn:aws:iam::123456789012:role/adminRole

Salida:

{
    "GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
    "GrantToken": "<grant token here>"
}

Para ver información detallada sobre la concesión, utilice el comando list-grants.

Para obtener más información, consulte las concesiones en AWS KMS en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Para crear una clave de KMS administrada por el cliente en AWS KMS

En el siguiente ejemplo create-key se crea una clave de KMS de cifrado simétrico.

Para crear la clave de KMS básica, una clave de cifrado simétrica, no es necesario especificar ningún parámetro. Los valores predeterminados de esos parámetros crean una clave de cifrado simétrica.

Puesto que este comando no especifica una política de claves, la clave de KMS obtiene la política de claves predeterminada para las claves de KMS creadas mediante programación. Utilice el comando get-key-policy para ver la política de claves. Utilice el comando put-key-policy para cambiar la política de claves.

aws kms create-key

El comando create-key devuelve los metadatos de la clave, incluidos el ID de la clave y el ARN de la nueva clave de KMS. Puede usar estos valores para identificar la clave de KMS en otras operaciones de AWS KMS. La salida no incluye las etiquetas. Para ver las etiquetas de una clave de KMS, utilice list-resource-tags command.

Salida:

{
    "KeyMetadata": {
        "AWSAccountId": "111122223333",
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "CreationDate": "2017-07-05T14:04:55-07:00",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "AWS_KMS"
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

Nota: El comando create-key no permite especificar un alias. Para crear un alias para la nueva clave de KMS, utilice el comando create-alias.

Para obtener más información, consulte Creación de claves en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 2: Creación de una clave KMS de RSA asimétrica para el cifrado y el descifrado

El siguiente ejemplo de create-key se crea una clave de KMS que incluye un par de claves asimétricas RSA para el cifrado y el descifrado. No se puede cambiar la especificación de clave y el uso de la clave después de crear la clave:

aws kms create-key \
   --key-spec RSA_4096 \
   --key-usage ENCRYPT_DECRYPT

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2021-04-05T14:04:55-07:00",
        "CustomerMasterKeySpec": "RSA_4096",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
            "RSAES_OAEP_SHA_1",
            "RSAES_OAEP_SHA_256"
        ],
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "RSA_4096",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "AWS_KMS"
    }
}

Para obtener más información, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 3: creación de una clave de KMS asimétrica de curva elíptica para la firma y la verificación

Creación de una clave de KMS asimétrica que contenga un par de claves asimétricas de curva elíptica (ECC) para la firma y la verificación. El parámetro --key-usage es obligatorio aunque SIGN_VERIFY sea el único valor válido para las claves KMS de ECC. No se puede cambiar la especificación de clave y el uso de la clave después de crear la clave:

aws kms create-key \
    --key-spec ECC_NIST_P521 \
    --key-usage SIGN_VERIFY

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2019-12-02T07:48:55-07:00",
        "CustomerMasterKeySpec": "ECC_NIST_P521",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "ECC_NIST_P521",
        "KeyState": "Enabled",
        "KeyUsage": "SIGN_VERIFY",
        "MultiRegion": false,
        "Origin": "AWS_KMS",
        "SigningAlgorithms": [
            "ECDSA_SHA_512"
        ]
    }
}

Para obtener más información, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 4: Creación de una clave de KMS ML-DSA asimétrica para la firma y la verificación

En este ejemplo, se crea una clave de algoritmo de firma digital de module-lattice (ML-DSA) para la firma y la verificación. El parámetro de clave de uso es obligatorio aunque SIGN_VERIFY sea el único valor válido para las claves de ML-DSA.

aws kms create-key \
    --key-spec ML_DSA_65 \
    --key-usage SIGN_VERIFY

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2019-12-02T07:48:55-07:00",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "ML_DSA_65",
        "KeyState": "Enabled",
        "KeyUsage": "SIGN_VERIFY",
        "MultiRegion": false,
        "Origin": "AWS_KMS",
        "SigningAlgorithms": [
            "ML_DSA_SHAKE_256"
        ]
    }
}

Para obtener más información, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 5: Creación de una clave de KMS HMAC

En el siguiente ejemplo de create-key se crea una clave de KMS HMAC de 384 bits. El valor GENERATE_VERIFY_MAC del parámetro --key-usage es obligatorio aunque sea el único valor válido para las claves KMS HMAC.

aws kms create-key \
    --key-spec HMAC_384 \
    --key-usage GENERATE_VERIFY_MAC

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2022-04-05T14:04:55-07:00",
        "CustomerMasterKeySpec": "HMAC_384",
        "Description": "",
        "Enabled": true,
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "HMAC_384",
        "KeyState": "Enabled",
        "KeyUsage": "GENERATE_VERIFY_MAC",
        "MacAlgorithms": [
            "HMAC_SHA_384"
        ],
        "MultiRegion": false,
        "Origin": "AWS_KMS"
    }
}

Para obtener más información, consulte las claves HMAC en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 6: Creación de una clave de KMS principal de varias regiones

En el siguiente ejemplo de create-key se crea una clave principal de cifrado simétrica de varias regiones. Puesto que los valores predeterminados de todos los parámetros crean una clave de cifrado simétrica, solo es necesario el parámetro --multi-region para esta clave de KMS. En la AWS CLI, para indicar que un parámetro booleano es verdadero, simplemente especifique el nombre del parámetro.

aws kms create-key \
    --multi-region

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2021-09-02T016:15:21-09:00",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
          "SYMMETRIC_DEFAULT"
        ],
        "KeyId": "mrk-1234abcd12ab34cd56ef12345678990ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": true,
        "MultiRegionConfiguration": {
            "MultiRegionKeyType": "PRIMARY",
            "PrimaryKey": {
                "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab",
                "Region": "us-west-2"
            },
            "ReplicaKeys": []
        },
        "Origin": "AWS_KMS"
    }
}

Para obtener más información, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del servicio de administración de AWS claves.

Ejemplo 7: Creación de una clave de KMS para material de claves importado

En el siguiente ejemplo de create-key se crea una clave de KMS sin material de claves. Cuando se complete la operación, puede importar su propio material de claves en la clave de KMS. Para crear esta clave de KMS, establezca el parámetro --origin en EXTERNAL.

aws kms create-key \
    --origin EXTERNAL

Salida:

{
     "KeyMetadata": {
         "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
         "AWSAccountId": "111122223333",
         "CreationDate": "2019-12-02T07:48:55-07:00",
         "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
         "Description": "",
         "Enabled": false,
         "EncryptionAlgorithms": [
             "SYMMETRIC_DEFAULT"
         ],
         "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
         "KeyManager": "CUSTOMER",
         "KeySpec": "SYMMETRIC_DEFAULT",
         "KeyState": "PendingImport",
         "KeyUsage": "ENCRYPT_DECRYPT",
         "MultiRegion": false,
         "Origin": "EXTERNAL"
     }
 }

Para obtener más información, consulte Importación de material clave en claves de AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 6: Para crear una clave KMS en un almacén de claves de AWS CloudHSM

En el siguiente create-key ejemplo, se crea una clave KMS en el almacén de claves de AWS CloudHSM especificado. La operación crea la clave de KMS y sus metadatos en AWS KMS y crea el material de claves en el clúster de AWS CloudHSM asociado al almacén de claves personalizado. Los parámetros --custom-key-store-id y --origin son obligatorios.

aws kms create-key \
    --origin AWS_CLOUDHSM \
    --custom-key-store-id cks-1234567890abcdef0

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CloudHsmClusterId": "cluster-1a23b4cdefg",
        "CreationDate": "2019-12-02T07:48:55-07:00",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "CustomKeyStoreId": "cks-1234567890abcdef0",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "AWS_CLOUDHSM"
    }
}

Para obtener más información, consulte Almacenes de claves de AWS CloudHSM en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 8: Creación de una clave de KMS en un almacén de claves externo

En el siguiente ejemplo de create-key se crea una clave de KMS en el almacén de claves externo especificado. Los parámetros --custom-key-store-id, --origin y --xks-key-id son obligatorios en este comando.

El parámetro --xks-key-id especifica el ID de una clave de cifrado simétrica existente en el administrador de claves externo. Esta clave sirve como material de clave externa para la clave de KMS. El valor del parámetro --origin debe ser EXTERNAL_KEY_STORE. El parámetro custom-key-store-id debe identificar un almacén de claves externo que esté conectado a su proxy de almacén de claves externo.

aws kms create-key \
    --origin EXTERNAL_KEY_STORE \
    --custom-key-store-id cks-9876543210fedcba9 \
    --xks-key-id bb8562717f809024

Salida:

{
    "KeyMetadata": {
        "Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "AWSAccountId": "111122223333",
        "CreationDate": "2022-12-02T07:48:55-07:00",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "CustomKeyStoreId": "cks-9876543210fedcba9",
        "Description": "",
        "Enabled": true,
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "MultiRegion": false,
        "Origin": "EXTERNAL_KEY_STORE",
        "XksKeyConfiguration": {
            "Id": "bb8562717f809024"
        }
    }
}

Para obtener más información, consulte Almacenes de claves externos en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Descifrado de un mensaje cifrado con una clave de KMS simétrica (Linux y macOS)

El siguiente ejemplo de decrypt comando muestra la forma recomendada de descifrar datos con la AWS CLI. Esta versión muestra cómo descifrar los datos en una clave de KMS simétrica.

Proporcione el texto cifrado de un archivo. En el valor del parámetro --ciphertext-blob, utilice el prefijo fileb://, que indica a la CLI que lea los datos de un archivo binario. Si el archivo no se encuentra en el directorio actual, escriba la ruta completa al archivo. Para obtener más información sobre la lectura de los valores de los parámetros AWS CLI de un archivo, consulte Carga de parámetros AWS CLI desde un archivo < https://docs.aws.amazon.com/cli/ latest/userguide/cli - usage-parameters-file .html> en la Guía del usuario de la interfaz de línea de AWS comandos y Prácticas recomendadas para los parámetros de archivos locales< https://aws.amazon.com/blogs/ developer/ best-practices-for-local -file-parameters/> en el blog de herramientas de línea de AWS comandos. Especifique la clave KMS para descifrar el texto cifrado. El parámetro no es necesario cuando se descifra con una clave KMS simétrica. --key-id AWS KMS puede obtener el identificador de clave de la clave KMS que se utilizó para cifrar los datos de los metadatos del texto cifrado. Pero siempre es una práctica recomendada especificar la clave KMS que está utilizando. Esta práctica garantiza que utilice la clave de KMS pretendida y le impide descifrar inadvertidamente un texto cifrado mediante una clave de KMS en la que no confía. Solicite la salida de texto sin formato como valor de texto. El parámetro --query indica a la CLI que obtenga únicamente el valor del campo Plaintext de la salida. El parámetro --output devuelve la salida como texto. Decodifique en base64 el texto sin formato y guárdelo en un archivo. El siguiente ejemplo canaliza (|) el valor del parámetro Plaintext a la utilidad Base64, que lo decodifica. A continuación, redirige (>) la salida descodificada al archivo ExamplePlaintext.

Antes de ejecutar este comando, sustituya el identificador de clave de ejemplo por un identificador de clave válido de su cuenta. AWS

aws kms decrypt \
    --ciphertext-blob fileb://ExampleEncryptedFile \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --output text \
    --query Plaintext | base64 \
    --decode > ExamplePlaintextFile

Este comando no genera ninguna salida. La salida del comando decrypt se descodifica en base64 y se guarda en un archivo.

Para obtener más información, consulte Decrypt en la Referencia de la API de AWS Key Management Service.

Ejemplo 2: Descifrado de un mensaje cifrado con una clave de KMS simétrica (símbolo del sistema de Windows)

El ejemplo siguiente es el mismo que el anterior, excepto que usa la utilidad certutil para descodificar en Base64 los datos de texto sin formato. Como se muestra en los siguientes ejemplos, este procedimiento requiere dos comandos.

Antes de ejecutar este comando, sustituya el identificador de clave de ejemplo por un identificador de clave válido de su AWS cuenta.

aws kms decrypt ^
    --ciphertext-blob fileb://ExampleEncryptedFile ^
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
    --output text ^
    --query Plaintext > ExamplePlaintextFile.base64

Ejecute el comando certutil.

certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile

Salida:

Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

Para obtener más información, consulte Descifrado en la AWS Referencia de la API de Key Management Service.

Ejemplo 3: descifrado de un mensaje cifrado con una clave de KMS asimétrica (Linux y macOS)

El siguiente comando decrypt de ejemplo muestra cómo descifrar los datos cifrados con una clave KMS de RSA asimétrica.

Cuando se utiliza una clave de KMS asimétrica, es obligatorio el parámetro encryption-algorithm, que especifica el algoritmo que se utiliza para cifrar el texto sin formato.

Antes de ejecutar este comando, sustituya el identificador de clave de ejemplo por un identificador de clave válido de su AWS cuenta.

aws kms decrypt \
    --ciphertext-blob fileb://ExampleEncryptedFile \
    --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --encryption-algorithm RSAES_OAEP_SHA_256 \
    --output text \
    --query Plaintext | base64 \
    --decode > ExamplePlaintextFile

Este comando no genera ninguna salida. La salida del comando decrypt se descodifica en base64 y se guarda en un archivo.

Para obtener más información, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del servicio de administración de AWS claves.

Para eliminar un alias de AWS KMS

En el siguiente ejemplo de delete-alias se elimina el alias alias/example-alias. El nombre de alias debe empezar por alias/.

aws kms delete-alias \
    --alias-name alias/example-alias

Este comando no genera ninguna salida. Utilice el comando list-aliases para encontrar el alias.

Para obtener más información, consulte Eliminación de un alias en la Guía para desarrolladores de AWS Key Management Service.

Para eliminar un almacén de claves personalizado

En el siguiente ejemplo de delete-custom-key-store se elimina el almacén de claves personalizado especificado.

La eliminación de un almacén de claves de AWS CloudHSM no afecta al clúster de CloudHSM asociado. La eliminación de un almacén de claves externo no afecta al proxy del almacén de claves externo asociado, al administrador de claves externo ni a las claves externas.

NOTA: Para poder eliminar un almacén de claves personalizado debe programar la eliminación de todas las claves de KMS del almacén de claves personalizado y, a continuación, esperar a que se eliminen esas claves de KMS. Seguidamente debe desconectar el almacén de claves personalizado. Para obtener ayuda para encontrar las claves de KMS en su almacén de claves personalizado, consulte Eliminar un almacén de claves (API) de AWS CloudHSM en AWS la Guía para desarrolladores de Key Management Service.

delete-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

El comando no devuelve ningún resultado. Para comprobar que el almacén de claves personalizado se ha eliminado, utilice el comando describe-custom-key-stores.

Para obtener información sobre cómo eliminar un almacén de claves de AWS CloudHSM, consulte Eliminar un almacén de claves de AWS CloudHSM en la Guía para desarrolladores de Key Management Service.AWS

Para obtener información sobre cómo eliminar almacenes de claves externos, consulte Deleting an external key store en la Guía para desarrolladores de AWS Key Management Service.

Para eliminar material de claves importado de una clave de KMS

En el siguiente ejemplo de delete-imported-key-material se elimina material de claves que se ha importado a una clave de KMS.

aws kms delete-imported-key-material \
   --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

Para obtener más información, consulte Eliminación de material de claves importado en la Guía para desarrolladores de AWS Key Management Service.

Para generar un secreto compartido

En el siguiente ejemplo de derive-shared-secret se genera un secreto compartido mediante un algoritmo de acuerdo de claves.

Debe utilizar una curva elíptica (ECC) asimétrica recomendada por el NIST o un key pair de claves KMS (solo para regiones de SM2 China) con un KeyUsage valor de to call. KEY_AGREEMENT DeriveSharedSecret

aws kms derive-shared-secret \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-agreement-algorithm ECDH \
    --public-key "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nKwgouaHbBWNJYjP5VutbbkKS4Kv4GojwZBJyHN17kmxo8yTjRmjR15SKIQ8cqRA2uaERMLnpztIXdZp232PQPbWGxDyXYJ0aJ5EFSag"

Salida:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "SharedSecret": "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG",
    "KeyAgreementAlgorithm": "ECDH",
    "KeyOrigin": "AWS_KMS"
}

Para obtener más información, consulte la referencia de la API del DeriveSharedSecretServicio de administración de AWS claves.

Ejemplo 1: Para obtener detalles sobre un almacén de claves de AWS CloudHSM

En el siguiente describe-custom-key-store ejemplo, se muestran detalles sobre el almacén de claves de AWS CloudHSM especificado. El comando es el mismo para todos los tipos de almacenes de claves personalizados, pero el resultado difiere según el tipo de almacén de claves y, en el caso de un almacén de claves externo, su opción de conectividad.

De forma predeterminada, este comando muestra información acerca de todos los almacenes de claves personalizados de la cuenta y la región. Para mostrar información sobre un almacén de claves personalizado concreto, utilice el parámetro custom-key-store-name o custom-key-store-id.

aws kms describe-custom-key-stores \
    --custom-key-store-name ExampleCloudHSMKeyStore

El resultado de este comando incluye detalles útiles sobre el almacén de claves de AWS CloudHSM, incluido su estado de conexión (). ConnectionState Si el estado de conexión es FAILED, el resultado incluye un campo ConnectionErrorCode que describe el problema.

Salida:

{
    "CustomKeyStores": [
        {
            "CloudHsmClusterId": "cluster-1a23b4cdefg",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-04-05T14:04:55-07:00",
            "CustomKeyStoreId": "cks-1234567890abcdef0",
            "CustomKeyStoreName": "ExampleExternalKeyStore",
            "TrustAnchorCertificate": "<certificate appears here>"
        }
    ]
}

Para obtener más información, consulte Visualización de un almacén de claves de AWS CloudHSM en AWS la Guía para desarrolladores de Key Management Service.

Ejemplo 2: obtener información sobre un almacén de claves externo con conectividad a puntos de conexión públicos

En el siguiente ejemplo de describe-custom-key-store se muestran los detalles sobre el almacén de claves externo especificado. El comando es el mismo para todos los tipos de almacenes de claves personalizados, pero el resultado difiere según el tipo de almacén de claves y, en el caso de un almacén de claves externo, su opción de conectividad.

De forma predeterminada, este comando muestra información acerca de todos los almacenes de claves personalizados de la cuenta y la región. Para mostrar información sobre un almacén de claves personalizado concreto, utilice el parámetro custom-key-store-name o custom-key-store-id.

aws kms describe-custom-key-stores \
    --custom-key-store-id cks-9876543210fedcba9

El resultado de este comando incluye detalles útiles sobre el almacén de claves externo, incluido su estado de conexión (ConnectionState). Si el estado de conexión es FAILED, el resultado incluye un campo ConnectionErrorCode que describe el problema.

Salida:

{
    "CustomKeyStores": [
        {
            "CustomKeyStoreId": "cks-9876543210fedcba9",
            "CustomKeyStoreName": "ExampleXKS",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-12-02T07:48:55-07:00",
            "CustomKeyStoreType": "EXTERNAL_KEY_STORE",
            "XksProxyConfiguration": {
                "AccessKeyId": "ABCDE12345670EXAMPLE",
                "Connectivity": "PUBLIC_ENDPOINT",
                "UriEndpoint": "https://myproxy.xks.example.com",
                "UriPath": "/example-prefix/kms/xks/v1"
            }
        }
    ]
}

Para obtener más información, consulte Viewing an external key store en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 3: obtener información acerca de un almacén de claves externo con conectividad al servicio de punto de conexión de VPC

En el siguiente ejemplo de describe-custom-key-store se muestran los detalles sobre el almacén de claves externo especificado. El comando es el mismo para todos los tipos de almacenes de claves personalizados, pero el resultado difiere según el tipo de almacén de claves y, en el caso de un almacén de claves externo, su opción de conectividad.

De forma predeterminada, este comando muestra información acerca de todos los almacenes de claves personalizados de la cuenta y la región. Para mostrar información sobre un almacén de claves personalizado concreto, utilice el parámetro custom-key-store-name o custom-key-store-id.

aws kms describe-custom-key-stores \
    --custom-key-store-id cks-2234567890abcdef0

El resultado de este comando incluye detalles útiles sobre el almacén de claves externo, incluido su estado de conexión (ConnectionState). Si el estado de conexión es FAILED, el resultado incluye un campo ConnectionErrorCode que describe el problema.

Salida:

{
    "CustomKeyStores": [
        {
            "CustomKeyStoreId": "cks-3234567890abcdef0",
            "CustomKeyStoreName": "ExampleVPCExternalKeyStore",
            "ConnectionState": "CONNECTED",
            "CreationDate": "2022-12-22T07:48:55-07:00",
            "CustomKeyStoreType": "EXTERNAL_KEY_STORE",
            "XksProxyConfiguration": {
                "AccessKeyId": "ABCDE12345670EXAMPLE",
                "Connectivity": "VPC_ENDPOINT_SERVICE",
                "UriEndpoint": "https://myproxy-private.xks.example.com",
                "UriPath": "/kms/xks/v1",
                "VpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example1"
            }
        }
    ]
}

Para obtener más información, consulte Viewing an external key store en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Búsqueda de información detallada sobre una clave de KMS

En el siguiente describe-key ejemplo, se obtiene información detallada sobre la clave AWS gestionada de Amazon S3 en la cuenta y la región de ejemplo. Puede usar este comando para obtener detalles sobre las claves AWS administradas y las claves administradas por el cliente.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un valor de nombre de alias, pero puede utilizar un ID de clave, un ARN de clave, un nombre de alias o un ARN de alias en este comando.

aws kms describe-key \
    --key-id alias/aws/s3

Salida:

{
    "KeyMetadata": {
        "AWSAccountId": "846764612917",
        "KeyId": "b8a9477d-836c-491f-857e-07937918959b",
        "Arn": "arn:aws:kms:us-west-2:846764612917:key/b8a9477d-836c-491f-857e-07937918959b",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "CreationDate": 2017-06-30T21:44:32.140000+00:00,
        "Enabled": true,
        "Description": "Default KMS key that protects my S3 objects when no other key is defined",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "AWS",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    }
}

Para obtener más información, consulte Visualización de claves en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 2: Obtención de detalles sobre una clave KMS de RSA asimétrica

En el siguiente ejemplo de describe-key se obtiene información detallada acerca de una clave KMS de RSA asimétrica que se utiliza para la firma y la verificación.

aws kms describe-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyMetadata": {
        "AWSAccountId": "111122223333",
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "CreationDate": "2019-12-02T19:47:14.861000+00:00",
        "CustomerMasterKeySpec": "RSA_2048",
        "Enabled": false,
        "Description": "",
        "KeyState": "Disabled",
        "Origin": "AWS_KMS",
        "MultiRegion": false,
        "KeyManager": "CUSTOMER",
        "KeySpec": "RSA_2048",
        "KeyUsage": "SIGN_VERIFY",
        "SigningAlgorithms": [
            "RSASSA_PKCS1_V1_5_SHA_256",
            "RSASSA_PKCS1_V1_5_SHA_384",
            "RSASSA_PKCS1_V1_5_SHA_512",
            "RSASSA_PSS_SHA_256",
            "RSASSA_PSS_SHA_384",
            "RSASSA_PSS_SHA_512"
        ]
    }
}

Ejemplo 3: obtención de detalles sobre una clave de réplica de varias regiones

En el siguiente ejemplo de describe-key se obtienen los metadatos de una clave de réplica de varias regiones. Esta clave de varias regiones es una clave de cifrado simétrica. La salida de un comando describe-key para cualquier clave de varias regiones devuelve información sobre la clave principal y todas sus réplicas.

aws kms describe-key \
    --key-id arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

Salida:

{
    "KeyMetadata": {
        "MultiRegion": true,
        "AWSAccountId": "111122223333",
        "Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
        "CreationDate": "2021-06-28T21:09:16.114000+00:00",
        "CurrentKeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
        "Description": "",
        "Enabled": true,
        "KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "Origin": "AWS_KMS",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "MultiRegionConfiguration": {
            "MultiRegionKeyType": "PRIMARY",
            "PrimaryKey": {
                "Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                "Region": "us-west-2"
            },
            "ReplicaKeys": [
                {
                    "Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "eu-west-1"
                },
                {
                    "Arn": "arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "ap-northeast-1"
                },
                {
                    "Arn": "arn:aws:kms:sa-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "sa-east-1"
                }
            ]
        }
    }
}

Ejemplo 4: obtención de detalles sobre una clave HMAC KMS

En el siguiente ejemplo de describe-key se obtiene información detallada acerca de una clave KMS de HMAC.

aws kms describe-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyMetadata": {
        "AWSAccountId": "123456789012",
        "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
        "Arn": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
        "CreationDate": "2022-04-03T22:23:10.194000+00:00",
        "Enabled": true,
        "Description": "Test key",
        "KeyUsage": "GENERATE_VERIFY_MAC",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "HMAC_256",
        "MacAlgorithms": [
            "HMAC_SHA_256"
        ],
        "MultiRegion": false
    }
}

Para deshabilitar la rotación automática de una clave de KMS

En el siguiente ejemplo de disable-key-rotation, se deshabilita la rotación automática de una clave de KMS administrada. Para volver a habilitar la rotación automática, utilice el comando enable-key-rotation.

aws kms disable-key-rotation \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no genera ninguna salida. Para comprobar que la rotación automática está deshabilitada para la clave de KMS, utilice el comando get-key-rotation-status.

Para obtener más información, consulte Rotación de claves en la Guía para desarrolladores de AWS Key Management Service.

Desactivación temporal de una clave de KMS

El siguiente comando disable-key desactiva una clave de KMS administrada por el cliente. Para volver a habilitar la clave de KMS, utilice el comando enable-key.

aws kms disable-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no genera ninguna salida.

Para obtener más información, consulte Habilitar y deshabilitar claves en la Guía para desarrolladores de AWS Key Management Service.

Para desconectar un almacén de claves personalizado

El siguiente disconnect-custom-key-store ejemplo desconecta un almacén de claves personalizado de su clúster de AWS CloudHSM. Puede desconectar un almacén de claves para solucionar un problema, actualizar su configuración o impedir que las claves de KMS del almacén de claves se utilicen en operaciones criptográficas.

Este comando es el mismo para todos los almacenes de claves personalizados, incluidos los almacenes de claves de AWS CloudHSM y los almacenes de claves externos.

Antes de ejecutar este comando, reemplace el ID del almacén de claves personalizado de ejemplo por uno válido.

$ aws kms disconnect-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0

Este comando no produce ningún resultado. Compruebe que el comando ha sido efectivo, utilice el comando describe-custom-key-stores.

Para obtener más información sobre cómo desconectar un almacén de claves de AWS CloudHSM, consulte Conexión y desconexión de un almacén de claves de AWS CloudHSM en la Guía para desarrolladores de Key Management Service.AWS

Para obtener más información sobre cómo desconectar un almacén de claves externo, consulte Connecting and disconnecting an external key store en la Guía para desarrolladores de AWS Key Management Service.

Para habilitar la rotación automática de una clave de KMS

El siguiente ejemplo de enable-key-rotation permite la rotación automática de una clave de KMS administrada por el cliente con un período de rotación de 180 días. La clave de KMS se rotará un año (aproximadamente 365 días) a partir de la fecha en que se complete este comando y cada año a partir de entonces.

El parámetro --key-id identifica las claves KMS. En este ejemplo, se utiliza un valor de ARN clave, pero puede utilizar el ID de clave o el ARN de la clave de KMS. El parámetro --rotation-period-in-days especifica el número de días entre cada fecha de rotación. Especifique un valor comprendido entre 90 y 2560 días. El valor predeterminado es 365 días si no se especifica ningún valor.

aws kms enable-key-rotation \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --rotation-period-in-days 180

Este comando no genera ninguna salida. Utilice el comando get-key-rotation-status para comprobar que la clave de KMS está habilitada.

Para obtener más información, consulte Rotación de claves en la Guía para desarrolladores de AWS Key Management Service.

Activación de una clave de KMS

En el siguiente ejemplo de enable-key se habilita una clave administrada por el cliente. Puede utilizar un comando como este para habilitar una clave de KMS que deshabilitó temporalmente mediante el comando disable-key. También puede usarlo para habilitar una clave de KMS que esté deshabilitada porque la eliminación estaba programada y esta se canceló.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un valor de ID de clave, pero puede utilizar un ID de clave o un valor de ARN de clave en este comando.

Antes de ejecutar este comando, reemplace el ID de claves de ejemplo por uno válido.

aws kms enable-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no genera ninguna salida. Utilice el comando describe-key para comprobar que la clave de KMS está habilitada. Consulte los valores de los campos KeyState y Enabled en la salida describe-key.

Para obtener más información, consulte Habilitar y deshabilitar claves en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Cifrado del contenido de un archivo en Linux o MacOS

El siguiente encrypt comando muestra la forma recomendada de cifrar datos con la AWS CLI.

aws kms encrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --plaintext fileb://ExamplePlaintextFile \
    --output text \
    --query CiphertextBlob | base64 \
    --decode > ExampleEncryptedFile

El comando hace varias cosas:

Utiliza el parámetro --plaintext para indicar los datos que se van a cifrar. El valor de este parámetro debe estar codificado en base64. El valor del plaintext parámetro debe estar codificado en base64 o debe usar el prefijofileb://, que indica a la AWS CLI que lea los datos binarios del archivo. Si el archivo no está en el directorio actual, escriba la ruta completa al archivo. Por ejemplo: fileb:///var/tmp/ExamplePlaintextFile o fileb://C:\Temp\ExamplePlaintextFile. Para obtener más información sobre la lectura de los valores de los parámetros de la AWS CLI de un archivo, consulte Carga de parámetros desde un archivo en la Guía del usuario de la interfaz de línea de AWS comandos y Prácticas recomendadas para los parámetros de archivos locales en el blog de herramientas de línea de AWS comandos. Utiliza los --query parámetros --output y para controlar la salida del comando. Estos parámetros extraen los datos cifrados, denominados texto cifrado, de la salida del comando. Para obtener más información sobre el control de la salida, consulte Control del comando Resultado de la Guía del usuario de la interfaz de línea de AWS comandos. Utiliza la base64 utilidad para decodificar el resultado extraído en datos binarios. El texto cifrado que devuelve un encrypt comando correcto es texto codificado en base64. Debe decodificar este texto antes de poder utilizar la AWS CLI para descifrarlo. Guarda el texto cifrado binario en un archivo. La parte final del comando (> ExampleEncryptedFile) guarda el texto cifrado binario en un archivo para facilitar el descifrado. Para ver un comando de ejemplo que usa la AWS CLI para descifrar datos, consulte los ejemplos de descifrado.

Ejemplo 2: Uso de la AWS CLI para cifrar datos en Windows

Este ejemplo es igual al anterior, excepto que utiliza la herramienta certutil en lugar de base64. Como se muestra en el siguiente ejemplo, este procedimiento requiere dos comandos.

aws kms encrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --plaintext fileb://ExamplePlaintextFile \
    --output text \
    --query CiphertextBlob > C:\Temp\ExampleEncryptedFile.base64

certutil -decode C:\Temp\ExampleEncryptedFile.base64 C:\Temp\ExampleEncryptedFile

Ejemplo 3: cifrado con una clave de KMS asimétrica

El siguiente comando encrypt muestra cómo cifrar texto sin formato con una clave de KMS asimétrica. El parámetro --encryption-algorithm es obligatorio. Como en todos los comandos de la encrypt CLI, el plaintext parámetro debe estar codificado en base64 o debe usar el fileb:// prefijo, que indica a la AWS CLI que lea los datos binarios del archivo.

aws kms encrypt \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --encryption-algorithm RSAES_OAEP_SHA_256 \
    --plaintext fileb://ExamplePlaintextFile \
    --output text \
    --query CiphertextBlob | base64 \
    --decode > ExampleEncryptedFile

Este comando no genera ninguna salida.

Para generar un par de claves de datos asimétricas ECC NIST P384

El siguiente generate-data-key-pair-without-plaintext ejemplo solicita un par de claves ECC NIST P384 para su uso fuera de. AWS

El comando devuelve una clave pública en texto no cifrado y una copia de la clave privada cifrada con la clave de KMS especificada. No devuelve una clave privada en texto no cifrado. Puede almacenar de forma segura la clave privada cifrada con los datos cifrados y llamar al AWS KMS para que descifre la clave privada cuando necesite usarla.

Para solicitar un par de claves de datos asimétricas ECC NIST P384, utilice el parámetro key-pair-spec con un valor de ECC_NIST_P384.

La clave de KMS que especifique debe ser una clave de KMS de cifrado simétrica, es decir, una clave de KMS con un valor KeySpec de SYMMETRIC_DEFAULT.

NOTA: Los valores de la salida de este ejemplo se han truncado para su visualización.

aws kms generate-data-key-pair-without-plaintext \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-pair-spec ECC_NIST_P384

Salida:

{
    "PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
    "PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
    "KeyPairSpec": "ECC_NIST_P384"
}

Las PublicKey y PrivateKeyCiphertextBlob se devuelven en formato codificado en Base64.

Para obtener más información, consulte Data key pairs en la Guía para desarrolladores de AWS Key Management Service.

Para generar un par de claves de datos asimétricas RSA de 2048 bits

El siguiente generate-data-key-pair ejemplo solicita un par de claves de datos asimétricas RSA de 2048 bits para su uso fuera de. AWS El comando devuelve una clave pública en texto no cifrado y una clave privada en texto no cifrado para su uso y eliminación inmediatos, y una copia de esa clave de datos cifrada con la clave de KMS especificada. Puede almacenar de forma segura la clave privada cifrada con los datos cifrados.

Para solicitar un par de claves de datos asimétricas RSA de 2048 bits, utilice el parámetro key-pair-spec con un valor de RSA_2048.

La clave de KMS que especifique debe ser una clave de KMS de cifrado simétrica, es decir, una clave de KMS con un valor KeySpec de SYMMETRIC_DEFAULT.

NOTA: Los valores de la salida de este ejemplo se han truncado para su visualización.

aws kms generate-data-key-pair \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --key-pair-spec RSA_2048

Salida:

{
    "PrivateKeyCiphertextBlob": "AQIDAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAFFxmiD134doUDzMGmfCEtcAAAHaTCCB2UGCSqGSIb3DQEHBqCCB1...",
    "PrivateKeyPlaintext": "MIIG/QIBADANBgkqhkiG9w0BAQEFAASCBucwggbjAgEAAoIBgQDcDd4YzI+u9Kfv4t2UkTWhShBXkekS4cBVt07I0P42ZgMf+YvU5IgS4ut...",
    "PublicKey": "MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA3A3eGMyPrvSn7+LdlJE1oUoQV5HpEuHAVbdOyND+NmYDH/mL1OSIEuLrcdZ5hrMH4pk83r40l...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
    "KeyPairSpec": "RSA_2048"
}

Las PublicKey, PrivateKeyPlaintext y PrivateKeyCiphertextBlob se devuelven en formato codificado en Base64.

Para obtener más información, consulte Data key pairs en la Guía para desarrolladores de AWS Key Management Service.

Generación de una clave de datos simétrica de 256 bits sin una clave de texto no cifrado

En el siguiente ejemplo de generate-data-key-without-plaintext se solicita una copia cifrada de una clave de datos simétrica de 256 bits para usarla fuera de AWS. Puede llamar a AWS KMS para descifrar la clave de datos cuando esté listo para usarla.

Para solicitar una clave de datos de 256 bits, utilice el parámetro key-spec con un valor de AES_256. Para solicitar una clave de datos de 128 bits, utilice el parámetro key-spec con un valor de AES_128. Para el resto longitudes de clave de datos, utilice el parámetro number-of-bytes.

La clave de KMS que especifique debe ser una clave de KMS de cifrado simétrica, es decir, una clave de KMS con un valor de especificación de clave SYMMETRIC_DEFAULT.

aws kms generate-data-key-without-plaintext \
    --key-id "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
    --key-spec AES_256

Salida:

{
    "CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogL",
    "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

CiphertextBlob (clave de datos cifrada) se devuelve en formato codificado en base64.

Para obtener más información, consulte Claves de datos en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Generación de una clave de datos simétrica de 256 bits

En el siguiente generate-data-key ejemplo, se solicita una clave de datos simétrica de 256 bits para utilizarla fuera de. AWS El comando devuelve una clave de datos en texto sin formato para su uso y eliminación inmediatos, y una copia de esa clave de datos cifrada bajo la clave de KMS especificada. Puede almacenar de forma segura la clave de datos cifrada con los datos cifrados.

Para solicitar una clave de datos de 256 bits, utilice el parámetro key-spec con un valor de AES_256. Para solicitar una clave de datos de 128 bits, utilice el parámetro key-spec con un valor de AES_128. Para el resto longitudes de clave de datos, utilice el parámetro number-of-bytes.

La clave de KMS que especifique debe ser una clave de KMS de cifrado simétrica, es decir, una clave de KMS con un valor de especificación de clave SYMMETRIC_DEFAULT.

aws kms generate-data-key \
    --key-id alias/ExampleAlias \
    --key-spec AES_256

Salida:

{
    "Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw=",
    "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6",
    "CiphertextBlob": "AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDEFogLqPWZconQhwHAIBEIA7d9AC7GeJJM34njQvg4Wf1d5sw0NIo1MrBqZa+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U="
}

Plaintext (clave de datos de texto sin formato) y CiphertextBlob (clave de datos cifrada) se devuelven en formato codificado en base64.

Para obtener más información, consulte Claves de datos en la Guía para desarrolladores de AWS Key Management Service. Ejemplo 2: Generación de una clave de datos simétrica de 512 bits

En el siguiente ejemplo de generate-data-key se solicita una clave de datos simétrica de 512 bits para cifrado y descifrado. El comando devuelve una clave de datos en texto sin formato para su uso y eliminación inmediatos, y una copia de esa clave de datos cifrada bajo la clave de KMS especificada. Puede almacenar de forma segura la clave de datos cifrada con los datos cifrados.

Para solicitar una longitud de clave distinta de 128 o 256 bits, utilice el parámetro number-of-bytes. Para solicitar una clave de datos de 512 bits, en el siguiente ejemplo se utiliza el parámetro number-of-bytes con un valor de 64 (bytes).

La clave KMS que especifique debe ser una clave de KMS de cifrado simétrica, es decir, una clave de KMS con un valor de especificación de clave de SYMMETRIC_DEFAULT.

NOTA: Los valores de la salida de este ejemplo se han truncado para su visualización.

aws kms generate-data-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --number-of-bytes 64

Salida:

{
    "CiphertextBlob": "AQIBAHi6LtupRpdKl2aJTzkK6FbhOtQkMlQJJH3PdtHvS/y+hAEnX/QQNmMwDfg2korNMEc8AAACaDCCAmQGCSqGSIb3DQEHBqCCAlUwggJRAgEAMIICSgYJKoZ...",
    "Plaintext": "ty8Lr0Bk6OF07M2BWt6qbFdNB+G00ZLtf5MSEb4al3R2UKWGOp06njAwy2n72VRm2m7z/Pm9Wpbvttz6a4lSo9hgPvKhZ5y6RTm4OovEXiVfBveyX3DQxDzRSwbKDPk/...",
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

Plaintext (clave de datos de texto sin formato) y CiphertextBlob (clave de datos cifrada) se devuelven en formato codificado en base64.

Para obtener más información, consulte Claves de datos en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Generación de un HMAC para un mensaje

El siguiente comando generate-mac genera un HMAC para un mensaje, una clave KMS HMAC y un algoritmo MAC. El algoritmo debe ser compatible con la clave KMS HMAC especificada.

En AWS CLI v2, el valor del message parámetro debe estar codificado en Base64. O bien, puede guardar el mensaje en un archivo y usar el fileb:// prefijo, que indica a la AWS CLI que lea los datos binarios del archivo.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su AWS cuenta. El ID de clave debe representar una clave KMS HMAC con un uso de clave de GENERATE_VERIFY_MAC.

msg=(echo 'Hello World' | base64)

aws kms generate-mac \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://Message \
    --mac-algorithm HMAC_SHA_384

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "Mac": "<HMAC_TAG>",
    "MacAlgorithm": "HMAC_SHA_384"
}

Para obtener más información sobre el uso de las claves HMAC KMS en AWS KMS, consulte las claves HMAC en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 2: Guardado de un HMAC en un archivo (Linux y macOS)

En el siguiente ejemplo de generate-mac, se genera un HMAC para un mensaje corto almacenado en un archivo local. El comando también obtiene la Mac propiedad de la respuesta, la decodifica en Base64 y la guarda en el archivo. ExampleMac Puede usar el archivo de MAC en un comando verify-mac que verifique el MAC.

El comando generate-mac requiere un mensaje codificado en Base64 y un algoritmo de MAC que admita la clave KMS HMAC. Para obtener los algoritmos de MAC que admite la clave KMS, utilice el comando describe-key.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su cuenta. AWS El ID de clave debe representar una clave KMS asimétrica con un uso de clave de GENERATE_VERIFY_MAC.

echo 'hello world' | base64 > EncodedMessage

aws kms generate-mac \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://EncodedMessage \
    --mac-algorithm HMAC_SHA_384 \
    --output text \
    --query Mac | base64 --decode > ExampleMac

Este comando no genera ninguna salida. En este ejemplo, se extrae la propiedad Mac del resultado y se guarda en un archivo.

Para obtener más información sobre el uso de las claves HMAC KMS en AWS KMS, consulte las claves HMAC en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 1: Generación de una cadena de bytes aleatoria de 256 bits (Linux o macOS)

En el siguiente ejemplo de generate-random se genera una cadena de bytes aleatoria de 256 bits (32 bytes) codificada en base64. El ejemplo decodifica la cadena de bytes y la guarda en el archivo aleatorio.

Al ejecutar este comando, debe usar el parámetro number-of-bytes para especificar la longitud del valor aleatorio en bytes.

No se especifica una clave de KMS cuando se ejecuta este comando. La cadena de bytes aleatoria no está relacionada con ninguna clave de KMS.

De forma predeterminada, AWS KMS genera el número aleatorio. Sin embargo, si especifica un almacén de claves personalizado, la cadena de bytes aleatorios se genera en el clúster de AWS CloudHSM asociado al almacén de claves personalizado.

Este ejemplo utiliza los parámetros y valores siguientes:

Utiliza el --number-of-bytes parámetro necesario con un valor de 32 para solicitar una cadena de 32 bytes (256 bits). Utiliza el --output parámetro con un valor de para text indicar a la AWS CLI que devuelva la salida como texto, en lugar de JSON. Utiliza el para extraer el valor de la Plaintext propiedad de la respuesta. Canaliza (|) la salida del comando --query parameter a la base64 utilidad, que decodifica la salida extraída. Utiliza el operador de redirección (>) para guardar el byte decodificado cadena al archivo. Utiliza el operador de redirección (>) ExampleRandom para guardar el texto cifrado binario en un archivo.

aws kms generate-random \
    --number-of-bytes 32 \
    --output text \
    --query Plaintext | base64 --decode > ExampleRandom

Este comando no genera ninguna salida.

Para obtener más información, consulte la referencia de GenerateRandomla API del Servicio de administración de AWS claves.

Ejemplo 2: Generación de un número aleatorio de 256 bits (símbolo del sistema de Windows)

En el siguiente ejemplo se utiliza el comando generate-random para generar una cadena de bytes aleatoria codificada en base64 de 256 bits (32 bytes). El ejemplo decodifica la cadena de bytes y la guarda en el archivo aleatorio. Este ejemplo es igual al anterior, excepto que usa la utilidad certutil de Windows para decodificar en base64 la cadena de bytes aleatoria antes de guardarla en un archivo.

En primer lugar, genere una cadena de bytes aleatoria codificada en base64 y guárdela en un archivo temporal, ExampleRandom.base64.

aws kms generate-random \
    --number-of-bytes 32 \
    --output text \
    --query Plaintext > ExampleRandom.base64

Puesto que el resultado del comando generate-random se guarda en un archivo, este ejemplo no produce ningún resultado.

Ahora utilice el comando certutil -decode para decodificar la cadena de bytes codificada en base64 del archivo ExampleRandom.base64. A continuación, guarda la cadena de bytes decodificada en el archivo ExampleRandom.

certutil -decode ExampleRandom.base64 ExampleRandom

Salida:

Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

Para obtener más información, consulte la referencia GenerateRandomde la API del Servicio de administración de AWS claves.

Copia de una política de claves de una clave de KMS a otra

En el siguiente ejemplo de get-key-policy se obtiene la política de claves de una clave de KMS y se guarda en un archivo de texto. A continuación, reemplaza la política de una clave de KMS diferente utilizando el archivo de texto como entrada de la política.

Puesto que el parámetro --policy de put-key-policy requiere una cadena, debe usar la opción --output text para devolver la salida como una cadena de texto en lugar de JSON.

aws kms get-key-policy \
    --policy-name default \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --query Policy \
    --output text > policy.txt

aws kms put-key-policy \
    --policy-name default \
    --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --policy file://policy.txt

Este comando no genera ninguna salida.

Para obtener más información, consulte la referencia PutKeyPolicyde la API de AWS KMS.

Para recuperar el estado de rotación de una clave de KMS.

El siguiente ejemplo de get-key-rotation-status devuelve información sobre el estado de rotación de la clave de KMS especificada, que incluye si la rotación automática está habilitada, el período de rotación y la próxima fecha de rotación programada. Puede usar este comando en las claves de KMS administradas por el cliente y en las claves de KMS AWS administradas. Sin embargo, todas las claves de KMS AWS administradas se rotan automáticamente cada año.

aws kms get-key-rotation-status \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyRotationEnabled": true,
    "NextRotationDate": "2024-02-14T18:14:33.587000+00:00",
    "RotationPeriodInDays": 365
}

Para obtener más información, consulte Rotación de claves en la Guía para desarrolladores de AWS Key Management Service.

Para obtener los elementos necesarios para importar material de claves en una clave de KMS

En el siguiente ejemplo de get-parameters-for-import se obtiene la clave pública y el token de importación que necesita para importar material de claves en una clave de KMS. Cuando utilice el comando import-key-material, asegúrese de utilizar el token de importación y el material de claves cifrados con la clave pública que se devolvieron en el mismo comando get-parameters-for-import. Además, el algoritmo de encapsulado que especifique en este comando debe ser el que utilice para cifrar el material de claves con la clave pública.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un ID de clave, pero puede utilizar un ID de clave o un ARN de clave en este comando.

aws kms get-parameters-for-import \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --wrapping-key-spec RSA_2048

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "PublicKey": "<public key base64 encoded data>",
    "ImportToken": "<import token base64 encoded data>",
    "ParametersValidTo": 1593893322.32
}

Para obtener más información, consulte Download the public key and import token en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: descargar la clave pública de una clave de KMS asimétrica

El siguiente ejemplo de get-public-key descarga la clave pública de una clave de KMS asimétrica.

Además de devolver la clave pública, el resultado incluye la información necesaria para utilizarla de forma segura fuera del AWS KMS, incluidos el uso de la clave y los algoritmos de cifrado compatibles.

aws kms get-public-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "PublicKey": "jANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAl5epvg1/QtJhxSi2g9SDEVg8QV/...",
    "CustomerMasterKeySpec": "RSA_4096",
    "KeyUsage": "ENCRYPT_DECRYPT",
    "EncryptionAlgorithms": [
        "RSAES_OAEP_SHA_1",
        "RSAES_OAEP_SHA_256"
    ]
}

Para obtener más información sobre el uso de claves KMS asimétricas en AWS KMS, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del servicio de administración de AWS claves. Ejemplo 2: convertir una clave pública a formato DER (Linux y macOS)

El siguiente ejemplo de get-public-key descarga la clave pública de una clave de KMS asimétrica y la guarda en un archivo DER.

Cuando utiliza el get-public-key comando en la AWS CLI, devuelve una clave pública X.509 codificada en DER y codificada en Base64. En este ejemplo se obtiene el valor de la propiedad PublicKey en forma de texto. Descodifica la PublicKey en Base64 y la guarda en el archivo public_key.der. El parámetro output devuelve el resultado como texto, en lugar de como JSON. El --query parámetro obtiene solo la PublicKey propiedad, no las propiedades que necesita para usar la clave pública de forma segura fuera del KMS. AWS

Antes de ejecutar este comando, sustituya el identificador de clave de ejemplo por un identificador de clave válido de su AWS cuenta.

aws kms get-public-key \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --output text \
    --query PublicKey | base64 --decode > public_key.der

Este comando no genera ninguna salida.

Para obtener más información sobre el uso de claves KMS asimétricas en AWS KMS, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Para importar material de claves en una clave de KMS

En el siguiente ejemplo de import-key-material se carga el material de claves en una clave de KMS que se ha creado sin material de claves. El estado de clave de la clave de KMS debe ser PendingImport.

Este comando utiliza material de claves que usted ha cifrado con la clave pública que ha devuelto el comando get-parameters-for-import. También usa el token de importación del mismo comando get-parameters-for-import.

El parámetro expiration-model indica que el material de claves caduca automáticamente en la fecha y la hora especificadas por el parámetro valid-to. Cuando el material clave caduca, AWS KMS lo elimina, el estado de clave de la clave de KMS cambia a Pending import y la clave de KMS queda inutilizable. Para restaurar la clave de KMS debe volver a importar el mismo material de claves. Para usar material de claves diferente debe crear una clave de KMS nueva.

Antes de ejecutar este comando, sustituya el identificador de clave de ejemplo por un identificador de clave o un ARN de clave válido de su AWS cuenta.

aws kms import-key-material \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --encrypted-key-material fileb://EncryptedKeyMaterial.bin \
    --import-token fileb://ImportToken.bin \
    --expiration-model KEY_MATERIAL_EXPIRES \
    --valid-to 2021-09-21T19:00:00Z

Salida:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyMaterialId": "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6"
}

Para obtener más información sobre la importación de material de claves, consulte Importing Key Material en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Para enumerar todos los alias de una AWS cuenta y una región

En el siguiente ejemplo, se utiliza el list-aliases comando para enumerar todos los alias de la región predeterminada de la AWS cuenta. El resultado incluye los alias asociados a las claves de KMS AWS administradas y a las claves de KMS administradas por el cliente.

aws kms list-aliases

Salida:

{
    "Aliases": [
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/testKey",
            "AliasName": "alias/testKey",
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/FinanceDept",
            "AliasName": "alias/FinanceDept",
            "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/dynamodb",
            "AliasName": "alias/aws/dynamodb",
            "TargetKeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
        },
        {
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/aws/ebs",
            "AliasName": "alias/aws/ebs",
            "TargetKeyId": "0987ab65-43cd-21ef-09ab-87654321cdef"
        },
        ...
    ]
}

Ejemplo 2: Creación de una lista de todos los alias de una clave de KMS concreta

En el siguiente ejemplo se utiliza el comando list-aliases y su parámetro key-id para mostrar todos los alias que están asociados con una determinada clave de KMS.

Cada alias está asociado a una sola clave de KMS, pero una clave de KMS puede tener varios alias. Este comando es muy útil porque la consola de AWS KMS solo muestra un alias para cada clave de KMS. Debe utilizar el comando list-aliases para encontrar todos los alias de una clave de KMS.

En este ejemplo, se utiliza el ID de la clave de KMS del parámetro --key-id, pero puede utilizar un ID de clave, un ARN de clave, un nombre de alias o un ARN de alias en este comando.

aws kms list-aliases --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "Aliases": [
        {
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/oregon-test-key",
            "AliasName": "alias/oregon-test-key"
        },
        {
            "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/project121-test",
            "AliasName": "alias/project121-test"
        }
    ]
}

Para obtener más información, consulte Uso de alias en la Guía para desarrolladores de AWS Key Management Service.

Para ver las concesiones de una clave de AWS KMS

En el siguiente list-grants ejemplo, se muestran todas las concesiones de la clave de KMS AWS gestionada especificada para Amazon DynamoDB en su cuenta. Esta concesión permite a DynamoDB utilizar la clave de KMS en su nombre para cifrar una tabla de DynamoDB antes de escribirla en el disco. Puede usar un comando como este para ver las concesiones de las claves de KMS AWS administradas y las claves de KMS administradas por el cliente en la AWS cuenta y la región.

Este comando usa el parámetro key-id con un ID de la clave para identificar la clave de KMS. Puede utilizar un ID o ARN de clave para identificar la clave de KMS. Para obtener el identificador de clave o el ARN de clave de una clave de KMS AWS administrada, utilice el comando list-keys olist-aliases.

aws kms list-grants \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

La salida muestra que la concesión otorga a Amazon DynamoDB permiso para usar la clave de KMS para operaciones criptográficas y le da permiso para ver detalles sobre la clave de KMS (DescribeKey) y para retirar concesiones (RetireGrant). La restricción EncryptionContextSubset limita estos permisos a las solicitudes que incluyen los pares de contexto de cifrado especificados. Como resultado, los permisos de la concesión solo son efectivos en la cuenta y la tabla de DynamoDB especificadas.

{
    "Grants": [
        {
            "Constraints": {
                "EncryptionContextSubset": {
                    "aws:dynamodb:subscriberId": "123456789012",
                    "aws:dynamodb:tableName": "Services"
                }
            },
            "IssuingAccount": "arn:aws:iam::123456789012:root",
            "Name": "8276b9a6-6cf0-46f1-b2f0-7993a7f8c89a",
            "Operations": [
                "Decrypt",
                "Encrypt",
                "GenerateDataKey",
                "ReEncryptFrom",
                "ReEncryptTo",
                "RetireGrant",
                "DescribeKey"
            ],
            "GrantId": "1667b97d27cf748cf05b487217dd4179526c949d14fb3903858e25193253fe59",
            "KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "RetiringPrincipal": "dynamodb.us-west-2.amazonaws.com",
            "GranteePrincipal": "dynamodb.us-west-2.amazonaws.com",
            "CreationDate": "2021-05-13T18:32:45.144000+00:00"
        }
    ]
}

Para obtener más información, consulte las concesiones en AWS KMS en la Guía para desarrolladores del servicio de administración de AWS claves.

Obtención de los nombres de las políticas de claves de una clave de KMS

En el siguiente ejemplo de list-key-policies se obtienen los nombres de las políticas de clave de una clave administrada por el cliente en la cuenta y la región del ejemplo. Puedes usar este comando para buscar los nombres de las políticas clave para las claves AWS administradas y las claves administradas por el cliente.

Este comando no resulta útil, ya que el único nombre de la política de claves válido es default.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un valor de ID de clave, pero puede utilizar un ID de clave o un ARN de clave en este comando.

aws kms list-key-policies \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "PolicyNames": [
    "default"
    ]
}

Para obtener más información sobre las políticas clave de AWS KMS, consulte Uso de políticas clave en AWS KMS en la Guía AWS para desarrolladores del Servicio de administración de claves.

Para recuperar información sobre todas las rotaciones de material de claves completadas

En el siguiente ejemplo de list-key-rotations se muestra información sobre todas las rotaciones de material de claves completadas para la clave de KMS especificada.

aws kms list-key-rotations \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "Rotations": [
        {
            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "RotationDate": "2024-03-02T10:11:36.564000+00:00",
            "RotationType": "AUTOMATIC"
        },
        {
            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
            "RotationDate": "2024-04-05T15:14:47.757000+00:00",
            "RotationType": "ON_DEMAND"
        }
    ],
    "Truncated": false
}

Para obtener más información, consulte Rotación de claves en la Guía para desarrolladores de AWS Key Management Service.

Obtención de las claves KMS de una cuenta y una región

En el siguiente ejemplo de list-keys se obtienen las claves de KMS de una cuenta y una región. Este comando devuelve tanto las claves AWS administradas como las claves administradas por el cliente.

aws kms list-keys

Salida:

{
    "Keys": [
        {
            "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
        },
        {
            "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
            "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321"
        },
        {
            "KeyArn": "arn:aws:kms:us-east-2:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d",
            "KeyId": "1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
        }
    ]
}

Para obtener más información, consulte Visualización de claves en la Guía para desarrolladores de AWS Key Management Service.

Para obtener las etiquetas de una clave de KMS

En el siguiente ejemplo de list-resource-tags se obtienen las etiquetas para una clave de KMS. Para añadir una o más etiquetas de recurso en claves de KMS, utilice el comando tag-resource. El resultado muestra que esta clave de KMS tiene dos etiquetas de recursos, cada una de las cuales tiene una clave y un valor.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un valor de ID de clave, pero puede utilizar un ID de clave o un ARN de clave en este comando.

aws kms list-resource-tags \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "Tags": [
    {
        "TagKey": "Dept",
        "TagValue": "IT"
    },
    {
        "TagKey": "Purpose",
        "TagValue": "Test"
    }
    ],
    "Truncated": false
}

Para obtener más información sobre el uso de etiquetas en AWS KMS, consulte Etiquetado de claves en la Guía para desarrolladores del Servicio de administración de AWS claves.

Para ver las concesiones que una entidad principal puede retirar

En el siguiente list-retirable-grants ejemplo, se muestran todas las concesiones que el ExampleAdmin usuario puede retirar en las claves de KMS de una AWS cuenta y una región. Puede usar un comando como este para ver las concesiones que cualquier titular de cuenta puede retirar en relación con las claves de KMS de la AWS cuenta y la región.

El valor del parámetro retiring-principal obligatorio debe ser el nombre de recurso de Amazon (ARN) de una cuenta, usuario o rol.

No puede especificar un servicio con el valor de retiring-principal en este comando, aunque un servicio pueda ser la entidad principal que se retira. Para buscar las concesiones en las que un servicio concreto es la entidad principal que se retira, utilice el comando list-grants.

El resultado muestra que el usuario ExampleAdmin tiene permiso para retirar concesiones en dos claves de KMS diferentes de la cuenta y la región. Además de la entidad principal que se retira, la cuenta tiene permiso para retirar cualquier concesión de la cuenta.

aws kms list-retirable-grants \
    --retiring-principal arn:aws:iam::111122223333:user/ExampleAdmin

Salida:

{
    "Grants": [
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
            "GrantId": "156b69c63cb154aa21f59929ff19760717be8d9d82b99df53e18b94a15a5e88e",
            "Name": "",
            "CreationDate": 2021-01-14T20:17:36.419000+00:00,
            "GranteePrincipal": "arn:aws:iam::111122223333:user/ExampleUser",
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Operations": [
                "Encrypt"
            ],
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            }
        },
        {
            "KeyId": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
            "GrantId": "8c94d1f12f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2",
            "Name": "",
            "CreationDate": "2021-02-02T19:49:49.638000+00:00",
            "GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
            "RetiringPrincipal": "arn:aws:iam::111122223333:user/ExampleAdmin",
            "IssuingAccount": "arn:aws:iam::111122223333:root",
            "Operations": [
                "Decrypt"
            ],
            "Constraints": {
                "EncryptionContextSubset": {
                    "Department": "IT"
                }
            }
        }
    ],
    "Truncated": false
}

Para obtener más información, consulte las concesiones en AWS KMS en la Guía para desarrolladores de AWS Key Management Service.

Cambio de la política de claves de una clave de KMS

En el siguiente ejemplo de put-key-policy se cambia la política de claves para una clave administrada por el cliente.

Para empezar, cree una política de clave y guárdela en un archivo JSON local. En este ejemplo, el archivo es key_policy.json. También puede especificar la política de claves como un valor de cadena del parámetro policy.

La primera declaración de esta política clave otorga a la AWS cuenta permiso para usar las políticas de IAM para controlar el acceso a la clave de KMS. La segunda instrucción otorga permiso al usuario test-user para ejecutar los comandos describe-key y list-keys de la clave de KMS.

Contenido de key_policy.json:

{
    "Version" : "2012-10-17",
    "Id" : "key-default-1",
    "Statement" : [
        {
            "Sid" : "Enable IAM User Permissions",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:root"
            },
            "Action" : "kms:*",
            "Resource" : "*"
        },
        {
            "Sid" : "Allow Use of Key",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:user/test-user"
            },
            "Action" : [
                "kms:DescribeKey",
                "kms:ListKeys"
            ],
            "Resource" : "*"
        }
    ]
}

Para identificar la clave de KMS, en este ejemplo se utiliza el ID de clave, pero también se puede utilizar un ARN de la clave. El comando utiliza el parámetro policy para especificar las políticas de claves. Para indicar que la política se encuentra en un archivo, utiliza el prefijo file:// necesario. Este prefijo es necesario para identificar los archivos de todos los sistemas operativos compatibles. Por último, el comando usa el parámetro policy-name con un valor de default. Si no se especifica ningún nombre de política, el valor predeterminado es default. El único valor válido es default.

aws kms put-key-policy \
    --policy-name default \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --policy file://key_policy.json

Este comando no produce ninguna salida. Para comprobar que se aplicó el comando, utilice el comando get-key-policy. El siguiente comando de ejemplo obtiene la política de claves para la misma clave de KMS. El parámetro output con un valor de text devuelve un formato de texto que es fácil de leer.

aws kms get-key-policy \
    --policy-name default \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --output text

Salida:

{
    "Version" : "2012-10-17",
    "Id" : "key-default-1",
    "Statement" : [
        {
            "Sid" : "Enable IAM User Permissions",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:root"
            },
            "Action" : "kms:*",
            "Resource" : "*"
            },
            {
            "Sid" : "Allow Use of Key",
            "Effect" : "Allow",
            "Principal" : {
                "AWS" : "arn:aws:iam::111122223333:user/test-user"
            },
            "Action" : [ "kms:Describe", "kms:List" ],
            "Resource" : "*"
        }
    ]
}

Para obtener más información, consulte Cambio de una política de claves en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: Cómo volver a cifrar un mensaje cifrado con una clave de KMS simétrica diferente (Linux y macOS).

El siguiente ejemplo de re-encrypt comando muestra la forma recomendada de volver a cifrar los datos con la CLI AWS .

Proporcione el texto cifrado de un archivo. En el valor del parámetro --ciphertext-blob, utilice el prefijo fileb://, que indica a la CLI que lea los datos de un archivo binario. Si el archivo no se encuentra en el directorio actual, escriba la ruta completa al archivo. Para obtener más información sobre la lectura de los valores de los parámetros AWS CLI de un archivo, consulte Carga de parámetros AWS CLI desde un archivo en la Guía del usuario de la interfaz de línea de AWS comandos y Prácticas recomendadas para los parámetros de archivos locales en el blog de herramientas de línea de AWS comandos. Especifique la clave KMS de origen, que descifra el texto cifrado. El --source-key-id parámetro no es necesario al descifrar con claves KMS de cifrado simétrico. AWS KMS puede obtener la clave KMS que se utilizó para cifrar los datos de los metadatos del blob de texto cifrado. Pero siempre es una práctica recomendada especificar la clave KMS que está utilizando. Esta práctica garantiza que utilice la clave de KMS pretendida y le impide descifrar inadvertidamente un texto cifrado mediante una clave de KMS en la que no confía. Especifique la clave de KMS de destino, que vuelve a cifrar los datos. El parámetro --destination-key-id siempre es obligatorio. En este ejemplo, se utiliza un ARN de clave, pero se puede utilizar cualquier identificador de clave válido. Solicite la salida de texto sin formato como un valor de texto. El parámetro --query indica a la CLI que obtenga únicamente el valor del campo Plaintext de la salida. El parámetro --output devuelve la salida como texto. Decodifique en base64 el texto sin formato y guárdelo en un archivo. El siguiente ejemplo canaliza (|) el valor del parámetro Plaintext a la utilidad Base64, que lo decodifica. A continuación, redirige (>) la salida descodificada al archivo ExamplePlaintext.

Antes de ejecutar este comando, sustituya la clave de ejemplo por los identificadores de clave IDs válidos de su cuenta. AWS

aws kms re-encrypt \
    --ciphertext-blob fileb://ExampleEncryptedFile \
    --source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --query CiphertextBlob \
    --output text | base64 --decode > ExampleReEncryptedFile

Este comando no genera ninguna salida. La salida del comando re-encrypt se descodifica en base64 y se guarda en un archivo.

Para obtener más información, consulta la referencia ReEncryptde la API del Servicio de administración de AWS claves.

Ejemplo 2: Cómo volver a cifrar un mensaje cifrado con una clave de KMS simétrica diferente (Linux y macOS).

El siguiente comando re-encrypt de ejemplo es el mismo que el anterior, excepto que usa la utilidad certutil para descodificar en Base64 los datos de texto sin formato. Como se muestra en los siguientes ejemplos, este procedimiento requiere dos comandos.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su AWS cuenta.

aws kms re-encrypt ^
    --ciphertext-blob fileb://ExampleEncryptedFile ^
    --source-key-id 1234abcd-12ab-34cd-56ef-1234567890ab ^
    --destination-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 ^
    --query CiphertextBlob ^
    --output text > ExampleReEncryptedFile.base64

A continuación, use la utilidad certutil

certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile

Salida:

Input Length = 18
Output Length = 12
CertUtil: -decode command completed successfully.

Para obtener más información, consulta la referencia ReEncryptde la API del Servicio de administración de AWS claves.

Retirada de una concesión en una clave maestra de cliente

En el siguiente ejemplo de retire-grant se elimina una concesión de una clave de KMS.

El siguiente comando de ejemplo especifica los parámetros grant-id y key-id. El valor del parámetro key-id debe ser el ARN de la clave de KMS.

aws kms retire-grant \
    --grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
    --key-id arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no genera ninguna salida. Utilice el comando list-grants para confirmar que la concesión se ha retirado.

Para obtener más información, consulte Retiro y revocación de concesiones en la Guía para desarrolladores de AWS Key Management Service.

Revocación de una concesión en una clave maestra de cliente

En el siguiente ejemplo de revoke-grant se elimina una concesión de una clave de KMS. El siguiente comando de ejemplo especifica los parámetros grant-id y key-id. El valor del parámetro key-id puede ser el ID de clave o el ARN de la clave de KMS.

aws kms revoke-grant \
    --grant-id 1234a2345b8a4e350500d432bccf8ecd6506710e1391880c4f7f7140160c9af3 \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no genera ninguna salida. Utilice el comando list-grants para confirmar que la concesión se ha revocado.

Para obtener más información, consulte Retiro y revocación de concesiones en la Guía para desarrolladores de AWS Key Management Service.

Para realizar rotación bajo demanda de una clave de KMS

El siguiente ejemplo de rotate-key-on-demand inicia inmediatamente la rotación del material de claves para la clave de KMS especificada.

aws kms rotate-key-on-demand \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Salida:

{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}

Para obtener más información, consulte How to perform on-demand key rotation en la Guía para desarrolladores de AWS Key Management Service.

Programación de la eliminación de una clave de KMS administrada por el cliente.

En el siguiente ejemplo de schedule-key-deletion se programa la eliminación de la clave de KMS administrada por el cliente especificada en 15 días.

El parámetro --key-id identifica las claves KMS. En este ejemplo, se utiliza un valor de ARN clave, pero puede utilizar el ID de clave o el ARN de la clave de KMS. El parámetro --pending-window-in-days especifica la duración del período de espera de 7 a 30 días. De forma predeterminada, el periodo de espera es de 30 días. En este ejemplo se especifica un valor de 15, que indica que hay que AWS eliminar permanentemente la clave KMS 15 días después de que se complete el comando.

aws kms schedule-key-deletion \
    --key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --pending-window-in-days 15

La respuesta incluye el ARN de la clave, el estado de la clave, el período de espera (PendingWindowInDays) y la fecha de eliminación en tiempo Unix. Para ver la fecha de eliminación en hora local, utilice la consola AWS KMS. Las claves KMS en el estado de clave PendingDeletion no se pueden utilizar en operaciones criptográficas.

{
    "KeyId": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "DeletionDate": "2022-06-18T23:43:51.272000+00:00",
    "KeyState": "PendingDeletion",
    "PendingWindowInDays": 15
}

Para obtener más información, consulte Eliminación de claves en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: generar una firma digital para un mensaje

El siguiente ejemplo de sign genera una firma criptográfica para un mensaje corto. El resultado del comando incluye un campo de Signature codificado en Base64 que puede comprobar mediante el comando verify.

Debe especificar un mensaje para firmar y un algoritmo de firma que admita su clave KMS asimétrica. Para obtener los algoritmos de firma de su clave KMS, utilice el comando describe-key.

En AWS CLI v2, el valor del message parámetro debe estar codificado en Base64. O bien, puede guardar el mensaje en un archivo y usar el fileb:// prefijo, que indica a la AWS CLI que lea los datos binarios del archivo.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su AWS cuenta. El ID de clave debe representar una clave KMS asimétrica con un uso de clave de SIGN_VERIFY.

msg=(echo 'Hello World' | base64)

aws kms sign \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://UnsignedMessage \
    --message-type RAW \
    --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "Signature": "ABCDEFhpyVYyTxbafE74ccSvEJLJr3zuoV1Hfymz4qv+/fxmxNLA7SE1SiF8lHw80fKZZ3bJ...",
    "SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}

Para obtener más información sobre el uso de claves KMS asimétricas en AWS KMS, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Ejemplo 2: guardar una firma digital en un archivo (Linux y macOS)

El siguiente ejemplo de sign genera una firma criptográfica para un mensaje corto almacenado en un archivo local. El comando también obtiene la Signature propiedad de la respuesta, la decodifica en Base64 y la guarda en el archivo. ExampleSignature Puede usar el archivo de firmas en un comando verify que verifique la firma.

El comando sign requiere un mensaje codificado en Base64 y un algoritmo de firma que admita su clave KMS asimétrica. Para obtener los algoritmos de firma que admite su clave KMS, utilice el comando describe-key.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su cuenta. AWS El ID de clave debe representar una clave KMS asimétrica con un uso de clave de SIGN_VERIFY.

echo 'hello world' | base64 > EncodedMessage

aws kms sign \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://EncodedMessage \
    --message-type RAW \
    --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
    --output text \
    --query Signature | base64 --decode > ExampleSignature

Este comando no genera ninguna salida. En este ejemplo, se extrae la propiedad Signature del resultado y se guarda en un archivo.

Para obtener más información sobre el uso de claves KMS asimétricas en AWS KMS, consulte Claves asimétricas en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Para agregar una etiqueta a una clave de KMS

En el siguiente ejemplo de tag-resource, se agregan las etiquetas "Purpose":"Test" y "Dept":"IT" a una clave KMS administrada por el cliente. Puede usar etiquetas como estas para etiquetar las claves KMS y crear categorías de claves KMS para permisos y auditoría.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un valor de ID de clave, pero puede utilizar un ID de clave o un ARN de clave en este comando.

aws kms tag-resource \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --tags TagKey='Purpose',TagValue='Test' TagKey='Dept',TagValue='IT'

Este comando no genera ninguna salida. Para ver las etiquetas de una clave AWS KMS de KMS, utilice el list-resource-tags comando.

Para obtener más información sobre el uso de etiquetas en AWS KMS, consulte Etiquetado de claves en la Guía para desarrolladores del Servicio de administración de AWS claves.

Para eliminar una etiqueta de una clave de KMS

En el siguiente ejemplo de untag-resource se elimina la etiqueta con la clave "Purpose" de una clave de KMS administrada por el cliente.

Para especificar la clave de KMS, utilice el parámetro key-id. En este ejemplo, se utiliza un valor de ID de clave, pero puede utilizar un ID de clave o un ARN de clave en este comando. Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su AWS cuenta.

aws kms untag-resource \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --tag-key 'Purpose'

Este comando no genera ninguna salida. Para ver las etiquetas de una clave AWS KMS de KMS, utilice el list-resource-tags comando.

Para obtener más información sobre el uso de etiquetas en AWS KMS, consulte Etiquetado de claves en la Guía para desarrolladores del Servicio de administración de AWS claves.

Asociación de un alias a una clave de KMS diferente

En el siguiente ejemplo de update-alias se asocia el alias alias/test-key a una clave de KMS diferente.

El parámetro --alias-name especifica el alias. El valor del nombre del alias debe empezar por alias/. El parámetro --target-key-id especifica la clave de KMS que se va a asociar al alias. No es necesario especificar la clave de KMS actual para el alias.

aws kms update-alias \
    --alias-name alias/test-key \
    --target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Este comando no genera ninguna salida. Utilice el comando list-aliases para encontrar el alias.

Para obtener más información, consulte Actualización de alias en la AWS Guía para desarrolladores de Key Management Service.

Ejemplo 1: editar el nombre descriptivo de un almacén de claves personalizado

En el siguiente ejemplo de update-custom-key-store se cambia el nombre del almacén de claves personalizado. Este ejemplo funciona para un almacén de claves de AWS CloudHSM o un almacén de claves externo.

Utilice el custom-key-store-id para identificar el almacén de claves. Utilice el parámetro new-custom-key-store-name para especificar el nuevo nombre descriptivo.

Para actualizar el nombre descriptivo de un almacén de claves de AWS CloudHSM, primero debe desconectar el almacén de claves, por ejemplo, mediante el comando. disconnect-custom-key-store Puede actualizar el nombre descriptivo de un almacén de claves externo mientras esté conectado o desconectado. Para buscar el estado de conexión del almacén de claves personalizado, utilice el comando describe-custom-key-store.

aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --new-custom-key-store-name ExampleKeyStore

Este comando no devuelve ningún dato. Para comprobar si el comando ha funcionado, utilice un comando describe-custom-key-stores.

Para obtener más información sobre la actualización de un almacén de claves de AWS CloudHSM, consulte Edición de la configuración del almacén de claves de AWS CloudHSM en la Guía para desarrolladores de Key Management Service.AWS

Para obtener más información sobre cómo actualizar un almacén de claves externo, consulte Editing external key store properties en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 2: Para editar la contraseña kmsuser de un almacén de claves de CloudHSM AWS

En el siguiente ejemplo de update-custom-key-store se actualiza el valor de la contraseña kmsuser a la contraseña actual del kmsuser en el clúster de CloudHSM asociado al almacén de claves especificado. Este comando no cambia la contraseña kmsuser del clúster. Simplemente indica a AWS KMS la contraseña actual. Si KMS no tiene la kmsuser contraseña actual, no podrá conectarse al almacén de claves de AWS CloudHSM.

NOTA: Antes de actualizar un almacén de claves de AWS CloudHSM, debe desconectarlo. Utilice el comando disconnect-custom-key-store. Cuando se complete el comando, puede volver a conectar el almacén de claves de AWS CloudHSM. Utilice el comando connect-custom-key-store.

aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --key-store-password ExamplePassword

El comando no devuelve ningún resultado. Para comprobar que el comando ha sido efectivo, utilice el comando describe-custom-key-stores.

Para obtener más información sobre la actualización de un almacén de claves de AWS CloudHSM, consulte Edición de la configuración del almacén de claves de AWS CloudHSM en la Guía para desarrolladores de Key Management Service.AWS

Ejemplo 3: Para editar el clúster de AWS CloudHSM de un AWS almacén de claves de CloudHSM

El siguiente ejemplo cambia el clúster de AWS CloudHSM que está asociado a un almacén de claves de AWS CloudHSM por un clúster relacionado, por ejemplo, una copia de seguridad diferente del mismo clúster.

NOTA: Antes de actualizar un almacén de claves de AWS CloudHSM, debe desconectarlo. Utilice el comando disconnect-custom-key-store. Cuando se complete el comando, puede volver a conectar el almacén de claves de AWS CloudHSM. Utilice el comando connect-custom-key-store.

aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --cloud-hsm-cluster-id cluster-1a23b4cdefg

El comando no devuelve ningún resultado. Para comprobar que el comando ha sido efectivo, utilice el comando describe-custom-key-stores.

Para obtener más información sobre la actualización de un almacén de claves de AWS CloudHSM, consulte Edición de la configuración del almacén de claves de AWS CloudHSM en la Guía para desarrolladores de Key Management Service.AWS

Ejemplo 4: editar la credencial de autenticación proxy de un almacén de claves externo

En el siguiente ejemplo se actualiza la credencial de autenticación del proxy para el almacén de claves externo. Debe especificar el raw-secret-access-key y el access-key-id, incluso si cambia solo uno de los valores. Puede utilizar esta característica para corregir una credencial no válida o cambiarla cuando la rota el proxy del almacén de claves externo.

Establezca la credencial de autenticación proxy para AWS KMS en su almacén de claves externo. A continuación, utilice este comando para proporcionar la credencial a AWS KMS. AWS KMS usa esta credencial para firmar sus solicitudes en el proxy de su almacén de claves externo.

Puede actualizar la credencial de autenticación del proxy mientras el almacén de claves externo esté conectado o desconectado. Para buscar el estado de conexión del almacén de claves personalizado, utilice el comando describe-custom-key-store.

aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --xks-proxy-authentication-credential "AccessKeyId=ABCDE12345670EXAMPLE, RawSecretAccessKey=DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="

El comando no devuelve ningún resultado. Para comprobar que el comando ha sido efectivo, utilice el comando describe-custom-key-stores.

Para obtener más información sobre cómo actualizar un almacén de claves externo, consulte Editing external key store properties en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 5: editar la conectividad del proxy de un almacén de claves externo

En el siguiente ejemplo se cambia la opción de conectividad del proxy del almacén de claves externo de conectividad de punto de conexión público a punto de conexión de servicio de punto de conexión de VPC. Además de cambiar el valor de xks-proxy-connectivity, debe cambiar el valor de xks-proxy-uri-endpoint para que refleje el nombre de DNS privado asociado al servicio de punto de conexión de VPC. También debe añadir un valor de xks-proxy-vpc-endpoint-service-name.

NOTA: Antes de actualizar la conectividad del proxy de un almacén externo debe desconectarlo. Utilice el comando disconnect-custom-key-store. Una vez completado el comando, puede volver a conectar el almacén de claves externo mediante el comando connect-custom-key-store.

aws kms update-custom-key-store \
    --custom-key-store-id cks-1234567890abcdef0 \
    --xks-proxy-connectivity VPC_ENDPOINT_SERVICE \
    --xks-proxy-uri-endpoint "https://myproxy-private.xks.example.com" \
    --xks-proxy-vpc-endpoint-service-name "com.amazonaws.vpce.us-east-1.vpce-svc-example"

El comando no devuelve ningún resultado. Para comprobar que el comando ha sido efectivo, utilice el comando describe-custom-key-stores.

Para obtener más información sobre cómo actualizar un almacén de claves externo, consulte Editing external key store properties en la Guía para desarrolladores de AWS Key Management Service.

Ejemplo 1: agregar o cambiar una descripción de una clave de KMS administrada por el cliente

En el siguiente ejemplo de update-key-description se agrega una descripción a una clave de KMS administrada por el cliente. Puede utilizar el mismo comando para cambiar una descripción existente.

El parámetro --key-id identifica la clave de KMS en el comando. En este ejemplo se utiliza un valor de ARN de clave, pero puede utilizar el ID de clave o el ARN de la clave de KMS. El parámetro --description especifica la nueva descripción. El valor de este parámetro reemplaza a la descripción actual de la clave de KMS, si la hay.

aws kms update-key-description \
    --key-id arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab \
    --description "IT Department test key"

Este comando no genera ninguna salida. Para ver la descripción de una clave de KMS, utilice el comando describe-key.

Para obtener más información, consulte la referencia UpdateKeyDescriptionde la API del Servicio de administración de AWS claves.

Ejemplo 2: eliminar la descripción de una clave de KMS administrada por el cliente

El siguiente ejemplo de update-key-description elimina la descripción de una clave de KMS administrada por el cliente

El parámetro --key-id identifica la clave de KMS en el comando. En este ejemplo se utiliza un valor de ID de clave, pero puede utilizar el ID de clave o el ARN de clave de la clave de KMS. El parámetro --description con un valor de cadena vacío ('') elimina la descripción existente.

aws kms update-key-description \
    --key-id 0987dcba-09fe-87dc-65ba-ab0987654321 \
    --description ''

Este comando no genera ninguna salida. Para ver la descripción de una clave de KMS, utilice el comando describe-key.

Para obtener más información, consulte la referencia UpdateKeyDescriptionde la API del Servicio de administración de AWS claves.

Ejemplo 1: Verificación de un HMAC

El siguiente comando verify-mac verifica un HMAC para un mensaje específico, claves KMS HMAC y un algoritmo MAC. Un valor de «verdadero» en el MacValid valor de la respuesta indica que el HMAC es válido.

En AWS CLI v2, el valor del message parámetro debe estar codificado en Base64. O bien, puede guardar el mensaje en un archivo y usar el fileb:// prefijo, que indica a la AWS CLI que lea los datos binarios del archivo.

El MAC que especifique no puede estar codificado en base64. Para obtener ayuda para decodificar el MAC que devuelve el comando generate-mac, consulte los ejemplos de comandos generate-mac.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su AWS cuenta. El ID de clave debe representar una clave KMS HMAC con un uso de clave de GENERATE_VERIFY_MAC.

msg=(echo 'Hello World' | base64)

aws kms verify-mac \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://Message \
    --mac-algorithm HMAC_SHA_384 \
    --mac fileb://ExampleMac

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "MacValid": true,
    "MacAlgorithm": "HMAC_SHA_384"
}

Para obtener más información sobre el uso de las claves HMAC KMS en AWS KMS, consulte las claves HMAC en AWS KMS en la Guía para desarrolladores del Servicio de administración de AWS claves.

Para verificar una firma digital

En el siguiente ejemplo de verify, se verifica una firma criptográfica para un mensaje corto codificado en Base64. El identificador de clave, el mensaje, el tipo de mensaje y el algoritmo de firma deben ser los mismos que se usaron para firmar el mensaje.

En AWS CLI v2, el valor del message parámetro debe estar codificado en Base64. O bien, puede guardar el mensaje en un archivo y usar el fileb:// prefijo, que indica a la AWS CLI que lea los datos binarios del archivo.

La firma que especifique no puede estar codificada en base64. Para obtener ayuda para decodificar la firma que devuelve el comando sign, consulte los ejemplos de comandos sign.

El resultado del comando incluye un campo SignatureValid booleano que indica que se verificó la firma. Si se produce un error en la validación de la firma, también se produce un error en el comando verify.

Antes de ejecutar este comando, sustituya la ID de clave de ejemplo por una ID de clave válida de su AWS cuenta.

aws kms verify \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --message fileb://EncodedMessage \
    --message-type RAW \
    --signing-algorithm RSASSA_PKCS1_V1_5_SHA_256 \
    --signature fileb://ExampleSignature

Salida:

{
    "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "SignatureValid": true,
    "SigningAlgorithm": "RSASSA_PKCS1_V1_5_SHA_256"
}

Para obtener más información sobre el uso de claves KMS asimétricas en AWS KMS, consulte Uso de claves asimétricas en la Guía para desarrolladores del Servicio de administración de AWS claves.