AWS KMS Porte-clés hiérarchiques - AWS SDK de chiffrement de base de données
Comment ça marchePrérequisCréation d'un porte-clés hiérarchiqueFaites pivoter votre clé de branche activeUtilisation du trousseau de clés hiérarchique avec des bases de données mutualiséesUtilisation du trousseau de clés hiérarchique pour un chiffrement consultable

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

AWS KMS Porte-clés hiérarchiques

Notre bibliothèque de chiffrement côté client a été renommée SDK de chiffrement de AWS base de données. Ce guide du développeur fournit toujours des informations sur le client de chiffrement DynamoDB.
Note

Depuis le 24 juillet 2023, les clés de branche créées lors de la version préliminaire pour les développeurs ne sont plus prises en charge. Créez de nouvelles clés de branche pour continuer à utiliser le magasin de clés de branche que vous avez créé lors de la version préliminaire pour les développeurs.

Avec le trousseau de clés AWS KMS hiérarchique, vous pouvez protéger vos documents cryptographiques sous une clé KMS de chiffrement symétrique sans avoir à appeler AWS KMS chaque fois que vous chiffrez ou déchiffrez un enregistrement. Il s'agit d'un bon choix pour les applications qui doivent minimiser les appels AWS KMS, ainsi que pour les applications qui peuvent réutiliser certains matériels cryptographiques sans enfreindre leurs exigences de sécurité.

Le trousseau de clés hiérarchique est une solution de mise en cache des matériaux cryptographiques qui réduit le nombre d' AWS KMS appels en utilisant des clés de branche AWS KMS protégées conservées dans une table Amazon DynamoDB, puis en mettant en cache localement les éléments clés de branche utilisés dans les opérations de chiffrement et de déchiffrement. La table DynamoDB sert de magasin de clés de branche qui gère et protège les clés de branche. Il stocke la clé de branche active et toutes les versions précédentes de la clé de branche. La clé de branche active est la version de clé de branche la plus récente. Le trousseau de clés hiérarchique utilise une clé de données unique pour chiffrer chaque champ et chiffre chaque clé de données avec une clé d'encapsulation unique dérivée de la clé de branche active. Le trousseau de clés hiérarchique dépend de la hiérarchie établie entre les clés de branche actives et leurs clés d'encapsulation dérivées.

Le trousseau de clés hiérarchique utilise généralement chaque version de clé de branche pour satisfaire plusieurs demandes. Mais vous contrôlez la mesure dans laquelle les clés de branche actives sont réutilisées et vous déterminez la fréquence à laquelle la clé de branche active est pivotée. La version active de la clé de branche reste active jusqu'à ce que vous la fassiez pivoter. Les versions précédentes de la clé de branche active ne seront pas utilisées pour effectuer des opérations de chiffrement, mais elles peuvent toujours être interrogées et utilisées dans des opérations de déchiffrement.

Lorsque vous instanciez le trousseau de clés hiérarchique, il crée un cache local. Vous spécifiez une limite de cache qui définit la durée maximale pendant laquelle les éléments clés de branche sont stockés dans le cache local avant leur expiration et leur expulsion du cache. Le trousseau de clés hiérarchique effectue un AWS KMS appel pour déchiffrer la clé de branche et assembler les matériaux de la clé de branche la première fois que a branch-key-id est spécifié dans une opération. Les éléments clés de branche sont ensuite stockés dans le cache local et réutilisés pour toutes les opérations de chiffrement et de déchiffrement qui le spécifient branch-key-id jusqu'à l'expiration de la limite de cache. Le stockage des éléments clés de branche dans le cache local réduit le nombre d' AWS KMS appels. Par exemple, considérez une limite de cache de 15 minutes. Si vous effectuez 10 000 opérations de chiffrement dans cette limite de cache, le trousseau de AWS KMS clés traditionnel devra effectuer 10 000 AWS KMS appels pour satisfaire 10 000 opérations de chiffrement. Si vous en avez un actifbranch-key-id, le trousseau de clés hiérarchique n'a besoin que d'un seul AWS KMS appel pour satisfaire 10 000 opérations de chiffrement.

Le cache local se compose de deux partitions, l'une pour les opérations de chiffrement et l'autre pour les opérations de déchiffrement. La partition de chiffrement stocke les éléments de clé de branche assemblés à partir de la clé de branche active et les réutilise pour toutes les opérations de chiffrement jusqu'à l'expiration de la limite de cache. La partition de déchiffrement stocke les matériaux de clé de branche assemblés pour les autres versions de clé de branche identifiées lors des opérations de déchiffrement. La partition de déchiffrement peut stocker plusieurs versions de documents clés de branche actifs à la fois. Lorsqu'elle est configurée pour utiliser un fournisseur d'ID de clé de branche pour une base de données mutualisée, la partition de chiffrement peut également stocker plusieurs versions de matériaux de clé de branche à la fois. Pour plus d’informations, consultez Utilisation du trousseau de clés hiérarchique avec des bases de données mutualisées.

Note

Toutes les mentions du jeu de clés hiérarchique dans le SDK de chiffrement AWS de base de données font référence au jeu de clés AWS KMS hiérarchique.

Comment ça marche

