Kit SDK de chiffrement AWS pour Java - AWS Encryption SDK
PrérequisInstallationAWS KMS porte-clésContexte de chiffrement requis CMM

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.

Kit SDK de chiffrement AWS pour Java

Cette rubrique explique comment installer et utiliser le kit Kit SDK de chiffrement AWS pour Java. Pour plus de détails sur la programmation avec le Kit SDK de chiffrement AWS pour Java, consultez le aws-encryption-sdk-javaréférentiel sur GitHub. Pour obtenir de API la documentation, consultez le Javadoc du. Kit SDK de chiffrement AWS pour Java

Rubriques

Prérequis

Avant d'installer le Kit SDK de chiffrement AWS pour Java, assurez-vous de remplir les conditions préalables suivantes.

Environnement de développement Java

Vous aurez besoin de Java 8 ou version ultérieure. Sur le site Web d'Oracle, accédez à la section Téléchargements de Java SE, puis téléchargez et installez le kit de développement Java SE (JDK).

Si vous utilisez OracleJDK, vous devez également télécharger et installer l'extension Java Cryptography Extension (JCE) Unlimited Strength Juridiction Policy Files.

Bouncy Castle

Kit SDK de chiffrement AWS pour Java Cela nécessite Bouncy Castle.

  • Kit SDK de chiffrement AWS pour Java les versions 1.6.1 et ultérieures utilisent Bouncy Castle pour sérialiser et désérialiser des objets cryptographiques. Vous pouvez utiliser Bouncy Castle ou Bouncy Castle FIPS pour satisfaire à cette exigence. Pour obtenir de l'aide sur l'installation et la configuration de Bouncy CastleFIPS, consultez FIPSla documentation BC, en particulier les guides de l'utilisateur et la politique PDFs de sécurité.

  • Les versions antérieures Kit SDK de chiffrement AWS pour Java utilisent la cryptographie de Bouncy Castle API pour Java. Cette exigence n'est satisfaite que par des châteaux non FIPS gonflables.

Si vous n'avez pas Bouncy Castle, rendez-vous sur les dernières versions de Bouncy Castle pour télécharger le fichier fournisseur correspondant à votre. JDK Vous pouvez également utiliser Apache Maven pour obtenir l'artefact pour le fournisseur standard de Bouncy Castle (bcprov-ext-jdk15on) ou l'artefact pour Bouncy Castle (bc-fips). FIPS

AWS SDK for Java

Version 3. x l' Kit SDK de chiffrement AWS pour Java exige AWS SDK for Java 2.x, même si vous n'utilisez pas de AWS KMS porte-clés.

Version 2. x ou une version antérieure Kit SDK de chiffrement AWS pour Java ne nécessite pas le AWS SDK for Java. Cependant, AWS SDK for Java il est nécessaire d'utiliser AWS Key Management Service(AWS KMS) comme fournisseur de clé principale. À partir de la Kit SDK de chiffrement AWS pour Java version 2.4.0, il Kit SDK de chiffrement AWS pour Java prend en charge les versions 1.x et 2.x du. AWS SDK for Java AWS Encryption SDK le code pour les versions AWS SDK for Java 1.x et 2.x est interopérable. Par exemple, vous pouvez chiffrer des données avec un AWS Encryption SDK code compatible avec la version AWS SDK for Java 1.x et les déchiffrer à l'aide d'un code compatible AWS SDK for Java 2.x (ou vice versa). Les versions antérieures à Kit SDK de chiffrement AWS pour Java 2.4.0 ne prennent en charge que la version AWS SDK for Java 1.x. Pour plus d'informations sur la mise à jour de votre version du AWS Encryption SDK, consultezMigrer votreAWS Encryption SDK.

Lorsque vous mettez à jour votre Kit SDK de chiffrement AWS pour Java code de la AWS SDK for Java version 1.x à AWS SDK for Java 2.x, remplacez les références à l'AWSKMSinterface de la version AWS SDK for Java 1.x par des références à l'KmsClientinterface de. AWS SDK for Java 2.x Kit SDK de chiffrement AWS pour Java Ne prend pas en charge l'KmsAsyncClientinterface. Mettez également à jour votre code pour utiliser les objets AWS KMS associés dans l'espace de kmssdkv2 noms, plutôt que dans l'espace de kms noms.

Pour l'installer AWS SDK for Java, utilisez Apache Maven.

  • Pour importer tout le AWS SDK for Java en tant que dépendance, déclarez-le dans votre fichier pom.xml.

  • Pour créer une dépendance uniquement pour le AWS KMS module dans la version AWS SDK for Java 1.x, suivez les instructions pour spécifier des modules particuliers et définissez la valeur surartifactId. aws-java-sdk-kms

  • Pour créer une dépendance uniquement pour le AWS KMS module dans la version AWS SDK for Java 2.x, suivez les instructions pour spécifier des modules particuliers. Réglez le groupId to software.amazon.awssdk et le artifactId tokms.

Pour plus de modifications, consultez la section Quelles sont les différences entre la version AWS SDK for Java 1.x et la version 2.x dans le manuel du AWS SDK for Java 2.x développeur.

Les exemples Java présentés dans le Guide du AWS Encryption SDK développeur utilisent le AWS SDK for Java 2.x.

Installation

Installez la dernière version du Kit SDK de chiffrement AWS pour Java.

Note

Toutes les versions Kit SDK de chiffrement AWS pour Java antérieures à la version 2.0.0 sont en end-of-supportphase.

Vous pouvez effectuer la mise à jour en toute sécurité à partir de la version 2.0. x et versions ultérieures vers la dernière version du Kit SDK de chiffrement AWS pour Java sans aucune modification du code ou des données. Cependant, de nouvelles fonctionnalités de sécurité ont été introduites dans la version 2.0. x ne sont pas rétrocompatibles. Pour effectuer une mise à jour à partir de versions antérieures à 1.7. x vers la version 2.0. x et versions ultérieures, vous devez d'abord effectuer la mise à jour vers la dernière version 1. version x du AWS Encryption SDK. Pour plus de détails, consultez Migrer votreAWS Encryption SDK.

Vous pouvez l'installer Kit SDK de chiffrement AWS pour Java de la manière suivante.

Manuellement

Pour installer Kit SDK de chiffrement AWS pour Java, cloner ou télécharger le aws-encryption-sdk-java GitHubréférentiel.

Utilisation d'Apache Maven

Kit SDK de chiffrement AWS pour Java Il est disponible via Apache Maven avec la définition de dépendance suivante.

<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-encryption-sdk-java</artifactId>
  <version>3.0.0</version>
</dependency>

Après avoir installé leSDK, commencez par consulter l'exemple de code Java présenté dans ce guide et le Javadoc activé. GitHub

AWS KMS porte-clés dans le Kit SDK de chiffrement AWS pour Java

Version 3. x of Kit SDK de chiffrement AWS pour Java utilise des trousseaux de clés pour chiffrer les enveloppes. Les AWS KMS porte-clés de base du jeu ne nécessitent Kit SDK de chiffrement AWS pour Java qu'une seule KMS clé. Ils ont également besoin d'un AWS KMS client, ce qui vous permet de configurer le client pour Région AWS la KMS clé.

Pour créer un AWS KMS porte-clés avec une ou plusieurs clés enveloppantes, utilisez un porte-clés à plusieurs clés. Kit SDK de chiffrement AWS pour Java Il possède un porte-clés spécial qui prend une ou plusieurs AWS KMS clés, et un porte-clés standard qui accepte un ou plusieurs porte-clés de n'importe quel type compatible. Certains programmeurs préfèrent utiliser une méthode à plusieurs jeux de clés pour créer tous leurs trousseaux de clés, et ils soutiennent cette stratégie. Kit SDK de chiffrement AWS pour Java

