Esempi di AWS KMS con la AWS CLI

Come annullare l’eliminazione pianificata di una chiave KMS gestita dal cliente

L’esempio cancel-key-deletion seguente annulla l’eliminazione pianificata di una chiave KMS gestita dal cliente.

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

Output:

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

Quando il comando cancel-key-deletion ha esito positivo, l’eliminazione pianificata viene annullata. Tuttavia, lo stato della chiave KMS è Disabled, quindi non è possibile utilizzare la chiave KMS nelle operazioni di crittografia. Per ripristinarne la funzionalità, utilizza il comando enable-key.

Per ulteriori informazioni, consulta Pianificazione e annullamento dell’eliminazione di chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come connettere un archivio chiavi personalizzato

L’esempio connect-custom-key-store seguente riconnette l’archivio chiavi personalizzato specificato. È possibile utilizzare un comando come questo per connettere un archivio chiavi personalizzato per la prima volta o per riconnetterne uno disconnesso.

È possibile utilizzare questo comando per connettere un archivio chiavi AWS CloudHSM o un archivio chiavi esterno.

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

Questo comando non restituisce alcun output. Per verificare che il comando sia stato eseguito correttamente, utilizza il comando describe-custom-key-stores.

Per informazioni sulla connessione di un archivio chiavi AWS CloudHSM, consulta Connessione e disconnessione di un archivio delle chiavi di AWS CloudHSM nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Per informazioni sulla connessione di un archivio chiavi esterno, consulta Connessione e disconnessione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come creare un alias per una chiave KMS

Il comando create-alias seguente crea un alias denominato example-alias per la chiave KMS identificata dall’ID chiave 1234abcd-12ab-34cd-56ef-1234567890ab.

Un nome di alias deve iniziare con alias/. Non utilizzare nomi di alias che iniziano con alias/aws in quanto questi sono riservati solo per l’uso da parte di AWS.

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

Questo comando non restituisce output. Per visualizzare il nuovo alias, utilizza il comando list-aliases.

Per ulteriori informazioni, consulta Utilizzo di alias nella Guida per gli sviluppatori di Servizio AWS di gestione delle chiavi.

Esempio 1: per creare un archivio chiavi AWS CloudHSM

L’esempio create-custom-key-store seguente crea un archivio chiavi AWS CloudHSM supportato da un cluster AWS CloudHSM utilizzando i parametri richiesti. Puoi anche utilizzare custom-key-store-type``parameter with the default value: ``AWS_CLOUDHSM.

Per specificare l’input del file per il comando trust-anchor-certificate nell’AWS CLI, è necessario il prefisso file://.

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

Output:

{
    "CustomKeyStoreId": cks-1234567890abcdef0
}

Per ulteriori informazioni, consulta Creating an AWS CloudHSM key store nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per creare un archivio chiavi esterno con connettività dell’endpoint pubblico

L’esempio create-custom-key-store seguente crea un archivio chiavi esterno (XKS) che comunica con AWS KMS tramite Internet.

In questo esempio, XksProxyUriPath utilizza un prefisso opzionale di example-prefix.

NOTA: se utilizzi l’AWS CLI versione 1.0, esegui il comando seguente prima di specificare un parametro con un valore HTTP o HTTPS, ad esempio il parametro XksProxyUriEndpoint.

aws configure set cli_follow_urlparam false

In caso contrario, l’AWS CLI versione 1.0 sostituisce il valore del parametro con il contenuto trovato in tale indirizzo 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="

Output:

{
    "CustomKeyStoreId": cks-2234567890abcdef0
}

Per ulteriori informazioni, consulta Creazione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 3: per creare un archivio chiavi esterno con connettività di servizio dell’endpoint VPC

L’esempio create-custom-key-store seguente crea un archivio chiavi esterno (XKS) che utilizza un servizio di endpoint Amazon VPC per comunicare con AWS KMS.

NOTA: se utilizzi l’AWS CLI versione 1.0, esegui il comando seguente prima di specificare un parametro con un valore HTTP o HTTPS, ad esempio il parametro XksProxyUriEndpoint.

aws configure set cli_follow_urlparam false

In caso contrario, l’AWS CLI versione 1.0 sostituisce il valore del parametro con il contenuto trovato in tale indirizzo 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="

Output:

{
    "CustomKeyStoreId": cks-3234567890abcdef0
}

Per ulteriori informazioni, consulta Creazione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come creare una concessione

L’esempio create-grant seguente crea una concessione che consente all’utente exampleUser di utilizzare il comando decrypt sulla chiave KMS di esempio 1234abcd-12ab-34cd-56ef-1234567890ab. Il principale in fase di ritiro è il ruolo adminRole. La concessione utilizza il vincolo di concessione EncryptionContextSubset per consentire questa autorizzazione solo quando il contesto di crittografia nella richiesta decrypt include la coppia chiave-valore "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

Output:

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

Per visualizzare informazioni dettagliate sulla concessione, utilizza il comando list-grants.

Per ulteriori informazioni, consulta Grants in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per creare una chiave KMS gestita dal cliente in AWS KMS

L’esempio create-key seguente crea una chiave KMS di crittografia simmetrica.

Per creare la chiave KMS di base, una chiave di crittografia simmetrica, non è necessario specificare alcun parametro. I valori predefiniti per questi parametri creano una chiave di crittografia simmetrica.

Poiché questo comando non specifica una policy della chiave, la chiave KMS ottiene la policy di chiave predefinita per le chiavi KMS create a livello di programmazione. Per visualizzare la policy della chiave, utilizza il comando get-key-policy. Per modificare la policy della chiave, utilizza il comando put-key-policy.

aws kms create-key

Il comando create-key restituisce i metadati della chiave, inclusi l’ID chiave e l’ARN della nuova chiave KMS. Questi valori possono essere utilizzati per identificare la chiave KMS in altre operazioni AWS KMS. L’output non include i tag. Per visualizzare i tag di una chiave KMS, utilizza list-resource-tags command.

Output:

{
    "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: il comando create-key non consente di specificare un alias. Per creare un alias per la nuova chiave KMS, utilizza il comando create-alias.

Per ulteriori informazioni, consulta Creazione di chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per creare una chiave KMS RSA asimmetrica per la crittografia e la decrittografia

L’esempio create-key seguente crea una chiave KMS contenente una coppia di chiavi RSA asimmetriche per la crittografia e la decrittografia. La specifica e l’utilizzo della chiave non possono essere modificati dopo che la chiave è stata creata.

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

Output:

{
    "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"
    }
}

Per ulteriori informazioni, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 3: per creare una chiave KMS asimmetrica a curva ellittica per la firma e la verifica

Per creare una chiave KMS asimmetrica contenente una coppia di chiavi asimmetriche basate su curva ellittica (ECC) per la firma e la verifica. Il parametro --key-usage è obbligatorio anche se SIGN_VERIFY è l’unico valore valido per le chiavi KMS ECC. La specifica e l’utilizzo della chiave non possono essere modificati dopo che la chiave è stata creata.

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

Output:

{
    "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"
        ]
    }
}

Per ulteriori informazioni, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 4: per creare una chiave KMS ML-DSA asimmetrica per la firma e la verifica

Questo esempio crea una chiave basata sullo schema ML-DSA (Module-Lattice Digital Signature Algorithm) per la firma e la verifica. Il parametro key-usage è obbligatorio anche se SIGN_VERIFY è l’unico valore valido per le chiavi ML-DSA.

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

Output:

{
    "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"
        ]
    }
}

Per ulteriori informazioni, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 5: per creare una chiave KMS HMAC

L’esempio create-key seguente crea una chiave KMS HMAC a 384 bit. Il valore GENERATE_VERIFY_MAC del parametro --key-usage è obbligatorio anche se è l’unico valore valido per le chiavi KMS HMAC.

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

Output:

{
    "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"
    }
}

Per ulteriori informazioni, consulta HMAC keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 6: per creare una chiave KMS primaria multi-Regione

L’esempio create-key seguente crea una chiave di crittografia simmetrica primaria multi-Regione. Poiché i valori predefiniti per tutti i parametri creano una chiave di crittografia simmetrica, per questa chiave KMS è richiesto solo il parametro --multi-region. Nell’AWS CLI, per indicare che un parametro booleano è true, è sufficiente specificare il nome del parametro.

