Partager via

Bibliothèque de plug-ins de chiffrement pour le Kit de développement logiciel (SDK) Java Azure Cosmos DB pour Java

  • Article

Le plug-in Azure Cosmos Encryption est utilisé pour chiffrer les données avec une clé fournie par l’utilisateur avant de les enregistrer dans Cosmos DB et de les déchiffrer lors de la lecture à partir de la base de données.

| Code sourcePackage (Maven) | Documentation de référence sur les | API | Documentation produitÉchantillons

Prise en main

Inclure le package

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-cosmos-encryption</artifactId>
  <version>2.6.0</version>
</dependency>

Reportez-vous à maven Central pour connaître les versions précédentes

Pour plus d’informations sur le package, consultez javadocs .

Prérequis

SLF4J n’est nécessaire que si vous envisagez d’utiliser la journalisation. Téléchargez également une liaison SLF4J qui lie l’API SLF4J à l’implémentation de journalisation de votre choix. Pour plus d’informations, consultez le manuel de l’utilisateur SLF4J.

Le Kit de développement logiciel (SDK) fournit des API asynchrones basées sur Reactor Core. Vous pouvez en savoir plus sur les types Core et Flux/Mono de réacteur ici

Concepts clés

Le plug-in Azure Cosmos Encryption est utilisé pour chiffrer les données avec une clé fournie par l’utilisateur avant de les enregistrer dans Cosmos DB et de les déchiffrer lors de la lecture à partir de la base de données. En dessous, il utilise le Kit de développement logiciel (SDK) Java Azure Cosmos DB qui fournit une représentation logique côté client pour accéder à l’API SQL Azure Cosmos DB. Un compte Cosmos DB contient zéro ou plusieurs bases de données, une base de données (DB) contient zéro ou plusieurs conteneurs et un conteneur contient zéro ou plusieurs éléments. Vous pouvez en savoir plus sur les bases de données, les conteneurs et les éléments ici. Quelques propriétés importantes sont définies au niveau du conteneur, dont le débit approvisionné et la clé de partition.

Exemples

La section suivante fournit plusieurs extraits de code couvrant certaines des tâches les plus courantes de l’API Cosmos Encryption, notamment :

Créer un client de chiffrement Cosmos

// Create a new CosmosEncryptionAsyncClient
CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildAsyncClient();
KeyEncryptionKeyClientBuilder keyEncryptionKeyClientBuilder = new KeyEncryptionKeyClientBuilder().credential(tokenCredentials);
CosmosEncryptionAsyncClient cosmosEncryptionAsyncClient =
    new CosmosEncryptionClientBuilder().cosmosAsyncClient(cosmosAsyncClient).keyEncryptionKeyResolver(
        keyEncryptionKeyClientBuilder).keyEncryptionKeyResolverName(CosmosEncryptionClientBuilder.KEY_RESOLVER_NAME_AZURE_KEY_VAULT).buildAsyncClient();

Créer une base de données Cosmos Encryption

Vous devez d’abord créer une base de données et, à l’aide du client de chiffrement cosmos créé dans l’exemple précédent, vous pouvez créer un objet proxy de base de données de chiffrement cosmos comme suit :

// This will create a database with the regular cosmosAsyncClient.
CosmosEncryptionAsyncDatabase cosmosEncryptionAsyncDatabase = cosmosEncryptionAsyncClient.getCosmosAsyncClient()
    .createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .map(databaseResponse ->
        // Get a reference to the encryption database
        // This will create a cosmos encryption database proxy object.
        cosmosEncryptionAsyncClient.getCosmosEncryptionAsyncDatabase(databaseResponse.getProperties().getId()))
    .block(); // Blocking for demo purposes (avoid doing this in production unless you must)

Créer un conteneur de chiffrement Cosmos

Vous devez d’abord créer un conteneur avec ClientEncryptionPolicy et à l’aide de l’objet de base de données de chiffrement cosmos créé dans l’exemple précédent, vous pouvez créer un objet proxy de conteneur de chiffrement cosmos comme suit :