Les procédures pas à pas suivantes décrivent comment le trousseau de clés hiérarchique assemble le matériel de chiffrement et de déchiffrement, ainsi que les différents appels effectués par le trousseau de clés pour les opérations de chiffrement et de déchiffrement. Pour plus de détails techniques sur les processus de dérivation des clés d'encapsulation et de chiffrement des clés de données en texte clair, consultez la section Détails techniques du trousseau de clés AWS KMS hiérarchique.

Chiffrer et signer

La procédure pas à pas suivante décrit comment le trousseau de clés hiérarchique assemble les matériaux de chiffrement et en déduit une clé d'encapsulation unique.

  1. La méthode de cryptage demande au trousseau de clés hiérarchique le matériel de cryptage. Le trousseau de clés génère une clé de données en texte brut, puis vérifie s'il existe des éléments de branche valides dans le cache local pour générer la clé d'encapsulation. S'il existe des documents relatifs aux clés de succursale valides, le porte-clés passe à l'étape 5.

  2. S'il n'existe aucun matériel de clé de branche valide, le trousseau de clés hiérarchique interroge le magasin de clés de branche pour trouver la clé de branche active.

    1. Le magasin de clés de branche appelle AWS KMS pour déchiffrer la clé de branche active et renvoie la clé de branche active en texte clair. Les données identifiant la clé de branche active sont sérialisées pour fournir des données authentifiées supplémentaires (AAD) lors de l'appel de déchiffrement à. AWS KMS

    2. Le magasin de clés de branche renvoie la clé de branche en texte brut et les données qui l'identifient, telles que la version de la clé de branche.

  3. Le trousseau de clés hiérarchique assemble les éléments clés de branche (version de clé de branche en texte clair et de clé de branche) et en stocke une copie dans le cache local.

  4. Le trousseau de clés hiérarchique déduit une clé d'encapsulation unique à partir de la clé de branche en texte brut et d'un sel aléatoire de 16 octets. Il utilise la clé d'encapsulation dérivée pour chiffrer une copie de la clé de données en texte brut.

La méthode de cryptage utilise le matériel de cryptage pour chiffrer et signer l'enregistrement. Pour plus d'informations sur la façon dont les enregistrements sont chiffrés et signés dans le SDK AWS de chiffrement de base de données, voir Chiffrer et signer.

Afficher plusAfficher moins
Déchiffrer et vérifier

La procédure pas à pas suivante décrit comment le trousseau de clés hiérarchique assemble le matériel de déchiffrement et déchiffre la clé de données chiffrée.

  1. Le procédé de déchiffrement identifie la clé de données chiffrée dans le champ de description matérielle de l'enregistrement chiffré et la transmet au trousseau de clés hiérarchique.

  2. Le trousseau hiérarchique désérialise les données identifiant la clé de données chiffrée, y compris la version de la clé de branche, le sel de 16 octets et d'autres informations décrivant le mode de chiffrement de la clé de données.

    Pour plus d’informations, consultez AWS KMSDétails techniques du porte-clés hiérarchique.

  3. Le trousseau de clés hiérarchique vérifie si le cache local contient des éléments de clé de branche valides qui correspondent à la version de clé de branche identifiée à l'étape 2. S'il existe des documents relatifs aux clés de succursale valides, le porte-clés passe à l'étape 6.

  4. S'il n'existe aucun matériel de clé de branche valide, le trousseau de clés hiérarchique interroge le magasin de clés de branche pour trouver la clé de branche correspondant à la version de clé de branche identifiée à l'étape 2.

    1. Le magasin de clés de branche appelle AWS KMS pour déchiffrer la clé de branche et renvoie la clé de branche active en texte clair. Les données identifiant la clé de branche active sont sérialisées pour fournir des données authentifiées supplémentaires (AAD) lors de l'appel de déchiffrement à. AWS KMS

    2. Le magasin de clés de branche renvoie la clé de branche en texte brut et les données qui l'identifient, telles que la version de la clé de branche.

  5. Le trousseau de clés hiérarchique assemble les éléments clés de branche (version de clé de branche en texte clair et de clé de branche) et en stocke une copie dans le cache local.

  6. Le trousseau de clés hiérarchique utilise les éléments de clé de branche assemblés et le sel de 16 octets identifié à l'étape 2 pour reproduire la clé d'encapsulation unique qui a chiffré la clé de données.

  7. Le trousseau de clés hiérarchique utilise la clé d'encapsulation reproduite pour déchiffrer la clé de données et renvoie la clé de données en texte brut.

La méthode de déchiffrement utilise le matériel de déchiffrement et la clé de données en texte brut pour déchiffrer et vérifier l'enregistrement. Pour plus d'informations sur la façon dont les enregistrements sont déchiffrés et vérifiés dans le SDK de chiffrement de AWS base de données, voir Déchiffrer et vérifier.

Afficher plusAfficher moins

Prérequis

Le SDK AWS de chiffrement de base de données n'en nécessite pas Compte AWS et n'en dépend pas Service AWS. Toutefois, le trousseau de clés hiérarchique dépend d'Amazon AWS KMS DynamoDB.

