Présentation des attributs Attributs pris en charge Définition des attributs pour une clé Tout mettre en place

Attributs de clé Java pris en charge pour le SDK client 3

Cette rubrique décrit comment utiliser une extension propriétaire pour la bibliothèque Java version 3.1 afin de définir les attributs des clés. Utilisez cette extension pour définir les attributs de clés pris en charge et leurs valeurs au cours des opérations suivantes :

Génération de clés
Importation de clés
Désencapsulage de clés

Note

L'extension permettant de définir des attributs de clés personnalisés est une fonctionnalité facultative. Si vous avez déjà du code qui fonctionne dans la bibliothèque Java version 3.0, vous n'avez pas besoin de modifier ce code. Les clés que vous créez continueront de contenir les mêmes attributs qu'auparavant.

Présentation des attributs

Les attributs de clés permettent de spécifier les actions autorisées sur les objets de type clé, y compris les clés publiques, privées ou secrètes. Vous définissez les attributs de clés et leurs valeurs lors des opérations de création d'objets de type clé.

Toutefois, l'extension JCE (Java Cryptography Extension) ne spécifie pas comment définir les valeurs des attributs de clés. Dès lors, la plupart des actions étaient autorisées par défaut. En revanche, la norme PKCS #11 définit un ensemble complet d'attributs avec des valeurs par défaut plus restrictives. À partir de la version 3.1 de la bibliothèque Java, CloudHSM fournit une extension propriétaire qui vous permet de définir des valeurs plus restrictives pour les attributs couramment utilisés.

Attributs pris en charge

Vous pouvez définir des valeurs pour les attributs répertoriés dans le tableau ci-dessous. Il est conseillé de spécifier uniquement des valeurs pour les attributs que vous souhaitez restreindre. Si vous n'indiquez pas de valeur, CloudHSM utilise la valeur par défaut spécifiée dans le tableau ci-dessous. Une cellule vide dans la colonne Default Value (Valeur par défaut) signale qu'aucune valeur par défaut n'est assignée à l'attribut.

Attribut	Valeur par défaut			Remarques
	Clé symétrique	Clé publique dans la paire de clés	Clé privée dans la paire de clés
`CKA_TOKEN`	`FALSE`	`FALSE`	`FALSE`	Clé permanente répliquée sur tous les HSM du cluster et incluse dans les sauvegardes. CKA_TOKEN = FALSE implique une clé de session, qui n'est chargée que sur un seul HSM et automatiquement effacée lorsque la connexion au HSM est interrompue.
`CKA_LABEL`				Chaîne définie par l'utilisateur. Permet d'identifier facilement les clés de votre HSM.
`CKA_EXTRACTABLE`	`TRUE`		`TRUE`	True indique que vous pouvez exporter cette clé hors du HSM.
`CKA_ENCRYPT`	`TRUE`	`TRUE`		True indique que vous pouvez utiliser la clé pour chiffrer n'importe quelle mémoire tampon.
`CKA_DECRYPT`	`TRUE`		`TRUE`	True indique que vous pouvez utiliser la clé pour déchiffrer n'importe quelle mémoire tampon. Vous définissez généralement cette valeur sur FALSE pour une clé dont l'attribut CKA_WRAP est défini sur true.
`CKA_WRAP`	`TRUE`	`TRUE`		True indique que vous pouvez utiliser la clé pour encapsuler une autre clé. Vous définissez généralement ce paramètre sur FALSE pour les clés privées.
`CKA_UNWRAP`	`TRUE`		`TRUE`	True indique que vous pouvez utiliser la clé pour décencapsuler (importer) une autre clé.
`CKA_SIGN`	`TRUE`		`TRUE`	True indique que vous pouvez utiliser la clé pour signer le résumé d'un message. Cette valeur est généralement définie sur FALSE pour les clés publiques et les clés privées que vous avez archivées.
`CKA_VERIFY`	`TRUE`	`TRUE`		True indique que vous pouvez utiliser la clé pour valider une signature. Cette valeur est généralement définie sur FALSE pour les clés privées.
`CKA_PRIVATE`	`TRUE`	`TRUE`	`TRUE`	True indique qu'un utilisateur ne peut pas accéder à la clé tant qu'il n'est pas authentifié. Pour plus de clarté, les utilisateurs ne peuvent accéder à aucune clé sur CloudHSM tant qu'ils n'ont pas été authentifiés, même si cet attribut est défini sur FALSE.

Note

Vous bénéficiez d'une prise en charge plus large des attributs dans la bibliothèque PKCS #11. Pour plus d'informations, consultez Attributs PKCS #11 pris en charge.

Définition des attributs pour une clé

CloudHsmKeyAttributesMap est un objet de type Java Map que vous pouvez utiliser pour définir des valeurs d'attribut pour les objets de type clé. Les méthodes de CloudHsmKeyAttributesMap fonctionne d'une manière similaire à celles utilisées pour la manipulation de Java Map.

