AWS KMS porte-clés - AWS Encryption SDK
Autorisations requises pour les AWS KMS porte-clésIdentification AWS KMS keys dans un AWS KMS porte-clésCréation d'un AWS KMS trousseau de clés pour le chiffrementCréation d'un AWS KMS trousseau de clés pour le déchiffrementUtilisation d'un porte-clés AWS KMS DiscoveryUtilisation d'un porte-clés de découverte AWS KMS régional

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

Un AWS KMS trousseau de clés utilise un chiffrement symétrique AWS KMS keyspour générer, chiffrer et déchiffrer des clés de données. AWS Key Management Service (AWS KMS) protège vos KMS clés et effectue des opérations cryptographiques à l'intérieur des FIPS limites. Nous vous recommandons d'utiliser un AWS KMS trousseau de clés, ou un trousseau de clés présentant des propriétés de sécurité similaires, dans la mesure du possible.

Vous pouvez utiliser une clé AWS KMS multirégionale dans un AWS KMS trousseau de clés ou un fournisseur de clés principales à partir de la version 2.3. x du AWS Encryption SDK et version 3.0. x du AWS chiffrementCLI. Pour plus de détails et des exemples d'utilisation du nouveau symbole prenant en compte plusieurs régions, voir. Utilisation de plusieurs régions AWS KMS keys Pour plus d'informations sur les clés multirégionales, consultez la section Utilisation des clés multirégionales dans le manuel du AWS Key Management Service développeur.

Note

La version 4. x du AWS Encryption SDK formulaire. NETet version 3. x of the Kit SDK de chiffrement AWS pour Java sont les seules implémentations de langage de programmation qui prennent en charge les trousseaux de AWS KMS clés asymétriques. RSA AWS KMS keys

Si vous essayez d'inclure une clé asymétrique dans un jeu de KMS clés de chiffrement dans une autre implémentation de langage, l'appel de chiffrement échoue. Si vous l'incluez dans un trousseau de clés de déchiffrement, il est ignoré.

Toutes les mentions de KMSporte-clés dans le document AWS Encryption SDK font référence à des AWS KMS porte-clés.

AWS KMS les porte-clés peuvent inclure deux types de clés d'emballage :

  • Clé du générateur : génère une clé de données en texte brut et la chiffre. Un trousseau de clés qui chiffre des données doit comporter une clé génératrice.

  • Clés supplémentaires : chiffre la clé de données en texte brut générée par la clé du générateur. AWS KMS les porte-clés peuvent comporter zéro ou plusieurs clés supplémentaires.

Lors du chiffrement, le AWS KMS trousseau de clés que vous utilisez doit comporter une clé génératrice. Lors du déchiffrement, la clé du générateur est facultative et la distinction entre les clés du générateur et les clés supplémentaires est ignorée.

Lorsqu'un jeu de clés de AWS KMS chiffrement ne comporte qu'une seule AWS KMS clé, celle-ci est utilisée pour générer et chiffrer la clé de données.

Comme tous les porte-clés, les AWS KMS porte-clés peuvent être utilisés indépendamment ou dans un porte-clés multiple avec d'autres porte-clés du même type ou d'un type différent.

Autorisations requises pour les AWS KMS porte-clés

AWS Encryption SDK Cela ne nécessite pas de Compte AWS et ne dépend d'aucun Service AWS. Toutefois, pour utiliser un AWS KMS trousseau de clés, vous devez disposer des autorisations minimales suivantes AWS KMS keys sur celui-ci. Compte AWS

  • Pour chiffrer avec un AWS KMS trousseau de clés, vous avez besoin de l'GenerateDataKeyautorisation kms : sur la clé du générateur. Vous devez disposer de l'autorisation KMS:Encrypt pour toutes les clés supplémentaires du trousseau de clés. AWS KMS

  • Pour déchiffrer avec un AWS KMS trousseau de clés, vous devez disposer de l'autorisation KMS:Decrypt sur au moins une des clés du trousseau de clés. AWS KMS

  • Pour chiffrer avec un trousseau de clés multiples composé de trousseaux de AWS KMS clés, vous avez besoin de l'GenerateDataKeyautorisation kms : sur la clé du générateur située dans le trousseau de clés du générateur. Vous avez besoin de l'autorisation KMS:Encrypt sur toutes les autres clés de tous les autres trousseaux de clés. AWS KMS

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.

Identification AWS KMS keys dans un AWS KMS porte-clés