aws kms create-key \
    --multi-region

Output:

{
    "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"
    }
}

Per ulteriori informazioni, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 7: per creare una chiave KMS per il materiale della chiave importato

L’esempio create-key seguente crea una chiave KMS senza materiale di chiave. Quando l’operazione è stata completata, puoi importare il materiale della chiave nella chiave KMS. Per creare questa chiave KMS, imposta il parametro --origin su EXTERNAL.

aws kms create-key \
    --origin EXTERNAL

Output:

{
     "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"
     }
 }

Per ulteriori informazioni, consulta Importing key material in AWS KMS keys nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 6: per creare una chiave KMS in un archivio chiavi AWS CloudHSM

L’esempio create-key seguente crea una chiave KMS nell’archivio chiavi AWS CloudHSM specificato. L’operazione crea la chiave KMS e i relativi metadati in AWS KMS e crea il materiale della chiave nel cluster AWS CloudHSM associato all’archivio chiavi personalizzato. I parametri --custom-key-store-id e --origin sono obbligatori.

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

Output:

{
    "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"
    }
}

Per ulteriori informazioni, consulta AWS CloudHSM key stores nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 8: per creare una chiave KMS in un archivio chiavi esterno

L’esempio create-key seguente crea una chiave KMS nell’archivio chiavi esterno specificato. I parametri --custom-key-store-id, --origin e --xks-key-id sono tutti obbligatori in questo comando.

Il parametro --xks-key-id specifica l’ID di una chiave di crittografia simmetrica esistente nel gestore chiavi esterno. Questa chiave funge da materiale della chiave esterna per la chiave KMS. Il valore del parametro --origin deve essere EXTERNAL_KEY_STORE. Il parametro custom-key-store-id deve identificare un archivio chiavi esterno collegato al proxy dell’archivio chiavi esterno.

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

Output:

{
    "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"
        }
    }
}

Per ulteriori informazioni, consulta Archivi delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per decrittografare un messaggio crittografato con una chiave KMS simmetrica (Linux e macOS)

Il seguente esempio di comando decrypt mostra il metodo consigliato per decrittografare i dati con l’AWS CLI. Questa versione mostra come decrittografare i dati con una chiave KMS simmetrica.

Fornisci il testo criptato in un file. Nel valore del parametro --ciphertext-blob utilizza il prefisso fileb:// per indicare alla CLI di leggere i dati da un file binario. Se il file non è presente nella directory corrente, digita il percorso completo del file. Per ulteriori informazioni sulla lettura dei valori dei parametri dell’AWS CLI da un file, consulta Loading AWS CLI parameters from a file <https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html> nella Guida per l’utente dell’interfaccia a riga di comando di AWS e Best Practices for Local File Parameters<https://aws.amazon.com/blogs/developer/best-practices-for-local-file-parameters/> nel blog dello strumento della riga di comando AWS. Specifica la chiave KMS per decrittografare il testo criptato. Il parametro --key-id non è obbligatorio per la decrittografia mediante una chiave KMS simmetrica. AWS KMS può recuperare l’ID della chiave KMS utilizzata per crittografare i dati dai metadati nel testo criptato. Tuttavia è sempre consigliabile specificare la chiave KMS che stai utilizzando. Questa procedura consente di utilizzare la chiave KMS desiderata e impedire di decrittografare inavvertitamente un testo criptato utilizzando una chiave KMS non attendibile. Richiedi l’output in testo non crittografato come valore di testo. Il parametro --query indica alla CLI di recuperare solo il valore del campo Plaintext dall’output. Il parametro --output restituisce l’output come testo. Procedi a decrittografare in formato Base64 il testo non crittografato e a salvarlo in un file. Nell’esempio seguente il valore del parametro Plaintext viene inviato (|) all’utilità Base64, che lo decodifica. Quindi, reindirizza (>) l’output decodificato al file ExamplePlaintext.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Questo comando non produce alcun output. L’output del comando decrypt viene decrittografato in formato Base64 e salvato in un file.

Per ulteriori informazioni, consulta Decrypt nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 2: per decrittografare un messaggio crittografato con una chiave KMS simmetrica (prompt dei comandi di Windows)

L’esempio seguente è lo stesso del precedente, tranne per il fatto che utilizza l’utilità certutil per decrittografato in formato Base64 i dati del testo non crittografato. Questa procedura richiede due comandi, come illustrato negli esempi seguenti.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Esegui il comando certutil.

certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile

Output:

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

Per ulteriori informazioni, consulta Decrypt nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 3: per decrittografare un messaggio crittografato con una chiave KMS asimmetrica (Linux e macOS)

Il seguente esempio di comando decrypt mostra come decrittografare i dati crittografati con una chiave KMS asimmetrica RSA.

Quando si utilizza una chiave KMS asimmetrica, il parametro encryption-algorithm obbligatorio specifica l’algoritmo utilizzato per crittografare il testo non crittografato.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Questo comando non produce alcun output. L’output del comando decrypt viene decrittografato in formato Base64 e salvato in un file.

Per ulteriori informazioni, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come eliminare un alias AWS KMS

L’esempio delete-alias seguente elimina l’alias alias/example-alias. Il nome di alias deve iniziare con alias/.

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

Questo comando non produce alcun output. Per cercare l’alias, utilizza il comando list-aliases.

Per ulteriori informazioni, consulta Eliminazione di un alias nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come eliminare un archivio chiavi personalizzato

L’esempio delete-custom-key-store seguente elimina l’archivio chiavi personalizzato specificato.

L’eliminazione di un archivio chiavi AWS CloudHSM non ha alcun effetto sul cluster CloudHSM associato. L’eliminazione di un archivio chiavi esterno non ha alcun effetto sul relativo proxy, sul gestore chiavi esterno o sulle chiavi esterne associati.

NOTA: prima di poter eliminare un archivio chiavi personalizzato, è necessario pianificare l’eliminazione di tutte le chiavi KMS nell’archivio chiavi personalizzato e quindi attendere che tali chiavi KMS vengano eliminate. Quindi, è necessario disconnettere l’archivio chiavi personalizzato. Per assistenza nella ricerca delle chiavi KMS nell’archivio chiavi personalizzato, consulta Delete an AWS CloudHSM key store (API) nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

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

Questo comando non restituisce alcun output. Per verificare che l’archivio chiavi personalizzato sia stato eliminato, utilizza il comando describe-custom-key-stores.

Per informazioni sull’eliminazione di un archivio chiavi AWS CloudHSM, consulta Deleting an AWS CloudHSM key store nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Per informazioni sull’eliminazione di archivi chiavi esterni, consulta Eliminazione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come eliminare il materiale della chiave importato da una chiave KMS

L’esempio delete-imported-key-material seguente elimina il materiale della chiave importato in una chiave KMS.

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

Output:

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

Per ulteriori informazioni, consulta Eliminazione del materiale della chiave importato nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come derivare un segreto condiviso

L’esempio derive-shared-secret seguente deriva un segreto condiviso utilizzando un algoritmo di chiave concordata.

È necessario utilizzare una coppia di chiavi KMS asimmetrica a curva ellittica (ECC) o SM2 (solo Regioni della Cina) consigliata dal NIST con un valore di KeyUsage pari a KEY_AGREEMENT per chiamare DeriveSharedSecret.

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

Output:

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

Per ulteriori informazioni, consulta DeriveSharedSecret nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 1: per ottenere dettagli su un archivio chiavi AWS CloudHSM

L’esempio describe-custom-key-store seguente visualizza i dettagli sull’archivio chiavi AWS CloudHSM specificato. Il comando è lo stesso per tutti i tipi di archivi chiavi personalizzati, ma l’output differisce a seconda del tipo di archivio chiavi e, per un archivio chiavi esterno, della relativa opzione di connettività.

Per impostazione predefinita, questo comando visualizza informazioni su tutti gli archivi chiavi personalizzati nell’account e nella Regione. Per visualizzare informazioni su un determinato archivio chiavi personalizzato, utilizza il parametro custom-key-store-name o custom-key-store-id.

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

L’output di questo comando include dettagli utili sull’archivio chiavi AWS CloudHSM, incluso lo stato della connessione (ConnectionState). Se lo stato della connessione è FAILED, l’output include un campo ConnectionErrorCode che descrive il problema.

Output:

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

