Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Provider JCE per AWS CloudHSM Client SDK 3 Il provider AWS CloudHSM JCE è un'implementazione del provider basata sul framework del provider Java Cryptographic Extension (JCE). JCE consente di eseguire operazioni di crittografia utilizzando Java Development Kit (JDK). In questa guida, il provider AWS CloudHSM JCE viene talvolta definito provider JCE. Utilizza il provider JCE e il JDK per trasferire le operazioni crittografiche sull'HSM. **Topics** + [Installare il provider JCE per AWS CloudHSM Client SDK 3](java-library-install.md) + [Nozioni di base sulla gestione delle chiavi nel provider JCE per Client SDK 3 AWS CloudHSM](java-library-key-basics.md) + [Meccanismi supportati per Client SDK 3 per AWS CloudHSM Client SDK 3](java-lib-supported.md) + [Attributi chiave Java supportati per AWS CloudHSM Client SDK 3](java-lib-attributes.md) + [Esempi di codice per la libreria AWS CloudHSM software per Java for Client SDK 3](java-samples_3.md) + [AWS CloudHSM KeyStore Classe Java per Client SDK 3](alternative-keystore.md) # Installare il provider JCE per AWS CloudHSM Client SDK 3 Prima di poter utilizzare il provider JCE, è necessario il AWS CloudHSM client. Il client è un demone che stabilisce una comunicazione end-to-end crittografata con i membri del HSMs cluster. Il provider JCE comunica localmente con il client. Se non hai installato e configurato il pacchetto AWS CloudHSM client, fallo ora seguendo la procedura riportata qui. [Installazione del client (Linux)](cmu-install-and-configure-client-linux.md) Dopo aver installato e configurato il client, esegui questo comando per avviarlo. È supportato solo sui sistemi operativi Linux e altri sistemi operativi compatibili. ------ #### [ Amazon Linux ] ``` $ sudo start cloudhsm-client ``` ------ #### [ Amazon Linux 2 ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ CentOS 7 ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ CentOS 8 ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ RHEL 7 ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ RHEL 8 ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl start cloudhsm-client ``` ------ #### [ Ubuntu 20.04 LTS ] ``` $ sudo systemctl start cloudhsm-client ``` ------ Utilizza le seguenti sezioni per installare, convalidare e fornire credenziali al provider. **Topics** + [Fase 1: Installare il provider JCE](#install-java-library) + [Fase 2: Convalidare l'installazione](#validate-install) + [Fase 3: Fornire le credenziali al provider JCE](#java-library-credentials) ## Fase 1: Installare il provider JCE Utilizza i seguenti comandi per scaricare e installare il provider JCE. Il provider è supportato solo sui sistemi operativi Linux e altri sistemi operativi compatibili. **Nota** Per l'aggiornamento, vedi [Aggiorna Client SDK 3](client-upgrade.md). ------ #### [ Amazon Linux ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-jce-latest.el6.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-client-jce-latest.el6.x86_64.rpm ``` ------ #### [ Amazon Linux 2 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-client-jce-latest.el7.x86_64.rpm ``` ------ #### [ CentOS 7 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-client-jce-latest.el7.x86_64.rpm ``` ------ #### [ CentOS 8 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-jce-latest.el8.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-client-jce-latest.el8.x86_64.rpm ``` ------ #### [ RHEL 7 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-client-jce-latest.el7.x86_64.rpm ``` ------ #### [ RHEL 8 ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-client-jce-latest.el8.x86_64.rpm ``` ``` $ sudo yum install ./cloudhsm-client-jce-latest.el8.x86_64.rpm ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-jce_latest_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-client-jce_latest_amd64.deb ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Bionic/cloudhsm-client-jce_latest_u18.04_amd64.deb ``` ``` $ sudo apt install ./cloudhsm-client-jce_latest_u18.04_amd64.deb ``` ------ Dopo aver eseguito i comandi precedenti, è possibile individuare i seguenti file della del provider JCE: + `/opt/cloudhsm/java/cloudhsm-.jar` + `/opt/cloudhsm/java/cloudhsm-test-.jar` + `/opt/cloudhsm/java/hamcrest-all-1.3.jar` + `/opt/cloudhsm/java/junit.jar` + `/opt/cloudhsm/java/log4j-api-2.17.1.jar` + `/opt/cloudhsm/java/log4j-core-2.17.1.jar` + `/opt/cloudhsm/lib/libcaviumjca.so` ## Fase 2: Convalidare l'installazione Esecuzione di operazioni di base sull’HSM per convalidare l'installazione. **Per convalidare l'installazione del provider JCE** 1. (Facoltativo) Se non hai già installato Java nell'ambiente, utilizza il comando seguente per installarlo. ------ #### [ Linux (and compatible libraries) ] ``` $ sudo yum install java-1.8.0-openjdk ``` ------ #### [ Ubuntu ] ``` $ sudo apt-get install openjdk-8-jre ``` ------ 1. Utilizza i seguenti comandi per impostare le variabili di ambiente necessarie. Sostituisci ** e ** con le credenziali di un utente crittografico (CU). ``` $ export LD_LIBRARY_PATH=/opt/cloudhsm/lib ``` ``` $ export HSM_PARTITION=PARTITION_1 ``` ``` $ export HSM_USER= ``` ``` $ export HSM_PASSWORD= ``` 1. Utilizza il seguente comando per eseguire il test di funzionalità di base. Se il comando viene eseguito correttamente, verrà visualizzato un output simile al seguente. ``` $ java8 -classpath "/opt/cloudhsm/java/*" org.junit.runner.JUnitCore TestBasicFunctionality JUnit version 4.11 .2018-08-20 17:53:48,514 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:33) - Adding provider. 2018-08-20 17:53:48,612 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:42) - Logging in. 2018-08-20 17:53:48,612 INFO [main] cfm2.LoginManager (LoginManager.java:104) - Looking for credentials in HsmCredentials.properties 2018-08-20 17:53:48,612 INFO [main] cfm2.LoginManager (LoginManager.java:122) - Looking for credentials in System.properties 2018-08-20 17:53:48,613 INFO [main] cfm2.LoginManager (LoginManager.java:130) - Looking for credentials in System.env SDK Version: 2.03 2018-08-20 17:53:48,655 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:54) - Generating AES Key with key size 256. 2018-08-20 17:53:48,698 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:63) - Encrypting with AES Key. 2018-08-20 17:53:48,705 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:84) - Deleting AES Key. 2018-08-20 17:53:48,707 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:92) - Logging out. Time: 0.205 OK (1 test) ``` ## Fase 3: Fornire le credenziali al provider JCE HSMs è necessario autenticare l'applicazione Java prima che l'applicazione possa utilizzarla. Ogni applicazione può utilizzare una sessione. HSMs autentica una sessione utilizzando il metodo di accesso esplicito o il metodo di accesso implicito. **Accesso Esplicito** – questo metodo consente di fornire le credenziali CloudHSM direttamente nell'applicazione. Utilizza il metodo `LoginManager.login()`, in cui si passa il nome utente, la password e l'ID della partizione HSM. Per ulteriori informazioni sull'utilizzo del metodo di accesso esplicito, vedi l'esempio di codice [Accesso a un HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java). **Accesso Implicito** – questo metodo consente di impostare le credenziali di CloudHSM in un nuovo file di proprietà, proprietà del sistema, oppure come variabili di ambiente. + **Nuovo file di proprietà** Crea un nuovo file con nome `HsmCredentials.properties` e aggiungilo al `CLASSPATH` della tua applicazione. Il file deve contenere il testo seguente: ``` HSM_PARTITION = PARTITION_1 HSM_USER = HSM_PASSWORD = ``` + **Proprietà di sistema** – Imposta le credenziali attraverso le proprietà di sistema durante l'esecuzione di un'applicazione. I seguenti esempi mostrano due modi differenti con cui è possibile eseguire questa operazione: ``` $ java -DHSM_PARTITION=PARTITION_1 -DHSM_USER= -DHSM_PASSWORD= ``` ``` System.setProperty("HSM_PARTITION","PARTITION_1"); System.setProperty("HSM_USER",""); System.setProperty("HSM_PASSWORD",""); ``` + **Variabili di ambiente** Imposta le credenziali come variabili di ambiente. ``` $ export HSM_PARTITION=PARTITION_1 $ export HSM_USER= $ export HSM_PASSWORD= ``` Le credenziali potrebbero non essere disponibili se l'applicazione non le fornisce o se viene eseguita un'operazione prima che l’HSM autentichi la sessione. In questi casi, la libreria software CloudHSM per Java cerca le credenziali nel seguente ordine: 1. `HsmCredentials.properties` 1. Proprietà di sistema 1. Variabili di ambiente **Gestione degli errori** La gestione degli errori è più facile con l'accesso esplicito rispetto al metodo di login implicito. Quando si utilizza la classe `LoginManager`, si dispone di un maggiore controllo sulla modalità con cui l'applicazione gestisce gli errori. Il metodo di accesso implicito rende difficile la comprensione della gestione degli errori quando le credenziali non sono valide o si verificano problemi nell'autenticazione della HSMs sessione. # Nozioni di base sulla gestione delle chiavi nel provider JCE per Client SDK 3 AWS CloudHSM Le nozioni di base sulla gestione delle chiavi nel provider JCE implicano l'importazione, l'esportazione, il caricamento tramite handle, oppure l'eliminazione di chiavi. Per ulteriori informazioni su come gestire le chiavi, vedi l'esempio di codice [Gestire le chiavi](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java). Puoi inoltre trovare ulteriori esempi di codice del provider JCE all'indirizzo[Esempi di codice](java-samples_3.md). # Meccanismi supportati per Client SDK 3 per AWS CloudHSM Client SDK 3 Questo argomento fornisce informazioni sui meccanismi supportati per il provider JCE con AWS CloudHSM Client SDK 3. Per informazioni sulle interfacce e le classi di motori Java Cryptography Architecture (JCA) supportate da AWS CloudHSM, consultate i seguenti argomenti. **Topics** + [Chiavi supportate](#java-keys) + [Cifrature supportate](#java-ciphers) + [Digest supportati](#java-digests) + [Algoritmi codice di autenticazione dei messaggi basato su hash (HMAC) supportati](#java-mac) + [Meccanismi supportati sign/verify](#java-sign-verify) + [Annotazioni sui meccanismi](#w2aac25c23c25c11c17) ## Chiavi supportate La libreria AWS CloudHSM software per Java consente di generare i seguenti tipi di chiavi. + AES - chiavi AES a 128, 192 e 256 bit. + DESede — Chiave 3DES a 92 bit. Vedi la nota [1](#java-keys-note-1) di seguito per una modifica imminente. + Coppie di chiavi ECC per curve NIST secp256r1 (P-256), secp384r1 (P-384), and secp256k1 (Blockchain). + RSA - chiavi RSA da 2048-bit a 4096-bit, con incrementi di 256 bit. Oltre ai parametri standard, supportiamo i seguenti parametri per ogni chiave generata. + **Etichetta**: un'etichetta della chiave che è possibile utilizzare per cercare le chiavi. + **è esportabile**: indica se la chiave può essere esportata dall'HSM. + **è Persistente**: indica se la chiave rimane sull'HSM quando la sessione corrente termina. **Nota** La libreria Java versione 3.1 offre la possibilità di specificare i parametri in modo più dettagliato. Per ulteriori informazioni, vedi la sezione relativa agli [attributi Java supportati](java-lib-attributes.md). ## Cifrature supportate La libreria AWS CloudHSM software per Java supporta le seguenti combinazioni di algoritmi, modalità e padding. | Algoritmo | Modalità | Padding | Note | | --- | --- | --- | --- | | AES | CBC | `AES/CBC/NoPadding` `AES/CBC/PKCS5Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. | | AES | ECB | `AES/ECB/NoPadding` `AES/ECB/PKCS5Padding` | Implementa Cipher.ENCRYPT\$1MODE e Cipher.DECRYPT\$1MODE. Usare AES di trasformazione. | | AES | CTR | `AES/CTR/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. | | AES | GCM | AES/GCM/NoPadding | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`, `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`.Quando si esegue la crittografia AES-GCM, l'HSM ignora il vettore di inizializzazione (IV) nella richiesta e utilizza un IV da lui generato. Al termine dell'operazione, è necessario chiamare `Cipher.getIV()` per ottenere il IV. | | AESWrap | ECB | `AESWrap/ECB/ZeroPadding` `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` | Implementa `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`, Usare AES di trasformazione. | | DESede (Triplo DES) | CBC | `DESede/CBC/NoPadding` `DESede/CBC/PKCS5Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Le routine di generazione della chiave accettano una dimensione di 168 o 192 bit. Tuttavia, internamente, tutte le DESede chiavi sono a 192 bit. Vedi la nota [1](#java-keys-note-1) di seguito per una modifica imminente. | | DESede (Triplo DES) | ECB | `DESede/ECB/NoPadding``DESede/ECB/PKCS5Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Le routine di generazione della chiave accettano una dimensione di 168 o 192 bit. Tuttavia, internamente, tutte le DESede chiavi sono a 192 bit. Vedi la nota [1](#java-keys-note-1) di seguito per una modifica imminente. | | RSA | ECB | `RSA/ECB/NoPadding``RSA/ECB/PKCS1Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Vedi la nota [1](#java-keys-note-1) di seguito per una modifica imminente. | | RSA | ECB | `RSA/ECB/OAEPPadding` `RSA/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-512ANDMGF1Padding` | Implementa `Cipher.ENCRYPT_MODE`, `Cipher.DECRYPT_MODE`, `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`. `OAEPPadding` è `OAEP` con il tipo di padding `SHA-1`. | | RSAAESWrap | ECB | OAEPPADDING | Implementa Cipher.WRAP\$1Mode e Cipher.UNWRAP\$1MODE. | ## Digest supportati La libreria AWS CloudHSM software per Java supporta i seguenti digest di messaggi. + `SHA-1` + `SHA-224` + `SHA-256` + `SHA-384` + `SHA-512` **Nota** I dati di lunghezza inferiore a 16 KB vengono sottoposti a hashing nell'HSM, mentre i dati di dimensioni maggiori vengono sottoposti a hashing nel software. ## Algoritmi codice di autenticazione dei messaggi basato su hash (HMAC) supportati La libreria AWS CloudHSM software per Java supporta i seguenti algoritmi HMAC. + `HmacSHA1` + `HmacSHA224` + `HmacSHA256` + `HmacSHA384` + `HmacSHA512` ## Meccanismi supportati sign/verify La libreria AWS CloudHSM software per Java supporta i seguenti tipi di firma e verifica. **Tipi di firma RSA** + `NONEwithRSA` + `SHA1withRSA` + `SHA224withRSA` + `SHA256withRSA` + `SHA384withRSA` + `SHA512withRSA` + `SHA1withRSA/PSS` + `SHA224withRSA/PSS` + `SHA256withRSA/PSS` + `SHA384withRSA/PSS` + `SHA512withRSA/PSS` **Tipi di firma ECDSA** + `NONEwithECDSA` + `SHA1withECDSA` + `SHA224withECDSA` + `SHA256withECDSA` + `SHA384withECDSA` + `SHA512withECDSA` ## Annotazioni sui meccanismi [1] In conformità con le linee guida del NIST, ciò non è consentito per i cluster in modalità FIPS dopo il 2023. Per i cluster in modalità non FIPS, è ancora consentito dopo il 2023. Per informazioni dettagliate, vedi [Conformità FIPS 140: meccanismo di deprecazione 2024](compliance-dep-notif.md#compliance-dep-notif-1). # Attributi chiave Java supportati per AWS CloudHSM Client SDK 3 Questo argomento descrive come utilizzare un'estensione proprietaria per la versione 3.1 della libreria Java per impostare gli attributi chiave per AWS CloudHSM Client SDK 3. Utilizzare questa estensione per impostare gli attributi della chiave supportati e i relativi valori durante le operazioni seguenti: + Generazione delle chiavi + Importazione delle chiavi + Annullamento del wrapping delle chiavi **Nota** L'estensione per l'impostazione degli attributi della chiave personalizzati è una funzionalità facoltativa. Se disponi già di un codice che funziona nella libreria Java versione 3.0, non è necessario modificare tale codice. Le chiavi create continueranno a contenere gli stessi attributi di prima. **Topics** + [Comprensione degli attributi](#java-understanding-attributes) + [Attributi supportati](#java-attributes) + [Impostazione attributi per una chiave](#java-setting-attributes) + [Mettere tutto insieme](#java-attributes-summary) ## Comprensione degli attributi Gli attributi chiave vengono utilizzati per specificare le operazioni consentite su oggetti chiave, incluse le chiavi pubbliche, private o segrete. Gli attributi e i valori della chiave vengono definiti durante le operazioni di creazione degli oggetti chiave. Tuttavia, la Java Cryptography Extension (JCE) non specifica come impostare i valori sugli attributi della chiave, pertanto la maggior parte delle operazioni erano consentite per impostazione predefinita. Al contrario, lo standard PKCS\$1 11 definisce un set completo di attributi con valori predefiniti più restrittivi. A partire dalla libreria Java versione 3.1, CloudHSM fornisce un'estensione proprietaria che ti consente di impostare valori più restrittivi per gli attributi utilizzati più di frequente. ## Attributi supportati Puoi impostare i valori per gli attributi elencati nella tabella sottostante. Come best practice, imposta i valori solo per gli attributi che desideri rendere restrittivi. Se non specifichi un valore, CloudHSM utilizza il valore predefinito specificato nella tabella sottostante. Una cella vuota nella colonna Valore predefinito indica che all'attributo non è stato assegnato alcun valore predefinito specifico. **** | Attributo | Valore predefinito | Note | | --- | --- | --- | | | Chiave simmetrica | Chiave pubblica in una coppia di chiavi | Chiave privata in una coppia di chiavi | | | CKA\$1TOKEN | FALSE | FALSE | FALSE | Una chiave permanente che viene replicata in tutto il cluster e inclusa HSMs nei backup. CKA\$1TOKEN = FALSO implica una chiave di sessione, che viene caricata solo su un HSM e cancellata automaticamente quando la connessione al HSM viene interrotta. | | CKA\$1LABEL | | | | Una stringa definita dall'utente. Consente di identificare comodamente le chiavi sull'HSM. | | CKA\$1EXTRACTABLE | TRUE | | TRUE | Il valore Vero indica che è possibile esportare questa chiave dall'HSM. | | CKA\$1ENCRYPT | TRUE | TRUE | | Il valore Vero indica che è possibile utilizzare la chiave per crittografare qualsiasi buffer. | | CKA\$1DECRYPT | TRUE | | TRUE | Il valore Vero indica che è possibile utilizzare la chiave per decodificare qualsiasi buffer. Questo attributo è in genere impostato su FALSO per una chiave il cui CKA\$1WRAP è impostato su vero. | | CKA\$1WRAP | TRUE | TRUE | | Il valore Vero indica che è possibile utilizzare la chiave per eseguire il wrapping di un'altra chiave. In genere viene impostato su FALSO per chiavi private. | | CKA\$1UNWRAP | TRUE | | TRUE | Il valore Vero indica che è possibile utilizzare la chiave per annullare il wrapping (importare) di un'altra chiave. | | CKA\$1SIGN | TRUE | | TRUE | Il valore Vero indica che è possibile utilizzare la chiave per firmare messaggio di digest. In genere viene impostato su FALSO per le chiavi pubbliche e per le chiavi private archiviate. | | CKA\$1VERIFY | TRUE | TRUE | | Il valore Vero indica che è possibile utilizzare la chiave per verificare una firma. In genere è impostato su FALSO per chiavi private. | | CKA\$1PRIVATE | TRUE | TRUE | TRUE | Il valore Vero indica che un utente potrebbe non avere accesso alla chiave finché l'utente non viene autenticato. Per chiarezza, gli utenti non possono accedere alle chiavi in CloudHSM fino a quando non vengono autenticati, anche se questo attributo è impostato su FALSO. | **Nota** È possibile ottenere un supporto più ampio per gli attributi nella libreria PKCS \$111. Per ulteriori informazioni, vedi [Attributi PKCS \$111 supportati](pkcs11-attributes.md). ## Impostazione attributi per una chiave `CloudHsmKeyAttributesMap` è un oggetto simile a [Java Map](https://devdocs.io/openjdk~8/java/util/map) che puoi utilizzare per impostare i valori degli attributi per gli oggetti chiave. I metodi per la funzione `CloudHsmKeyAttributesMap` sono simili a quelli utilizzati per la manipolazione della mappa Java. Per impostare valori personalizzati sugli attributi, sono disponibili due opzioni: + Utilizzare i metodi elencati nella tabella seguente + Utilizzare i modelli di generatore illustrati più avanti in questo documento Gli oggetti della mappa attributi supportano i seguenti metodi per impostare gli attributi: **** | Operation | Valore restituito | Metodo `CloudHSMKeyAttributesMap` | | --- | --- | --- | | Ottenere il valore di un attributo chiave per una chiave esistente | Oggetto (contenente il valore) o nulla | **get**(keyAttribute) | | Inserire il valore di un attributo chiave | Il valore precedente associato all'attributo chiave o nulla se non esiste alcuna mappatura per un attributo chiave | **put**(keyAttribute, value) | | Compilare i valori per più attributi chiave | N/D | **PutAll** () keyAttributesMap | | Rimuovere una coppia chiave-valore dalla mappa degli attributi | Il valore precedente associato all'attributo chiave o *nulla* se non esiste alcuna mappatura per un attributo chiave | **remove**(keyAttribute) | **Nota** Eventuali attributi non specificati in modo esplicito vengono impostati sui valori predefiniti elencati nella tabella precedente in [Attributi supportati](#java-attributes). ### Esempio di modello di generatore Gli sviluppatori troveranno generalmente più conveniente utilizzare le classi tramite il modello di generatore. Come esempi: ``` import com.amazonaws.cloudhsm.CloudHsmKeyAttributes; import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap; import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap; CloudHsmKeyAttributesMap keyAttributesSessionDecryptionKey = new CloudHsmKeyAttributesMap.Builder() .put(CloudHsmKeyAttributes.CKA_LABEL, "ExtractableSessionKeyEncryptDecrypt") .put(CloudHsmKeyAttributes.CKA_WRAP, false) .put(CloudHsmKeyAttributes.CKA_UNWRAP, false) .put(CloudHsmKeyAttributes.CKA_SIGN, false) .put(CloudHsmKeyAttributes.CKA_VERIFY, false) .build(); CloudHsmKeyAttributesMap keyAttributesTokenWrappingKey = new CloudHsmKeyAttributesMap.Builder() .put(CloudHsmKeyAttributes.CKA_LABEL, "TokenWrappingKey") .put(CloudHsmKeyAttributes.CKA_TOKEN, true) .put(CloudHsmKeyAttributes.CKA_ENCRYPT, false) .put(CloudHsmKeyAttributes.CKA_DECRYPT, false) .put(CloudHsmKeyAttributes.CKA_SIGN, false) .put(CloudHsmKeyAttributes.CKA_VERIFY, false) .build(); ``` Gli sviluppatori possono inoltre utilizzare set di attributi predefiniti come un modo conveniente per applicare le best practice in modelli chiave. Ad esempio: ``` //best practice template for wrapping keys CloudHsmKeyAttributesMap commonKeyAttrs = new CloudHsmKeyAttributesMap.Builder() .put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, false) .put(CloudHsmKeyAttributes.CKA_DECRYPT, false) .build(); // initialize a new instance of CloudHsmKeyAttributesMap by copying commonKeyAttrs // but with an appropriate label CloudHsmKeyAttributesMap firstKeyAttrs = new CloudHsmKeyAttributesMap(commonKeyAttrs); firstKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, "key label"); // alternatively, putAll() will overwrite existing values to enforce conformance CloudHsmKeyAttributesMap secondKeyAttrs = new CloudHsmKeyAttributesMap(); secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_DECRYPT, true); secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_ENCRYPT, true); secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, “safe wrapping key”); secondKeyAttrs.putAll(commonKeyAttrs); // will overwrite CKA_DECRYPT to be FALSE ``` ### Impostazione di attributi per una coppia di chiavi Utilizza la classe Java `CloudHsmKeyPairAttributesMap` per gestire gli attributi chiave per una coppia di chiavi. `CloudHsmKeyPairAttributesMap` incapsula due oggetti `CloudHsmKeyAttributesMap`; uno per una chiave pubblica e uno per una chiave privata. Per impostare singoli attributi per la chiave pubblica e la chiave privata separatamente, puoi utilizzare il metodo `put()` sull'oggetto mappa `CloudHsmKeyAttributes` corrispondente per tale chiave. Utilizza il metodo `getPublic()` per recuperare la mappa degli attributi per la chiave pubblica e utilizza `getPrivate()` per recuperare la mappa degli attributi per la chiave privata. Compila il valore di più attributi chiave insieme per coppie di chiavi pubbliche e private utilizzando la `putAll()` con una mappa degli attributi della coppia di chiavi come relativo argomento. ### Esempio di modello di generatore Gli sviluppatori troveranno generalmente più comodo impostare gli attributi chiave tramite il modello di generatore. Esempio: ``` import com.amazonaws.cloudhsm.CloudHsmKeyAttributes; import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap; import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap; //specify attributes up-front CloudHsmKeyAttributesMap keyAttributes = new CloudHsmKeyAttributesMap.Builder() .put(CloudHsmKeyAttributes.CKA_SIGN, false) .put(CloudHsmKeyAttributes.CKA_LABEL, "PublicCertSerial12345") .build(); CloudHsmKeyPairAttributesMap keyPairAttributes = new CloudHsmKeyPairAttributesMap.Builder() .withPublic(keyAttributes) .withPrivate( new CloudHsmKeyAttributesMap.Builder() //or specify them inline .put(CloudHsmKeyAttributes.CKA_LABEL, "PrivateCertSerial12345") .put (CloudHSMKeyAttributes.CKA_WRAP, FALSE) .build() ) .build(); ``` **Nota** [Per ulteriori informazioni su questa estensione proprietaria, vedete l'archivio [Javadoc](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Docs/CloudHsm_CustomKeyAttributes_Javadoc.zip) e l'esempio su.](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CustomKeyAttributesRunner.java) GitHub Per esplorare Javadoc, scarica ed espandi l'archivio. ## Mettere tutto insieme Per specificare gli attributi chiave con le operazioni chiave, attenersi alla seguente procedura: 1. Creare un'istanza `CloudHsmKeyAttributesMap` per chiavi simmetriche o `CloudHsmKeyPairAttributesMap` per coppie di chiavi. 1. Definire l'oggetto attributi dalla fase 1 con gli attributi e i valori chiave richiesti. 1. Creare un'istanza di una classe `Cavium*ParameterSpec`, corrispondente al tipo di chiave specifico e passare al costruttore questo oggetto attributi configurato. 1. Passare questo oggetto `Cavium*ParameterSpec` in una classe o metodo crittografico corrispondente. Per riferimento, la tabella seguente contiene le classi `Cavium*ParameterSpec` e i metodi che supportano gli attributi chiave personalizzati. **** | Tipo di chiavi | Classe specifiche del parametro | Esempio Costruttori | | --- | --- | --- | | Classe di base | CaviumKeyGenAlgorithmParameterSpec | CaviumKeyGenAlgorithmParameterSpec(CloudHsmKeyAttributesMap keyAttributesMap) | | DES | CaviumDESKeyGenParameterSpec | CaviumDESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) | | RSA | CaviumRSAKeyGenParameterSpec | CaviumRSAKeyGenParameterSpec(int keysize, BigInteger publicExponent, CloudHsmKeyPairAttributesMap keyPairAttributesMap) | | Segreto | CaviumGenericSecretKeyGenParameterSpec | CaviumGenericSecretKeyGenParameterSpec(int size, CloudHsmKeyAttributesMap keyAttributesMap) | | AES | CaviumAESKeyGenParameterSpec | CaviumAESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) | | EC | CaviumECGenParameterSpec | CaviumECGenParameterSpec(String stdName, CloudHsmKeyPairAttributesMap keyPairAttributesMap) | ### Esempio di codice: generare ed eseguire il wrapping di una chiave Questi brevi codici di esempio illustrano le fasi per due diverse operazioni: Generazione chiave e Wrapping della chiave: ``` // Set up the desired key attributes KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium"); CaviumAESKeyGenParameterSpec keyAttributes = new CaviumAESKeyGenParameterSpec( 256, new CloudHsmKeyAttributesMap.Builder() .put(CloudHsmKeyAttributes.CKA_LABEL, "MyPersistentAESKey") .put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, true) .put(CloudHsmKeyAttributes.CKA_TOKEN, true) .build() ); // Assume we already have a handle to the myWrappingKey // Assume we already have the wrappedBytes to unwrap // Unwrap a key using Custom Key Attributes CaviumUnwrapParameterSpec unwrapSpec = new CaviumUnwrapParameterSpec(myInitializationVector, keyAttributes); Cipher unwrapCipher = Cipher.getInstance("AESWrap", "Cavium"); unwrapCipher.init(Cipher.UNWRAP_MODE, myWrappingKey, unwrapSpec); Key unwrappedKey = unwrapCipher.unwrap(wrappedBytes, "AES", Cipher.SECRET_KEY); ``` # Esempi di codice per la libreria AWS CloudHSM software per Java for Client SDK 3 Questo argomento fornisce risorse e informazioni sugli esempi di codice Java per AWS CloudHSM Client SDK 3. ## Prerequisiti Prima di eseguire gli esempi, è necessario configurare l'ambiente: + Installa e configura il [provider Java Cryptographic Extension (JCE)](java-library-install.md#install-java-library) e il pacchetto [client AWS CloudHSM](cmu-install-and-configure-client-linux.md). + Configura un [nome utente e una password HSM](manage-hsm-users.md) validi. Le autorizzazioni per l'utente di crittografia (CU) sono sufficienti per queste attività. L'applicazione utilizza queste credenziali per accedere all'HSM in ciascun esempio. + Decidi come fornire le credenziali al [provider JCE.](java-library-install.md#java-library-credentials) ## Esempi di codice I seguenti esempi di codice mostrano come utilizzare il [provider JCE AWS CloudHSM](java-library.md) per eseguire attività di base. Altri esempi di codice sono disponibili su. [GitHub](https://github.com/aws-samples/aws-cloudhsm-jce-examples/) + [Esegui l'accesso a un modulo HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java) + [Gestisci chiavi](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java) + [Generazione di una chiave AES](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java) + [Crittografia e decodifica con AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java) + [Crittografia e decodifica con AES-CTR]( https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java) + [Crittografia e decodifica con D3DES-ECB ]( https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java)**vedi nota [1](#java-samples-code-note-1)** + [Wrapping e annullamento del wrapping delle chiavi con AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMWrappingRunner.java) + [Wrapping e annullamento del wrapping delle chiavi con AES](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/AESWrappingRunner.java) + [Wrapping e annullamento del wrapping delle chiavi con RSA](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/RSAWrappingRunner.java) + [Usa attributi chiave supportati](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CustomKeyAttributesRunner.java) + [Enumerazione delle chiavi nell'archivio delle chiavi](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java) + [Utilizzo dell'archivio delle chiavi CloudHSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CloudHSMKeyStoreExampleRunner.java) + [Firma di messaggi in un esempio multi-thread](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/SignThreadedRunner.java) + [Firma e verifica con chiavi EC](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java) [1] In conformità alle linee guida del NIST, ciò non è consentito per i cluster in modalità FIPS dopo il 2023. Per i cluster in modalità non FIPS, è ancora consentito dopo il 2023. Per informazioni dettagliate, vedi [Conformità FIPS 140: meccanismo di deprecazione 2024](compliance-dep-notif.md#compliance-dep-notif-1). # AWS CloudHSM KeyStore Classe Java per Client SDK 3 **La AWS CloudHSM `KeyStore` classe fornisce un archivio di PKCS12 chiavi per scopi speciali che consente l'accesso alle AWS CloudHSM chiavi tramite applicazioni come **keytool** e jarsigner.** Questo archivio chiavi può archiviare i certificati insieme ai dati della chiave e correlarli ai dati della chiave memorizzati su AWS CloudHSM. **Nota** Poiché i certificati sono informazioni pubbliche e, per massimizzare la capacità di archiviazione delle chiavi crittografiche, AWS CloudHSM non supporta l'archiviazione dei certificati su. HSMs La AWS CloudHSM `KeyStore` classe implementa la `KeyStore` Service Provider Interface (SPI) della Java Cryptography Extension (JCE). [Per ulteriori informazioni sull'utilizzo`KeyStore`, vedete Class. KeyStore](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) ## Scegli l'archivio di chiavi appropriato per AWS CloudHSM Client SDK 3 Il provider AWS CloudHSM Java Cryptographic Extension (JCE) è dotato di un key store pass-through predefinito di sola lettura che trasferisce tutte le transazioni all'HSM. Questo archivio di chiavi predefinito è distinto da quello per scopi speciali. AWS CloudHSM KeyStore Nella maggior parte delle situazioni, è possibile ottenere prestazioni di runtime e velocità effettiva migliori utilizzando l'impostazione predefinita. È consigliabile utilizzarlo solo AWS CloudHSM KeyStore per le applicazioni in cui è necessario il supporto per i certificati e le operazioni basate sui certificati oltre a trasferire le operazioni chiave sull'HSM. Sebbene entrambi gli archivi di chiavi utilizzino il provider JCE per le operazioni, sono entità indipendenti e non scambiano informazioni tra loro. Carica l'archivio chiavi predefinito per l'applicazione Java come segue: ``` KeyStore ks = KeyStore.getInstance("Cavium"); ``` Caricate il CloudHSM per scopi speciali come segue: KeyStore ``` KeyStore ks = KeyStore.getInstance("CloudHSM") ``` ## Inizializza for Client SDK 3 AWS CloudHSM KeyStore Effettua AWS CloudHSM KeyStore l'accesso nello stesso modo in cui accedi al provider JCE. È possibile utilizzare le variabili di ambiente o il file delle proprietà del sistema ed è necessario effettuare il login prima di iniziare a utilizzare CloudHSM KeyStore. Per un esempio di accesso a un HSM utilizzando JCE, vedi [Accedi a un HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java). Se lo desideri, puoi specificare una password per crittografare il PKCS12 file locale che contiene i dati dell'archivio delle chiavi. Quando si crea il AWS CloudHSM Keystore, si imposta la password e la si fornisce quando si utilizzano i metodi load, set e get. Crea un'istanza di un nuovo oggetto CloudHSM come segue KeyStore : ``` ks.load(null, null); ``` Scrivi i dati dell'archivio chiavi in un file utilizzando il metodo `store`. Da quel momento in poi, puoi caricare l'archivio chiavi esistente utilizzando il metodo `load` con il file sorgente e la password come segue: ``` ks.load(inputStream, password); ``` ## Usa for Client SDK 3 AWS CloudHSM KeyStore AWS CloudHSM [Un oggetto KeyStore CloudHSM viene generalmente utilizzato tramite un'applicazione di terze parti [come](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/jarsigner.html) jarsigner o keytool.](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) Puoi anche accedere direttamente all'oggetto con il codice. AWS CloudHSM KeyStore è conforme alle specifiche della [classe KeyStore](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) JCE e fornisce le seguenti funzioni. + `load` Carica l'archivio chiavi dal flusso di input specificato. Se durante il salvataggio dell'archivio chiavi è stata impostata una password, è necessario fornire questa stessa password affinché il caricamento abbia esito positivo. Impostare entrambi i parametri su nulla per inizializzare un nuovo archivio di chiavi vuoto. ``` KeyStore ks = KeyStore.getInstance("CloudHSM"); ks.load(inputStream, password); ``` + `aliases` Restituisce un'enumerazione dei nomi alias di tutte le voci nell'istanza dell'archivio chiavi considerato. I risultati includono oggetti archiviati localmente nel PKCS12 file e oggetti residenti nell'HSM. **Esempio di codice:** ``` KeyStore ks = KeyStore.getInstance("CloudHSM"); for(Enumeration entry = ks.aliases(); entry.hasMoreElements();) { String label = entry.nextElement(); System.out.println(label); } ``` + `ContainsAlias` Restituisce vero se l'archivio chiavi ha accesso ad almeno un oggetto con l'alias specificato. L'archivio delle chiavi controlla gli oggetti archiviati localmente nel PKCS12 file e gli oggetti che risiedono sull'HSM. + `DeleteEntry` Elimina una voce di certificato dal file locale PKCS12 . L'eliminazione dei dati chiave archiviati in un HSM non è supportata utilizzando. AWS CloudHSM KeyStore È possibile eliminare le chiavi con lo strumento [key\$1mgmt\$1util](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util.html) di CloudHSM. + `GetCertificate` Restituisce il certificato associato a un alias, se disponibile. Se l'alias non esiste o fa riferimento a un oggetto che non è un certificato, la funzione restituisce NULLA. ``` KeyStore ks = KeyStore.getInstance("CloudHSM"); Certificate cert = ks.getCertificate(alias) ``` + `GetCertificateAlias` Restituisce il nome (alias) della prima voce dell'archivio chiavi i cui dati corrispondono al certificato specificato. ``` KeyStore ks = KeyStore.getInstance("CloudHSM"); String alias = ks.getCertificateAlias(cert) ``` + `GetCertificateChain` Restituisce la catena di certificati associata all'alias specificato. Se l'alias non esiste o fa riferimento a un oggetto che non è un certificato, la funzione restituisce NULLA. + `GetCreationDate` Restituisce la data di creazione della voce identificata dall'alias specificato. Se una data di creazione non è disponibile, la funzione restituisce la data in cui il certificato è diventato valido. + `GetKey` GetKey viene passato all'HSM e restituisce un oggetto chiave corrispondente all'etichetta specificata. Poiché interroga `getKey` direttamente l'HSM, può essere utilizzato per qualsiasi chiave sull'HSM indipendentemente dal fatto che sia stata generata da. KeyStore ``` Key key = ks.getKey(keyLabel, null); ``` + `IsCertificateEntry` Controlla se la voce con l'alias specificato rappresenta una voce di certificato. + `IsKeyEntry` Controlla se la voce con l'alias specificato rappresenta una voce chiave. L'azione cerca l'alias sia nel PKCS12 file che nell'HSM. + `SetCertificateEntry` Assegna il certificato dato all'alias specificato. Se l'alias specificato è già in uso per identificare una chiave o un certificato, viene generata una `KeyStoreException`. È possibile utilizzare il codice JCE per ottenere l'oggetto chiave e quindi utilizzare il KeyStore `SetKeyEntry` metodo per associare il certificato alla chiave. + `SetKeyEntry` con chiave `byte[]` **Questa API non è attualmente supportata con Client SDK 3.** + `SetKeyEntry` con oggetto `Key` Assegna la chiave considerata all'alias specificato e la memorizza all'interno dell'HSM. Se l'oggetto `Key` non è di tipo `CaviumKey`, la chiave viene importata nell'HSM come chiave di sessione estraibile. Se l'oggetto `Key` è di tipo `PrivateKey`, deve essere accompagnato da una catena di certificati corrispondente. Se l'alias esiste già, la chiamata `SetKeyEntry` genera un `KeyStoreException` e impedisce la sovrascrittura della chiave. Se la chiave deve essere sovrascritta, utilizza KMU o JCE a tale scopo. + `EngineSize` Restituisce il numero di voci nell'archivio chiavi. + `Store` Memorizza l'archivio delle chiavi nel flusso di output specificato come PKCS12 file e lo protegge con la password specificata. Inoltre, persiste tutte le chiavi caricate (che sono impostate usando le chiamate `setKey`).