Pour utiliser un trousseau de clés hiérarchique, vous avez besoin d'un chiffrement symétrique AWS KMS key avec les autorisations KMS:Decrypt. Vous pouvez également utiliser une clé multirégionale de chiffrement symétrique. Pour obtenir des informations détaillées sur les autorisations pour AWS KMS keys, voir Authentification et contrôle d'accès dans le Guide du AWS Key Management Service développeur.

Avant de pouvoir créer et utiliser un trousseau de clés hiérarchique, vous devez créer votre magasin de clés de succursale et le remplir avec votre première clé de branche active.

Étape 1 : Configuration d'un nouveau service de stockage de clés

Le service de magasin de clés propose plusieurs opérations, telles que CreateKeyStore etCreateKey, pour vous aider à réunir les prérequis relatifs au jeu de clés hiérarchique et à gérer le magasin de clés de votre succursale.

L'exemple suivant crée un service de stockage de clés. Vous devez spécifier un nom de table DynamoDB qui servira de nom à votre magasin de clés de branche, un nom logique pour le magasin de clés de branche et l'ARN de la clé KMS qui identifie la clé KMS qui protégera vos clés de branche.

Le nom du magasin de clés logique est lié de manière cryptographique à toutes les données stockées dans la table afin de simplifier les opérations de restauration DynamoDB. Le nom logique du magasin de clés peut être identique au nom de votre table DynamoDB, mais ce n'est pas obligatoire. Nous vous recommandons vivement de spécifier le nom de votre table DynamoDB comme nom de table logique lorsque vous configurez votre service de banque de clés pour la première fois. Vous devez toujours spécifier le même nom de table logique. Si le nom de votre banque de clés de branche change après la restauration de votre table DynamoDB à partir d'une sauvegarde, le nom de la banque de clés logique correspond au nom de la table DynamoDB que vous spécifiez pour garantir que le trousseau de clés hiérarchique peut toujours accéder à votre magasin de clés de succursale.

Java
final KeyStore keystore = KeyStore.builder().KeyStoreConfig(
                KeyStoreConfig.builder()
                        .ddbClient(DynamoDbClient.create())
                        .ddbTableName(keyStoreName)
                        .logicalKeyStoreName(logicalKeyStoreName)
                        .kmsClient(KmsClient.create())
                        .kmsConfiguration(KMSConfiguration.builder()
                                .kmsKeyArn(kmsKeyArn)
                                .build())
                        .build()).build();
C# / .NET
var kmsConfig = new KMSConfiguration { KmsKeyArn = kmsKeyArn };
var keystoreConfig = new KeyStoreConfig
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsConfiguration = kmsConfig,
    DdbTableName = keyStoreName,
    DdbClient = new AmazonDynamoDBClient(),
    LogicalKeyStoreName = logicalKeyStoreName
};
var keystore = new KeyStore(keystoreConfig);
Étape 2 : Appelez CreateKeyStore pour créer un magasin de clés de succursale

L'opération suivante crée le magasin de clés de branche qui conservera et protégera vos clés de branche.

Java
keystore.CreateKeyStore(CreateKeyStoreInput.builder().build());
C# / .NET
var createKeyStoreOutput = keystore.CreateKeyStore(new CreateKeyStoreInput());

L'CreateKeyStoreopération crée une table DynamoDB avec le nom de table que vous avez spécifié à l'étape 1 et les valeurs obligatoires suivantes.

Clé de partition Clé de tri
Table de base branch-key-id type
Note

Vous pouvez créer manuellement la table DynamoDB qui sert de magasin de clés de branche au lieu d'utiliser l'opération. CreateKeyStore Si vous choisissez de créer manuellement le magasin de clés de branche, vous devez spécifier les valeurs de chaîne suivantes pour la partition et les clés de tri :

  • Clé de partition: branch-key-id

  • Clé de tri: type

Étape 3 : Appelez CreateKey pour créer une nouvelle clé de branche active

L'opération suivante crée une nouvelle clé de branche active à l'aide de la clé KMS que vous avez spécifiée à l'étape 1 et ajoute la clé de branche active à la table DynamoDB que vous avez créée à l'étape 2.

Lorsque vous appelezCreateKey, vous pouvez choisir de spécifier les valeurs facultatives suivantes.

Java
final Map<String, String> additionalEncryptionContext = Collections.singletonMap("Additional Encryption Context for",
        "custom branch key id");
            
final String BranchKey = keystore.CreateKey(
        CreateKeyInput.builder()
                .branchKeyIdentifier(custom-branch-key-id) //OPTIONAL
                .encryptionContext(additionalEncryptionContext) //OPTIONAL
                .build()).branchKeyIdentifier();
C# / .NET
var additionalEncryptionContext = new Dictionary<string, string>();
additionalEncryptionContext.Add("Additional Encryption Context for", "custom branch key id");
        
var branchKeyId = keystore.CreateKey(new CreateKeyInput
{
    BranchKeyIdentifier = "custom-branch-key-id", // OPTIONAL
    EncryptionContext = additionalEncryptionContext // OPTIONAL
});

Tout d'abord, l'CreateKeyopération génère les valeurs suivantes.

Ensuite, l'CreateKeyopération appelle kms : GenerateDataKeyWithoutPlaintext en utilisant la requête suivante.