Per ulteriori informazioni, consulta Viewing an AWS CloudHSM key store nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per ottenere dettagli su un archivio chiavi esterno con connettività dell’endpoint pubblico

L’esempio describe-custom-key-store seguente visualizza i dettagli sull’archivio chiavi esterno specificato. Il comando è lo stesso per tutti i tipi di archivi chiavi personalizzati, ma l’output differisce a seconda del tipo di archivio chiavi e, per un archivio chiavi esterno, della relativa opzione di connettività.

Per impostazione predefinita, questo comando visualizza informazioni su tutti gli archivi chiavi personalizzati nell’account e nella Regione. Per visualizzare informazioni su un determinato archivio chiavi personalizzato, utilizza il parametro custom-key-store-name o custom-key-store-id.

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

L’output di questo comando include dettagli utili sull’archivio chiavi esterno, incluso lo stato della connessione (ConnectionState). Se lo stato della connessione è FAILED, l’output include un campo ConnectionErrorCode che descrive il problema.

Output:

{
    "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"
            }
        }
    ]
}

Per ulteriori informazioni, consulta Visualizzazione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 3: per ottenere dettagli su un archivio chiavi esterno con connettività di servizio dell’endpoint VPC

L’esempio describe-custom-key-store seguente visualizza i dettagli sull’archivio chiavi esterno specificato. Il comando è lo stesso per tutti i tipi di archivi chiavi personalizzati, ma l’output differisce a seconda del tipo di archivio chiavi e, per un archivio chiavi esterno, della relativa opzione di connettività.

Per impostazione predefinita, questo comando visualizza informazioni su tutti gli archivi chiavi personalizzati nell’account e nella Regione. Per visualizzare informazioni su un determinato archivio chiavi personalizzato, utilizza il parametro custom-key-store-name o custom-key-store-id.

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

L’output di questo comando include dettagli utili sull’archivio chiavi esterno, incluso lo stato della connessione (ConnectionState). Se lo stato della connessione è FAILED, l’output include un campo ConnectionErrorCode che descrive il problema.

Output:

{
    "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"
            }
        }
    ]
}

Per ulteriori informazioni, consulta Visualizzazione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per trovare informazioni dettagliate su una chiave KMS

L’esempio describe-key seguente ottiene informazioni dettagliate sulla chiave AWS gestita per Amazon S3 nell’account e nella Regione di esempio. Puoi utilizzare questo comando per trovare dettagli sulle chiavi gestite da AWS e sulle chiavi gestite dai clienti.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un valore per il nome di alias, ma in questo comando puoi utilizzare un ID di chiave, un ARN di chiave o un ARN di alias.

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

Output:

{
    "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"
        ]
    }
}

Per ulteriori informazioni, consulta Visualizzazione di chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per ottenere dettagli su una chiave KMS RSA asimmetrica

L’esempio describe-key seguente ottiene informazioni dettagliate su una chiave KMS RSA asimmetrica utilizzata per la firma e la verifica.

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

Output:

{
    "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"
        ]
    }
}

Esempio 3: per ottenere dettagli su una chiave di replica multi-Regione

L’esempio describe-key seguente ottiene i metadati per una chiave di replica multi-Regione. Questa chiave multi-Regione è una chiave di crittografia simmetrica. L’output di un comando describe-key per qualsiasi chiave multi-Regione restituisce informazioni sulla chiave primaria e su tutte le relative repliche.

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

Output:

{
    "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"
                }
            ]
        }
    }
}

Esempio 4: per ottenere dettagli su una chiave KMS HMAC

L’esempio describe-key seguente ottiene informazioni dettagliate su una chiave KMS HMAC.

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

Output:

{
    "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
    }
}

Come disabilitare la rotazione automatica di una chiave KMS

L’esempio disable-key-rotation seguente disabilita la rotazione automatica di una chiave KMS gestita dal cliente. Per riabilitare la rotazione automatica, utilizza il comando enable-key-rotation.

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

Questo comando non produce alcun output. Per verificare che la rotazione automatica sia disabilitata per la chiave KMS, utilizza il comando get-key-rotation-status.

Per ulteriori informazioni, consulta Rotazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come disabilitare temporaneamente una chiave KMS

Il seguente comando disable-key disabilita una chiave KMS gestita dal cliente. Per riabilitare la chiave KMS, utilizza il comando enable-key.

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

Questo comando non produce alcun output.

Per ulteriori informazioni, consulta Abilitazione e disabilitazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come disconnettere un archivio chiavi personalizzato

L’esempio disconnect-custom-key-store seguente disconnette un archivio chiavi personalizzato dal relativo cluster AWS CloudHSM. È possibile disconnettere un archivio chiavi per risolvere un problema, aggiornarne le impostazioni o impedire l’utilizzo delle chiavi KMS nell’archivio chiavi nelle operazioni crittografiche.

Questo comando è uguale per tutti gli archivi chiavi personalizzati, inclusi gli archivi chiavi AWS CloudHSM e gli archivi chiavi esterni.

Prima di eseguire questo comando, sostituisci l'ID store chiavi personalizzate di esempio con uno valido.

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

Questo comando non produce alcun output. Verifica che il comando sia stato eseguito correttamente utilizzando il comando describe-custom-key-stores.

Per ulteriori informazioni sulla disconnessione di un archivio chiavi AWS CloudHSM, consulta Connessione e disconnessione di un archivio delle chiavi di AWS CloudHSM nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Per ulteriori informazioni sulla disconnessione di un archivio chiavi esterno, consulta Connessione e disconnessione di un archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come abilitare la rotazione automatica di una chiave KMS

L’esempio enable-key-rotation seguente abilita la rotazione automatica di una chiave KMS gestita dal cliente con un periodo di rotazione di 180 giorni. La rotazione della chiave KMS avviene dopo un anno (circa 365 giorni) dalla data di completamento di questo comando e successivamente ogni anno.

Il parametro --key-id identifica la chiave KMS. Questo esempio utilizza un valore ARN della chiave, ma è possibile utilizzare l’ID chiave o l’ARN della chiave KMS. Il parametro --rotation-period-in-days specifica il numero di giorni tra ogni data di rotazione. Specifica un valore compreso tra 90 e 2.560 giorni. Se non viene specificato alcun valore, il valore predefinito è 365 giorni.

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

Questo comando non produce alcun output. Per verificare se la chiave KMS è abilitata, utilizza il comando get-key-rotation-status.

Per ulteriori informazioni, consulta Rotazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come abilitare una chiave KMS

L’esempio enable-key seguente abilita una chiave gestita dal cliente. Puoi utilizzare un comando come il seguente per abilitare una chiave KMS temporaneamente disabilitata utilizzando il comando disable-key. Puoi anche usarlo per abilitare una chiave KMS disabilitata perché era stata pianificata per l’eliminazione e l’eliminazione è stata annullata.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un valore per l’ID chiave, ma in questo comando puoi utilizzare un ID o un ARN di chiave.

Prima di eseguire questo comando, sostituisci l’ID della chiave di esempio con un ID valido.

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

Questo comando non produce alcun output. Per verificare se la chiave KMS è abilitata, utilizza il comando describe-key. Verifica i valori dei campi KeyState e Enabled nell’output di describe-key.

Per ulteriori informazioni, consulta Abilitazione e disabilitazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per crittografare il contenuto di un file in Linux o macOS

Il seguente comando encrypt illustra il metodo consigliato per crittografare i dati con l’AWS CLI.

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

Il comando esegue diverse operazioni:

Utilizza il parametro --plaintext per indicare i dati da crittografare. Il valore di questo parametro deve essere decrittografato in formato Base64. Il valore del parametro plaintext deve essere codificato in formato Base64 oppure è necessario utilizzare il prefisso fileb://, che indica all’AWS CLI di leggere i dati binari dal file. Se il file non si trova nella directory corrente, specifica il percorso completo del file. Ad esempio: fileb:///var/tmp/ExamplePlaintextFile o fileb://C:\Temp\ExamplePlaintextFile. Per ulteriori informazioni sulla lettura dei valori dei parametri dell’AWS CLI da un file, consulta Caricamento di parametri da un file nella Guida per l’utente dell’interfaccia a riga di comando AWS e Best Practices for Local File Parameters nel blog dello strumento della riga di comando AWS. Utilizza i parametri --output e --query per controllare l’output del comando. Questi parametri estraggono i dati crittografati, definiti testo criptato, dall’output del comando. Per ulteriori informazioni sul controllo dell’output, consulta Controllo dell’output dei comandi nella Guida per l’utente dell’interfaccia a riga di comando AWS. Utilizza l’utilità base64 per decodificare l’output estratto in dati binari. Il testo criptato restituito dalla corretta esecuzione del comando encrypt è un testo crittografato in formato Base64. È necessario decodificare questo testo prima di poter utilizzare l’AWS CLI per decrittografarlo. Salva il testo criptato binario in un file. La parte finale del comando (> ExampleEncryptedFile) salva il testo criptato binario in un file per semplificare la decrittografia. Per un comando di esempio che utilizza l’AWS CLI per decrittografare i dati, consulta gli esempi di decrittografia.