Kit SDK de chiffrement AWS pour Java Il fournit des porte-clés simples et des porte-clés multiples de base pour tous les cas d'utilisation courants, y compris les clés multirégionales. AWS KMS

Par exemple, pour créer un AWS KMS trousseau de clés avec une seule AWS KMS clé, vous pouvez utiliser la méthodeCreateAwsKmsKeyring()].

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

// Create the keyring
CreateAwsKmsKeyringInput kmsKeyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

Pour créer un trousseau de clés avec une ou plusieurs AWS KMS clés, utilisez CreateAwsKmsMultiKeyring() cette méthode. Cet exemple utilise deux KMS touches. Pour spécifier une KMS clé, utilisez uniquement le generator paramètre. Le msKeyIds paramètre qui spécifie des KMS clés supplémentaires est facultatif.

La saisie de ce trousseau de clés ne nécessite aucun AWS KMS client. Il AWS Encryption SDK utilise plutôt le AWS KMS client par défaut pour chaque région représentée par une KMS clé dans le trousseau de clés. Par exemple, si la KMS clé identifiée par la valeur du Generator paramètre se trouve dans la région USA Ouest (Oregon) (us-west-2), un AWS KMS client par défaut est AWS Encryption SDK créé pour us-west-2 cette région. Si vous devez personnaliser le AWS KMS client, utilisez CreateAwsKmsKeyring() cette méthode.

// 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("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);

Kit SDK de chiffrement AWS pour Java prend en charge les AWS KMS trousseaux de clés qui utilisent un chiffrement symétrique (SYMMETRIC_DEFAULT) ou des clés asymétriques RSAKMS. AWS KMS les porte-clés créés avec des RSA KMS clés asymétriques ne peuvent contenir qu'une seule paire de clés.

Pour chiffrer avec un trousseau de RSA AWS KMS clés asymétrique, vous n'avez pas besoin de kms : GenerateDataKey ou de KMS:Encrypt car vous devez spécifier le matériel de clé publique que vous souhaitez utiliser pour le chiffrement lorsque vous créez le trousseau de clés. Aucun AWS KMS appel n'est effectué lors du chiffrement avec ce porte-clés. Pour déchiffrer avec un trousseau de RSA AWS KMS clés asymétrique, vous devez disposer de l'autorisation KMS:Decrypt.

Pour créer un trousseau de RSA AWS KMS clés asymétrique, vous devez fournir la clé publique et la clé privée ARN à partir de votre clé asymétrique RSAKMS. La clé publique doit être PEM codée. L'exemple suivant crée un AWS KMS porte-clés avec une paire de RSA clés asymétrique.

// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder()
        // Specify algorithmSuite without asymmetric signing here
        //
        // ALG_AES_128_GCM_IV12_TAG16_NO_KDF("0x0014"),
        // ALG_AES_192_GCM_IV12_TAG16_NO_KDF("0x0046"),
        // ALG_AES_256_GCM_IV12_TAG16_NO_KDF("0x0078"),
        // ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256("0x0114"),
        // ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256("0x0146"),
        // ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256("0x0178")
        .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256)
        .build();
                
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create a KMS RSA keyring.
//    This keyring takes in:
//     - kmsClient
//     - kmsKeyId: Must be an ARN representing an asymmetric RSA KMS key
//     - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
//                  key for the key passed into kmsKeyId
//     - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
        CreateAwsKmsRsaKeyringInput.builder()
                .kmsClient(KmsClient.create())
                .kmsKeyId(rsaKeyArn)
                .publicKey(publicKey)
                .encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
                .build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);

Contextes de chiffrement requis dans la version 3.x