{
   "EncryptionContext": { 
      "branch-key-id" : "branch-key-id",
      "type" : "type",
      "create-time" : "timestamp",
      "logical-key-store-name" : "the logical table name for your branch key store",
      "kms-arn" : the KMS key ARN,
      "hierarchy-version" : "1",
      "aws-crypto-ec:contextKey": "contextValue"
   },
   "KeyId": "the KMS key ARN you specified in Step 1",
   "NumberOfBytes": "32"
}
Note

L'CreateKeyopération crée une clé de branche active et une clé de balise, même si vous n'avez pas configuré votre base de données pour un chiffrement consultable. Les deux clés sont stockées dans le magasin de clés de votre agence. Pour plus d'informations, voir Utilisation du trousseau de clés hiérarchique pour le chiffrement consultable.

Ensuite, l'CreateKeyopération appelle kms : ReEncrypt pour créer un enregistrement actif pour la clé de branche en mettant à jour le contexte de chiffrement.

Enfin, l'CreateKeyopération appelle ddb : TransactWriteItems pour écrire un nouvel élément qui conservera la clé de branche dans la table que vous avez créée à l'étape 2. L'article possède les attributs suivants.

{
    "branch-key-id" : branch-key-id,
    "type" : "branch:ACTIVE",
    "enc" : the branch key returned by the GenerateDataKeyWithoutPlaintext call,
    "version": "branch:version:the branch key version UUID",
    "create-time" : "timestamp",
    "kms-arn" : "the KMS key ARN you specified in Step 1",
    "hierarchy-version" : "1",
    "aws-crypto-ec:contextKey": "contextValue"
}

Création d'un porte-clés hiérarchique

Pour initialiser le trousseau de clés hiérarchique, vous devez fournir les valeurs suivantes :

  • Un nom de magasin clé de succursale

    Nom de la table DynamoDB que vous avez créée pour servir de magasin de clés de succursale.

  • Une limite de durée de vie du cache (TTL)

    Durée en secondes pendant laquelle une entrée de clé de branche dans le cache local peut être utilisée avant son expiration. La limite de cache TTL détermine la fréquence à laquelle le client appelle AWS KMS pour autoriser l'utilisation des clés de branche. Cette valeur doit être supérieure à zéro. Lorsque la limite de cache TTL expire, l'entrée est expulsée du cache local.

  • Un identifiant de clé de branche

    Le branch-key-id qui identifie la clé de succursale active dans votre magasin de clés de succursale.

    Note

    Pour initialiser le trousseau de clés hiérarchique pour une utilisation par plusieurs locataires, vous devez spécifier un fournisseur d'ID de clé de branche au lieu d'un. branch-key-id Pour plus d’informations, consultez Utilisation du trousseau de clés hiérarchique avec des bases de données mutualisées.

  • (Facultatif) Une liste de jetons de subvention

    Si vous contrôlez l'accès à la clé KMS dans votre trousseau de clés hiérarchique avec des autorisations, vous devez fournir tous les jetons de subvention nécessaires lorsque vous initialisez le trousseau de clés.

Les exemples suivants montrent comment initialiser un jeu de clés hiérarchique avec le SDK AWS Database Encryption pour le client DynamoDB. L'exemple suivant indique une limite de cache TTL de 600 secondes.

Java
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(branchKeyStoreName)
        .branchKeyId(branch-key-id)
        .ttlSeconds(600)
        .build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
C# / .NET
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);

Faites pivoter votre clé de branche active

Il ne peut y avoir qu'une seule version active à la fois pour chaque clé de branche. Le trousseau de clés hiérarchique utilise généralement chaque version de clé de branche active pour satisfaire plusieurs demandes. Mais vous contrôlez la mesure dans laquelle les clés de branche actives sont réutilisées et vous déterminez la fréquence à laquelle la clé de branche active est pivotée.

Les clés de branche ne sont pas utilisées pour chiffrer les clés de données en texte brut. Ils sont utilisés pour dériver les clés d'encapsulation uniques qui chiffrent les clés de données en texte brut. Le processus de dérivation de la clé d'encapsulation produit une clé d'encapsulation unique de 32 octets avec 28 octets aléatoires. Cela signifie qu'une clé de branche peut obtenir plus de 79 octillions, soit 2 96, clés d'encapsulation uniques avant que l'usure cryptographique ne se produise. Malgré ce très faible risque d'épuisement, il se peut que vous deviez effectuer une rotation de vos clés de succursale actives en raison de règles commerciales, contractuelles ou gouvernementales.

La version active de la clé de branche reste active jusqu'à ce que vous la fassiez pivoter. Les versions précédentes de la clé de branche active ne seront pas utilisées pour effectuer des opérations de chiffrement et ne peuvent pas être utilisées pour dériver de nouvelles clés d'encapsulation. Mais ils peuvent toujours être interrogés et fournir des clés d'encapsulation pour déchiffrer les clés de données qu'ils ont chiffrées lorsqu'ils sont actifs.

Utilisez le VersionKey service Key Store pour faire pivoter votre clé de branche active. Lorsque vous faites pivoter la clé de branche active, une nouvelle clé de branche est créée pour remplacer la version précédente. branch-key-idCela ne change pas lorsque vous faites pivoter la clé de branche active. Vous devez spécifier le code branch-key-id qui identifie la clé de branche active actuelle lorsque vous appelezVersionKey.

Java
keystore.VersionKey(
    VersionKeyInput.builder()
        .branchKeyIdentifier("branch-key-id")
        .build()
);
C# / .NET
 keystore.VersionKey(new VersionKeyInput{BranchKeyIdentifier = branchKeyId});

Utilisation du trousseau de clés hiérarchique avec des bases de données mutualisées

Vous pouvez utiliser la hiérarchie des clés établie entre les clés de branche actives et leurs clés d'encapsulation dérivées pour prendre en charge les bases de données mutualisées en créant une clé de branche pour chaque locataire de votre base de données. Le trousseau de clés hiérarchique chiffre et signe ensuite toutes les données d'un locataire donné avec sa clé de branche distincte. Cela vous permet de stocker les données mutualisées dans une base de données unique et d'isoler les données des locataires par clé de branche.

Chaque locataire possède sa propre clé de branche définie par une clé uniquebranch-key-id. Il ne peut y avoir qu'une seule version active de chaque version branch-key-id à la fois.

Fournisseur de clés d'identification de succursale

Avant de pouvoir initialiser votre trousseau de clés hiérarchique pour une utilisation par plusieurs locataires, vous devez créer une clé de branche pour chaque locataire et créer un fournisseur d'ID de clé de branche. Le fournisseur d'ID de clé de branche utilise les champs stockés dans le contexte de chiffrement pour déterminer la clé de branche du locataire requise pour déchiffrer un enregistrement. Par défaut, seules les clés de partition et de tri sont incluses dans le contexte de chiffrement. Toutefois, vous pouvez utiliser l'action SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT cryptographique pour inclure des champs supplémentaires dans le contexte de chiffrement.

Note

Pour utiliser l'action SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT cryptographique, vous devez utiliser la version 3.3 ou ultérieure du SDK AWS Database Encryption. Déployez la nouvelle version sur tous les lecteurs avant de mettre à jour votre modèle de données pour l'inclureSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.

Vous pouvez utiliser le fournisseur d'identifiant de clé de succursale pour créer un nom convivial branch-key-ids afin de permettre à un locataire de reconnaître facilement le nom correctbranch-key-id. Par exemple, le nom convivial vous permet de faire référence à une clé de branche au tenant1 lieu deb3f61619-4d35-48ad-a275-050f87e15122.

Pour les opérations de déchiffrement, vous pouvez soit configurer de manière statique un jeu de clés hiérarchique unique pour limiter le déchiffrement à un seul locataire, soit utiliser le fournisseur d'ID de clé de branche pour identifier le locataire responsable du déchiffrement d'un enregistrement.

Tout d'abord, suivez les étapes 1 et 2 des procédures relatives aux prérequis. Utilisez ensuite les procédures suivantes pour créer une clé de branche pour chaque locataire, créer un fournisseur d'ID de clé de branche et initialiser votre jeu de clés hiérarchique pour une utilisation par plusieurs locataires.

Étape 1 : créer une clé de branche pour chaque locataire de votre base de données

Appelez CreateKey chaque locataire de votre base de données.

L'opération suivante crée deux clés de branche à l'aide de la clé KMS que vous avez spécifiée lors de la création de votre service de magasin de clés, et ajoute les clés de branche à la table DynamoDB que vous avez créée pour servir de magasin de clés de branche. La même clé KMS doit protéger toutes les clés de branche.

Java
CreateKeyOutput branchKeyId1 = keystore.CreateKey(CreateKeyInput.builder().build());
CreateKeyOutput branchKeyId2 = keystore.CreateKey(CreateKeyInput.builder().build());
C# / .NET
var branchKeyId1 = keystore.CreateKey(new CreateKeyInput());
var branchKeyId2 = keystore.CreateKey(new CreateKeyInput());
Étape 2 : créer un fournisseur d'ID de clé de succursale

L'exemple suivant crée des noms conviviaux pour les deux clés de branche créées à l'étape 1 et appelle CreateDynamoDbEncryptionBranchKeyIdSupplier à créer un fournisseur d'ID de clé de branche avec le SDK AWS Database Encryption pour le client DynamoDB.

Java
// Create friendly names for each branch-key-id 
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
    private static String branchKeyIdForTenant1;
    private static String branchKeyIdForTenant2;

    public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
        this.branchKeyIdForTenant1 = tenant1Id;
        this.branchKeyIdForTenant2 = tenant2Id;
    }
// Create the branch key ID supplier    
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
        .DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
        .build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
    CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
            .ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
            .build()).branchKeyIdSupplier();
C# / .NET
// Create friendly names for each branch-key-id
 class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
    private String _branchKeyIdForTenant1;
    private String _branchKeyIdForTenant2;

    public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
        this._branchKeyIdForTenant1 = tenant1Id;
        this._branchKeyIdForTenant2 = tenant2Id;
    }    
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
    new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
    {
        DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
    }).BranchKeyIdSupplier;
Étape 3 : Initialisez votre trousseau de clés hiérarchique avec le fournisseur d'ID de clé de branche