Esempio 2: utilizzo dell’AWS CLI per crittografare i dati in Windows

Questo esempio è uguale a quello precedente, tranne per il fatto che utilizza lo strumento certutil al posto di base64. Questa procedura richiede due comandi, come illustrato nell’esempio seguente.

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

Esempio 3: crittografia con una chiave KMS asimmetrica

Il seguente comando encrypt mostra come crittografare il testo non crittografato con una chiave KMS asimmetrica. Il parametro --encryption-algorithm è obbligatorio. Come in tutti i comandi dell’encrypt CLI, il parametro plaintext deve essere crittografato in formato Base64 oppure è necessario utilizzare il prefisso fileb://, che indica all’AWS CLI di leggere i dati binari dal file.

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

Questo comando non produce alcun output.

Come generare una coppia di chiavi dati asimmetriche ECC NIST P384

L’esempio generate-data-key-pair-without-plaintext seguente richiede una coppia di chiavi ECC NIST P384 da utilizzare all’esterno di AWS.

Il comando restituisce una chiave pubblica in testo normale e una copia della chiave privata crittografata con la chiave KMS specificata. Non restituisce una chiave privata in testo normale. È possibile archiviare la chiave privata crittografata con i dati crittografati e chiamare AWS KMS per decrittografare la chiave privata quando è necessario utilizzarla.

Per richiedere una coppia di chiavi dati asimmetriche ECC NIST P384, utilizza il parametro key-pair-spec con un valore di ECC_NIST_P384.

La chiave KMS specificata deve essere una chiave KMS di crittografia simmetrica, ovvero una chiave KMS con un valore di KeySpec pari a SYMMETRIC_DEFAULT.

NOTA: i valori nell’output di questo esempio vengono troncati ai fini della visualizzazione.

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

Output:

{
    "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"
}

PublicKey e PrivateKeyCiphertextBlob vengono restituiti crittografati in formato Base64.

Per ulteriori informazioni, consulta Coppia di chiavi di dati nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come generare una coppia di chiavi dati asimmetriche RSA a 2.048 bit

L’esempio generate-data-key-pair seguente richiede una coppia di chiavi dati asimmetriche RSA a 2.048 bit da utilizzare all’esterno di AWS. Il comando restituisce una chiave pubblica in testo normale e una chiave privata in testo normale per l’utilizzo e l’eliminazione immediati, nonché una copia della chiave privata crittografata sotto la chiave KMS specificata. Puoi archiviare la chiave privata crittografata in modo sicuro con i dati crittografati.

Per richiedere una coppia di chiavi dati asimmetriche RSA a 2.048 bit, utilizza il parametro key-pair-spec con un valore di RSA_2048.

La chiave KMS specificata deve essere una chiave KMS di crittografia simmetrica, ovvero una chiave KMS con un valore di KeySpec pari a SYMMETRIC_DEFAULT.

NOTA: i valori nell’output di questo esempio vengono troncati ai fini della visualizzazione.

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

Output:

{
    "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"
}

PublicKey, PrivateKeyPlaintext e PrivateKeyCiphertextBlob vengono restituiti crittografati in formato Base64.

Per ulteriori informazioni, consulta Coppia di chiavi di dati nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come generare una chiave dati simmetrica a 256 bit senza una chiave in testo non crittografato

L’esempio generate-data-key-without-plaintext seguente richiede una copia crittografata di una chiave dati simmetrica a 256 bit da utilizzare all’esterno di AWS. Puoi eseguire una chiamata ad AWS KMS per decrittografare la chiave dati quando è il momento di utilizzarla.

Per richiedere una chiave dati a 256 bit, utilizza il parametro key-spec con il valore AES_256. Per richiedere una chiave dati a 128 bit, utilizza il parametro key-spec con il valore AES_128. Per tutte le altre lunghezze di chiavi dati, utilizza il parametro number-of-bytes.

La chiave KMS specificata deve essere una chiave KMS di crittografia simmetrica, ovvero una chiave KMS con un valore di KeySpec pari a 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

Output:

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

Il valore CiphertextBlob (chiave dati crittografati) viene restituito crittografato in formato Base64.

Per ulteriori informazioni, consulta Chiavi di dati nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per generare una chiave dati simmetrica a 256 bit

L’esempio generate-data-key seguente richiede una chiave dati simmetrica a 256 bit da utilizzare all’esterno di AWS. Il comando restituisce una chiave dati in testo non crittografato per l’utilizzo e l’eliminazione immediati e una copia di tale chiave dati crittografata sotto la chiave KMS specificata. Puoi archiviare la chiave di dati crittografata in modo sicuro con i dati crittografati.

Per richiedere una chiave dati a 256 bit, utilizza il parametro key-spec con il valore AES_256. Per richiedere una chiave dati a 128 bit, utilizza il parametro key-spec con il valore AES_128. Per tutte le altre lunghezze di chiavi dati, utilizza il parametro number-of-bytes.

La chiave KMS specificata deve essere una chiave KMS di crittografia simmetrica, ovvero una chiave KMS con un valore di KeySpec pari a SYMMETRIC_DEFAULT.

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

Output:

{
    "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="
}

I valori Plaintext (chiave dati in testo normale) CiphertextBlob e (chiave dati crittografata) vengono restituiti crittografati in formato Base64.

Per ulteriori informazioni, consulta Chiavi di dati nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi. Esempio 2: per generare una chiave dati simmetrica a 512 bit

L’esempio generate-data-key seguente richiede una chiave dati simmetrica a 512 bit per la crittografia e la decrittografia. Il comando restituisce una chiave dati in testo non crittografato per l’utilizzo e l’eliminazione immediati e una copia di tale chiave dati crittografata sotto la chiave KMS specificata. Puoi archiviare la chiave di dati crittografata in modo sicuro con i dati crittografati.

Per richiedere una lunghezza di chiave diversa da 128 o 256 bit, utilizza il parametro number-of-bytes. Per richiedere una chiave dati a 512 bit, l’esempio seguente utilizza il parametro number-of-bytes con il valore 64 (byte).

La chiave KMS specificata deve essere una chiave KMS di crittografia simmetrica, ovvero una chiave KMS con un valore di KeySpec pari a SYMMETRIC_DEFAULT.

NOTA: i valori nell’output di questo esempio vengono troncati ai fini della visualizzazione.

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

Output:

{
    "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"
}

I valori Plaintext (chiave di dati non crittografati) e CiphertextBlob (chiave di dati crittografati) vengono restituiti crittografati in formato Base64.

Per ulteriori informazioni, consulta Chiavi di dati nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per generare un codice HMAC per un messaggio

Il comando generate-mac seguente genera un codice HMAC per un messaggio, una chiave KMS HMAC e un algoritmo MAC. L’algoritmo deve essere supportato dalla chiave KMS HMAC specificata.

Nell’AWS CLI v2, il valore del parametro message deve essere crittografato in formato Base64. In alternativa, puoi salvare il messaggio in un file e utilizzare il prefisso fileb://, che indica all’AWS CLI di leggere i dati binari dal file.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente. L’ID chiave deve rappresentare una chiave KMS HMAC con un utilizzo chiave di 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

Output:

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

Per ulteriori informazioni sull’utilizzo di chiavi KMS HMAC in AWS KMS, consulta Chiavi HMAC in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per salvare un codice HMAC in un file (Linux e macOS)

L’esempio generate-mac seguente genera un codice HMAC per un messaggio breve archiviato in un file locale. Il comando ottiene inoltre la proprietà Mac dalla risposta, applica la decrittografia Base64 e la salva nel file ExampleMac. Puoi utilizzare il file MAC in un comando verify-mac che verifica il codice MAC.

Il comando generate-mac richiede un messaggio crittografato in formato Base64 e un algoritmo MAC supportato dalla chiave KMS HMAC asimmetrica. Per ottenere gli algoritmi MAC supportati dalla chiave KMS, utilizza il comando describe-key.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente. L’ID chiave deve rappresentare una chiave KMS asimmetrica il cui utilizzo è definito da 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

Questo comando non produce alcun output. Questo esempio estrae la proprietà Mac dell’output e la salva in un file.

Per ulteriori informazioni sull’utilizzo di chiavi KMS HMAC in AWS KMS, consulta Chiavi HMAC in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per generare una stringa di byte casuale a 256 bit (Linux o macOS)

L’esempio generate-random seguente genera una stringa di byte casuali a 256 bit (32 byte) crittografata in formato Base64. L’esempio decodifica la stringa di byte e la salva in un file casuale.

Quando esegui questo comando, devi utilizzare il parametro number-of-bytes per specificare la lunghezza del valore casuale in byte.

Non viene specificata una chiave KMS quando si esegue questo comando. La stringa di byte casuali non è correlata ad alcuna chiave KMS.

Per impostazione predefinita, AWS KMS genera il numero casuale. Tuttavia, se specifichi un archivio chiavi personalizzato, la stringa di byte casuali viene generata nel cluster AWS CloudHSM associato all’archivio chiavi personalizzato.

Questo esempio utilizza i seguenti parametri e valori:

Utilizza il parametro obbligatorio --number-of-bytes con il valore 32 per richiedere una stringa a 32 byte (256 bit). Utilizza il parametro --output con il valore text per indicare all’AWS CLI di restituire l’output sotto forma di testo anziché in formato JSON. Utilizza --query parameter per estrarre il valore della proprietà Plaintext dalla risposta. Indirizza ( | ) l’output del comando all’utilità base64, che decodifica l’output estratto. Utilizza l’operatore di reindirizzamento ( > ) per salvare la stringa di byte decodificati nel file ExampleRandom. Utilizza l’operatore di reindirizzamento ( > ) per salvare il testo binario criptato in un file.

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

Questo comando non produce alcun output.

Per ulteriori informazioni, consulta GenerateRandom nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 2: per generare un numero casuale a 256 bit (prompt dei comandi di Windows)

L’esempio seguente utilizza il comando generate-random per generare una stringa di byte casuali a 256 bit (32 byte) crittografata in formato Base64. L’esempio decodifica la stringa di byte e la salva in un file casuale. Questo esempio è uguale all’esempio precedente tranne per il fatto che utilizza l’utilità certutil di Windows per decrittografare in formato Base64 la stringa di byte casuali prima di salvarla in un file.

Genera innanzitutto una stringa di byte casuali crittografata in formato Base64 e la salva nel file temporaneo ExampleRandom.base64.

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

Poiché l’output del comando generate-random viene salvato in un file, questo esempio non produce alcun output.

Ora utilizza il comando certutil -decode per decrittografare la stringa di byte crittografata in formato Base64 nel file ExampleRandom.base64. Quindi, salva la stringa di byte decodificata nel file ExampleRandom.

certutil -decode ExampleRandom.base64 ExampleRandom

Output:

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

Per ulteriori informazioni, consulta GenerateRandom nel riferimento API del Servizio AWS di gestione delle chiavi.

Come copiare una policy della chiave da una chiave KMS a un’altra

L’esempio get-key-policy seguente ottiene la policy della chiave da una chiave KMS e la salva in un file di testo. Sostituisce quindi la policy di una chiave KMS diversa utilizzando il file di testo come input della policy.

Poiché il parametro --policy di put-key-policy richiede una stringa, devi utilizzare l’opzione --output text per restituire l’output come stringa di testo anziché 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

Questo comando non produce alcun output.

Per ulteriori informazioni, consulta PutKeyPolicy nel riferimento API di AWS KMS.

Come recuperare lo stato di rotazione di una chiave KMS.

L’esempio get-key-rotation-status seguente restituisce informazioni sullo stato di rotazione della chiave KMS specificata, tra cui se la rotazione automatica è abilitata, il periodo di rotazione e la successiva data di rotazione pianificata. Puoi utilizzare questo comando sulle chiavi KMS gestite dal cliente e sulle chiavi KMS gestite da AWS. Tuttavia, tutte le chiavi KMS gestite da AWS vengono ruotate automaticamente ogni anno.

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

Output:

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

Per ulteriori informazioni, consulta Rotazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come ottenere gli elementi necessari per importare il materiale della chiave in una chiave KMS

L’esempio get-parameters-for-import seguente ottiene la chiave pubblica e il token di importazione necessari per importare il materiale della chiave in una chiave KMS. Quando utilizzi il comando import-key-material, assicurati di utilizzare il token di importazione e il materiale della chiave crittografati dalla chiave pubblica restituiti nello stesso comando get-parameters-for-import. Inoltre, l’algoritmo di wrapping specificato in questo comando deve essere utilizzato per crittografare il materiale della chiave con la chiave pubblica.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un ID chiave, ma in questo comando è possibile utilizzare un ID o un ARN di chiave.

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

Output:

{
    "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
}

Per ulteriori informazioni, consulta Scaricare la chiave pubblica e il token di importazione nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per scaricare la chiave pubblica di una chiave KMS asimmetrica

L’esempio get-public-key seguente scarica la chiave pubblica di una chiave KMS asimmetrica.

Oltre alla restituzione della chiave pubblica, l’output include informazioni necessarie per utilizzare la chiave pubblica in sicurezza all’esterno di AWS KMS, inclusi l’utilizzo della chiave e gli algoritmi di crittografia supportati.

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

Output:

{
    "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"
    ]
}

Per ulteriori informazioni sull’utilizzo di chiavi KMS asimmetriche in AWS KMS, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi. Esempio 2: per convertire una chiave pubblica in formato DER (Linux e macOS)

L’esempio get-public-key seguente scarica la chiave pubblica di una chiave KMS asimmetrica e la salva in un file DER.

Quando utilizzi il comando get-public-key nell’AWS CLI, restituisce una chiave pubblica X.509 con codifica DER e crittografata in formato Base64. Questo esempio ottiene il valore della proprietà PublicKey come testo. Applica la crittografia in formato Base64 della proprietà PublicKey e la salva nel file public_key.der. Il parametro output restituisce l’output come testo, anziché in formato JSON. Il parametro --query ottiene solo la proprietà PublicKey, non le proprietà necessarie per utilizzare la chiave pubblica in modo sicuro all’esterno di AWS KMS.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Questo comando non produce alcun output.

Per ulteriori informazioni sull’utilizzo di chiavi KMS asimmetriche in AWS KMS, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come importare il materiale della chiave in una chiave KMS

L’esempio import-key-material seguente carica il materiale della chiave in una chiave KMS creata senza il materiale della chiave. Lo stato della chiave KMS deve essere PendingImport.

Questo comando utilizza il materiale della chiave crittografato con la chiave pubblica restituita dal comando get-parameters-for-import. Utilizza anche il token di importazione dello stesso comando get-parameters-for-import.

Il parametro expiration-model indica che il materiale della chiave scade automaticamente alla data e all’ora specificate dal parametro valid-to. Quando il materiale della chiave scade, AWS KMS elimina tale materiale, lo stato della chiave KMS cambia in Pending import e la chiave KMS diventa inutilizzabile. Per ripristinare la chiave KMS, è necessario importare nuovamente lo stesso materiale della chiave. Per utilizzare un materiale della chiave diverso, è necessario creare una nuova chiave KMS.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID o un ARN di chiave valido dall’account AWS corrente.

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

Output:

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

Per ulteriori informazioni sull’importazione del materiale delle chiavi, consulta Importazione del materiale delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per elencare tutti gli alias in un account e in una Regione AWS

L’esempio seguente utilizza il comando list-aliases per elencare tutti gli alias nella Regione predefinita dell’account AWS. L’output include alias associati a chiavi KMS gestite da AWS e a chiavi KMS e gestite dal cliente.

aws kms list-aliases

Output:

{
    "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"
        },
        ...
    ]
}