Un AWS KMS porte-clés peut en inclure un ou plusieurs AWS KMS keys. Pour spécifier un AWS KMS key dans un AWS KMS trousseau de clés, utilisez un identifiant de AWS KMS clé compatible. Les identificateurs de clé que vous pouvez utiliser pour identifier un élément AWS KMS key dans un trousseau de clés varient en fonction de l'opération et de l'implémentation du langage. Pour plus de détails sur les identificateurs de clé d'un AWS KMS key, consultez la section Identifiants de clé dans le guide du AWS Key Management Service développeur.

Il est recommandé d'utiliser l'identifiant de clé le plus précis qui soit adapté à votre tâche.

  • Dans un jeu de clés de chiffrement pour le Kit SDK de chiffrement AWS pour C, vous pouvez utiliser une clé ARN ou un alias ARN pour identifier les KMS clés. Dans toutes les autres implémentations linguistiques, vous pouvez utiliser un identifiant de clé, une clé ARN, un nom d'alias ou un alias ARN pour chiffrer les données.

  • Dans un trousseau de clés de déchiffrement, vous devez utiliser une clé ARN pour vous identifier. AWS KMS keys Cette exigence s'applique à toutes les implémentations de langage du kit AWS Encryption SDK. Pour plus de détails, consultez Sélection des clés d'emballage.

  • Dans un trousseau de clés utilisé pour le chiffrement et le déchiffrement, vous devez utiliser une clé ARN pour vous identifier. AWS KMS keys Cette exigence s'applique à toutes les implémentations de langage du kit AWS Encryption SDK.

Si vous spécifiez un nom d'alias ou un alias ARN pour une KMS clé d'un jeu de clés de chiffrement, l'opération de chiffrement enregistre la clé ARN actuellement associée à l'alias dans les métadonnées de la clé de données cryptée. Cela n'enregistre pas l'alias. Les modifications apportées à l'alias n'affectent pas la KMS clé utilisée pour déchiffrer vos clés de données chiffrées.

Création d'un AWS KMS trousseau de clés pour le chiffrement

Vous pouvez configurer chaque AWS KMS porte-clés avec un AWS KMS key ou plusieurs AWS KMS keys éléments identiques ou différents Comptes AWS . Régions AWS Les clés de chiffrement AWS KMS keys doivent être symétriques (SYMMETRIC_DEFAULT). Vous pouvez également utiliser une clé multirégionale KMS de chiffrement symétrique. Comme pour tous les porte-clés, vous pouvez utiliser un ou plusieurs AWS KMS porte-clés dans un porte-clés multiple.

Lorsque vous créez un AWS KMS trousseau de clés pour chiffrer des données, vous devez spécifier une clé de génération, AWS KMS key qui est utilisée pour générer une clé de données en texte brut et la chiffrer. La clé de données n'est mathématiquement pas liée à la KMS clé. Ensuite, si vous le souhaitez, vous pouvez en spécifier d'autres AWS KMS keys qui chiffrent la même clé de données en texte brut.

Pour déchiffrer le message chiffré protégé par ce trousseau de clés, le trousseau que vous utilisez doit inclure au moins l'un des éléments AWS KMS keys définis dans le trousseau de clés, ou non. AWS KMS keys(Un AWS KMS porte-clés sans numéro AWS KMS keys est connu sous le nom de porte-clés AWS KMS Discovery.)

Dans les implémentations de AWS Encryption SDK langage autres que le Kit SDK de chiffrement AWS pour C, toutes les clés d'encapsulage d'un jeu de clés de chiffrement ou d'un jeu de clés multiples doivent être en mesure de chiffrer la clé de données. Si le chiffrement d'une clé d'encapsulation échoue, la méthode de chiffrement échoue. Par conséquent, l'appelant doit disposer des autorisations requises pour toutes les clés du trousseau de clés. Si vous utilisez un jeu de clés de découverte pour chiffrer des données, seul ou dans un jeu de clés multiples, l'opération de chiffrement échoue. L'exception est le Kit SDK de chiffrement AWS pour C cas où l'opération de chiffrement ignore un jeu de clés de découverte standard, mais échoue si vous spécifiez un jeu de clés de découverte multirégional, seul ou dans un jeu de clés multiclés.

Les exemples suivants créent un AWS KMS trousseau de clés avec une clé génératrice et une clé supplémentaire. Ces exemples utilisent des clés ARNs pour identifier les KMS clés. Il s'agit d'une bonne pratique pour les AWS KMS trousseaux de clés utilisés pour le chiffrement et d'une exigence pour les AWS KMS trousseaux de clés utilisés pour le déchiffrement. Pour plus de détails, consultez Identification AWS KMS keys dans un AWS KMS porte-clés.