Avec la version 3. x du Kit SDK de chiffrement AWS pour Java, vous pouvez utiliser le contexte de chiffrement requis CMM pour exiger des contextes de chiffrement dans vos opérations cryptographiques. Un contexte de chiffrement est un ensemble de paires clé-valeur non secrètes. Le contexte de chiffrement est lié cryptographiquement aux données chiffrées, de sorte que le même contexte de chiffrement est requis pour déchiffrer le champ. Lorsque vous utilisez le contexte de chiffrement requisCMM, vous pouvez spécifier une ou plusieurs clés de contexte de chiffrement requises (clés obligatoires) qui doivent être incluses dans tous les appels de chiffrement et de déchiffrement.

Note

Le contexte de chiffrement requis n'CMMest pris en charge que par les versions suivantes :

  • Version 3. x du Kit SDK de chiffrement AWS pour Java

  • Version 4. x du AWS Encryption SDK formulaire. NET

  • Version 4. x du Kit SDK de chiffrement AWS pour Python, lorsqu'il est utilisé avec la dépendance optionnelle Cryptographic Material Providers Library (MPL).

Si vous chiffrez des données à l'aide du contexte de chiffrement requisCMM, vous ne pouvez les déchiffrer qu'avec l'une de ces versions prises en charge.

Lors du chiffrement, il AWS Encryption SDK vérifie que toutes les clés de contexte de chiffrement requises sont incluses dans le contexte de chiffrement que vous avez spécifié. Les AWS Encryption SDK signes indiquent les contextes de chiffrement que vous avez spécifiés. Seules les paires clé-valeur qui ne sont pas des clés obligatoires sont sérialisées et stockées en texte clair dans l'en-tête du message chiffré renvoyé par l'opération de chiffrement.

Lors du déchiffrement, vous devez fournir un contexte de chiffrement contenant toutes les paires clé-valeur représentant les clés requises. AWS Encryption SDK Utilise ce contexte de chiffrement et les paires clé-valeur stockées dans l'en-tête du message chiffré pour reconstruire le contexte de chiffrement d'origine que vous avez spécifié lors de l'opération de chiffrement. S'il est AWS Encryption SDK impossible de reconstruire le contexte de chiffrement d'origine, l'opération de déchiffrement échoue. Si vous fournissez une paire clé-valeur contenant la clé requise avec une valeur incorrecte, le message chiffré ne peut pas être déchiffré. Vous devez fournir la même paire clé-valeur que celle spécifiée lors du chiffrement.

Important

Réfléchissez bien aux valeurs que vous choisissez pour les clés requises dans votre contexte de chiffrement. Vous devez être en mesure de fournir à nouveau les mêmes clés et les valeurs correspondantes lors du déchiffrement. Si vous ne parvenez pas à reproduire les clés requises, le message crypté ne peut pas être déchiffré.

L'exemple suivant initialise un AWS KMS trousseau de clés avec le contexte de chiffrement requis. CMM

// Instantiate the AWS Encryption SDK
final AwsCrypto crypto = AwsCrypto.builder()
        .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
        .build();
    
// Create your encryption context
final Map<String, String> encryptionContext = new HashMap<>();
encryptionContext.put("encryption", "context");
encryptionContext.put("is not", "secret");
encryptionContext.put("but adds", "useful metadata");
encryptionContext.put("that can help you", "be confident that");
encryptionContext.put("the data you are handling", "is what you think it is");    

// Create a list of required encryption contexts
final List<String> requiredEncryptionContextKeys = Arrays.asList("encryption", "context");
    
// Create the keyring
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsKeyringInput keyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(keyringInput);
    
// Create the required encryption context CMM
ICryptographicMaterialsManager cmm = 
    materialProviders.CreateDefaultCryptographicMaterialsManager(
        CreateDefaultCryptographicMaterialsManagerInput.builder()
            .keyring(kmsKeyring)
            .build()
    );
ICryptographicMaterialsManager requiredCMM = 
    materialProviders.CreateRequiredEncryptionContextCMM(
        CreateRequiredEncryptionContextCMMInput.builder()
            .requiredEncryptionContextKeys(requiredEncryptionContextKeys)
            .underlyingCMM(cmm)
            .build()
        );