Esempio 2: per elencare tutti gli alias per una particolare chiave KMS

L’esempio seguente utilizza il comando list-aliases e il relativo parametro key-id per elencare tutti gli alias associati a una particolare chiave KMS.

Ogni alias è associato a una sola chiave KMS, ma una chiave KMS può avere più alias. Questo comando è molto utile perché la Console AWS KMS riporta solo un alias per ogni chiave KMS. Per trovare tutti gli alias di una chiave KMS, devi utilizzare il comando list-aliases.

Questo esempio utilizza l’ID della chiave KMS per il parametro --key-id, ma in questo comando puoi utilizzare un ID chiave, un ARN di chiave, un nome di alias o un ARN di alias.

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

Output:

{
    "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"
        }
    ]
}

Per ulteriori informazioni, consulta Utilizzo degli alias nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come visualizzare le concessioni relative a una chiave AWS KMS

L’esempio list-grants seguente mostra tutte le concessioni sulla chiave KMS AWS gestita specificata per Amazon DynamoDB nel tuo account. Questa concessione consente a DynamoDB di utilizzare la chiave KMS per tuo conto per crittografare una tabella DynamoDB prima di scriverla su disco. Puoi utilizzare un comando simile per visualizzare le concessioni relative alle chiavi KMS gestite da AWS e alle chiavi KMS gestite dal cliente nell’account e nella Regione AWS.

Questo comando utilizza il parametro key-id con un ID chiave per identificare la chiave KMS. Puoi utilizzare un ID o un ARN di chiave per identificare la chiave KMS. Per ottenere l’ID o l’ARN di chiave di una chiave KMS gestita da AWS, utilizza il comando list-keys o list-aliases.

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

L’output mostra che la concessione assegna l’autorizzazione Amazon DynamoDB per utilizzare la chiave KMS per le operazioni di crittografia e visualizzare i dettagli sulla chiave KMS (DescribeKey) e di ritirare le concessioni (RetireGrant). Il vincolo EncryptionContextSubset limita queste autorizzazioni alle richieste che includono le coppie di contesti di crittografia specificate. Di conseguenza, le autorizzazioni incluse nella concessione sono valide solo per l’account e la tabella DynamoDB specificati.

{
    "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"
        }
    ]
}

Per ulteriori informazioni, consulta Grants in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come ottenere i nomi delle policy della chiave per una chiave KMS

L’esempio list-key-policies seguente ottiene i nomi delle policy della chiave per una chiave gestita dal cliente nell’account e nella Regione di esempio. Puoi utilizzare questo comando per trovare i nomi delle policy della chiave per le chiavi gestite da AWS e per le chiavi gestite dal cliente.

Poiché l’unico nome di policy della chiave valido è default, questo comando non è utile.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un valore per l’ID chiave, ma in questo comando è possibile utilizzare un ID o un ARN di chiave.

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

Output:

{
    "PolicyNames": [
    "default"
    ]
}

Per ulteriori informazioni sulle policy delle chiavi AWS KMS, consulta Using Key Policies in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come recuperare informazioni su tutte le rotazioni dei materiali della chiave completate

L’esempio list-key-rotations seguente elenca le informazioni su tutte le rotazioni del materiale della chiave completate per la chiave KMS specificata.

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

Output:

{
    "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
}

Per ulteriori informazioni, consulta Rotazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come ottenere le chiavi KMS in un account e in una Regione

L’esempio list-keys seguente ottiene le chiavi KMS in un account e in una Regione. Questo comando restituisce sia le chiavi gestite da AWS che le chiavi gestite dal cliente.

aws kms list-keys

Output:

{
    "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"
        }
    ]
}

Per ulteriori informazioni, consulta Visualizzazione di chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come ottenere i tag su una chiave KMS

L’esempio list-resource-tags seguente ottiene i tag per una chiave KMS. Per aggiungere o sostituire tag di risorsa sulle chiavi KMS, utilizza il comando tag-resource. L’output mostra che questa chiave KMS ha due tag di risorsa, ognuno dei quali ha una chiave e un valore.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un valore per l’ID chiave, ma in questo comando è possibile utilizzare un ID o un ARN di chiave.

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

Output:

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

Per informazioni sull’utilizzo dei tag in AWS KMS, consulta Chiavi di tagging nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come visualizzare le concessioni che un principale può ritirare

L’esempio list-retirable-grants seguente mostra tutte le concessioni che l’utente ExampleAdmin può ritirare con le chiavi KMS in un account e in una Regione AWS. Puoi usare un comando come questo per visualizzare le concessioni che qualsiasi principale di account può ritirare sulle chiavi KMS nell’account e nella Regione AWS.

Il valore del parametro retiring-principal obbligatorio deve essere il nome della risorsa Amazon (ARN) di un account, utente o ruolo.

Non è possibile specificare un servizio per il valore di retiring-principal in questo comando, anche se un servizio può essere il principale che esegue il ritiro. Per trovare le concessioni in cui un particolare servizio è il principale che esegue il ritiro, utilizza il comando list-grants.

L’output mostra che l’utente ExampleAdmin dispone dell’autorizzazione a ritirare le concessioni su due diverse chiavi KMS nell’account e nella Regione. Oltre al principale che esegue il ritiro, l’account è autorizzato a ritirare qualsiasi concessione nell’account.

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

Output:

{
    "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
}

Per ulteriori informazioni, consulta Grants in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come modificare la policy della chiave per una chiave KMS

L’esempio put-key-policy seguente modifica la policy della chiave per una chiave gestita dal cliente.

Per iniziare, crea una policy della chiave e salvala in un file JSON locale. In questo esempio, il file è key_policy.json. Puoi anche specificare la policy della chiave come valore di stringa del parametro policy.

La prima istruzione di questa policy della chiave concede all’account AWS l’autorizzazione a utilizzare le policy IAM per controllare l’accesso alla chiave KMS. La seconda istruzione concede all’utente test-user l’autorizzazione a eseguire i comandi describe-key e list-keys sulla chiave KMS.

Contenuto di 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" : "*"
        }
    ]
}

Per identificare la chiave KMS, questo esempio utilizza l’ID chiave, ma puoi utilizzare anche un ARN di chiave. Per specificare la policy della chiave, il comando utilizza il parametro policy. Per indicare che la policy è contenuta in un file, utilizza il prefisso obbligatorio file://. Questo prefisso è necessario per identificare i file in tutti i sistemi operativi supportati. Infine, il comando utilizza il parametro policy-name con il valore default. Se nessun nome di policy è specificato, il valore predefinito è default. L'unico valore valido è default.

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

Il comando non produce output. Per verificare che il comando sia stato eseguito correttamente, utilizza il comando get-key-policy. Il comando di esempio seguente ottiene la policy della chiave per la stessa chiave KMS. Il parametro output con il valore text restituisce un formato di testo facile da leggere.

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

Output:

{
    "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" : "*"
        }
    ]
}

Per ulteriori informazioni, consulta Modifica di una policy delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per ripetere la crittografia di un messaggio crittografato con una chiave KMS simmetrica diversa (Linux e macOS).

Il seguente comando re-encrypt di esempio illustra il metodo consigliato per ripetere la crittografia dei dati con l’AWS CLI.

Fornisci il testo criptato in un file. Nel valore del parametro --ciphertext-blob utilizza il prefisso fileb:// per indicare alla CLI di leggere i dati da un file binario. Se il file non è presente nella directory corrente, digita il percorso completo del file. Per ulteriori informazioni sulla lettura dei valori dei parametri dell’AWS CLI da un file, consulta Loading AWS CLI parameters from a file nella Guida per l’utente dell’interfaccia a riga di comando di AWS e Best Practices for Local File Parameters nel blog dello strumento della riga di comando di AWS. Specifica la chiave KMS di origine, che decrittografa il testo criptato. Il parametro --source-key-id non è obbligatorio quando si esegue la decrittografia con chiavi KMS di crittografia simmetrica. AWS KMS può recuperare la chiave KMS utilizzata per crittografare i dati dai metadati nel blob in testo criptato. Tuttavia è sempre consigliabile specificare la chiave KMS che stai utilizzando. Questa procedura garantisce di utilizzare la chiave KMS desiderata e impedisce di decrittografare inavvertitamente un testo criptato utilizzando una chiave KMS non attendibile. Specifica la chiave KMS di destinazione, che ripete la crittografia dei dati. Il parametro --destination-key-id è sempre obbligatorio. Questo esempio utilizza un ARN di chiave, ma puoi utilizzare qualsiasi identificatore di chiave valido. Richiedi l’output in testo normale come valore di testo. Il parametro --query indica alla CLI di recuperare solo il valore del campo Plaintext dall’output. Il parametro --output restituisce l’output come testo. Procedi a decrittografare in formato Base64 il testo non crittografato e a salvarlo in un file. Nell’esempio seguente il valore del parametro Plaintext viene inviato (|) all’utilità Base64, che lo decodifica. Quindi, reindirizza (>) l’output decodificato al file ExamplePlaintext.