C

Pour identifier une clé AWS KMS key dans un jeu de clés de chiffrement dans le Kit SDK de chiffrement AWS pour C, spécifiez une clé ARN ou un alias ARN. Dans un trousseau de clés de déchiffrement, vous devez utiliser une clé. ARN Pour plus de détails, consultez Identification AWS KMS keys dans un AWS KMS porte-clés.

Pour obtenir un exemple complet, veuillez consulter string.cpp.

const char * generator_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"

const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"    

struct aws_cryptosdk_keyring *kms_encrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key,{additional_key});
C# / .NET

Pour créer un AWS KMS porte-clés avec une ou plusieurs AWS KMS clés dans le formulaire AWS Encryption SDK . NET, créez un porte-clés multiple. Le AWS Encryption SDK pour. NETcomprend un porte-clés multiple juste pour les AWS KMS clés.

Lorsque vous spécifiez un AWS KMS key pour un jeu de clés de chiffrement dans le formulaire AWS Encryption SDK . NET, vous pouvez utiliser n'importe quel identifiant de clé valide : un identifiant de clé, une clé ARN, un nom d'alias ou un alias ARN. Pour obtenir de l'aide pour identifier le AWS KMS keys contenu d'un AWS KMS trousseau de clés, voirIdentification AWS KMS keys dans un AWS KMS porte-clés.

L'exemple suivant utilise la version 4. x du AWS Encryption SDK formulaire. NETpour créer un AWS KMS porte-clés avec une clé génératrice et des clés supplémentaires. Pour un exemple complet, consultez AwsKmsMultiKeyringExample.cs.

// Instantiate the AWS Encryption SDK and material provider
var mpl = new MaterialProviders(new MaterialProvidersConfig());
var esdk =  new ESDK(new AwsEncryptionSdkConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKey = new List<string> { "alias/exampleAlias" };

// Instantiate the keyring input object
var kmsEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKey
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(kmsEncryptKeyringInput);
JavaScript Browser

Lorsque vous spécifiez un AWS KMS key pour un jeu de clés de chiffrement dans le Kit SDK de chiffrement AWS pour JavaScript, vous pouvez utiliser n'importe quel identifiant de clé valide : un identifiant de clé, une clé ARN, un nom d'alias ou un alias ARN. Pour obtenir de l'aide pour identifier le AWS KMS keys contenu d'un AWS KMS trousseau de clés, voirIdentification AWS KMS keys dans un AWS KMS porte-clés.

Pour un exemple complet, consultez kms_simple.ts dans le référentiel de. Kit SDK de chiffrement AWS pour JavaScript GitHub

const clientProvider = getClient(KMS, { credentials })
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
const additionalKey = 'alias/exampleAlias'

const keyring = new KmsKeyringBrowser({
  clientProvider, 
  generatorKeyId, 
  keyIds: [additionalKey] 
})
JavaScript Node.js

Lorsque vous spécifiez un AWS KMS key pour un jeu de clés de chiffrement dans le Kit SDK de chiffrement AWS pour JavaScript, vous pouvez utiliser n'importe quel identifiant de clé valide : un identifiant de clé, une clé ARN, un nom d'alias ou un alias ARN. Pour obtenir de l'aide pour identifier le AWS KMS keys contenu d'un AWS KMS trousseau de clés, voirIdentification AWS KMS keys dans un AWS KMS porte-clés.

Pour un exemple complet, consultez kms_simple.ts dans le référentiel de. Kit SDK de chiffrement AWS pour JavaScript GitHub

const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
                            
const additionalKey = 'alias/exampleAlias'

const keyring = new KmsKeyringNode({
  generatorKeyId,
  keyIds: [additionalKey]
})
Java

Pour créer un AWS KMS porte-clés contenant une ou plusieurs AWS KMS clés Kit SDK de chiffrement AWS pour Java, créez un porte-clés multiple. Kit SDK de chiffrement AWS pour Java Il comprend un porte-clés multiple juste pour les AWS KMS clés.

Lorsque vous spécifiez un AWS KMS key pour un jeu de clés de chiffrement dans le Kit SDK de chiffrement AWS pour Java, vous pouvez utiliser n'importe quel identifiant de clé valide : un identifiant de clé, une clé ARN, un nom d'alias ou un alias ARN. Pour obtenir de l'aide pour identifier le AWS KMS keys contenu d'un AWS KMS trousseau de clés, voirIdentification AWS KMS keys dans un AWS KMS porte-clés.

Pour un exemple complet, voir BasicEncryptionKeyringExample.java dans le Kit SDK de chiffrement AWS pour Java référentiel dans GitHub.

 // Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
            .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
            .build();

String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<String> additionalKey = Collections.singletonList("alias/exampleAlias");

// Create the AWS KMS keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);

Création d'un AWS KMS trousseau de clés pour le déchiffrement

Vous spécifiez également un AWS KMS trousseau de clés lors du déchiffrement du message chiffré renvoyé. AWS Encryption SDK Si le jeu de clés de déchiffrement le spécifie AWS KMS keys, seules ces clés d'encapsulation AWS Encryption SDK seront utilisées pour déchiffrer les clés de données chiffrées du message chiffré. (Vous pouvez également utiliser un trousseau de clés de AWS KMS découverte, qui n'en spécifie aucun AWS KMS keys.)

Lors du déchiffrement, il AWS Encryption SDK recherche dans le AWS KMS trousseau de clés un élément capable de déchiffrer l'une AWS KMS key des clés de données cryptées. Plus précisément, le modèle suivant est AWS Encryption SDK utilisé pour chaque clé de données chiffrée d'un message chiffré.

  • AWS Encryption SDK obtient la clé ARN AWS KMS key qui a chiffré la clé de données à partir des métadonnées du message crypté.

  • Il AWS Encryption SDK recherche dans le trousseau de clés de déchiffrement un AWS KMS key avec une clé correspondante. ARN

  • S'il trouve une AWS KMS key clé correspondante ARN dans le trousseau de clés, il AWS Encryption SDK demande AWS KMS à utiliser la KMS clé pour déchiffrer la clé de données cryptée.

  • Dans le cas contraire, il passe à la clé de données chiffrée suivante, le cas échéant.

Il AWS Encryption SDK ne tente jamais de déchiffrer une clé de données chiffrée à moins AWS KMS key que la clé ARN de cette clé de données ne soit incluse dans le trousseau de clés de déchiffrement. Si le trousseau de clés de déchiffrement n'inclut aucune ARNs des AWS KMS keys clés de données chiffrées, l'appel de déchiffrement AWS Encryption SDK échoue sans jamais appeler. AWS KMS

À partir de la version 1.7. x, lors du déchiffrement d'une clé de données cryptée, passe AWS Encryption SDK toujours la clé du au KeyId paramètre ARN de l' AWS KMS key opération de déchiffrement. AWS KMS L'identifier AWS KMS key lors du déchiffrement est une AWS KMS bonne pratique qui garantit que vous déchiffrez la clé de données cryptée avec la clé d'encapsulation que vous souhaitez utiliser.

Un appel de déchiffrement avec un AWS KMS trousseau de clés réussit lorsqu'au moins un AWS KMS key élément du trousseau de clés de déchiffrement peut déchiffrer l'une des clés de données chiffrées du message chiffré. En outre, le mandataire doit disposer de l'autorisation kms:Decrypt pour cette AWS KMS key. Ce comportement vous permet de chiffrer des données AWS KMS keys sous plusieurs comptes Régions AWS et de fournir un jeu de clés de déchiffrement plus limité adapté à un compte, une région, un utilisateur, un groupe ou un rôle en particulier.

Lorsque vous spécifiez un AWS KMS key dans un trousseau de clés de déchiffrement, vous devez utiliser sa clé. ARN Dans le cas contraire, le n' AWS KMS key est pas reconnu. Pour obtenir de l'aide pour trouver la cléARN, consultez la section Trouver l'identifiant de la clé et ARN le manuel du AWS Key Management Service développeur.

Note

Si vous réutilisez un jeu de clés de chiffrement pour le déchiffrer, assurez-vous que les éléments qu'il contient AWS KMS keys sont identifiés par leur clé. ARNs

Par exemple, le jeu de AWS KMS clés suivant inclut uniquement la clé supplémentaire qui a été utilisée dans le jeu de clés de chiffrement. Toutefois, au lieu de faire référence à la clé supplémentaire par son aliasalias/exampleAlias, l'exemple utilise la clé supplémentaire ARN comme l'exigent les appels de déchiffrement.

