Funciones de cifrado - ClickHouse Documentation

Estas funciones implementan el cifrado y descifrado de datos mediante el algoritmo AES (Estándar de Cifrado Avanzado). La longitud de la clave depende del modo de cifrado: 16, 24 y 32 bytes de longitud para los modos -128-, -196- y -256-, respectivamente. La longitud del vector de inicialización es siempre de 16 bytes (se ignoran los bytes que excedan los 16).

HMAC

Introducido en: v25.12.0 Calcula el HMAC (código de autenticación de mensajes basado en hash) para el mensaje dado mediante el algoritmo hash especificado y la clave secreta. Algoritmos hash compatibles:

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

Sintaxis

HMAC(mode, message, key)

Argumentos

mode — Nombre del algoritmo hash (sin distinción entre mayúsculas y minúsculas). Admitidos: md5, sha1, sha224, sha256, sha384, sha512. String
message — Mensaje que se va a autenticar. String
key — Clave secreta para HMAC. String

Valor devuelto Devuelve una cadena binaria que contiene el resumen HMAC. String Ejemplos HMAC-SHA256 básico

Query

SELECT hex(HMAC('sha256', 'The quick brown fox jumps over the lazy dog', 'secret_key'));

Response

┌─hex(HMAC('sha256', 'The quick brown fox jumps over the lazy dog', 'secret_key'))─┐
│ 31FD15FA0F61FD40DC09D919D4AA5B4141A0B27C1D51E74A6789A890AAAA187C                 │
└──────────────────────────────────────────────────────────────────────────────────┘

Diferentes algoritmos de hash

Query

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;

Response

┌─hmac_md5─────────────────────────┬─hmac_sha1────────────────────────────────┬─hmac_sha256──────────────────────────────────────────────────────┐
│ 4E4748E62B463521F6775FBF921234B5 │ 2088DF74D5F2146B48146CAF4965377E9D0BE3A4 │ 6E9EF29B75FFFC5B7ABAE527D58FDADB2FE42E7219011976917343065F58ED4A │
└──────────────────────────────────┴──────────────────────────────────────────┴──────────────────────────────────────────────────────────────────┘

Modo sin distinción entre mayúsculas y minúsculas

Query

SELECT
    hmac('SHA256', 'message', 'key') = HMAC('sha256', 'message', 'key') AS same_result,
    HMAC('SHA256', 'message', 'key') = Hmac('Sha256', 'message', 'key') AS also_same;

Response

┌─same_result─┬─also_same─┐
│           1 │         1 │
└─────────────┴───────────┘

aes_decrypt_mysql

Introducido en: v20.12.0 Descifra datos cifrados por la función AES_ENCRYPT de MySQL. Produce el mismo texto plano que decrypt con los mismos argumentos. Cuando key o iv son más largos de lo que normalmente deberían ser, aes_decrypt_mysql seguirá el comportamiento de aes_decrypt de MySQL: “plegar” key e ignorar los bits sobrantes de IV. Admite los siguientes modos de descifrado:

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

Sintaxis

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

Argumentos

mode — Modo de descifrado. String
ciphertext — Texto cifrado que debe descifrarse. String
key — Clave de descifrado. String
iv — Opcional. Vector de inicialización. String

Valor devuelto Devuelve una String descifrada. String Ejemplos Descifrar datos de MySQL

Query

-- Descifremos los datos que hemos cifrado previamente con 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

Response

┌─plaintext─┐
│ Secret    │
└───────────┘

aes_encrypt_mysql

Introducido en: v20.12.0 Cifra el texto de la misma manera que la función AES_ENCRYPT de MySQL. El texto cifrado resultante puede descifrarse con la función AES_DECRYPT de MySQL. Produce el mismo texto cifrado que la función encrypt con las mismas entradas. Cuando key o iv son más largos de lo habitual, aes_encrypt_mysql sigue el comportamiento de aes_encrypt de MySQL: ‘pliega’ key e ignora los bits sobrantes de iv. Los modos de cifrado compatibles son:

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

Sintaxis

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

Argumentos

mode — Modo de cifrado. String
plaintext — Texto que se debe cifrar. String
key — Clave de cifrado. Si la clave es más larga de lo que requiere mode, se aplica el plegado de claves específico de MySQL. String
iv — Opcional. Vector de inicialización. Solo se tienen en cuenta los primeros 16 bytes. String

Valor devuelto Cadena binaria de texto cifrado. String Ejemplos Comparación de entradas idénticas

Query

-- Con la misma entrada, encrypt y aes_encrypt_mysql producen el mismo texto cifrado:
SELECT encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv') = aes_encrypt_mysql('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv') AS ciphertexts_equal;

Response

┌─ciphertexts_equal─┐
│                 1 │
└───────────────────┘

El cifrado falla con una clave larga

Query

-- Pero encrypt falla cuando key o iv son más largos de lo esperado:
SELECT encrypt('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123');

Response

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').

Compatibilidad con MySQL

Query

-- aes_encrypt_mysql produce una salida compatible con MySQL:
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123')) AS ciphertext;

Response

┌─ciphertext───┐
│ 24E9E4966469 │
└──────────────┘

Un IV más largo da el mismo resultado

Query

-- Observe cómo proporcionar un IV aún más largo produce el mismo resultado
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123456')) AS ciphertext

Response

┌─ciphertext───┐
│ 24E9E4966469 │
└──────────────┘

decrypt

Introducido en: v20.12.0 Esta función descifra una cadena binaria cifrada con AES mediante los siguientes 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

Sintaxis

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

Argumentos

mode — Modo de descifrado. String
ciphertext — Texto cifrado que debe descifrarse. String
key — Clave de descifrado. String
iv — Vector de inicialización. Obligatorio para los modos -gcm y opcional para los demás. String
aad — Datos autenticados adicionales. No se descifrará si este valor es incorrecto. Solo funciona en los modos -gcm; en los demás, lanza una excepción. String

Valor devuelto Devuelve el texto plano descifrado. String Ejemplos Descifrado correcto de datos cifrados

Query

-- Reutilizando la tabla del ejemplo de la función encrypt
SELECT comment, hex(secret) FROM encryption_test;

Response

┌─comment──────────────┬─hex(secret)──────────────────────────────────┐
│ aes-256-gcm          │ A8A3CCBC6426CFEEB60E4EAE03D3E94204C1B09E0254 │
│ aes-256-gcm with AAD │ A8A3CCBC6426D9A1017A0A932322F1852260A4AD6837 │
└──────────────────────┴──────────────────────────────────────────────┘
┌─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 │
└──────────────────────────────────┴──────────────────────────────────┘

Descifrado incorrecto de datos cifrados

Query

SELECT comment, decrypt('aes-256-cfb128', secret, '12345678910121314151617181920212') AS plaintext FROM encryption_test

Response

-- Observe cómo solo una parte de los datos fue descifrada correctamente, y el resto es texto ilegible, ya que `mode`, `key` o `iv` eran distintos durante el cifrado.
┌─comment──────────────┬─plaintext──┐
│ aes-256-gcm          │ OQ�E
                             �t�7T�\\���\\�   │
│ aes-256-gcm with AAD │ OQ�E
                             �\\��si����;�o�� │
└──────────────────────┴────────────┘
┌─comment──────────────────────────┬─plaintext─┐
│ aes-256-ofb no IV                │ Secret    │
│ aes-256-ofb no IV, different key │ �4�
                                        �         │
│ aes-256-ofb with IV              │ ���6�~        │
│aes-256-cbc no IV                │ �2*4�h3c�4w��@
└──────────────────────────────────┴───────────┘

encrypt

Introducido en: v20.12.0 Cifra texto plano y lo convierte en texto cifrado mediante AES en uno de los siguientes 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

Sintaxis

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

Argumentos

mode — Modo de cifrado. String
plaintext — Texto que debe cifrarse. String
key — Clave de cifrado. String
iv — Vector de inicialización. Obligatorio para los modos -gcm; opcional para los demás. String
aad — Datos autenticados adicionales. No se cifran, pero afectan al descifrado. Solo funcionan en los modos -gcm; en los demás, lanza una excepción. String

Valor devuelto Devuelve el texto cifrado como una cadena binaria. String Ejemplos Ejemplo de cifrado

Query

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;

Response

┌─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 │
└──────────────────────────────────┴──────────────────────────────────┘

Ejemplo con el modo GCM

Query

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%';

Response

┌─comment──────────────┬─hex(secret)──────────────────────────────────┐
│ aes-256-gcm          │ A8A3CCBC6426CFEEB60E4EAE03D3E94204C1B09E0254 │
│ aes-256-gcm with AAD │ A8A3CCBC6426D9A1017A0A932322F1852260A4AD6837 │
└──────────────────────┴──────────────────────────────────────────────┘

tryDecrypt

Introducido en: v22.10.0 Similar a la función decrypt, pero devuelve NULL si el descifrado falla al usar una clave incorrecta. Sintaxis

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

Argumentos

mode — Modo de descifrado. String
ciphertext — Texto cifrado que se debe descifrar. String
key — Clave de descifrado. String
iv — Opcional. Vector de inicialización. Obligatorio para los modos -gcm; opcional para otros modos. String
aad — Opcional. Datos autenticados adicionales. No se podrá descifrar si este valor es incorrecto. Funciona solo en los modos -gcm; en otros modos, lanza una excepción. String

Valor devuelto Devuelve la cadena descifrada o NULL si el descifrado falla. Nullable(String) Ejemplos Crear tabla e insertar datos

Query

-- Creemos una tabla donde user_id es el identificador único del usuario, encrypted es un campo de cadena cifrada e iv es un vector inicial para descifrar/cifrar.
-- Se asume que los usuarios conocen su id y la clave para descifrar el campo cifrado:
CREATE TABLE decrypt_null
(
    dt DateTime,
    user_id UInt32,
    encrypted String,
    iv String
)
ENGINE = MergeTree;

-- Insertar algunos datos:
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');

-- Intentar descifrar con una clave
SELECT
    dt,
    user_id,
    tryDecrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) AS value
FROM decrypt_null
ORDER BY user_id ASC

Response

┌──────────────────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 │ ᴺᵁᴸᴸ   │
└─────────────────────┴─────────┴────────┘

​HMAC

​aes_decrypt_mysql

​aes_encrypt_mysql

​decrypt

​encrypt

​tryDecrypt

HMAC

aes_decrypt_mysql

aes_encrypt_mysql

decrypt

encrypt

tryDecrypt