Prima di eseguire questo comando, sostituisci gli ID chiave di esempio con identificatori di chiave validi dall’account AWS corrente.

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

Questo comando non produce alcun output. L’output del comando re-encrypt viene decrittografato in formato Base64 e salvato in un file.

Per ulteriori informazioni, consulta ReEncrypt nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 2: per crittografare di nuovo un messaggio crittografato con una chiave KMS simmetrica diversa (prompt dei comandi di Windows).

Il seguente comando re-encrypt di esempio è lo stesso del precedente, tranne per il fatto che utilizza l’utilità certutil per decrittografare in formato Base64 i dati in testo normale. Questa procedura richiede due comandi, come illustrato negli esempi seguenti.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Utilizza quindi l’utilità certutil

certutil -decode ExamplePlaintextFile.base64 ExamplePlaintextFile

Output:

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

Per ulteriori informazioni, consulta ReEncrypt nel riferimento API del Servizio AWS di gestione delle chiavi.

Come ritirare una concessione associata a una chiave principale del cliente

L’esempio retire-grant seguente elimina una concessione da una chiave KMS.

Il comando di esempio seguente specifica i parametri grant-id e key-id. Il valore del parametro key-id deve essere l’ARN della chiave KMS.

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

Questo comando non produce alcun output. Per confermare il ritiro della concessione, utilizza il comando list-grants.

Per ulteriori informazioni, consulta Ritirare e revocare le concessioni nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come revocare una concessione associata a una chiave principale del cliente

L’esempio revoke-grant seguente elimina una concessione da una chiave KMS. Il comando di esempio seguente specifica i parametri grant-id e key-id. Il valore del parametro key-id può essere l’ID o l’ARN della chiave KMS.

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

Questo comando non produce alcun output. Per confermare la revoca della concessione, utilizza il comando list-grants.

Per ulteriori informazioni, consulta Ritirare e revocare le concessioni nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come eseguire la rotazione on demand di una chiave KMS

L’esempio rotate-key-on-demand seguente avvia immediatamente la rotazione del materiale della chiave per la chiave KMS specificata.

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

Output:

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

Per ulteriori informazioni, consulta How to perform on-demand key rotation nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come pianificare l’eliminazione di una chiave KMS gestita dal cliente.

L’esempio schedule-key-deletion seguente pianifica l’eliminazione della chiave KMS gestita dal cliente specificata tra 15 giorni.

Il parametro --key-id identifica la chiave KMS. Questo esempio utilizza il valore di un ARN di chiave, ma puoi utilizzare l’ID o l’ARN della chiave KMS. Il parametro --pending-window-in-days specifica la durata del periodo di attesa (da 7 a 30 giorni). Per impostazione predefinita, il periodo di attesa è pari a 30 giorni. Questo esempio specifica il valore 15, che indica ad AWS di eliminare definitivamente la chiave KMS 15 giorni dopo il completamento del 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 risposta include l’ARN della chiave, lo stato della chiave, il periodo di attesa (PendingWindowInDays) e la data di eliminazione in formato Unix. Per visualizzare la data di eliminazione nell’ora locale, utilizza la Console AWS KMS. Le chiavi KMS con stato PendingDeletion non possono essere utilizzate nelle operazioni di crittografia.

{
    "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
}

Per ulteriori informazioni, consulta Eliminazione delle chiavi nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per generare una firma digitale per un messaggio

L’esempio sign seguente genera una firma crittografica per un messaggio breve. L’output del comando include un campo Signature crittografato in formato Base64 che è possibile verificare utilizzando il comando verify.

È necessario specificare un messaggio da firmare e un algoritmo di firma supportato dalla chiave KMS asimmetrica. Per ottenere gli algoritmi di firma per la chiave KMS, utilizza il comando describe-key.

Nell’AWS CLI v2, il valore del parametro message deve essere crittografato in formato Base64. In alternativa, puoi salvare il messaggio in un file e utilizzare il prefisso fileb://, che indica all’AWS CLI di leggere i dati binari dal file.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente. L’ID chiave deve rappresentare una chiave KMS asimmetrica il cui utilizzo è definito da 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

Output:

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

Per ulteriori informazioni sull’utilizzo di chiavi KMS asimmetriche in AWS KMS, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per salvare una firma digitale in un file (Linux e macOS)

L’esempio sign seguente genera una firma crittografica per un messaggio breve archiviato in un file locale. Il comando ottiene inoltre la proprietà Signature dalla risposta, applica la decrittografia in formato Base64 e la salva nel file ExampleSignature. Puoi utilizzare il file di firma in un comando verify che verifica la firma.

Il comando sign richiede un messaggio crittografato in formato Base64 e un algoritmo di firma supportato dalla chiave KMS asimmetrica. Per ottenere gli algoritmi di firma supportati dalla chiave KMS, utilizza il comando describe-key.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente. L’ID chiave deve rappresentare una chiave KMS asimmetrica il cui utilizzo è definito da 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

Questo comando non produce alcun output. Questo esempio estrae la proprietà Signature dell’output e la salva in un file.

Per ulteriori informazioni sull’utilizzo di chiavi KMS asimmetriche in AWS KMS, consulta Asymmetric keys in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come aggiungere un tag a una chiave KMS

L’esempio tag-resource seguente aggiunge i tag "Purpose":"Test" e "Dept":"IT" a una chiave KMS gestita dal cliente. Puoi utilizzare tag simili a quelli riportati di seguito per etichettare le chiavi KMS e creare categorie di chiavi KMS per le autorizzazioni e il controllo.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un valore per l’ID chiave, ma in questo comando è possibile utilizzare un ID o un ARN di chiave.

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

Questo comando non produce alcun output. Per visualizzare i tag su una chiave AWS KMS, utilizza il comando list-resource-tags.

Per informazioni sull’utilizzo dei tag in AWS KMS, consulta Chiavi di tagging nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come eliminare un tag da una chiave KMS

L’esempio untag-resource seguente elimina il tag con la chiave "Purpose" da una chiave KMS gestita dal cliente.

Per specificare la chiave KMS, utilizza il parametro key-id. Questo esempio utilizza un valore per l’ID chiave, ma in questo comando è possibile utilizzare un ID o un ARN di chiave. Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Questo comando non produce alcun output. Per visualizzare i tag su una chiave AWS KMS, utilizza il comando list-resource-tags.

Per informazioni sull’utilizzo dei tag in AWS KMS, consulta Chiavi di tagging nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come associare un alias a una chiave KMS diversa

L’esempio update-alias seguente associa l’alias alias/test-key a una chiave KMS diversa.

Il parametro --alias-name specifica l’alias. Il valore del nome dell’alias deve iniziare con alias/. Il parametro --target-key-id specifica la chiave KMS da associare all’alias. Non è necessario specificare la chiave KMS corrente per l’alias.

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

Questo comando non produce alcun output. Per cercare l’alias, utilizza il comando list-aliases.

Per ulteriori informazioni, consulta Aggiornamento degli alias nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per modificare il nome descrittivo di un archivio chiavi personalizzato

L’esempio update-custom-key-store seguente modifica il nome dell’archivio chiavi personalizzato. Questo esempio funziona per un archivio chiavi AWS CloudHSM o per un archivio chiavi esterno.

Utilizza custom-key-store-id per identificare l’archivio chiavi. Utilizza il parametro new-custom-key-store-name per specificare il nuovo nome descrittivo.

Per aggiornare il nome descrittivo di un archivio chiavi AWS CloudHSM, devi prima disconnetterlo, ad esempio utilizzando il comando disconnect-custom-key-store. Puoi aggiornare il nome descrittivo di un archivio chiavi esterno mentre è connesso o disconnesso. Per individuare lo stato di connessione dell’archivio chiavi personalizzato, utilizza il comando describe-custom-key-store.

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