Vous pouvez utiliser ce porte-clés pour déchiffrer un message qui a été chiffré sous la clé du générateur et la clé supplémentaire, à condition que vous soyez autorisé à utiliser la clé supplémentaire pour déchiffrer les données.

C
const char * additional_key = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"    

struct aws_cryptosdk_keyring *kms_decrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(additional_key);
C# / .NET

Comme ce trousseau de clés de déchiffrement ne comprend qu'une seule AWS KMS clé, l'exemple utilise la CreateAwsKmsKeyring() méthode avec une instance de son CreateAwsKmsKeyringInput objet. Pour créer un AWS KMS porte-clés avec une seule AWS KMS clé, vous pouvez utiliser un porte-clés à une ou plusieurs touches. Pour plus de détails, consultez Chiffrer des données dans le AWS Encryption SDK pour .NET. L'exemple suivant utilise la version 4. x du AWS Encryption SDK formulaire. NETpour créer un AWS KMS trousseau de clés à déchiffrer.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string additionalKey = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321";

// Instantiate a KMS keyring for one AWS KMS key.
var kmsDecryptKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = additionalKey
};

var kmsDecryptKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);
JavaScript Browser
const clientProvider = getClient(KMS, { credentials })
const additionalKey = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'

const keyring = new KmsKeyringBrowser({ clientProvider, keyIds: [additionalKey] })
JavaScript Node.js
const additionalKey = 'arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321'

const keyring = new KmsKeyringNode({ keyIds: [additionalKey] })
Java

Comme ce trousseau de clés de déchiffrement ne comprend qu'une seule AWS KMS clé, l'exemple utilise la CreateAwsKmsKeyring() méthode avec une instance de son CreateAwsKmsKeyringInput objet. Pour créer un AWS KMS porte-clés avec une seule AWS KMS clé, vous pouvez utiliser un porte-clés à une ou plusieurs touches.

// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
        
String additionalKey = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321";

// Create a AwsKmsKeyring
CreateAwsKmsKeyringInput kmsDecryptKeyringInput = CreateAwsKmsKeyringInput.builder()
        .generator(additionalKey)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

Vous pouvez également utiliser un AWS KMS trousseau de clés qui spécifie une clé génératrice pour le déchiffrement, telle que la suivante. Lors du déchiffrement, le AWS Encryption SDK ignore la distinction entre les clés du générateur et les clés supplémentaires. Il peut utiliser n'importe lequel des éléments spécifiés AWS KMS keys pour déchiffrer une clé de données cryptée. L'appel à ne AWS KMS réussit que lorsque l'appelant est autorisé à l'utiliser pour déchiffrer AWS KMS key les données.

C
struct aws_cryptosdk_keyring *kms_decrypt_keyring = 
       Aws::Cryptosdk::KmsKeyring::Builder().Build(generator_key, {additional_key, other_key});
C# / .NET

L'exemple suivant utilise la version 4. x du AWS Encryption SDK formulaire. NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate a KMS keyring for one AWS KMS key.
var kmsDecryptKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = generatorKey
};

var kmsDecryptKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);
JavaScript Browser
const clientProvider = getClient(KMS, { credentials })

const keyring = new KmsKeyringBrowser({
  clientProvider, 
  generatorKeyId, 
  keyIds: [additionalKey, otherKey]
})
JavaScript Node.js
const keyring = new KmsKeyringNode({
  generatorKeyId,
  keyIds: [additionalKey, otherKey]
})
Java
// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
        
String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a AwsKmsKeyring
CreateAwsKmsKeyringInput kmsDecryptKeyringInput = CreateAwsKmsKeyringInput.builder()
        .generator(generatorKey)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsDecryptKeyringInput);

Contrairement à un jeu de clés de chiffrement qui utilise tous les éléments spécifiés AWS KMS keys, vous pouvez déchiffrer un message chiffré à l'aide d'un jeu de clés de déchiffrement AWS KMS keys qui inclut des éléments non liés au message chiffré et AWS KMS keys que l'appelant n'est pas autorisé à utiliser. Si un appel de déchiffrement envoyé à AWS KMS échoue, par exemple lorsque le mandataire ne dispose pas de l'autorisation requise, le kit AWS Encryption SDK se contente de passer à la clé de données chiffrée suivante.

Utilisation d'un porte-clés AWS KMS Discovery