//Create Client Encryption Key
EncryptionKeyWrapMetadata metadata = new EncryptionKeyWrapMetadata(this.cosmosEncryptionAsyncClient.getKeyEncryptionKeyResolverName(), "key", "tempmetadata", EncryptionAlgorithm.RSA_OAEP.toString());
CosmosEncryptionAsyncContainer cosmosEncryptionAsyncContainer = cosmosEncryptionAsyncDatabase
    .createClientEncryptionKey("key", CosmosEncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256.getName(), metadata)
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .then(Mono.defer(() -> {
        //Create Encryption Container
        ClientEncryptionIncludedPath includedPath = new ClientEncryptionIncludedPath();
        includedPath.setClientEncryptionKeyId("key");
        includedPath.setPath("/sensitiveString");
        includedPath.setEncryptionType(CosmosEncryptionType.DETERMINISTIC.toString());
        includedPath.setEncryptionAlgorithm(CosmosEncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256.getName());

        List<ClientEncryptionIncludedPath> paths = new ArrayList<>();
        paths.add(includedPath);
        ClientEncryptionPolicy clientEncryptionPolicy = new ClientEncryptionPolicy(paths);
        CosmosContainerProperties properties = new CosmosContainerProperties("<YOUR CONTAINER NAME>", "/mypk");
        properties.setClientEncryptionPolicy(clientEncryptionPolicy);
        return cosmosEncryptionAsyncDatabase.getCosmosAsyncDatabase().createContainer(properties);
    }))
    .map(containerResponse ->
        // Create a reference to the encryption container
        // This will create a cosmos encryption container proxy object.
        cosmosEncryptionAsyncDatabase.getCosmosEncryptionAsyncContainer(containerResponse.getProperties().getId()))
    .block(); // Blocking for demo purposes (avoid doing this in production unless you must)

Opération CRUD sur les éléments

// Create an item
Pojo pojo = new Pojo();
pojo.setSensitiveString("Sensitive Information need to be encrypted");
cosmosEncryptionAsyncContainer.createItem(pojo)
    .flatMap(response -> {
        System.out.println("Created item: " + response.getItem());
        // Read that item 👓
        return cosmosEncryptionAsyncContainer.readItem(response.getItem().getId(),
            new PartitionKey(response.getItem().getId()),
            Pojo.class);
    })
    .flatMap(response -> {
        System.out.println("Read item: " + response.getItem());
        // Replace that item 🔁
        Pojo p = response.getItem();
        pojo.setSensitiveString("New Sensitive Information");
        return cosmosEncryptionAsyncContainer.replaceItem(p, response.getItem().getId(),
            new PartitionKey(response.getItem().getId()));
    })
    // delete that item 💣
    .flatMap(response -> cosmosEncryptionAsyncContainer.deleteItem(response.getItem().getId(),
        new PartitionKey(response.getItem().getId())))
    .subscribe();

Nous avons un exemple d’application de prise en main disponible ici.

Dépannage

Général

Azure Cosmos DB est une base de données distribuée rapide et flexible qui peut être mise à l’échelle en toute transparence avec une latence et un débit garantis. Vous n’avez pas à apporter de modifications d’architecture majeures ou écrire de code complexe pour mettre à l’échelle votre base de données avec Azure Cosmos DB. La réduction et l’augmentation de l’échelle est aussi simple que le passage d’un appel d’API ou de Kit de développement logiciel (SDK). Toutefois, étant donné qu’Azure Cosmos DB est accessible au moyen d’appels réseau, vous pouvez apporter des optimisations côté client de manière à atteindre des performances de pointe quand vous utilisez le SDK Java v4 Azure Cosmos DB.

  • Le Guide des performances couvre ces optimisations côté client.

  • Le Guide de résolution des problèmes décrit les problèmes courants, les solutions de contournement, les étapes de diagnostic et les outils lorsque vous utilisez le Kit de développement logiciel (SDK) Java Azure Cosmos DB v4 avec des comptes d’API SQL Azure Cosmos DB.

Activer la journalisation du client

Le kit SDK Java v4 Azure Cosmos DB utilise SLF4j comme façade de journalisation prenant en charge la journalisation dans les frameworks de journalisation populaires tels que log4j et logback.

Par exemple, si vous souhaitez utiliser log4j en tant que framework de journalisation, ajoutez les bibliothèques suivantes dans votre chemin de classe Java.

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

Ajoutez également une configuration log4j.

# this is a sample log4j configuration

# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

Étapes suivantes

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions