Comprensione degli attributi Attributi supportati Impostazione attributi per una chiave Mettere tutto insieme

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 il 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.

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, Java Cryptography Extension (JCE) non specifica come impostare i valori sugli attributi chiave, quindi la maggior parte delle azioni era consentita per impostazione predefinita. Al contrario, lo standard PKCS n. 11 definisce un set completo di attributi con impostazioni predefinite più restrittive. A partire dalla versione 3.1 della libreria Java, Cloud HSM 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 specifichi un valore, Cloud HSM 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
`CKA_TOKEN`	`FALSE`	`FALSE`	`FALSE`	Una chiave permanente che viene replicata HSMs in tutto il cluster e inclusa nei backup. CKA_ TOKEN = FALSE implica una chiave di sessione, che viene caricata solo su una chiave HSM e cancellata automaticamente quando la connessione a viene interrottaHSM.
`CKA_LABEL`				Una stringa definita dall'utente. Ti consente di identificare comodamente le chiavi sul tuo. HSM
`CKA_EXTRACTABLE`	`TRUE`		`TRUE`	Il valore True indica che è possibile esportare questa chiave da. HSM
`CKA_ENCRYPT`	`TRUE`	`TRUE`		Il valore Vero indica che è possibile utilizzare la chiave per crittografare qualsiasi buffer.
`CKA_DECRYPT`	`TRUE`		`TRUE`	Il valore Vero indica che è possibile utilizzare la chiave per decodificare qualsiasi buffer. In genere lo si imposta su FALSE una chiave il cui CKA _ WRAP è impostato su true.
`CKA_WRAP`	`TRUE`	`TRUE`		Il valore Vero indica che è possibile utilizzare la chiave per eseguire il wrapping di un'altra chiave. In genere lo imposterai su FALSE per le chiavi private.
`CKA_UNWRAP`	`TRUE`		`TRUE`	Il valore Vero indica che è possibile utilizzare la chiave per annullare il wrapping (importare) di un'altra chiave.
`CKA_SIGN`	`TRUE`		`TRUE`	Il valore Vero indica che è possibile utilizzare la chiave per firmare messaggio di digest. In genere è impostato FALSE per le chiavi pubbliche e per le chiavi private archiviate.
`CKA_VERIFY`	`TRUE`	`TRUE`		Il valore Vero indica che è possibile utilizzare la chiave per verificare una firma. Questa impostazione è generalmente impostata FALSE per le chiavi private.
`CKA_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 su Cloud HSM finché non vengono autenticati, anche se questo attributo è impostato su. FALSE

Nota

Ottieni un supporto più ampio per gli attributi nella libreria PKCS #11. Per ulteriori informazioni, consulta Attributi PKCS #11 supportati.

Impostazione attributi per una chiave

CloudHsmKeyAttributesMap è un oggetto simile a Java 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:

Operazione	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, valore)
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	rimuovere (keyAttribute)

Nota

Eventuali attributi non specificati in modo esplicito vengono impostati sui valori predefiniti elencati nella tabella precedente in Attributi supportati.

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. Per 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 e l'esempio su. 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:

Creare un'istanza CloudHsmKeyAttributesMap per chiavi simmetriche o CloudHsmKeyPairAttributesMap per coppie di chiavi.
Definire l'oggetto attributi dalla fase 1 con gli attributi e i valori chiave richiesti.
Creare un'istanza di una classe Cavium*ParameterSpec, corrispondente al tipo di chiave specifico e passare al costruttore questo oggetto attributi configurato.
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);

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Meccanismi

Esempi di codice