Integrar EncJDBC - Database Autonomy Service: Central de Documentação do Alibaba Cloud

Para acessar dados em colunas protegidas por criptografia de coluna a partir de uma aplicação Java, use o driver EncJDBC para se conectar ao banco de dados. Esse driver oferece uma maneira prática e econômica de trabalhar com dados criptografados. Este tópico demonstra como usar o EncJDBC para recuperar texto simples de colunas criptografadas do banco de dados.

Ao fornecer a chave mestra de criptografia, o canal de transmissão de dados fica totalmente criptografado. O cliente EncJDBC descriptografa automaticamente os dados e retorna o texto simples, permitindo que a aplicação exiba as informações com configurações mínimas.

Pré-requisitos

Execute uma varredura de detecção de dados sensíveis para identificar as colunas que exigem criptografia.
Configure a criptografia de coluna para o banco de dados de destino e defina a permissão da conta do banco de dados como Ciphertext Permission (JDBC Decryption). Para obter instruções detalhadas, consulte Criptografia de coluna.

Gerar uma MEK

Intervalo de valores: string hexadecimal de 16 bytes, com exatamente 32 caracteres.

Com base no key type selecionado durante a configuração da criptografia de coluna, use uma KMS Key ou gere uma local key como MEK para descriptografar o banco de dados.

Chave KMS

Importante

Garanta que o service KMS esteja disponível ao usar uma chave KMS. Caso contrário, o driver de cliente always-confidential 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 banco de dados, além do AccessKey ID e do 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 login no console usando uma conta Alibaba Cloud ou um usuário RAM.
Se estiver usando um usuário RAM, conceda a permissão de descriptografia do KMS ao usuário RAM.
1. Crie uma política personalizada. Use o seguinte conteúdo de política:
  { "Version": "1", "Statement": [ { "Effect": "Allow", "Action": "KMS:Decrypt", "Resource": "*" } ] }
2. Anexe a política personalizada criada ao usuário RAM especificado. Para mais detalhes, consulte Gerencie permissões de usuário RAM.
Obter o endpoint da instância KMS.
- Por padrão, as chaves em uma instância KMS permitem acesso apenas a partir de redes VPC. Na página de gerenciamento de instâncias KMS, localize a instância KMS desejada, clique em Actions, depois em Details e visualize o endpoint VPC na aba Basic Information.
- Para acessar chaves pela rede pública, ative o acesso à rede pública e visualize o endpoint público. Para mais detalhes, consulte Ativar acesso à rede pública.
Obter credenciais de acesso.

Salve o AccessKey ID e o AccessKey secret ao criar o AccessKey para sua conta Alibaba Cloud ou usuário RAM. Para mais detalhes, consulte Crie um AccessKey.

Chave local

Quando o Encryption Method na configuração de criptografia de coluna do banco de dados estiver definido como Local Key, gere uma MEK. Exemplo: 00112233445566778899aabbccddeeff.

Os métodos comuns de geração incluem geradores de senhas ou funções aleatórias em linguagens de programação.

Exemplos:

No Linux, use a ferramenta OpenSSL integrada executando openssl rand -hex 16 para gerar uma chave.
No Windows, instale o pacote de software OpenSSL.

Instruções de integração do cliente

Importante

Use o 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 texto simples a partir de colunas criptografadas do banco de dados.

1. Instale dependências

Adicione a seguinte dependência ao arquivo de configuração do projeto Maven pom.xml.

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

2. Configure a MEK para conectar 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 mais de um método for configurado simultaneamente, a ordem de prioridade será: configuração de propriedades JDBC > configuração por arquivo > configuração por URL.

Nota

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 da MEK.

Escolha conectar-se ao banco de dados usando uma chave local ou uma chave KMS com base no Encryption method definido na configuração de criptografia de coluna do banco de dados.

Conectar ao banco de dados usando uma chave KMS

Importante

Se usar credenciais temporárias STS para recuperar uma MEK gerenciada pelo KMS, use 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 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

Incorpore 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 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

Importe parâmetros como a MEK necessária por meio de um arquivo de configuração.

Nota

A configuração por arquivo aplica-se apenas a MEKs de chave local.

Defina uma property chamada encJdbcConfigFile no projeto e defina seu valor como o caminho do arquivo de configuração (por padrão, o arquivo encjdbc.conf é utilizado). O conteúdo do arquivo de configuração é o seguinte:

MEK=00112233445566778899aabbccddeeff

Coloque o arquivo de configuração em um destes dois locais:

Insira o arquivo no diretório resources do projeto, conforme mostrado abaixo:
```
src
  main
    java
    resources
      encjdbc.conf
```
Insira o arquivo no diretório raiz do projeto (o diretório de tempo de execução do programa).

Após configurar o arquivo, nenhuma configuração adicional é necessária no 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

Incorpore 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");
}