Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funções de criptografia

View as MarkdownEdit this pageReport an issueSet up docs MCP

Estas funções implementam a criptografia e a descriptografia de dados com o algoritmo AES (Advanced Encryption Standard).

O tamanho da chave depende do modo de criptografia: 16, 24 e 32 bytes para os modos -128-, -196- e -256-, respectivamente.

O comprimento do vetor de inicialização é sempre de 16 bytes (os bytes que excederem 16 são ignorados).

HMAC

Introduzido em: v25.12.0

Calcula o HMAC (Código de Autenticação de Mensagem baseado em Hash) da mensagem fornecida usando o algoritmo de hash especificado e a chave secreta.

Algoritmos de hash compatíveis:

  • blake2b512
  • blake2s256
  • md4
  • md5
  • md5-sha1
  • mdc2
  • ripemd (aliases: RIPEMD160, ripemd)
  • ripemd160
  • rmd160 (aliases: RIPEMD160, rmd160)
  • sha1
  • sha224
  • sha256
  • sha3-224
  • sha3-256
  • sha3-384
  • sha3-512
  • sha384
  • sha512
  • sha512-224
  • sha512-256
  • shake128
  • shake256
  • sm3
  • ssl3-md5 (aliases: MD5, ssl3-md5)
  • ssl3-sha1 (aliases: SHA1, ssl3-sha1)
  • whirlpool

Sintaxe

HMAC(mode, message, key)

Argumentos

  • mode — Nome do algoritmo de hash (não diferencia maiúsculas de minúsculas). Compatível com: md5, sha1, sha224, sha256, sha384, sha512. String
  • message — Mensagem a ser autenticada. String
  • key — Chave secreta para HMAC. String

Valor retornado

Retorna uma string binária que contém o resumo HMAC. String

Exemplos

HMAC-SHA256 básico

SELECT hex(HMAC('sha256', 'The quick brown fox jumps over the lazy dog', 'secret_key'));
┌─hex(HMAC('sha256', 'The quick brown fox jumps over the lazy dog', [HIDDEN id: 1]))─┐
│ 31FD15FA0F61FD40DC09D919D4AA5B4141A0B27C1D51E74A6789A890AAAA187C                   │
└────────────────────────────────────────────────────────────────────────────────────┘

Diferentes algoritmos de hash

SELECT
    hex(HMAC('md5', 'message', 'key')) AS hmac_md5,
    hex(HMAC('sha1', 'message', 'key')) AS hmac_sha1,
    hex(HMAC('sha256', 'message', 'key')) AS hmac_sha256;
┌─hmac_md5─────────────────────────┬─hmac_sha1────────────────────────────────┬─hmac_sha256──────────────────────────────────────────────────────┐
│ 4E4748E62B463521F6775FBF921234B5 │ 2088DF74D5F2146B48146CAF4965377E9D0BE3A4 │ 6E9EF29B75FFFC5B7ABAE527D58FDADB2FE42E7219011976917343065F58ED4A │
└──────────────────────────────────┴──────────────────────────────────────────┴──────────────────────────────────────────────────────────────────┘

Modo não sensível a maiúsculas e minúsculas

SELECT
    hmac('SHA256', 'message', 'key') = HMAC('sha256', 'message', 'key') AS same_result,
    HMAC('SHA256', 'message', 'key') = Hmac('Sha256', 'message', 'key') AS also_same;
┌─same_result─┬─also_same─┐
│           1 │         1 │
└─────────────┴───────────┘

aes_decrypt_mysql

Introduzido em: v20.12.0

Descriptografa dados criptografados pela função AES_ENCRYPT do MySQL.

Produz o mesmo texto em claro que decrypt para as mesmas entradas. Quando key ou iv são maiores do que deveriam ser, aes_decrypt_mysql seguirá o comportamento de aes_decrypt do MySQL: dobrar key e ignorar os bits excedentes de IV.

Compatível com os seguintes modos de descriptografia:

  • aes-128-ecb, aes-192-ecb, aes-256-ecb
  • aes-128-cbc, aes-192-cbc, aes-256-cbc
  • aes-128-cfb128
  • aes-128-ofb, aes-192-ofb, aes-256-ofb

Sintaxe

aes_decrypt_mysql(mode, ciphertext, key[, iv])

Argumentos

  • mode — Modo de descriptografia. String
  • ciphertext — Texto cifrado que precisa ser descriptografado. String
  • key — Chave de descriptografia. String
  • iv — Opcional. Vetor de inicialização. String

Valor retornado

Retorna a String descriptografada. String

Exemplos

Descriptografar dados do MySQL

-- Let's decrypt data we've previously encrypted with MySQL:
-- mysql> SET  block_encryption_mode='aes-256-ofb';
-- Query OK, 0 rows affected (0.00 sec)
--
-- mysql> SELECT aes_encrypt('Secret', '123456789101213141516171819202122', 'iviviviviviviviv123456') as ciphertext;
-- +------------------------+
-- | ciphertext             |
-- +------------------------+
-- | 0x24E9E4966469         |
-- +------------------------+
-- 1 row in set (0.00 sec)

SELECT aes_decrypt_mysql('aes-256-ofb', unhex('24E9E4966469'), '123456789101213141516171819202122', 'iviviviviviviviv123456') AS plaintext
┌─plaintext─┐
│ Secret    │
└───────────┘

aes_encrypt_mysql

Introduzido em: v20.12.0

Criptografa texto da mesma forma que a função AES_ENCRYPT do MySQL. O texto cifrado resultante pode ser descriptografado com a função AES_DECRYPT do MySQL. Produz o mesmo texto cifrado que a função encrypt para as mesmas entradas. Quando key ou iv forem maiores do que o normal, aes_encrypt_mysql seguirá o comportamento do aes_encrypt do MySQL: “dobrar” key e ignorar os bits excedentes de iv.

Os modos de criptografia compatíveis são:

  • aes-128-ecb, aes-192-ecb, aes-256-ecb
  • aes-128-cbc, aes-192-cbc, aes-256-cbc
  • aes-128-ofb, aes-192-ofb, aes-256-ofb

Sintaxe

aes_encrypt_mysql(mode, plaintext, key[, iv])

Argumentos

  • mode — Modo de criptografia. String
  • plaintext — Texto que deve ser criptografado. String
  • key — Chave de criptografia. Se a chave for maior do que o exigido por mode, é aplicado o key folding específico do MySQL. String
  • iv — Opcional. Vetor de inicialização. Apenas os 16 primeiros bytes são considerados. String

Valor retornado

String binária contendo o texto cifrado. String

Exemplos

Comparação de entradas iguais

-- Com o mesmo input, encrypt e aes_encrypt_mysql produzem o mesmo ciphertext:
SELECT encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv') = aes_encrypt_mysql('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv') AS ciphertexts_equal;
┌─ciphertexts_equal─┐
│                 1 │
└───────────────────┘

Falha na criptografia com chave longa

-- Mas encrypt falha quando key ou iv é maior que o esperado:
SELECT encrypt('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123');
Received exception from server (version 22.6.1):
Code: 36. DB::Exception: Received from localhost:9000. DB::Exception: Invalid key size: 33 expected 32: While processing encrypt('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123').

Compatibilidade com MySQL

-- aes_encrypt_mysql produz saída compatível com MySQL:
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123')) AS ciphertext;
┌─ciphertext───┐
│ 24E9E4966469 │
└──────────────┘

Um IV mais longo gera o mesmo resultado

-- Observe como fornecer um IV ainda mais longo produz o mesmo resultado
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123456')) AS ciphertext
┌─ciphertext───┐
│ 24E9E4966469 │
└──────────────┘

decrypt

Introduzido em: v20.12.0

