Após configurar a criptografia de coluna para dados sensíveis em tabelas de banco de dados RDS MySQL, RDS PostgreSQL, PolarDB MySQL ou PolarDB PostgreSQL, utilize o driver EncJDBC para conectar-se ao banco de dados caso sua aplicação Java precise acessar o texto simples dessas colunas criptografadas. Este tópico descreve como usar o EncJDBC para estabelecer a conexão com o banco de dados e acessar os dados em texto simples das colunas criptografadas.
Pré-requisitos
Ative a criptografia de coluna no banco de dados de destino e defina a permissão de texto cifrado da conta correspondente como Ciphertext Permission (JDBC Decryption). Para obter instruções detalhadas sobre como configurar a criptografia de coluna e as permissões da conta, consulte Configurar criptografia de coluna do banco de dados.
Obtenha as informações de conexão do banco de dados criptografado: endpoint, porta, nome do banco de dados, conta do banco de dados e senha.
Informações básicas
O recurso de criptografia de coluna permite aplicar proteção dinâmica de saída a colunas sensíveis específicas no seu banco de dados, aumentando a segurança dos dados. Após ativar esse recurso, o sistema controla os resultados das consultas com base na política de acesso da conta do banco de dados:
Contas com Plaintext Permissions podem visualizar os dados brutos diretamente.
Contas configuradas com Ciphertext Permission (JDBC Decryption) recebem o texto cifrado criptografado, mas conseguem restaurá-lo automaticamente para texto simples utilizando o driver JDBC sempre confidencial da Alibaba Cloud (EncJDBC), desde que forneçam uma chave mestra de criptografia (MEK) compatível com a política de criptografia.
Contas configuradas com Ciphertext Permission (No Decryption Permission) visualizam apenas o texto cifrado e não possuem nenhuma forma de descriptografá-lo.
Esse mecanismo garante a proteção eficaz dos dados sensíveis na etapa de saída. Mesmo que os dados sejam exportados ou interceptados, partes não autorizadas não conseguirão lê-los.
Gerar uma MEK
Ao ativar a criptografia de coluna usando o método Local key para uma coluna, o gateway de criptografia de coluna do DSC criptografa os campos sensíveis usando uma chave controlada antes de retornar os resultados da consulta ao cliente. Exceto pelas contas com Plaintext permission, todas as demais recebem texto cifrado criptografado ao consultar essa coluna.
Para acessar o texto simples posteriormente usando uma conta com Ciphertext permission (JDBC decryption), forneça e registre sua própria MEK durante a configuração inicial da criptografia de coluna. Somente uma MEK compatível com a política de criptografia permite que o driver EncJDBC descriptografe corretamente os campos de texto cifrado nos resultados da consulta no lado do cliente.
Intervalo de valores: Uma string hexadecimal de 16 bytes, com exatamente 32 caracteres.
Função da MEK: A MEK é a credencial raiz que autoriza o cliente EncJDBC a descriptografar campos de texto cifrado nos resultados da consulta. Ela protege a chave real usada para criptografar esses resultados.
Responsabilidade de segurança: A Alibaba Cloud não armazena, faz backup nem hospeda sua MEK. Proteja-a utilizando uma solução segura de gerenciamento de chaves, como o KMS.
Aviso importante: Se você perder sua MEK, todos os resultados históricos de consulta criptografados sob esta política tornar-se-ão permanentemente indecifráveis.
Com base no Encryption Method selecionado na configuração de criptografia de coluna do seu banco de dados, obtenha uma KMS Key ou gere uma Local Key para usar como sua MEK na descriptografia do banco de dados correspondente.
Chave KMS
Garanta que o service KMS esteja disponível ao usar uma chave KMS. Caso contrário, o driver de cliente sempre confidencial EncJDBC não funcionará.
Obtenha o endpoint da instância KMS proprietária da KMS key selecionada na configuração de criptografia de coluna do seu banco de dados, juntamente com o AccessKey ID e o AccessKey secret da conta Alibaba Cloud ou do usuário RAM (que deve ter permissão de descriptografia do KMS) para ler essa chave KMS a partir do cliente. Siga estas etapas:
Faça logon no console usando uma conta Alibaba Cloud ou um usuário RAM.
-
-
-
Chave local
Quando o Encryption Method na configuração de criptografia de coluna do seu banco de dados estiver definido como Local Key, gere uma MEK. Por exemplo: 00112233445566778899aabbccddeeff.
Métodos comuns de geração incluem geradores de senhas ou funções aleatórias em linguagens de programação.
Por exemplo:
No Linux, use a ferramenta integrada OpenSSL executando
openssl rand -hex 16para gerar uma chave.No Windows, instale o pacote de software OpenSSL.
Instruções de integração do cliente
Use JDK 1.8 ou superior para Java.
No lado do cliente, altere o driver de conexão do banco de dados para EncJDBC, atualize a URL de conexão do banco de dados e especifique a MEK para acessar o texto simples das colunas criptografadas do banco de dados.
1. Instalar dependências
Adicione a seguinte dependência ao arquivo de configuração do seu projeto Maven pom.xml.
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-cls-jdbc</artifactId>
<version>1.0.10-3</version>
</dependency>2. Configurar a MEK para conectar-se ao banco de dados
Os métodos a seguir descrevem como configurar a MEK: configuração de propriedades JDBC, configuração por arquivo e configuração por URL. Se você configurar mais de um método simultaneamente, a ordem de prioridade será: configuração de propriedades JDBC > configuração por arquivo > configuração por URL.
Na configuração por URL, separe múltiplos parâmetros com
&.Em todas as configurações e métodos de conexão abaixo, a
MEKé processada localmente no cliente e enviada com segurança ao servidor usando criptografia de envelope para evitar vazamento daMEK.
Escolha conectar-se ao banco de dados usando uma chave local ou uma chave KMS com base no Encryption method da configuração de criptografia de coluna do seu banco de dados.
Conectar-se ao banco de dados usando uma chave KMS
Se você usar credenciais temporárias STS para recuperar uma MEK gerenciada pelo KMS, utilize o SDK STS para obter o token de credencial temporária STS. Para exemplos do SDK STS, consulte Visão geral do SDK STS.
Não codifique as credenciais de acesso (AccessKey ID e AccessKey secret) diretamente no código da sua aplicação. Este exemplo usa variáveis de ambiente do sistema para gerenciar as credenciais de acesso. Para mais detalhes, consulte Configurar variáveis de ambiente no Linux, macOS e Windows.
Configuração de propriedades JDBC
O JDBC padrão permite definir propriedades personalizadas usando Properties durante a conexão. O exemplo a seguir mostra como configurar as propriedades JDBC e executar o 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 ...Configuração por URL
É possível incorporar parâmetros para recuperar a chave KMS diretamente na URL, conforme mostrado abaixo:
// 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 ...Conectar-se ao banco de dados usando uma chave local
Configuração de propriedades JDBC
O JDBC padrão permite definir propriedades personalizadas usando Properties durante a conexão. O exemplo a seguir mostra como configurar as propriedades JDBC e executar o 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 ...Configuração por arquivo
Você pode importar parâmetros como a MEK necessária através de um arquivo de configuração.
A configuração por arquivo aplica-se apenas a MEKs de chave local.
Defina uma property chamada encJdbcConfigFile no seu projeto e defina seu valor como o caminho do arquivo de configuração (por padrão, o arquivo encjdbc.conf é usado). O conteúdo do arquivo de configuração é o seguinte:
MEK=00112233445566778899aabbccddeeffColoque o arquivo de configuração em um destes dois locais:
-
Coloque o arquivo no diretório resources do seu projeto, conforme mostrado abaixo:
src main java resources encjdbc.conf Coloque o arquivo no diretório raiz do projeto (o diretório de execução do programa).
Após configurar o arquivo, nenhuma configuração adicional é necessária no seu código, conforme mostrado abaixo:
// 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 ...Configuração por URL
É possível incorporar parâmetros como a MEK diretamente na URL, conforme mostrado abaixo:
// 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. Consultar dados em texto simples de colunas criptografadas
Após conectar-se com sucesso ao banco de dados, opere-o exatamente como em uma consulta JDBC padrão. O EncJDBC descriptografa automaticamente as colunas criptografadas e retorna os dados em texto simples.
Código de exemplo:
// 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");
}Exemplo de código completo
Usando propriedades JDBC para configurar uma MEK de chave local, este exemplo consulta dados em texto simples de colunas criptografadas em um banco de dados RDS MySQL usando uma conta de banco de dados com Ciphertext Permission (JDBC Decryption).
Para informações sobre a configuração do banco de dados no exemplo a seguir, consulte Verificar resultados da criptografia de coluna no Exemplo de criptografia de coluna do banco de dados RDS MySQL.
Este exemplo usa a versão 3.9.9 do Maven e a ferramenta de desenvolvimento IntelliJ IDEA Community Edition 2024.1.2.
import java.sql.*;
import java.util.Properties;
public class EncryptedColumnAccess {
public static void main(String[] args) throws ClassNotFoundException, SQLException {
// Update the following connection information (hostname, port, database name, username, password) with your instance details.
String hostname = "rm-******.mysql.rds.aliyuncs.com";
String port = "3306";
String dbname = "sddp_em_db";
String username = "sddp_em03";
String password = "******";
// Example only. Use a more complex key in production.
String mek="00112233445566778899aabbccddeeff";
Properties props = new Properties();
props.setProperty("user", username);
props.setProperty("password", password);
props.setProperty("MEK", mek);
String dbUrl = String.format("jdbc:mysql:encdb://%s:%s/%s", hostname, port, dbname);
// Load the EncJDBC driver.
Class.forName("com.aliyun.encdb.mysql.jdbc.EncDriver");
// Get the database connection.
Connection connection = DriverManager.getConnection(dbUrl, props);
// Execute a query.
try {
// Create a query statement.
Statement statement = connection.createStatement();
ResultSet resultSet = statement.executeQuery("SELECT * FROM users");
// Traverse the result set.
while (resultSet.next()) {
int id = resultSet.getInt("id");
String name = resultSet.getString("username");
String phone = resultSet.getString("phone");
// Process other fields based on your table schema.
System.out.println("ID: " + id + ", Name: " + name + ", Phone: " + phone);
}
// Close resources.
resultSet.close();
statement.close();
} catch (SQLException e) {
e.printStackTrace();
}
}
}Saída de exemplo:
ID: 1, Name: username008808, Phone: 15xxx95
ID: 2, Name: username187643, Phone: 15xxx81