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 5
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. Per la risoluzione dei problemi, vedere. [Problemi noti relativi all'SDK JCE per AWS CloudHSM](ki-jce-sdk.md)
Per informazioni sull'utilizzo di Client SDK 3, vedi [Utilizzo della versione SDK precedente con cui lavorare AWS CloudHSM](choose-client-sdk.md).
**Topics**
+ [Installare il provider JCE per AWS CloudHSM Client SDK 5](java-library-install_5.md)
+ [Tipi di chiavi supportati per il provider JCE per AWS CloudHSM Client SDK 5](java-lib-keys_5.md)
+ [Nozioni di base sulla gestione delle chiavi nel provider JCE per AWS CloudHSM Client SDK 5](java-library-key-basics_5.md)
+ [Meccanismi supportati per il provider JCE per AWS CloudHSM Client SDK 5](java-lib-supported_5.md)
+ [Attributi chiave Java supportati per AWS CloudHSM Client SDK 5](java-lib-attributes_5.md)
+ [Esempi di codice per la libreria AWS CloudHSM software per Java for Client SDK 5](java-samples.md)
+ [AWS CloudHSM Fornitore JCE Javadocs](java-javadocs_5.md)
+ [AWS CloudHSM KeyStore Classe Java per Client SDK 5](alternative-keystore_5.md)
+ [Configurazioni avanzate per AWS CloudHSM JCE for Client SDK 5](java-lib-configs.md)
# Installare il provider JCE per AWS CloudHSM Client SDK 5
Il provider JCE per AWS CloudHSM Client SDK 5 è compatibile con OpenJDK 8, OpenJDK 11, OpenJDK 17, OpenJDK 21 e OpenJDK 25. Puoi scaricarli entrambi dal [sito Web di OpenJDK.](https://openjdk.java.net/)
Utilizza le seguenti sezioni per installare e fornire credenziali al provider.
**Nota**
Per eseguire un singolo cluster HSM con Client SDK 5, è necessario gestire innanzitutto le impostazioni di durabilità delle chiavi del client impostando `disable_key_availability_check` su `True`. Per ulteriori informazioni, consulta la pagina sulla [sincronizzazione delle chiavi](manage-key-sync.md) e la pagina sullo [strumento di configurazione di Client SDK 5](configure-sdk-5.md).
**Topics**
+ [Fase 1: Installare il provider JCE](#install-java-library_5)
+ [Fase 2: Fornire le credenziali al provider JCE](#java-library-credentials_5)
## Fase 1: Installare il provider JCE
1. Utilizza i seguenti comandi per scaricare e installare il provider JCE.
------
#### [ Amazon Linux 2023 ]
Installa il provider JCE per Amazon Linux 2023 sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
Installa il provider JCE per Amazon Linux 2023 sull' ARM64 architettura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Installa il provider JCE per Amazon Linux 2 sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
```
Installa il provider JCE per Amazon Linux 2 sull' ARM64 architettura:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
Installa il provider JCE per RHEL 10 sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.x86_64.rpm
```
Installa il provider JCE per RHEL 10 sull'architettura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
Installa il provider JCE per RHEL 9 (9.2\$1) sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.x86_64.rpm
```
Installa il provider JCE per RHEL 9 (9.2\$1) sull'architettura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
Installa il provider JCE per RHEL 8 sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.x86_64.rpm
```
Installa il provider JCE per RHEL 8 sull'architettura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Installa il provider JCE per Ubuntu 24.04 LTS sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_amd64.deb
```
Installa il provider JCE per Ubuntu 24.04 LTS sull'architettura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Installa il provider JCE per Ubuntu 22.04 LTS sull'architettura x86\$164:
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_amd64.deb
```
Installa il provider JCE per Ubuntu 22.04 LTS sull'architettura: ARM64
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
Installa il provider JCE per Windows Server sull'architettura x86\$164, apri PowerShell come amministratore ed esegui il seguente comando:
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
------
1. Esegui il bootstrap di Client SDK 5. Per ulteriori informazioni sulle operazioni di bootstrap, consulta la pagina [Esegui il bootstrap di Client SDK](cluster-connect.md#connect-how-to).
1. Individua i seguenti file del provider JCE:
------
#### [ Linux ]
+ `/opt/cloudhsm/java/cloudhsm-.jar`
+ `/opt/cloudhsm/bin/configure-jce`
+ `/opt/cloudhsm/bin/jce-info`
------
#### [ Windows ]
+ `C:\Program Files\Amazon\CloudHSM\java\cloudhsm-.jar>`
+ `C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe`
+ `C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe`
------
## Fase 2: Fornire le credenziali al provider JCE
Prima che l'applicazione Java possa utilizzare un HSM, quest'ultimo deve prima autenticare l'applicazione. HSMs eseguire l'autenticazione utilizzando un metodo di accesso esplicito o implicito.
**Accesso esplicito** questo metodo consente di fornire le credenziali AWS CloudHSM direttamente nell'applicazione. Utilizza il metodo dal [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html), in cui si passa il nome utente CU, la password e l'ID nel modello di pin. Per ulteriori informazioni, vedi codice di esempio di [Accesso a un HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java).
**Accesso implicito ** questo metodo consente di impostare le credenziali AWS CloudHSM in un nuovo file di proprietà, proprietà del sistema, oppure come variabili di ambiente.
+ **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:
------
#### [ Linux ]
```
$ java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
#### [ Windows ]
```
PS C:\> java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
+ **Variabili di ambiente** Imposta le credenziali come variabili di ambiente.
**Nota**
Quando impostate le variabili di ambiente, dovete evitare qualsiasi carattere speciale che possa essere interpretato dalla vostra shell.
------
#### [ Linux ]
```
$ export HSM_USER=
$ export HSM_PASSWORD=
```
------
#### [ Windows ]
```
PS C:\> $Env:HSM_USER=""
PS C:\> $Env: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. Proprietà di sistema
1. Variabili di ambiente
# Tipi di chiavi supportati per il provider JCE per AWS CloudHSM Client SDK 5
La libreria AWS CloudHSM software per Java consente di generare i seguenti tipi di chiavi.
****
| Tipo di chiavi | Description |
| --- | --- |
| AES | Genera chiavi AES a 128, 192 e 256 bit. |
| Triplo DES (3DES, DESede) | Genera una chiave DES tripla a 192 bit. [*](#java-lib-keys_5-note-1) |
| EC | Genera coppie di chiavi EC - curve NIST secp224r1 (P-224), secp256r1 (P-256), secp256k1 (Blockchain), secp384r1 (P-384), e secp521r1 (P-521). |
| GENERIC\$1SECRET | Genera segreti generici da 1 a 800 byte. |
| HMAC | Supporto hash per SHA1,, SHA224, SHA256. SHA384 SHA512 |
| RSA | General chiavi RSA da 2048-bit a 4096-bit, con incrementi di 256 bit. |
\$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).
# Nozioni di base sulla gestione delle chiavi nel provider JCE per AWS CloudHSM Client SDK 5
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/sdk5/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.md).
# Meccanismi supportati per il provider JCE per AWS CloudHSM Client SDK 5
Questo argomento fornisce informazioni sui meccanismi supportati per il provider JCE con AWS CloudHSM Client SDK 5. Per informazioni sulle interfacce e le classi di motori Java Cryptography Architecture (JCA) supportate da AWS CloudHSM, consultate i seguenti argomenti.
**Topics**
+ [Funzioni di generazione chiavi e coppie di chiavi](#java-gen-key-pairs-5)
+ [Funzioni di cifratura](#java-ciphers_5)
+ [Funzioni di firma e verifica](#java-sign-verify_5)
+ [Funzioni set digest](#java-digests_5)
+ [Funzioni di codice di autenticazione dei messaggi basato su hash (HMAC).](#java-mac_5)
+ [Funzioni di codice di autenticazione dei messaggi basato su crittografia (CMAC)](#java-cmac_5)
+ [Funzioni chiave dell'accordo](#java-key-derivation_5)
+ [Converti le chiavi in specifiche chiave utilizzando le principali fabbriche](#java-key-factories)
+ [Annotazioni sui meccanismi](#w2aac25c21c25c15c23)
## Funzioni di generazione chiavi e coppie di chiavi
La libreria AWS CloudHSM software per Java consente di utilizzare le seguenti operazioni per generare funzioni di chiavi e coppie di chiavi.
+ `RSA`
+ `EC`
+ `AES`
+ `DESede (Triple DES)`vedi nota[1](#java-gen-key-pairs-5-note-1)
+ `GenericSecret`
## Funzioni di cifratura
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`. Implementa `Cipher.UNWRAP_MODE for AES/CBC NoPadding` |
| AES | ECB | `AES/ECB/PKCS5Padding` `AES/ECB/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| AES | CTR | `AES/CTR/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| AES | GCM | `AES/GCM/NoPadding` | Implementa `Cipher.WRAP_MODE`, `Cipher.UNWRAP_MODE`, `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_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/NoPadding` `AESWrap/ECB/PKCS5Padding` `AESWrap/ECB/ZeroPadding` | Implementa `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`. |
| DESede (Triplo DES) | CBC | `DESede/CBC/PKCS5Padding` `DESede/CBC/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Vedi la nota [1](#java-gen-key-pairs-5-note-1) di seguito per una modifica imminente. |
| DESede (DES triplo) | ECB | `DESede/ECB/NoPadding` `DESede/ECB/PKCS5Padding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. Vedi la nota [1](#java-gen-key-pairs-5-note-1) di seguito per una modifica imminente. |
| RSA | ECB | `RSA/ECB/PKCS1Padding` **vedi nota [1](#java-gen-key-pairs-5-note-1)** `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.WRAP_MODE`, `Cipher.UNWRAP_MODE`, `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| RSA | ECB | `RSA/ECB/NoPadding` | Implementa `Cipher.ENCRYPT_MODE` e `Cipher.DECRYPT_MODE`. |
| RSAAESWrap | ECB | `RSAAESWrap/ECB/OAEPPadding` `RSAAESWrap/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-512ANDMGF1Padding` | Implementa `Cipher.WRAP_MODE` e `Cipher.UNWRAP_MODE`. |
## Funzioni di firma e verifica
La libreria AWS CloudHSM software per Java supporta i seguenti tipi di firma e verifica. Con Client SDK 5 e gli algoritmi di firma con hashing, i dati vengono sottoposti a hash localmente nel software prima di essere inviati all'HSM per la firma/verifica. Ciò significa che non ci sono limiti alla dimensione dei dati che possono essere sottoposti a hash dall'SDK.
**Tipi di firma RSA**
+ `NONEwithRSA`
+ `RSASSA-PSS`
+ `SHA1withRSA`
+ `SHA1withRSA/PSS`
+ `SHA1withRSAandMGF1`
+ `SHA224withRSA`
+ `SHA224withRSAandMGF1`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA`
+ `SHA256withRSAandMGF1`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA`
+ `SHA384withRSAandMGF1`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA`
+ `SHA512withRSAandMGF1`
+ `SHA512withRSA/PSS`
**Tipi di firma ECDSA**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## Funzioni set digest
La libreria AWS CloudHSM software per Java supporta i seguenti digest di messaggi. Con Client SDK 5, l'hashing dei dati viene eseguito localmente nel software. Ciò significa che non ci sono limiti alla dimensione dei dati che possono essere sottoposti a hash dall'SDK.
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## Funzioni di codice di autenticazione dei messaggi basato su hash (HMAC).
La libreria AWS CloudHSM software per Java supporta i seguenti algoritmi HMAC.
+ `HmacSHA1`(Dimensione massima dei dati in byte: 16288)
+ `HmacSHA224`(Dimensione massima dei dati in byte: 16256)
+ `HmacSHA256`(Dimensione massima dei dati in byte: 16288)
+ `HmacSHA384`(Dimensione massima dei dati in byte: 16224)
+ `HmacSHA512`(Dimensione massima dei dati in byte: 16224)
## Funzioni di codice di autenticazione dei messaggi basato su crittografia (CMAC)
CMACs (Codici di autenticazione dei messaggi basati su crittografia) crea codici di autenticazione dei messaggi (MACs) utilizzando un codice a blocchi e una chiave segreta. Differiscono dal fatto che utilizzano un metodo HMACs a chiave simmetrica a blocchi anziché un metodo di hashing. MACs
La libreria AWS CloudHSM software per Java supporta i seguenti algoritmi CMAC.
+ `AESCMAC`
## Funzioni chiave dell'accordo
La libreria AWS CloudHSM software per Java supporta ECDH con Key Derivation Functions (KDF). Sono supportati i seguenti tipi di KDF:
+ `ECDHwithX963SHA1KDF`Supporta l'algoritmo KDF X9.63 SHA1 [2](#kdf2)
+ `ECDHwithX963SHA224KDF`Supporta l'algoritmo KDF X9.63 SHA224 [2](#kdf2)
+ `ECDHwithX963SHA256KDF`Supporta l'algoritmo KDF X9.63 SHA256 [2](#kdf2)
+ `ECDHwithX963SHA384KDF`Supporta l'algoritmo KDF X9.63 SHA384 [2](#kdf2)
+ `ECDHwithX963SHA512KDF`Supporta l'algoritmo KDF X9.63 SHA512 [2](#kdf2)
## Converti le chiavi in specifiche chiave utilizzando le principali fabbriche
È possibile utilizzare le fabbriche di chiavi per convertire le chiavi in specifiche chiave. AWS CloudHSM dispone di due tipi di fabbriche chiave per JCE:
**SecretKeyFactory:** utilizzato per importare o derivare chiavi simmetriche. Utilizzando SecretKeyFactory, è possibile passare una chiave supportata o una chiave supportata KeySpec per importare o derivare chiavi simmetriche. AWS CloudHSM Di seguito sono riportate le specifiche supportate per: KeyFactory
+ Sono supportate le seguenti [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)classi SecretKeyFactory del `generateSecret` metodo For:
+ **KeyAttributesMap**può essere usato per importare byte chiave con attributi aggiuntivi come chiave CloudHSM. Un esempio può essere trovato [qui](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java).
+ **[SecretKeySpec](https://docs.oracle.com/javase/8/docs/api/javax/crypto/spec/SecretKeySpec.html)**può essere usato per importare una specifica chiave simmetrica come chiave CloudHSM.
+ **AesCmacKdfParameterSpec**può essere usato per derivare chiavi simmetriche utilizzando un'altra chiave AES CloudHSM.
**Nota**
SecretKeyFactory[il `translateKey` metodo accetta qualsiasi chiave che implementa l'interfaccia chiave.](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)
**KeyFactory:** utilizzato per importare chiavi asimmetriche. Utilizzando KeyFactory, è possibile passare una chiave supportata o supportata KeySpec per importare una chiave asimmetrica. AWS CloudHSM Per ulteriori informazioni, fai riferimento a queste risorse:
+ KeyFactoryIl `generatePublic` metodo di For, sono supportate le seguenti [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)classi:
+ KeyAttributesMap CloudHSM per RSA ed EC, tra cui: KeyTypes
+ KeyAttributesMap CloudhSM per RSA ed EC public. KeyTypes Un esempio può essere trovato [qui](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [X509](https://docs.oracle.com/javase/8/docs/api/java/security/spec/X509EncodedKeySpec.html) sia EncodedKeySpec per RSA che per EC Public Key
+ [RSAPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPublicKeySpec.html)per RSA Public Key
+ [ECPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPublicKeySpec.html)per EC Public Key
+ KeyFactoryIl `generatePrivate` metodo di For, sono supportate [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html)le seguenti classi:
+ KeyAttributesMap CloudHSM per RSA ed EC, tra cui: KeyTypes
+ KeyAttributesMap CloudhSM per RSA ed EC public. KeyTypes Un esempio può essere trovato [qui](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [PKCS8EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/PKCS8EncodedKeySpec.html)sia per EC che per RSA Private Key
+ [RSAPrivateCrtKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPrivateCrtKeySpec.html)per RSA Private Key
+ [ECPrivateKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPrivateKeySpec.html)per EC Private Key
KeyFactoryIl `translateKey` metodo di For, accetta qualsiasi chiave che implementa l'[interfaccia chiave](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html).
## 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).
[2] Le principali funzioni di derivazione (KDFs) sono specificate nella pubblicazione [speciale 800-56A Revisione 3 del NIST](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf).
# Attributi chiave Java supportati per AWS CloudHSM Client SDK 5
Questo argomento fornisce informazioni sugli attributi chiave Java supportati per AWS CloudHSM Client SDK 5. In questo argomento viene descritto come utilizzare un'estensione proprietaria per il provider JCE per impostare attributi chiave. Utilizzare questa estensione per impostare gli attributi della chiave supportati e i relativi valori durante le operazioni seguenti:
+ Generazione delle chiavi
+ Importazione delle chiavi
Per esempi di utilizzo degli attributi chiave, vedi [Esempi di codice per la libreria AWS CloudHSM software per Java for Client SDK 5](java-samples.md).
**Topics**
+ [Comprensione degli attributi](#java-understanding-attributes_5)
+ [Attributi supportati](#java-attributes_5)
+ [Impostazione attributi per una chiave](#java-setting-attributes_5)
## 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 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 dal provider JCE 3.1, AWS CloudHSM fornisce un'estensione proprietaria che consente di impostare valori più restrittivi per gli attributi di uso comune.
## 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 si specifica un valore, AWS CloudHSM utilizza il valore predefinito specificato nella tabella seguente. 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 | |
| --- | --- | --- | --- | --- | --- | --- | --- |
| DECRYPT | 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 WRAP è impostato su vero. |
| DERIVE | | | | Consente di utilizzare una chiave per derivare altre chiavi. |
| ENCRYPT | TRUE | TRUE | | Il valore Vero indica che è possibile utilizzare la chiave per crittografare qualsiasi buffer. |
| EXTRACTABLE | TRUE | | TRUE | Il valore Vero indica che è possibile esportare questa chiave dall'HSM. |
| ID | | | | Un valore definito dall'utente utilizzato per identificare la chiave. |
| KEY\$1TYPE | | | | Utilizzato per identificare il tipo di chiave (AES DESede, segreto generico, EC o RSA). |
| LABEL | | | | Una stringa definita dall'utente che consente di identificare comodamente le chiavi sull'HSM. Per seguire le best practice, utilizza un'etichetta univoca per ogni chiave in modo che sia più facile trovarla in seguito. |
| LOCAL | | | | Indica una chiave generata dall'HSM. |
| OBJECT\$1CLASS | | | | Utilizzato per identificare la classe dell'oggetto di una chiave (SecretKey, PublicKey o PrivateKey). |
| PRIVATE | TRUE | TRUE | TRUE | Il valore Vero indica che un utente potrebbe non poter accedere alla chiave finché l'utente non viene autenticato. Per motivi di chiarezza, gli utenti non possono accedere a nessuna chiave AWS CloudHSM finché non vengono autenticati, anche se questo attributo è impostato su FALSE. |
| SIGN | TRUE | | TRUE | Il valore Vero indica che è possibile utilizzare la chiave per firmare un messaggio di digest. In genere viene impostato su FALSO per le chiavi pubbliche e per le chiavi private archiviate. |
| SIZE | | | | Un attributo che definisce la dimensione di una chiave. Per maggiori dettagli sulle dimensioni delle chiavi supportate, vedi [Meccanismi supportati per Client SDK 5](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5). |
| TOKEN | FALSE | FALSE | FALSE | Una chiave permanente che viene replicata HSMs in tutto il cluster e inclusa nei backup. TOKEN = FALSO implica una chiave effimera, che viene cancellata automaticamente quando la connessione al HSM viene interrotta o ci si disconnette. |
| UNWRAP | TRUE | | TRUE | Il valore Vero indica che è possibile utilizzare la chiave per annullare il wrapping (importazione) di un'altra chiave. |
| VERIFY | TRUE | TRUE | | Il valore Vero indica che è possibile utilizzare la chiave per verificare una firma. In genere è impostato su FALSO per chiavi private. |
| WRAP | 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. |
| WRAP\$1WITH\$1TRUSTED | FALSE | | FALSE | Il valore Vero indica che una chiave può essere soggetta a wrapping e ad annullamento del wrapping con chiavi con l'attributo TRUSTED impostato su vero. Una volta che una chiave ha il valore WRAP\$1WITH\$1TRUSTED impostato su vero, tale attributo è di sola lettura e non può essere impostato su falso. Per saperne di più sul wrapping di fiducia, vedi [Utilizzo di chiavi fidate per controllare l'annullamento del wrapping delle chiavi](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_using_trusted_keys_control_key_wrap.html). |
**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
`KeyAttributesMap` è un oggetto simile a Java Map che puoi utilizzare per impostare i valori degli attributi per gli oggetti chiave. I metodi per la funzione `KeyAttributesMap` 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 `KeyAttributesMap` |
| --- | --- | --- |
| 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_5).
### Impostazione di attributi per una coppia di chiavi
Utilizza la classe Java `KeyPairAttributesMap` per gestire gli attributi chiave per una coppia di chiavi. `KeyPairAttributesMap` incapsula due oggetti `KeyAttributesMap`; 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 `KeyAttributes` 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.
# Esempi di codice per la libreria AWS CloudHSM software per Java for Client SDK 5
Questo argomento fornisce risorse e informazioni sugli esempi di codice Java per AWS CloudHSM Client SDK 5.
## Prerequisiti
Prima di eseguire gli esempi, devi configurare l'ambiente:
+ Installa e configura il provider [Java Cryptographic Extension (JCE).](java-library-install_5.md#install-java-library_5)
+ 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_5.md#java-library-credentials_5)
## 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/tree/sdk5)
+ [Esegui l'accesso a un modulo HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [Gestisci chiavi](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [Genera di chiavi simmetriche](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [Genera chiavi asimmetriche](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java)
+ [Crittografa e decodifica con AES-GCM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java)
+ [Crittografa e decodifica con AES-CTR](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ Crittografa [e decrittografa con DESede](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java) -ECB (vedi nota) [1](#java-samples-code-5-note-1)
+ [Firma e verifica con chiavi RSA](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [Firma e verifica con Chiavi EC](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java)
+ [Usa attributi chiave supportati](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyAttributesRunner.java)
+ [Utilizzo dell'archivio delle chiavi CloudHSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.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 Fornitore JCE Javadocs
Utilizza il provider JCE Javadocs per ottenere informazioni sull'utilizzo dei tipi e dei metodi Java definiti nell'SDK JCE di AWS CloudHSM. Per scaricare la versione più recente di Javadoc per AWS CloudHSM, consultate la [AWS CloudHSM ultima versione di Client SDK](latest-releases.md) sezione della pagina Download.
È possibile importare Javadocs in un ambiente di sviluppo integrato (IDE) o visualizzarli in un Web browser.
# AWS CloudHSM KeyStore Classe Java per Client SDK 5
La AWS CloudHSM `KeyStore` classe fornisce un archivio di chiavi per scopi speciali PKCS12 . Questo archivio chiavi può archiviare i certificati insieme ai dati della chiave e correlarli ai dati della chiave memorizzati su AWS CloudHSM. 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://devdocs.io/openjdk~8/java/security/keystore)
**Nota**
Poiché i certificati sono informazioni pubbliche e, per massimizzare la capacità di archiviazione delle chiavi crittografiche, non AWS CloudHSM supporta l'archiviazione dei certificati su. HSMs
## Scegli l'archivio di chiavi appropriato per AWS CloudHSM Client SDK 5
Il provider AWS CloudHSM Java Cryptographic Extension (JCE) offre un AWS CloudHSM per scopi speciali. KeyStore La AWS CloudHSM `KeyStore` classe supporta l'offload delle operazioni chiave sull'HSM, l'archiviazione locale dei certificati e le operazioni basate sui certificati.
Caricate il CloudHSM per scopi speciali come segue: KeyStore
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## Inizializza il Client SDK 5 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/sdk5/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 il nostro Client SDK 5 AWS CloudHSM KeyStore AWS CloudHSM
AWS CloudHSM KeyStore è conforme alle KeyStore specifiche della [classe](https://devdocs.io/openjdk~8/java/security/keystore) 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 memorizzati in un HSM non è supportata utilizzando. AWS CloudHSM KeyStore È possibile eliminare le chiavi utilizzando il metodo `destroy` dell'interfaccia [Distruggibile](https://devdocs.io/openjdk~8/javax/security/auth/destroyable#destroy--).
```
((Destroyable) key).destroy();
```
+ `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 5.**
+ `setKeyEntry` con oggetto `Key`
Assegna la chiave considerata all'alias specificato e la memorizza all'interno dell'HSM. Se la chiave non esiste già all'interno dell'HSM, verrà 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`).
# Configurazioni avanzate per AWS CloudHSM JCE for Client SDK 5
Il provider AWS CloudHSM JCE include le seguenti configurazioni avanzate, che non fanno parte delle configurazioni generali utilizzate dalla maggior parte dei clienti.
+ [Connessione a più cluster](java-lib-configs-multi.md)
+ [Estrazione delle chiavi tramite JCE](java-lib-configs-getencoded.md)
+ [Riprova la configurazione per JCE](java-lib-configs-retry.md)
# Connessione a più AWS CloudHSM cluster con il provider JCE
Questa configurazione consente a una singola istanza client di comunicare con più AWS CloudHSM cluster. Rispetto al fatto che una singola istanza comunica solo con un singolo cluster, questa può essere una funzionalità che in alcuni casi consente di risparmiare sui costi. La `CloudHsmProvider` classe è l'implementazione AWS CloudHSM della [classe Provider di Java Security](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html). Ogni istanza di questa classe rappresenta una connessione all'intero AWS CloudHSM cluster. Si crea un'istanza di questa classe e la si aggiunge all'elenco del provider di sicurezza Java in modo da poter interagire con essa utilizzando classi JCE standard.
L'esempio seguente crea un'istanza di questa classe e la aggiunge all'elenco del provider di sicurezza Java:
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
`CloudHsmProvider` può essere configurato in due modi:
1. Configura con file (configurazione predefinita)
1. Configura usando il codice
I seguenti argomenti descrivono queste configurazioni e come connettersi a più cluster.
**Topics**
+ [Configura la AWS CloudHSM `CloudHsmProvider` classe con un file (configurazione predefinita)](java-lib-configs-default.md)
+ [Configura la AWS CloudHSM `CloudHsmProvider` classe usando il codice](java-lib-configs-using-code.md)
+ [Connect a più AWS CloudHSM cluster](java-lib-connecting-to-multiclusters.md)
# Configura la AWS CloudHSM `CloudHsmProvider` classe con un file (configurazione predefinita)
Il modo predefinito per configurare la AWS CloudHSM `CloudHsmProvider` classe è con un file.
Quando si crea un'istanza `CloudHsmProvider` utilizzando il costruttore predefinito, per impostazione predefinita cercherà il file di configurazione nel percorso `/opt/cloudhsm/etc/cloudhsm-jce.cfg` in Linux. Questo file di configurazione può essere configurato utilizzando `configure-jce`.
Un oggetto creato utilizzando il costruttore predefinito utilizzerà il nome del provider CloudHSM predefinito `CloudHSM`. Il nome del provider è utile per interagire con JCE e fargli sapere quale provider utilizzare per varie operazioni. Di seguito è riportato un esempio di utilizzo del nome del provider CloudHSM per il funzionamento della crittografia:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHSM");
```
# Configura la AWS CloudHSM `CloudHsmProvider` classe usando il codice
A partire dalla versione 5.8.0 di Client SDK, puoi anche configurare la AWS CloudHSM `CloudHsmProvider` classe utilizzando il codice Java. Il modo per farlo è usare un oggetto di classe `CloudHsmProviderConfig`. È possibile creare l'oggetto utilizzando `CloudHsmProviderConfigBuilder`.
`CloudHsmProvider` ha un altro costruttore che accetta l'oggetto `CloudHsmProviderConfig`, come mostra l'esempio seguente.
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider = new CloudHsmProvider(config);
```
In questo esempio, il nome del provider JCE è. `CloudHsmCluster1` Questo è il nome che l'applicazione può quindi utilizzare per interagire con JCE:
**Example**
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHsmCluster1");
```
In alternativa, le applicazioni possono anche utilizzare l'oggetto provider creato sopra per far sapere a JCE di utilizzare quel provider per l'operazione:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider);
```
Se con il metodo `withClusterUniqueIdentifier` non viene specificato un identificatore univoco, viene creato automaticamente un nome casuale. Per ottenere questo identificatore casuale, le applicazioni possono chiamare `provider.getName()` per ottenere l'identificatore.
# Connect a più AWS CloudHSM cluster
Ciascuno `CloudHsmProvider` rappresenta una connessione al tuo AWS CloudHSM Cluster. Se si desidera comunicare con un altro cluster dalla stessa applicazione, è possibile creare un altro oggetto `CloudHsmProvider` con configurazioni per l'altro cluster e interagire con quest'altro cluster utilizzando l'oggetto provider o utilizzando il nome del provider, come illustrato nell'esempio seguente.
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider1 = new CloudHsmProvider(config);
if (Security.getProvider(provider1.getName()) == null) {
Security.addProvider(provider1);
}
CloudHsmProviderConfig config2 = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath2)
.withClusterUniqueIdentifier("CloudHsmCluster2")
.withServer(CloudHsmServer.builder().withHostIP(hostName2).build())
.build())
.build();
CloudHsmProvider provider2 = new CloudHsmProvider(config2);
if (Security.getProvider(provider2.getName()) == null) {
Security.addProvider(provider2);
}
```
Dopo aver configurato entrambi i provider (entrambi i cluster) sopra, è possibile interagire con essi utilizzando l'oggetto provider o utilizzando il nome del provider.
Ampliando questo esempio che mostra come parlare con`cluster1`, è possibile utilizzare il seguente esempio per un'AES/GCM/NoPaddingoperazione:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider1);
```
E nella stessa applicazione per eseguire la generazione di chiavi "AES" sul secondo cluster utilizzando il nome del provider, è possibile utilizzare anche il seguente esempio:
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# Estrazione delle chiavi con JCE per AWS CloudHSM
La Java Cryptography Extension (JCE) utilizza un'architettura che consente di collegare diverse implementazioni di crittografia. AWS CloudHSM fornisce uno di questi provider JCE che trasferisce le operazioni crittografiche all'HSM. Affinché la maggior parte degli altri provider JCE lavori con le chiavi archiviate in AWS CloudHSM, devono estrarre i byte chiave HSMs dal testo in chiaro nella memoria della macchina per utilizzarli. HSMs in genere consentono l'estrazione delle chiavi solo come oggetti avvolti, non come testo in chiaro. Tuttavia, per supportare i casi d'uso di integrazione tra provider, AWS CloudHSM consente un'opzione di configurazione opt-in per consentire l'estrazione dei byte delle chiavi in chiaro.
**Importante**
JCE trasferisce le operazioni AWS CloudHSM ogni volta che viene specificato il provider AWS CloudHSM o AWS CloudHSM viene utilizzato un oggetto chiave. Non è necessario estrarre le chiavi in chiaro se si prevede che l'operazione avvenga all'interno dell'HSM. L'estrazione delle chiavi in testo non crittografato è necessaria solo quando l'applicazione non può utilizzare meccanismi sicuri come eseguire e annullare il wrapping di una chiave a causa delle restrizioni imposte da una libreria di terze parti o da un provider JCE.
Per impostazione predefinita, il provider AWS CloudHSM JCE consente l'estrazione di **chiavi pubbliche** per funzionare con provider JCE esterni. I seguenti metodi sono sempre consentiti:
| Classe | Metodo | Formato (getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded() | X.509 |
| | getW() | N/D |
| RSAPublicChiave | getEncoded() | X.509 |
| | getPublicExponent() | N/D |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | N/D |
Per impostazione predefinita, il provider AWS CloudHSM JCE non consente l'estrazione di byte di chiave in chiaro per le chiavi **private** o **segrete**. Se il tuo caso d'uso lo richiede, puoi abilitare l'estrazione dei byte di chiave in chiaro per le chiavi **private** o **segrete** alle seguenti condizioni:
1. L'attributo `EXTRACTABLE` per le chiavi private e segrete è impostato su **true**.
+ Per impostazione predefinita, l'attributo `EXTRACTABLE` per le chiavi private e segrete è impostato su **true**. Le chiavi `EXTRACTABLE` sono chiavi che possono essere esportate dall'HSM. Per ulteriori informazioni, vedi Attributi Java supportati per [Client SDK 5](java-lib-attributes_5.md).
1. L'attributo `WRAP_WITH_TRUSTED` per le chiavi private e segrete è impostato su **falso**.
+ `getEncoded`, `getPrivateExponent` e `getS` non possono essere utilizzate con chiavi private che non possono essere esportate in chiaro. `WRAP_WITH_TRUSTED` non consente l'esportazione delle chiavi private dall'HSM in chiaro. Per maggiori informazioni, vedi [Using trusted keys to control key unwraps](manage-keys-using-trusted-keys.md).
# Consenti al provider JCE di estrarre chiavi private segrete da AWS CloudHSM
Utilizza i seguenti passaggi per consentire al provider AWS CloudHSM JCE di estrarre i segreti della tua chiave privata.
**Importante**
Questa modifica alla configurazione consente l'estrazione di tutti i byte chiave `EXTRACTABLE` in chiaro dal cluster HSM. Per una maggiore sicurezza, è consigliabile prendere in considerazione l'utilizzo di [metodi di wrapping di chiavi](java-lib-supported_5.md) per estrarre la chiave dall'HSM in modo sicuro. Ciò impedisce l'estrazione involontaria dei byte della chiave dall'HSM.
1. Utilizza i seguenti comandi per consentire l'estrazione delle chiavi **private** o **segrete** in JCE:
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --enable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --enable-clear-key-extraction-in-software
```
------
1. Una volta abilitata l'estrazione delle chiavi in chiaro, vengono abilitati i seguenti metodi per estrarre le chiavi private in memoria.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/cloudhsm/latest/userguide/get-encoded-take-out-private-keys.html)
Se desideri ripristinare il comportamento predefinito e non consentire a JCE di esportare le chiavi in chiaro, esegui il seguente comando:
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --disable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-clear-key-extraction-in-software
```
------
# Riprova i comandi per JCE per AWS CloudHSM
AWS CloudHSM Client SDK 5.8.0 e versioni successive dispongono di una strategia di riprova automatica integrata che riproverà le operazioni con limitazione HSM dal lato client. Quando un HSM rallenta le operazioni perché è troppo occupato nell'esecuzione di operazioni precedenti e non può accettare altre richieste, il client SDKs tenterà di riprovare le operazioni limitate fino a 3 volte, effettuando un backup esponenziale. Questa strategia automatica può essere impostata su una delle due modalità: **off** e **standard**.
+ **off**: il Client SDK non eseguirà alcun ulteriore tentativo per le operazioni limitate da parte dell'HSM.
+ **standard**: questa è la modalità predefinita per Client SDK 5.8.0 e successive. In questa modalità, il client SDKs riproverà automaticamente le operazioni limitate effettuando un backup esponenziale.
Per ulteriori informazioni, consulta [Limitazione HSM](troubleshoot-hsm-throttling.md).
## Disattiva i comandi per l'esecuzione di ulteriori tentativi
------
#### [ Linux ]
**Come impostare i comandi Nuovo tentativo su **off** per Client SDK 5 su Linux**
+ Per impostare la configurazione in modalità **off**, utilizza i seguenti comandi:
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**Per impostare i comandi Nuovo Tentativo su **off** per Client SDK 5 su Windows**
+ Per impostare la configurazione in modalità **off**, utilizza i seguenti comandi:
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------