Pour définir des valeurs personnalisées pour les attributs, deux options s'offrent à vous :

Utiliser les méthodes répertoriées dans le tableau suivant
Utiliser les modèles de générateur illustrés plus loin dans ce document

Les objets de mappage d'attribut prennent en charge les méthodes suivantes pour définir les attributs :

Opération	Valeur renvoyée	Méthode `CloudHSMKeyAttributesMap`
Obtenir la valeur d'un attribut pour une clé existante	Objet (contenant la valeur) ou null	get(keyAttribute)
Renseigner la valeur d'un attribut de clé	Valeur précédente associée à l'attribut de clé, ou null en l'absence de mappage pour un attribut de clé	put(keyAttribute, value)
Renseigner des valeurs pour plusieurs attributs de clés	N/A	Tout mettre () keyAttributesMap
Supprimer une paire clé-valeur du mappage d'attributs	Valeur précédente associée à l'attribut de clé, ou null en l'absence de mappage pour un attribut de clé	remove(keyAttribute)

Note

Tous les attributs que vous ne spécifiez pas explicitement utilisent les valeurs par défaut répertoriées dans le tableau précédent, dans Attributs pris en charge.

Exemple de modèle de générateur

Les développeurs trouvent généralement plus pratique d'utiliser les classes via le modèle de générateur. À titre d'exemple :


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();

Les développeurs peuvent également utiliser des ensembles d'attributs prédéfinis comme un moyen pratique d'imposer le respect des bonnes pratiques dans les modèles de clés. À titre d'exemple :


//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

Définition des attributs pour une paire de clés

Utilisez la classe Java CloudHsmKeyPairAttributesMap pour gérer les attributs d'une paire de clés. CloudHsmKeyPairAttributesMap encapsule deux objets CloudHsmKeyAttributesMap : un pour une clé publique et un pour une clé privée.

Pour définir des attributs individuels de la clé publique et la clé privée séparément, vous pouvez utiliser la méthode put() sur l'objet mappé CloudHsmKeyAttributes correspondant à cette clé. Choisissez la méthode getPublic() pour récupérer le mappage d'attributs de la clé publique, et utilisez getPrivate() pour récupérer le mappage d'attributs de la clé privée. Renseignez la valeur de plusieurs attributs de clés pour les paires de clés publiques et privées en utilisant putAll() avec le mappage d'attributs d'une paire de clés comme argument.

Exemple de modèle de générateur

Les développeurs trouvent généralement plus pratique de définir des attributs de clés via le modèle de générateur. Par exemple :


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();

Note

Pour plus d'informations sur cette extension propriétaire, consultez l'archive Javadoc et l'exemple sur. GitHub Pour explorer Javadoc, téléchargez et développez l'archive.

Tout mettre en place

Pour spécifier des attributs de clés avec vos opérations de clés, procédez comme suit :

Instancier CloudHsmKeyAttributesMap pour les clés symétriques ou CloudHsmKeyPairAttributesMap pour les paires de clés.
Définissez l'objet Attributs de l'étape 1 avec les attributs et valeurs de clés requis.
Instanciez une classe Cavium*ParameterSpec, correspondant à votre type de clé spécifique, et transmettez cet objet d'attributs configuré à son constructeur.
Transmettez cet objet Cavium*ParameterSpec à une classe ou une méthode de chiffrement correspondante.

Pour référence, le tableau suivant contient les classes et méthodes Cavium*ParameterSpec qui prennent en charge les attributs de clé personnalisés.

Type de clé	Classe de spécification de paramètre	Exemples de constructeurs
Classe de base	`CaviumKeyGenAlgorithmParameterSpec`	`CaviumKeyGenAlgorithmParameterSpec(CloudHsmKeyAttributesMap keyAttributesMap)`
DES	`CaviumDESKeyGenParameterSpec`	`CaviumDESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap)`
RSA	`CaviumRSAKeyGenParameterSpec`	`CaviumRSAKeyGenParameterSpec(int keysize, BigInteger publicExponent, CloudHsmKeyPairAttributesMap keyPairAttributesMap)`
Secret	`CaviumGenericSecretKeyGenParameterSpec`	`CaviumGenericSecretKeyGenParameterSpec(int size, CloudHsmKeyAttributesMap keyAttributesMap)`
AES	`CaviumAESKeyGenParameterSpec`	`CaviumAESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap)`
EC	`CaviumECGenParameterSpec`	`CaviumECGenParameterSpec(String stdName, CloudHsmKeyPairAttributesMap keyPairAttributesMap)`

Exemple de code : générer et encapsuler une clé

Ces brefs exemples de code illustrent les étapes de deux opérations différentes : la génération d'une clé et son encapsulage :


// 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);

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Mécanismes

Exemples de code