Esta função descriptografa uma string binária criptografada com AES usando os seguintes modos:

  • aes-128-ecb, aes-192-ecb, aes-256-ecb
  • aes-128-cbc, aes-192-cbc, aes-256-cbc
  • aes-128-ofb, aes-192-ofb, aes-256-ofb
  • aes-128-gcm, aes-192-gcm, aes-256-gcm
  • aes-128-ctr, aes-192-ctr, aes-256-ctr
  • aes-128-cfb, aes-128-cfb1, aes-128-cfb8

Sintaxe

decrypt(mode, ciphertext, key[, iv, aad])

Argumentos

  • mode — Modo de descriptografia. String
  • ciphertext — Texto cifrado que deve ser descriptografado. String
  • key — Chave de descriptografia. String
  • iv — Vetor de inicialização. Obrigatório para os modos -gcm, opcional para os demais. String
  • aad — Dados autenticados adicionais. A descriptografia falhará se esse valor estiver incorreto. Funciona apenas nos modos -gcm; nos demais, lança uma exceção. String

Valor retornado

Retorna o texto em claro descriptografado. String

Exemplos

Descriptografando corretamente dados criptografados

CREATE TABLE encryption_test
(
    `comment` String,
    `secret` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO encryption_test VALUES
('aes-256-ofb no IV', encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212')),
('aes-256-ofb no IV, different key', encrypt('aes-256-ofb', 'Secret', 'keykeykeykeykeykeykeykeykeykeyke')),
('aes-256-ofb with IV', encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv')),
('aes-256-cbc no IV', encrypt('aes-256-cbc', 'Secret', '12345678910121314151617181920212'));

SELECT comment, hex(secret) FROM encryption_test;
┌─comment──────────────────────────┬─hex(secret)──────────────────────┐
│ aes-256-ofb no IV                │ B4972BDC4459                     │
│ aes-256-ofb no IV, different key │ 2FF57C092DC9                     │
│ aes-256-ofb with IV              │ 5E6CB398F653                     │
│ aes-256-cbc no IV                │ 1BC0629A92450D9E73A00E7D02CF4142 │
└──────────────────────────────────┴──────────────────────────────────┘

Descriptografia incorreta de dados criptografados

SELECT comment, hex(decrypt('aes-256-cfb8', secret, '12345678910121314151617181920212')) AS plaintext FROM encryption_test
aes-256-ofb no IV	53A69A28E815
aes-256-ofb no IV, different key	C86BD2404D8A
aes-256-ofb with IV	B9658159142A
aes-256-cbc no IV	FC552E5096F1455997B2732FB31DCFEB

encrypt

Introduzido em: v20.12.0

Criptografa texto em claro em texto cifrado com AES em um dos seguintes modos:

  • aes-128-ecb, aes-192-ecb, aes-256-ecb
  • aes-128-cbc, aes-192-cbc, aes-256-cbc
  • aes-128-ofb, aes-192-ofb, aes-256-ofb
  • aes-128-gcm, aes-192-gcm, aes-256-gcm
  • aes-128-ctr, aes-192-ctr, aes-256-ctr
  • aes-128-cfb, aes-128-cfb1, aes-128-cfb8

Sintaxe

encrypt(mode, plaintext, key[, iv, aad])

Argumentos

  • mode — Modo de criptografia. String
  • plaintext — Texto que deve ser criptografado. String
  • key — Chave de criptografia. String
  • iv — Vetor de inicialização. Obrigatório para modos -gcm e opcional para os demais. String
  • aad — Dados autenticados adicionais. Não são criptografados, mas afetam a descriptografia. Funciona apenas em modos -gcm; nos demais, lança uma exceção. String

Valor retornado

Retorna o texto cifrado como uma string binária. String

Exemplos

Exemplo de criptografia

CREATE TABLE encryption_test
(
    `comment` String,
    `secret` String
)
ENGINE = MergeTree;

INSERT INTO encryption_test VALUES
('aes-256-ofb no IV', encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212')),
('aes-256-ofb no IV, different key', encrypt('aes-256-ofb', 'Secret', 'keykeykeykeykeykeykeykeykeykeyke')),
('aes-256-ofb with IV', encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv')),
('aes-256-cbc no IV', encrypt('aes-256-cbc', 'Secret', '12345678910121314151617181920212'));

SELECT comment, hex(secret) FROM encryption_test;
┌─comment──────────────────────────┬─hex(secret)──────────────────────┐
│ aes-256-ofb no IV                │ B4972BDC4459                     │
│ aes-256-ofb no IV, different key │ 2FF57C092DC9                     │
│ aes-256-ofb with IV              │ 5E6CB398F653                     │
│ aes-256-cbc no IV                │ 1BC0629A92450D9E73A00E7D02CF4142 │
└──────────────────────────────────┴──────────────────────────────────┘

Exemplo no modo GCM

INSERT INTO encryption_test VALUES
('aes-256-gcm', encrypt('aes-256-gcm', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv')),

('aes-256-gcm with AAD', encrypt('aes-256-gcm', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv', 'aad'));

SELECT comment, hex(secret) FROM encryption_test WHERE comment LIKE '%gcm%';
┌─comment──────────────┬─hex(secret)──────────────────────────────────┐
│ aes-256-gcm          │ A8A3CCBC6426CFEEB60E4EAE03D3E94204C1B09E0254 │
│ aes-256-gcm with AAD │ A8A3CCBC6426D9A1017A0A932322F1852260A4AD6837 │
└──────────────────────┴──────────────────────────────────────────────┘

tryDecrypt

Introduzido em: v22.10.0

Semelhante à função decrypt, mas retorna NULL se a descriptografia falhar ao usar a chave incorreta.

Sintaxe

tryDecrypt(mode, ciphertext, key[, iv, aad])

Argumentos

  • mode — Modo de descriptografia. String
  • ciphertext — Texto cifrado que deve ser descriptografado. String
  • key — Chave de descriptografia. String
  • iv — Opcional. Vetor de inicialização. Obrigatório para modos -gcm e opcional para os demais. String
  • aad — Opcional. Dados autenticados adicionais. A descriptografia não funcionará se esse valor estiver incorreto. Funciona apenas em modos -gcm; nos outros modos, lança uma exceção. String

Valor retornado

Retorna a String descriptografada ou NULL se a descriptografia falhar. Nullable(String)

Exemplos

Criar tabela e inserir dados

-- Vamos criar uma tabela onde user_id é o identificador único do usuário, encrypted é um campo de string criptografado e iv é o vetor inicial para descriptografar/criptografar.
-- Assume-se que os usuários conhecem seu id e a chave para descriptografar o campo encrypted:
CREATE TABLE decrypt_null
(
    dt DateTime,
    user_id UInt32,
    encrypted String,
    iv String
)
ENGINE = MergeTree;

-- Inserir alguns dados:
INSERT INTO decrypt_null VALUES
('2022-08-02 00:00:00', 1, encrypt('aes-256-gcm', 'value1', 'keykeykeykeykeykeykeykeykeykey01', 'iv1'), 'iv1'),
('2022-09-02 00:00:00', 2, encrypt('aes-256-gcm', 'value2', 'keykeykeykeykeykeykeykeykeykey02', 'iv2'), 'iv2'),
('2022-09-02 00:00:01', 3, encrypt('aes-256-gcm', 'value3', 'keykeykeykeykeykeykeykeykeykey03', 'iv3'), 'iv3');

-- Tentar descriptografar com uma chave
SELECT
    dt,
    user_id,
    tryDecrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) AS value
FROM decrypt_null
ORDER BY user_id ASC
┌──────────────────dt─┬─user_id─┬─value──┐
│ 2022-08-02 00:00:00 │       1 │ ᴺᵁᴸᴸ   │
│ 2022-09-02 00:00:00 │       2 │ value2 │
│ 2022-09-02 00:00:01 │       3 │ ᴺᵁᴸᴸ   │
└─────────────────────┴─────────┴────────┘
Navigation