Questo comando non restituisce dati. Per verificare che il comando funzioni, utilizza un comando describe-custom-key-stores.

Per informazioni sull’aggiornamento di un archivio chiavi AWS CloudHSM, consulta Editing AWS CloudHSM key store settings nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Per informazioni sull’aggiornamento di un archivio chiavi esterno, consulta Modifica delle proprietà dell’archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 2: per modificare la password kmsuser di un archivio chiavi AWS CloudHSM

L’esempio update-custom-key-store seguente aggiorna il valore della password kmsuser con la password corrente per kmsuser nel cluster CloudHSM associato all’archivio chiavi specificato. Questo comando non modifica la password kmsuser del cluster. Indica solo ad AWS KMS la password corrente. Se KMS non ha la password kmsuser corrente, non può connettersi all’archivio chiavi AWS CloudHSM.

NOTA: prima di aggiornare un archivio chiavi AWS CloudHSM, è necessario disconnetterlo. Utilizza il comando disconnect-custom-key-store. Una volta completato il comando, puoi connettere l’archivio chiavi AWS CloudHSM. Utilizza il comando connect-custom-key-store.

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

Questo comando non restituisce alcun output. Per verificare che la modifica sia stata eseguita correttamente, utilizza un comando describe-custom-key-stores.

Per informazioni sull’aggiornamento di un archivio chiavi AWS CloudHSM, consulta Editing AWS CloudHSM key store settings nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 3: per modificare il cluster AWS CloudHSM di un archivio chiavi AWS CloudHSM

L’esempio seguente modifica il cluster AWS CloudHSM associato a un archivio chiavi AWS CloudHSM in un cluster correlato, ad esempio un backup diverso dello stesso cluster.

NOTA: prima di aggiornare un archivio chiavi AWS CloudHSM, è necessario disconnetterlo. Utilizza il comando disconnect-custom-key-store. Una volta completato il comando, puoi connettere l’archivio chiavi AWS CloudHSM. Utilizza il comando connect-custom-key-store.

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

Questo comando non restituisce alcun output. Per verificare che la modifica sia stata eseguita correttamente, utilizza un comando describe-custom-key-stores.

Per informazioni sull’aggiornamento di un archivio chiavi AWS CloudHSM, consulta Editing AWS CloudHSM key store settings nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 4: per modificare le credenziali di autenticazione proxy di un archivio chiavi esterno

L’esempio seguente aggiorna le credenziali di autenticazione proxy per l’archivio chiavi esterno. Devi specificare raw-secret-access-key e access-key-id, anche se modifichi solo uno dei valori. È possibile utilizzare questa funzionalità per correggere credenziali non valide o per modificarle quando il proxy dell’archivio chiavi esterno le ruota.

Crea le credenziali di autenticazione proxy per AWS KMS sull’archivio chiavi esterno. Quindi utilizza questo comando per fornire le credenziali a AWS KMS. AWS KMS utilizza queste credenziali per firmare le richieste indirizzate al proxy dell’archivio chiavi esterno.

Puoi aggiornare le credenziali di autenticazione proxy mentre l’archivio chiavi esterno è connesso o disconnesso. Per individuare lo stato di connessione dell’archivio chiavi personalizzato, utilizza il 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="

Questo comando non restituisce alcun output. Per verificare che la modifica sia stata eseguita correttamente, utilizza un comando describe-custom-key-stores.

Per informazioni sull’aggiornamento di un archivio chiavi esterno, consulta Modifica delle proprietà dell’archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 5: per modificare la connettività proxy di un archivio chiavi esterno

L’esempio seguente modifica l’opzione di connettività proxy dell’archivio chiavi esterno dalla connettività dell’endpoint pubblico alla connettività di servizio dell’endpoint VPC. Oltre a modificare il valore xks-proxy-connectivity, è necessario modificare il valore xks-proxy-uri-endpoint in modo che rifletta il nome DNS privato associato al servizio dell’endpoint VPC. È inoltre necessario aggiungere un valore xks-proxy-vpc-endpoint-service-name.

NOTA: prima di aggiornare la connettività proxy di un archivio esterno, è necessario disconnetterlo. Utilizza il comando disconnect-custom-key-store. Al completamento del comando, è possibile riconnettere l’archivio chiavi esterno utilizzando il 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"

Questo comando non restituisce alcun output. Per verificare che la modifica sia stata eseguita correttamente, utilizza un comando describe-custom-key-stores.

Per informazioni sull’aggiornamento di un archivio chiavi esterno, consulta Modifica delle proprietà dell’archivio delle chiavi esterne nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Esempio 1: per aggiungere o modificare una descrizione in una chiave KMS gestita dal cliente

L’esempio update-key-description seguente aggiunge una descrizione a una chiave KMS gestita dal cliente. Puoi utilizzare lo stesso comando per modificare una descrizione esistente.

Il parametro --key-id identifica la chiave KMS nel comando. Questo esempio utilizza un valore ARN di chiave, ma è possibile utilizzare l’ID chiave o l’ARN della chiave KMS. Il parametro --description specifica la nuova descrizione. Il valore di questo parametro sostituisce l’eventuale descrizione corrente della chiave KMS.

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"

Questo comando non produce alcun output. Per visualizzare la descrizione di una chiave KMS, utilizza il comando describe-key.

Per ulteriori informazioni, consulta UpdateKeyDescription nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 2: per eliminare la descrizione di una chiave KMS gestita dal cliente

L’esempio update-key-description seguente elimina la descrizione da una chiave KMS gestita dal cliente.

Il parametro --key-id identifica la chiave KMS nel comando. Questo esempio utilizza un valore ID chiave, ma è possibile utilizzare l’ID chiave o l’ARN della chiave KMS. Il parametro --description con un valore di stringa vuoto (“) elimina la descrizione esistente.

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

Questo comando non produce alcun output. Per visualizzare la descrizione di una chiave KMS, utilizza il comando describe-key.

Per ulteriori informazioni, consulta UpdateKeyDescription nel riferimento API del Servizio AWS di gestione delle chiavi.

Esempio 1: per verificare un codice HMAC

Il comando verify-mac seguente verifica un codice HMAC per un particolare messaggio, chiavi KMS HMAC e un algoritmo MAC. Un valore “true” nel valore MacValid nella risposta indica che il codice HMAC è valido.

Nell’AWS CLI v2, il valore del parametro message deve essere crittografato in formato Base64. In alternativa, puoi salvare il messaggio in un file e utilizzare il prefisso fileb://, che indica all’AWS CLI di leggere i dati binari dal file.

Il codice MAC specificato non può essere crittografato in formato Base64. Per informazioni sulla decrittografia del codice MAC restituito dal comando generate-mac, consulta gli esempi del comando generate-mac.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente. L’ID chiave deve rappresentare una chiave KMS HMAC con un utilizzo chiave di 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

Output:

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

Per ulteriori informazioni sull’utilizzo di chiavi KMS HMAC in AWS KMS, consulta Chiavi HMAC in AWS KMS nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.

Come verificare una firma digitale

Il seguente comando verify verifica una firma crittografica per un breve messaggio crittografato in formato Base64. L’ID chiave, il messaggio, il tipo di messaggio e l’algoritmo di firma devono essere gli stessi utilizzati per firmare il messaggio.

Nell’AWS CLI v2, il valore del parametro message deve essere crittografato in formato Base64. In alternativa, puoi salvare il messaggio in un file e utilizzare il prefisso fileb://, che indica all’AWS CLI di leggere i dati binari dal file.

La firma specificata non può essere crittografata in formato Base64. Per informazioni sulla decrittografia della firma restituita dal comando sign, consulta gli esempi del comando sign.

L’output del comando include un campo booleano SignatureValid che indica che la firma è stata verificata. Se la convalida della firma ha esito negativo, anche il comando verify ha esito negativo.

Prima di eseguire questo comando, sostituisci l’ID chiave di esempio con un ID chiave valido nell’account AWS corrente.

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

Output:

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

Per ulteriori informazioni sull’utilizzo di chiavi KMS asimmetriche in AWS KMS, consulta Using asymmetric keys nella Guida per gli sviluppatori del Servizio AWS di gestione delle chiavi.