PolarDB:Integrate the EncDB SDK

Preparations

• Obtain the information needed to connect to the database on which PolarDB Always Encrypted is enabled, such as the hostname, port, database name, username, and password.

• Configure encryption rules. For more information, see the Create an encryption rule section of the "Manage encryption rules" topic.

Configure the EncDB SDK

Add the following dependencies in your Maven project:

<dependencies>
   ...
   <!-- All versions of MySQL Connector/J are supported. -->
   <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
      <version>8.0.32</version>
   </dependency>
   <dependency>
      <groupId>com.alibaba.encdb</groupId>
      <artifactId>libencdb</artifactId>
      <version>1.2.11-SNAPSHOT</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/org.bouncycastle/bcprov-jdk15on -->
   <dependency>
     <groupId>org.bouncycastle</groupId>
     <artifactId>bcprov-jdk15on</artifactId>
     <version>1.62</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/org.bouncycastle/bcpkix-jdk15on -->
   <dependency>
     <groupId>org.bouncycastle</groupId>
     <artifactId>bcpkix-jdk15on</artifactId>
     <version>1.62</version>
   </dependency>
   <dependency>
     <groupId>com.alibaba.fastjson2</groupId>
     <artifactId>fastjson2</artifactId>
     <version>2.0.2</version>
   </dependency>
   <!-- https://mvnrepository.com/artifact/org.postgresql/postgresql -->
   <dependency>
     <groupId>org.postgresql</groupId>
     <artifactId>postgresql</artifactId>
     <version>42.2.23</version>
   </dependency>
   <dependency>
     <groupId>com.google.guava</groupId>
     <artifactId>guava</artifactId>
     <version>24.1.1-jre</version>
   </dependency>
   ...
</dependencies>

Configuration example

You can use any MySQL client that can properly parse Text Protocol queries. The following demo is built based on MySQL Connector/J (introduced to the POM file of the Maven project) and the EncDB SDK. You need to complete the demo with cluster connection information of a PolarDB cluster on which PolarDB Always Encrypted is enabled and configure encryption rules for the enc_int column.

// The information needed to connect to the database on which PolarDB Always Encrypted is enabled. The endpoint cannot be a primary endpoint.
String hostname = "asodijasdoijaisd.rwlb.rds.aliyuncs.com";
String port = "3306";
String dbname = "test_db";
String username = "ruanbu";
String password = "123456Abc!";
Class.forName("com.mysql.cj.jdbc.Driver");
String dbUrl = String.format("jdbc:mysql://%s:%s/%s", hostname, port, dbname);
java.sql.Connection conn = java.sql.DriverManager.getConnection(dbUrl, username, password);
// The customer master key, which is a 32-bit hexadecimal string in this demo.
String mek = "00112233445566778899aabbccddeeff";
com.alibaba.encdb.EncdbSDK sdk =
        com.alibaba.encdb.crypto.EncdbSDKBuilder.newInstance()
                .setKeyMgmtType(com.alibaba.encdb.common.Constants.KeyMgmtType.MYSQL_PROXY)
                .setDbConnection(conn)
                .setMek(mek)
                .build();
com.alibaba.encdb.Cryptor cryptor = sdk.getCryptor();
// A table creation test.
conn.createStatement().executeUpdate("drop table if exists test");
conn.createStatement().executeUpdate("create table test (enc_int int)");
conn.createStatement().executeUpdate("insert into test values (1)");
java.sql.ResultSet rs = conn.createStatement().executeQuery("select * from test");
rs.next();
// Obtains the ciphertext.
byte[] cipher = rs.getBytes(1);
// Calls the Cryptor.decrypt method to obtain the plaintext.
byte[] plaintext = cryptor.decrypt(cipher);
// Returns the ciphertext and plaintext.
System.out.println("Plaintext: " + new String(plaintext) + " Ciphertext: " + new String(cipher));

Output:

Plaintext: 1 Ciphertext: QmEA/4d0ROXfA3QeUZFiu7EdlvZy4Yaa+uDnyFHvFOnVK4dtgVIzjrYI54I=

EncDB SDK for Java

• EncdbSDKBuilder refers to com.alibaba.encdb.crypto.EncdbSDKBuilder, which is a constructor of the EncdbSDK class. The following APIs are used:

  // Creates an EncdbSDKBuilder instance. Always use this method to construct EncdbSDKBuilder. 
  EncdbSDKBuilder newInstance();
  // (Required) Configures a database connection used to perform key management operations related to the EncDB SDK. This connection can be different from the database connection used in actual business. 
  EncdbSDKBuilder setDbConnection(java.sql.Connection dbConnection);
  // (Required) Specifies the client type. Add the MYSQL_PROXY option.
  EncdbSDKBuilder setKeyMgmtType(KeyMgmtType kmType);
  // (Required) Configures the customer master key, which is a 128-bit (or 16-byte) byte[] object.
  EncdbSDKBuilder setMek(byte[] mek);
  // (Optional) Configures the encryption algorithm. Valid values: AES_128_GCM, AES_128_CTR, AES_128_CBC, AES_128_ECB, SM4_128_CBC, SM4_128_ECB, SM4_128_GCM, and SM4_128_CTR. Default value: SM4_128_CBC. 
  EncdbSDKBuilder setEncAlgo(EncAlgo encAlgo);
  // Constructs an EncdbSDK object after the preceding configurations.
  EncdbSDK build();

• EncdbSDK refers to com.alibaba.encdb.EncdbSDK. The following API is used:

  // Obtains a Cryptor object used to perform operations on the ciphertext or plaintext. 
  Cryptor getCryptor();

• Cryptor refers to com.alibaba.encdb.Cryptor. The following API is used:

  // Obtains plaintext corresponding to the input ciphertext.
  byte[] decrypt(byte[] val);