Intégrer EncJDBC - Database Autonomy Service - Centre de documentation Alibaba Cloud

Pour accéder aux données des colonnes protégées par le chiffrement de colonne depuis une application Java, utilisez le pilote EncJDBC pour vous connecter à votre base de données. EncJDBC récupère le texte en clair des colonnes chiffrées avec une configuration minimale.

Lorsque vous fournissez la clé de chiffrement principale, l'intégralité du lien de transmission des données est chiffrée. Le client EncJDBC déchiffre automatiquement les données et renvoie le texte en clair que votre application peut afficher avec des modifications de code minimales.

Prérequis

Exécutez une analyse de détection des données sensibles pour identifier les colonnes nécessitant un chiffrement.
Configurez le chiffrement de colonne pour la base de données cible et définissez l'autorisation du compte de base de données sur Ciphertext Permission (JDBC Decryption). Pour obtenir des instructions détaillées, consultez la rubrique relative au chiffrement de colonne.
Les détails de connexion de l'instance : nom d'hôte, port, nom de la base de données, nom d'utilisateur et mot de passe.

Générer une MEK

Plage de valeurs : une chaîne hexadécimale de 16 octets, soit exactement 32 caractères.

Selon le key type sélectionné lors de la configuration du chiffrement de colonne, vous pouvez utiliser soit une KMS Key soit générer une local key en tant que MEK pour déchiffrer la base de données.

Clé KMS

Important

Assurez-vous que le service KMS est disponible lorsque vous utilisez une clé KMS. Sinon, le pilote client toujours confidentiel EncJDBC ne fonctionnera pas.

Récupérez le endpoint de l'instance KMS propriétaire de la KMS key sélectionnée dans votre configuration de chiffrement de colonne de base de données, ainsi que l'AccessKey ID et l'AccessKey secret du compte Alibaba Cloud ou de l'utilisateur RAM (qui doit disposer de l'autorisation de déchiffrement KMS) pour lire cette clé KMS depuis le client. Suivez les étapes ci-dessous :

Connectez-vous à la console en utilisant un compte Alibaba Cloud ou un utilisateur RAM.
Si vous utilisez un utilisateur RAM, accordez-lui l'autorisation de déchiffrement KMS.
1. Créez une stratégie personnalisée. Utilisez le contenu de stratégie suivant :
  { "Version": "1", "Statement": [ { "Effect": "Allow", "Action": "KMS:Decrypt", "Resource": "*" } ] }
2. Attachez la stratégie personnalisée créée à l'utilisateur RAM spécifié. Pour plus de détails, consultez la rubrique Gérer les autorisations des utilisateurs RAM.
Récupérez le endpoint de l'instance KMS.
- Par défaut, les clés d'une instance KMS n'autorisent l'accès qu'à partir des réseaux VPC. Sur la page de gestion des instances KMS, localisez votre instance KMS cible, cliquez sur Actions, puis sur Details, et affichez le endpoint VPC dans l'onglet Basic Information.
- Pour accéder aux clés via le réseau public, activez l'accès au réseau public, puis affichez le endpoint public. Pour plus de détails, consultez la rubrique Activer l'accès au réseau public.
Récupérez les identifiants d'accès.

Enregistrez l'AccessKey ID et l'AccessKey secret lors de la création de l'AccessKey pour votre compte Alibaba Cloud ou votre utilisateur RAM. Pour plus de détails, consultez la rubrique Créer une AccessKey.

Clé locale

Lorsque la Encryption Method dans votre configuration de chiffrement de colonne de base de données est définie sur Local Key, générez une MEK. Par exemple : 00112233445566778899aabbccddeeff.

Les méthodes de génération courantes incluent les générateurs de mots de passe ou les fonctions aléatoires des langages de programmation.

Par exemple :

Sous Linux, utilisez l'outil OpenSSL intégré en exécutant openssl rand -hex 16 pour générer une clé.
Sous Windows, installez le package logiciel OpenSSL.

Instructions d'intégration du client

Important

Utilisez JDK 1.8 ou une version ultérieure pour Java.

Côté client, remplacez le pilote de connexion à la base de données par EncJDBC, mettez à jour l'URL de connexion à la base de données et spécifiez la MEK pour accéder au texte en clair des colonnes chiffrées de la base de données.

1. Installer les dépendances

Ajoutez la dépendance suivante au fichier de configuration de votre projet Maven pom.xml.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-cls-jdbc</artifactId>
    <version>1.0.10-3</version>
</dependency>

2. Configurer laMEK pour se connecter à la base de données

Les méthodes suivantes décrivent comment configurer la MEK : configuration des propriétés JDBC, configuration par fichier et configuration par URL. Si vous configurez plusieurs méthodes simultanément, l'ordre de priorité est le suivant : configuration des propriétés JDBC > configuration par fichier > configuration par URL.

Remarque

Dans la configuration par URL, séparez plusieurs paramètres par &.
Dans toutes les configurations et méthodes de connexion ci-dessous, la MEK est traitée localement sur le client et envoyée en toute sécurité au serveur à l'aide du chiffrement sous enveloppe pour éviter la fuite de la MEK.

Choisissez de vous connecter à la base de données en utilisant soit une clé locale, soit une clé KMS, en fonction de la méthode de chiffrement dans votre configuration de chiffrement de colonne de base de données.

Se connecter à la base de données à l'aide d'une clé KMS

Important

Si vous utilisez des informations d'identification temporaires STS pour récupérer une MEK gérée par KMS, utilisez le SDK STS pour obtenir le jeton STS des informations d'identification temporaires. Pour des exemples de SDK STS, consultez la rubrique Présentation du SDK STS.
Ne codez pas en dur les informations d'identification d'accès (AccessKey ID et AccessKey secret) directement dans le code de votre application. Cet exemple utilise des variables d'environnement système pour gérer les informations d'identification d'accès. Pour plus de détails, consultez la rubrique Configurer les variables d'environnement sous Linux, macOS et Windows.

Configuration des propriétés JDBC

JDBC standard vous permet de définir des propriétés personnalisées à l'aide de Properties lors de la connexion. L'exemple suivant montre comment configurer les propriétés JDBC et exécuter JDBC :

// Prepare connection information such as hostname, port, database name, username, and password.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
// Retrieve access credentials (AccessKey ID and AccessKey secret) from environment variables.
String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// If using STS temporary credentials to read the KMS key, also provide the obtained STS token.
// String stsToken = "yourSecurityToken";
// KMS instance endpoint. Use the public endpoint if public network access is enabled. Use the VPC endpoint for VPC access.
String kmsEndpoint = "kms.cn-hangzhou.aliyuncs.com";
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("ALIBABA_CLOUD_ACCESS_KEY_ID", accessKeyId);
props.setProperty("ALIBABA_CLOUD_ACCESS_KEY_SECRET", accessKeySecret);
props.setProperty("ALIBABA_CLOUD_KMS_ENDPOINT", kmsEndpoint);
// props.setProperty("ALIBABA_CLOUD_STS_TOKEN", "stsToken");
// Connection URL format for MySQL: "jdbc:mysql:encdb://%s:%s/%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
// Load the EncJDBC driver for MySQL.
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
// Get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, props);
// ... Execute queries ...

Configuration par URL

Vous pouvez intégrer directement dans l'URL les paramètres permettant de récupérer la clé KMS, comme indiqué ci-dessous :

// Prepare connection information such as hostname, port, database name, username, and password.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
// Retrieve access credentials (AccessKey ID and AccessKey secret) from environment variables.
String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// If using STS temporary credentials to read the KMS key, also provide the obtained STS token.
// String stsToken = "yourSecurityToken";
// KMS instance endpoint. Use the public endpoint if public network access is enabled. Use the VPC endpoint for VPC access.
String kmsEndpoint = "kms.cn-hangzhou.aliyuncs.com";
// Connection URL format for MySQL.
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?ALIBABA_CLOUD_ACCESS_KEY_ID=%s&ALIBABA_CLOUD_ACCESS_KEY_SECRET=%s&ALIBABA_CLOUD_KMS_ENDPOINT=%s", hostname, port, dbname, accessKeyId, accessKeySecret, kmsEndpoint);
// With STS token.
// String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?ALIBABA_CLOUD_ACCESS_KEY_ID=%s&ALIBABA_CLOUD_ACCESS_KEY_SECRET=%s&ALIBABA_CLOUD_KMS_ENDPOINT=%s&ALIBABA_CLOUD_STS_TOKEN=%s", hostname, port, dbname, accessKeyId, accessKeySecret, kmsEndpoint, stsToken);
// Load the EncJDBC driver for MySQL.
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
// Get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Execute queries ...

Se connecter à la base de données à l'aide d'une clé locale

Configuration des propriétés JDBC

// Prepare connection information such as hostname, port, database name, username, and password.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
// Master encryption key.
String mek = "00112233445566778899aabbccddeeff"; 
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);
// Connection URL format for MySQL: "jdbc:mysql:encdb://%s:%s/%s". For PostgreSQL, use "jdbc:postgresql:encdb://%s:%s/%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
// Load the EncJDBC driver for MySQL. For PostgreSQL, use "com.aliyun.encdb.postgresql.jdbc.EncDriver".
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
// Get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, props);
// ... Execute queries ...

Configuration par fichier

Vous pouvez importer des paramètres tels que la MEK requise via un fichier de configuration.

Remarque

La configuration par fichier s'applique uniquement aux MEK de clé locale.

Définissez une property nommée encJdbcConfigFile dans votre projet et définissez sa valeur sur le chemin du fichier de configuration (par défaut, le fichier encjdbc.conf est utilisé). Le contenu du fichier de configuration est le suivant :

MEK=00112233445566778899aabbccddeeff

Placez le fichier de configuration à l'un des deux emplacements suivants :

Placez le fichier dans le répertoire resources de votre projet, comme illustré ci-dessous :
```
src
  main
    java
    resources
      encjdbc.conf
```
Placez le fichier dans le répertoire racine du projet (le répertoire d'exécution du programme).

Après avoir configuré le fichier, aucune configuration supplémentaire n'est nécessaire dans votre code, comme illustré ci-dessous :

// Prepare connection information such as hostname, port, database name, username, and password.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
// Connection URL format for MySQL: "jdbc:mysql:encdb://%s:%s/%s". For PostgreSQL, use "jdbc:postgresql:encdb://%s:%s/%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
// Load the EncJDBC driver for MySQL. For PostgreSQL, use "com.aliyun.encdb.postgresql.jdbc.EncDriver".
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
// Get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Execute queries ...

Configuration par URL

Vous pouvez intégrer directement dans l'URL des paramètres tels que la MEK, comme illustré ci-dessous :

// Prepare connection information such as hostname, port, database name, username, and password.
// ...
String hostname = "your-hostname";
String port = "your-port";
String dbname = "your-database-name";
String username = "your-username";
String password = "your-password";
 // Master encryption key.
String mek = "00112233445566778899aabbccddeeff";
// Connection URL format for MySQL: "jdbc:mysql:encdb://%s:%s/%s?MEK=%s". For PostgreSQL, use "jdbc:postgresql:encdb://%s:%s/%s?MEK=%s".
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s?MEK=%s", hostname, port, dbname, mek);
// Load the EncJDBC driver for MySQL. For PostgreSQL, use "com.aliyun.encdb.postgresql.jdbc.EncDriver".
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
// Get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, username, password);
// ... Execute queries ...

3. Interroger les données en texte clair des colonnes chiffrées

Une fois la connexion à la base de données établie avec succès, utilisez-la comme pour une requête JDBC standard. EncJDBC déchiffre automatiquement les colonnes chiffrées et renvoie les données en texte clair.

Exemple de code :

// Execute the query.
// Create a query statement.
Statement statement = connection.createStatement();
ResultSet resultSet = statement.executeQuery("SELECT * FROM your_table_name");
// Traverse the result set.
while (resultSet.next()) {
    for (int i = 0; i < rs.getMetaData().getColumnCount(); i++) {
        System.out.print(rs.getString(i + 1));
        System.out.print("\t");
    }
    System.out.print("\n");
}

Dépannage

`IllegalAccessError: cannot access class com.sun.crypto.provider.SunJCE`

Cette erreur se produit car les versions plus récentes de JDK restreignent l'accès inter-modules par défaut. Ajoutez l'option VM suivante lors de l'exécution de votre programme :

--add-exports=java.base/com.sun.crypto.provider=ALL-UNNAMED

`failed in mek provision: gcmEncrypt error`

Il s'agit d'un problème connu avec Oracle JDK. Utilisez l'une des corrections suivantes :

Basculez vers Amazon Corretto — une distribution OpenJDK compatible qui ne présente pas ce problème.
Ajoutez le fournisseur de sécurité BouncyCastle à Oracle JDK :
1. Localisez le répertoire d'installation de votre JDK.
2. Ouvrez <jdk-path>/conf/security/java.security.
3. Dans la section List of providers and their preference orders, ajoutez : `` security.provider.14=org.bouncycastle.jce.provider.BouncyCastleProvider ``