Lors du déchiffrement, il est recommandé de spécifier les clés d'encapsulation qu'ils peuvent utiliser. AWS Encryption SDK Pour suivre cette bonne pratique, utilisez un jeu de clés de AWS KMS déchiffrement qui limite les clés AWS KMS d'encapsulage à celles que vous spécifiez. Toutefois, vous pouvez également créer un trousseau de clés de AWS KMS découverte, c'est-à-dire un AWS KMS trousseau de clés ne spécifiant aucune clé d'encapsulation.

AWS Encryption SDK Il fournit un porte-clés de AWS KMS découverte standard et un porte-clés de découverte pour les clés AWS KMS multirégionales. Pour plus d'informations sur l'utilisation de clés multirégionales avec le AWS Encryption SDK, voirUtilisation de plusieurs régions AWS KMS keys.

Comme il ne spécifie aucune clé d'encapsulation, un jeu de clés de découverte ne peut pas chiffrer les données. Si vous utilisez un jeu de clés de découverte pour chiffrer des données, seul ou dans un jeu de clés multiples, l'opération de chiffrement échoue. L'exception est le Kit SDK de chiffrement AWS pour C cas où l'opération de chiffrement ignore un jeu de clés de découverte standard, mais échoue si vous spécifiez un jeu de clés de découverte multirégional, seul ou dans un jeu de clés multiclés.

Lors du déchiffrement, un jeu de clés de découverte permet de demander AWS Encryption SDK AWS KMS à déchiffrer n'importe quelle clé de données cryptée en utilisant AWS KMS key celle qui l'a chiffrée, indépendamment de qui la possède ou qui y a accès. AWS KMS key L'appel ne réussit que lorsque l'appelant est kms:Decrypt autorisé à utiliser le. AWS KMS key

Important

Si vous incluez un trousseau de clés de AWS KMS découverte dans un jeu de clés multiples de déchiffrement, le trousseau de découverte remplace toutes les restrictions de clé spécifiées par les autres trousseaux de KMS clés du trousseau de clés multiples. Le porte-clés multiple se comporte comme le porte-clés le moins restrictif. Un trousseau de AWS KMS découverte n'a aucun effet sur le chiffrement lorsqu'il est utilisé seul ou dans un jeu de clés multiples.

AWS Encryption SDK Il fournit un porte-clés AWS KMS Discovery pour plus de commodité. Cependant, nous vous recommandons d'utiliser un porte-clés plus limité chaque fois que possible pour les raisons suivantes.

  • Authenticité — Un trousseau de clés de AWS KMS découverte peut utiliser AWS KMS key n'importe quel élément utilisé pour chiffrer une clé de données dans le message chiffré, juste pour que AWS KMS key l'appelant soit autorisé à l'utiliser pour le déchiffrer. Il est possible qu'il ne s'agisse pas de la AWS KMS key que le mandataire a l'intention d'utiliser. Par exemple, l'une des clés de données cryptées peut avoir été cryptée sous une forme moins sécurisée AWS KMS key que tout le monde peut utiliser.

  • Latence et performances — Un AWS KMS jeu de clés de découverte peut être sensiblement plus lent que les autres car il AWS Encryption SDK tente de déchiffrer toutes les clés de données chiffrées, y compris celles chiffrées AWS KMS keys dans d'autres régions, Comptes AWS et AWS KMS keys que l'appelant n'est pas autorisé à utiliser pour le déchiffrement.

Si vous utilisez un trousseau de clés de découverte, nous vous recommandons d'utiliser un filtre de découverte afin de limiter le nombre de KMS clés pouvant être utilisées à celles des partitions spécifiées Comptes AWS et des partitions. Les filtres de découverte sont pris en charge dans les versions 1.7. x et versions ultérieures du AWS Encryption SDK. Pour obtenir de l'aide pour trouver votre identifiant de compte et votre partition, consultez la section Vos Compte AWS identifiants et votre ARNformat dans le Références générales AWS.

Le code suivant instancie un jeu de clés de AWS KMS découverte avec un filtre de découverte qui limite les KMS clés AWS Encryption SDK pouvant être utilisées à celles de la aws partition et à l'exemple de compte 111122223333.

Avant d'utiliser ce code, remplacez les valeurs d'exemple Compte AWS et de partition par des valeurs valides pour votre partition Compte AWS and. Si vos KMS clés se trouvent dans des régions chinoises, utilisez la valeur de aws-cn partition. Si vos KMS clés sont entrées AWS GovCloud (US) Regions, utilisez la valeur de aws-us-gov partition. Pour tous les autres Régions AWS, utilisez la valeur de aws partition.

C

Pour obtenir un exemple complet, veuillez consulter : kms_discovery.cpp.

std::shared_ptr<KmsKeyring::> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .Build());

struct aws_cryptosdk_keyring *kms_discovery_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .BuildDiscovery(discovery_filter));
C# / .NET

L'exemple suivant utilise la version 4. x du AWS Encryption SDK formulaire. NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };
        
// In a discovery keyring, you specify an AWS KMS client and a discovery filter,
// but not a AWS KMS key
var kmsDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = account,
        Partition = "aws"
    }
};
        
var kmsDiscoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(kmsDiscoveryKeyringInput);
JavaScript Browser

Dans JavaScript, vous devez spécifier explicitement la propriété de découverte.

const clientProvider = getClient(KMS, { credentials })

const discovery = true
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})
JavaScript Node.js

Dans JavaScript, vous devez spécifier explicitement la propriété de découverte.

const discovery = true

const keyring = new KmsKeyringNode({
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
Java
// Create discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
        .partition("aws")
        .accountIds(111122223333)
        .build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
        .discoveryFilter(discoveryFilter)
        .build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);

Utilisation d'un porte-clés de découverte AWS KMS régional

Un porte-clés de découverte AWS KMS régional est un porte-clés qui ne précise pas la ou les ARNs clés. KMS Au lieu de cela, il permet AWS Encryption SDK de déchiffrer en utilisant uniquement les KMS clés en particulier Régions AWS.

Lors du déchiffrement à l'aide d'un jeu de clés de découverte AWS KMS régional, il AWS Encryption SDK déchiffre toute clé de données chiffrée selon un dans le spécifié. AWS KMS key Région AWS Pour réussir, l'appelant doit avoir l'kms:Decryptautorisation d'utiliser au moins l'un des éléments spécifiés Région AWS qui ont chiffré une clé de données. AWS KMS keys

Comme les autres trousseaux de découverte, le trousseau de clés de découverte régional n'a aucun effet sur le chiffrement. Cela ne fonctionne que lors du déchiffrement de messages chiffrés. Si vous utilisez un jeu de clés de découverte régional dans un jeu de clés multiples utilisé pour le chiffrement et le déchiffrement, il n'est efficace que lors du déchiffrement. Si vous utilisez un jeu de clés de découverte multirégional pour chiffrer des données, seul ou dans un jeu de clés multirégional, l'opération de chiffrement échoue.

Important

Si vous incluez un trousseau de clés de découverte AWS KMS régional dans un jeu de clés multiples de déchiffrement, le trousseau de découverte régional remplace toutes les restrictions de clé spécifiées par les autres trousseaux de KMS clés du jeu de clés multiples. Le porte-clés multiple se comporte comme le porte-clés le moins restrictif. Un trousseau de AWS KMS découverte n'a aucun effet sur le chiffrement lorsqu'il est utilisé seul ou dans un jeu de clés multiples.

Le trousseau de découverte régional Kit SDK de chiffrement AWS pour C tente de déchiffrer uniquement avec KMS les clés de la région spécifiée. Lorsque vous utilisez un porte-clés de découverte dans Kit SDK de chiffrement AWS pour JavaScript et AWS Encryption SDK pour. NET, vous configurez la région sur le AWS KMS client. Ces AWS Encryption SDK implémentations ne filtrent pas KMS les clés par région, mais AWS KMS échoueront à une demande de déchiffrement de KMS clés en dehors de la région spécifiée.

Si vous utilisez un trousseau de clés de découverte, nous vous recommandons d'utiliser un filtre de découverte afin de limiter les KMS clés utilisées pour le déchiffrement à celles Comptes AWS des partitions spécifiées. Les filtres de découverte sont pris en charge dans les versions 1.7. x et versions ultérieures du AWS Encryption SDK.

Par exemple, le code suivant crée un trousseau de clés de découverte AWS KMS régional avec un filtre de découverte. Ce porte-clés limite les deux KMS clés du AWS Encryption SDK compte 111122223333 dans la région de l'ouest des États-Unis (Oregon) (us-west-2).

C

Pour afficher ce porte-clés ainsi que la méthode create_kms_client dans un exemple pratique, consultez kms_discovery.cpp.

std::shared_ptr<KmsKeyring::DiscoveryFilter> discovery_filter(
    KmsKeyring::DiscoveryFilter::Builder("aws")
        .AddAccount("111122223333")
        .Build());

struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
       .WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
C# / .NET

Le AWS Encryption SDK pour. NETne possède pas de porte-clés dédié aux découvertes régionales. Cependant, vous pouvez utiliser plusieurs techniques pour limiter le nombre de KMS clés utilisées lors du déchiffrement dans une région donnée.

Le moyen le plus efficace de limiter le nombre de régions dans un jeu de clés de découverte consiste à utiliser un jeu de clés de découverte prenant en compte plusieurs régions, même si vous avez chiffré les données uniquement à l'aide de clés à région unique. Lorsqu'il rencontre des clés à région unique, le trousseau de clés compatible avec plusieurs régions n'utilise aucune fonctionnalité multirégionale.

Le trousseau de clés renvoyé par la CreateAwsKmsMrkDiscoveryKeyring() méthode filtre les KMS clés par région avant l'appel AWS KMS. Il envoie une demande de déchiffrement AWS KMS uniquement lorsque la clé de données chiffrée a été chiffrée par une KMS clé dans la région spécifiée par le Region paramètre de l'CreateAwsKmsMrkDiscoveryKeyringInputobjet.

Les exemples suivants utilisent la version 4. x du AWS Encryption SDK formulaire. NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };

// Create the discovery filter
var filter = DiscoveryFilter = new DiscoveryFilter
{
    AccountIds = account,
    Partition = "aws"
};
                                
var regionalDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    Region = RegionEndpoint.USWest2,
    DiscoveryFilter = filter
};                                

var kmsRegionalDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(regionalDiscoveryKeyringInput);

Vous pouvez également limiter KMS les clés à une valeur particulière Région AWS en spécifiant une région dans votre instance du AWS KMS client (AmazonKeyManagementServiceClient). Toutefois, cette configuration est moins efficace et potentiellement plus coûteuse que l'utilisation d'un trousseau de clés de découverte prenant en compte plusieurs régions. Au lieu de filtrer KMS les clés par région avant d'appeler AWS KMS, le AWS Encryption SDK for. NETappelle chaque clé AWS KMS de données chiffrée (jusqu'à ce qu'elle en déchiffre une) et s'appuie sur cette clé AWS KMS pour limiter les KMS clés utilisées à la région spécifiée.

L'exemple suivant utilise la version 4. x du AWS Encryption SDK formulaire. NET.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

List<string> account = new List<string> { "111122223333" };
        
// Create the discovery filter,
// but not a AWS KMS key
var createRegionalDiscoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = account,
        Partition = "aws"
    }
};
        
var kmsRegionalDiscoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(createRegionalDiscoveryKeyringInput);
JavaScript Browser
const clientProvider = getClient(KMS, { credentials })

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
JavaScript Node.js

Pour afficher ce porte-clés, ainsi que limitRegions et la fonction, dans un exemple pratique, veuillez consulter kms_regional_discovery.ts.

const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: ['111122223333'], partition: 'aws' }
})
Java
// Create the discovery filter
DiscoveryFilter discoveryFilter = DiscoveryFilter.builder()
        .partition("aws")
        .accountIds(111122223333)
        .build();
// Create the discovery keyring
CreateAwsKmsMrkDiscoveryMultiKeyringInput createAwsKmsMrkDiscoveryMultiKeyringInput = CreateAwsKmsMrkDiscoveryMultiKeyringInput.builder()
        .discoveryFilter(discoveryFilter)
        .regions("us-west-2")
        .build();
IKeyring decryptKeyring = matProv.CreateAwsKmsMrkDiscoveryMultiKeyring(createAwsKmsMrkDiscoveryMultiKeyringInput);

Kit SDK de chiffrement AWS pour JavaScript Il exporte également une excludeRegions fonction pour Node.js et le navigateur. Cette fonction crée un jeu de clés de découverte AWS KMS régional qui omet certaines AWS KMS keys régions. L'exemple suivant crée un trousseau de clés de découverte AWS KMS régional qui peut être utilisé AWS KMS keys dans le compte 111122223333 partout Région AWS sauf dans l'est des États-Unis (Virginie du Nord) (us-east-1).

Il Kit SDK de chiffrement AWS pour C n'existe pas de méthode analogue, mais vous pouvez en implémenter une en créant une méthode personnalisée ClientSupplier.

Cet exemple montre le code pour Node.js.

const discovery = true
const clientProvider = excludeRegions(['us-east-1'], getKmsClient)
const keyring = new KmsKeyringNode({
    clientProvider,
    discovery,
    discoveryFilter: { accountIDs: [111122223333], partition: 'aws' }
})