Pour initialiser le trousseau de clés hiérarchique, vous devez fournir les valeurs suivantes :

  • Un nom de magasin clé de succursale

  • Une limite de durée de vie du cache (TTL)

  • Un fournisseur d'identifiant de clé de succursale

  • (Facultatif) Un cache

    Si vous souhaitez personnaliser le type de cache ou le nombre d'entrées clés de branche pouvant être stockées dans le cache local, spécifiez le type de cache et la capacité d'entrée lorsque vous initialisez le trousseau de clés.

    Le type de cache définit le modèle de threading. Le trousseau de clés hiérarchique fournit trois types de cache qui prennent en charge les bases de données mutualisées : Default,, MultiThreaded. StormTracking

    Si vous ne spécifiez pas de cache, le trousseau de clés hiérarchique utilise automatiquement le type de cache par défaut et définit la capacité d'entrée à 1 000.

    Default (Recommended)

    Pour la plupart des utilisateurs, le cache par défaut répond à leurs exigences en matière de threading. Le cache par défaut est conçu pour prendre en charge les environnements fortement multithread. Lorsqu'une entrée de matériel de clé de branche expire, le cache par défaut empêche plusieurs threads d'appeler AWS KMS en notifiant à un thread que l'entrée de matériaux de clé de branche va expirer 10 secondes à l'avance. Cela garantit qu'un seul thread envoie une demande AWS KMS pour actualiser le cache.

    Pour initialiser votre trousseau de clés hiérarchique avec un cache par défaut, spécifiez la valeur suivante :

    • Capacité d'entrée : limite le nombre d'entrées de matériaux clés de branche qui peuvent être stockées dans le cache local.

    Java
    .cache(CacheType.builder()
        .Default(DefaultCache.builder()
        .entryCapacity(100)
        .build())
    C#//.NET
    CacheType defaultCache = new CacheType
{
    Default = new DefaultCache{EntryCapacity = 100}
};

    La valeur par défaut et StormTracking les caches prennent en charge le même modèle de thread, mais il suffit de spécifier la capacité d'entrée pour initialiser le trousseau de clés hiérarchique avec le cache par défaut. Pour des personnalisations de cache plus détaillées, utilisez le StormTracking cache.

    MultiThreaded

    Le MultiThreaded cache peut être utilisé en toute sécurité dans les environnements multithread, mais il ne fournit aucune fonctionnalité permettant de minimiser les appels Amazon AWS KMS DynamoDB. Par conséquent, lorsqu'une entrée de contenu clé de branche expire, tous les fils de discussion seront avertis en même temps. Cela peut entraîner plusieurs AWS KMS appels pour actualiser le cache.

    Pour initialiser votre jeu de clés hiérarchique avec un MultiThreaded cache, spécifiez les valeurs suivantes :

    • Capacité d'entrée : limite le nombre d'entrées de matériaux clés de branche qui peuvent être stockées dans le cache local.

    • Taille de la queue d'élagage d'entrée : définit le nombre d'entrées à élaguer si la capacité d'entrée est atteinte.

    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
    C#//.NET
    CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
    StormTracking

    Le StormTracking cache est conçu pour prendre en charge les environnements fortement multithread. Lorsqu'une entrée de matériel de clé de branche expire, le StormTracking cache empêche plusieurs threads d'appeler AWS KMS en notifiant à l'un d'entre eux que l'entrée de matériaux de clé de branche va expirer à l'avance. Cela garantit qu'un seul thread envoie une demande AWS KMS pour actualiser le cache.

    Pour initialiser votre jeu de clés hiérarchique avec un StormTracking cache, spécifiez les valeurs suivantes :

    • Capacité d'entrée : limite le nombre d'entrées de matériaux clés de branche qui peuvent être stockées dans le cache local.

    • Taille de la queue d'élagage d'entrée : définit le nombre d'entrées de matériaux clés de branche à tailler à la fois.

      Valeur par défaut : 1 entrée

    • Période de grâce : définit le nombre de secondes avant l'expiration pendant lesquelles une tentative d'actualisation des documents clés de la branche est effectuée.

      Valeur par défaut : 10 secondes

    • Intervalle de grâce : définit le nombre de secondes entre les tentatives d'actualisation des éléments clés de la branche.

      Valeur par défaut : 1 seconde

    • Ventilateur : définit le nombre de tentatives simultanées qui peuvent être effectuées pour actualiser les documents clés de la branche.

      Valeur par défaut : 20 tentatives

    • In flight time to live (TTL) : définit le nombre de secondes avant l'expiration d'une tentative d'actualisation des informations clés de branche. Chaque fois que le cache revient NoSuchEntry en réponse à unGetCacheEntry, cette clé de branche est considérée comme étant en vol jusqu'à ce que la même clé soit écrite avec une PutCache entrée.

      Valeur par défaut : 20 secondes

    • Sommeil : définit le nombre de secondes pendant lesquelles un thread doit être mis en veille si le fanOut délai est dépassé.

      Valeur par défaut : 20 millisecondes

    Java
    .cache(CacheType.builder()
        .StormTracking(StormTrackingCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())
    C#//.NET
    CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};

  • (Facultatif) Une liste de jetons de subvention

    Si vous contrôlez l'accès à la clé KMS dans votre trousseau de clés hiérarchique avec des autorisations, vous devez fournir tous les jetons de subvention nécessaires lorsque vous initialisez le trousseau de clés.

Les exemples suivants initialisent un jeu de clés hiérarchique avec le fournisseur d'ID de clé de branche créé à l'étape 2, une limite de cache TLL de 600 secondes et une taille de cache maximale de 1 000. Cet exemple initialise un jeu de clés hiérarchique avec le SDK AWS Database Encryption pour le client DynamoDB.

Java
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(keystore)
        .branchKeyIdSupplier(branchKeyIdSupplier)
        .ttlSeconds(600)
        .cache(CacheType.builder() //OPTIONAL
                .Default(DefaultCache.builder()
                .entryCapacity(100)
                .build())
        .build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
C# / .NET
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   TtlSeconds = 600, 
   Cache = new CacheType
   {
        Default = new DefaultCache { EntryCapacity = 100 }
   }
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
Afficher plusAfficher moins

Utilisation du trousseau de clés hiérarchique pour un chiffrement consultable

Le chiffrement consultable vous permet de rechercher des enregistrements cryptés sans déchiffrer l'intégralité de la base de données. Pour ce faire, il faut indexer la valeur en texte brut d'un champ chiffré à l'aide d'une balise. Pour implémenter le chiffrement consultable, vous devez utiliser un trousseau de clés hiérarchique.

L'CreateKeyopération de stockage des clés génère à la fois une clé de branche et une clé de balise. La clé de branche est utilisée dans les opérations de chiffrement et de déchiffrement des enregistrements. La clé de balise est utilisée pour générer des balises.

La clé de branche et la clé de balise sont protégées par la même protection AWS KMS key que celle que vous spécifiez lors de la création de votre service de magasin de clés. Une fois que l'CreateKeyopération appelle AWS KMS pour générer la clé de branche, elle appelle kms : GenerateDataKeyWithoutPlaintext une seconde fois pour générer la clé de balise en utilisant la requête suivante.

{
   "EncryptionContext": { 
      "branch-key-id" : "branch-key-id",
      "type" : type,
      "create-time" : "timestamp",
      "logical-key-store-name" : "the logical table name for your branch key store",
      "kms-arn" : the KMS key ARN,
      "hierarchy-version" : 1
   },
   "KeyId": "the KMS key ARN",
   "NumberOfBytes": "32"
}

Après avoir généré les deux clés, l'CreateKeyopération appelle ddb : TransactWriteItems pour écrire deux nouveaux éléments qui conserveront la clé de branche et la clé de balise dans votre magasin de clés de succursale.

Lorsque vous configurez une balise standard, le SDK AWS de chiffrement de base de données interroge le magasin de clés de branche pour obtenir la clé de balise. Il utilise ensuite une fonction de dérivation de extract-and-expand clé basée sur HMAC (HKDF) pour combiner la clé de balise avec le nom de la balise standard afin de créer la clé HMAC pour une balise donnée.

Contrairement aux clés de branche, il n'existe qu'une seule version de clé de balise par branch-key-id magasin de clés de succursale. La clé de la balise n'est jamais tournée.

Définition de la source clé de votre balise

Lorsque vous définissez la version de balise pour vos balises standard et composées, vous devez identifier la clé de balise et définir une durée de vie limite de cache (TTL) pour les éléments clés de la balise. Les éléments clés des balises sont stockés dans un cache local distinct de celui des clés de branche. L'extrait suivant montre comment définir le pour une base de données à keySource locataire unique. Identifiez la clé de votre balise par celle à laquelle branch-key-id elle est associée.

Java
keySource(BeaconKeySource.builder()
        .single(SingleKeyStore.builder()
                .keyId(branch-key-id)
                .cacheTTL(6000)
                .build())
        .build())
C# / .NET
KeySource = new BeaconKeySource
{
    Single = new SingleKeyStore
    {
       KeyId = branch-key-id,
       CacheTTL = 6000
    }
}
Définition de la source de balise dans une base de données mutualisée

Si vous disposez d'une base de données mutualisée, vous devez spécifier les valeurs suivantes lors de la keySource configuration de.

  • keyFieldName

    Définit le nom du champ qui stocke la clé branch-key-id associée à la balise utilisée pour générer des balises pour un locataire donné. Il keyFieldName peut s'agir de n'importe quelle chaîne, mais elle doit être unique à tous les autres champs de votre base de données. Lorsque vous écrivez de nouveaux enregistrements dans votre base de données, la clé branch-key-id identifiant la clé de balise utilisée pour générer des balises pour cet enregistrement est stockée dans ce champ. Vous devez inclure ce champ dans vos requêtes sur les balises et identifier les éléments clés de balise appropriés nécessaires pour recalculer la balise. Pour plus d’informations, consultez Interrogation de balises dans une base de données mutualisée.

  • CacheTTL

    Durée en secondes pendant laquelle une entrée de contenu clé de balise dans le cache de balises local peut être utilisée avant son expiration. Cette valeur doit être supérieure à zéro. Lorsque la limite de cache TTL expire, l'entrée est expulsée du cache local.

  • (Facultatif) Un cache

    Si vous souhaitez personnaliser le type de cache ou le nombre d'entrées clés de branche pouvant être stockées dans le cache local, spécifiez le type de cache et la capacité d'entrée lorsque vous initialisez le trousseau de clés.

    Le type de cache définit le modèle de threading. Le trousseau de clés hiérarchique fournit trois types de cache qui prennent en charge les bases de données mutualisées : Default,, MultiThreaded. StormTracking

    Si vous ne spécifiez pas de cache, le trousseau de clés hiérarchique utilise automatiquement le type de cache par défaut et définit la capacité d'entrée à 1 000.

    Default (Recommended)

    Pour la plupart des utilisateurs, le cache par défaut répond à leurs exigences en matière de threading. Le cache par défaut est conçu pour prendre en charge les environnements fortement multithread. Lorsqu'une entrée de matériel de clé de branche expire, le cache par défaut empêche plusieurs threads d'appeler AWS KMS en notifiant à un thread que l'entrée de matériaux de clé de branche va expirer 10 secondes à l'avance. Cela garantit qu'un seul thread envoie une demande AWS KMS pour actualiser le cache.

    Pour initialiser votre trousseau de clés hiérarchique avec un cache par défaut, spécifiez la valeur suivante :

    • Capacité d'entrée : limite le nombre d'entrées de matériaux clés de branche qui peuvent être stockées dans le cache local.

    Java
    .cache(CacheType.builder()
        .Default(DefaultCache.builder()
        .entryCapacity(100)
        .build())
    C#//.NET
    CacheType defaultCache = new CacheType
{
    Default = new DefaultCache{EntryCapacity = 100}
};

    La valeur par défaut et StormTracking les caches prennent en charge le même modèle de thread, mais il suffit de spécifier la capacité d'entrée pour initialiser le trousseau de clés hiérarchique avec le cache par défaut. Pour des personnalisations de cache plus détaillées, utilisez le StormTracking cache.

    MultiThreaded

    Le MultiThreaded cache peut être utilisé en toute sécurité dans les environnements multithread, mais il ne fournit aucune fonctionnalité permettant de minimiser les appels Amazon AWS KMS DynamoDB. Par conséquent, lorsqu'une entrée de contenu clé de branche expire, tous les fils de discussion seront avertis en même temps. Cela peut entraîner plusieurs AWS KMS appels pour actualiser le cache.

    Pour initialiser votre jeu de clés hiérarchique avec un MultiThreaded cache, spécifiez les valeurs suivantes :

    • Capacité d'entrée : limite le nombre d'entrées de matériaux clés de branche qui peuvent être stockées dans le cache local.

    • Taille de la queue d'élagage d'entrée : définit le nombre d'entrées à élaguer si la capacité d'entrée est atteinte.

    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
    C#//.NET
    CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
    StormTracking

    Le StormTracking cache est conçu pour prendre en charge les environnements fortement multithread. Lorsqu'une entrée de matériel de clé de branche expire, le StormTracking cache empêche plusieurs threads d'appeler AWS KMS en notifiant à l'un d'entre eux que l'entrée de matériaux de clé de branche va expirer à l'avance. Cela garantit qu'un seul thread envoie une demande AWS KMS pour actualiser le cache.

    Pour initialiser votre jeu de clés hiérarchique avec un StormTracking cache, spécifiez les valeurs suivantes :

    • Capacité d'entrée : limite le nombre d'entrées de matériaux clés de branche qui peuvent être stockées dans le cache local.

    • Taille de la queue d'élagage d'entrée : définit le nombre d'entrées de matériaux clés de branche à tailler à la fois.

      Valeur par défaut : 1 entrée

    • Période de grâce : définit le nombre de secondes avant l'expiration pendant lesquelles une tentative d'actualisation des documents clés de la branche est effectuée.

      Valeur par défaut : 10 secondes

    • Intervalle de grâce : définit le nombre de secondes entre les tentatives d'actualisation des éléments clés de la branche.

      Valeur par défaut : 1 seconde

    • Ventilateur : définit le nombre de tentatives simultanées qui peuvent être effectuées pour actualiser les documents clés de la branche.

      Valeur par défaut : 20 tentatives

    • In flight time to live (TTL) : définit le nombre de secondes avant l'expiration d'une tentative d'actualisation des informations clés de branche. Chaque fois que le cache revient NoSuchEntry en réponse à unGetCacheEntry, cette clé de branche est considérée comme étant en vol jusqu'à ce que la même clé soit écrite avec une PutCache entrée.

      Valeur par défaut : 20 secondes

    • Sommeil : définit le nombre de secondes pendant lesquelles un thread doit être mis en veille si le fanOut délai est dépassé.

      Valeur par défaut : 20 millisecondes

    Java
    .cache(CacheType.builder()
        .StormTracking(StormTrackingCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())
    C#//.NET
    CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};

L'exemple suivant initialise un jeu de clés hiérarchique avec le fournisseur d'ID de clé de branche créé à l'étape 2, une limite de cache TLL de 600 secondes et une capacité d'entrée de 1 000.

Java
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
        .keyStore(branchKeyStoreName)
        .branchKeyIdSupplier(branchKeyIdSupplier)
        .ttlSeconds(600)
        .cache(CacheType.builder() //OPTIONAL
                .Default(DefaultCache.builder()
                        .entryCapacity(1000)
                        .build())
                .build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
C# / .NET
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   TtlSeconds = 600, 
   Cache = new CacheType
   {
        Default = new DefaultCache { EntryCapacity = 1000 }
   }
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);