Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Fonctions de chiffrement

View as MarkdownEdit this pageReport an issueSet up docs MCP

Ces fonctions assurent le chiffrement et le déchiffrement des données à l’aide de l’algorithme AES (Advanced Encryption Standard).

La longueur de la clé dépend du mode de chiffrement : 16, 24 et 32 octets pour les modes -128-, -196- et -256-, respectivement.

La longueur du vecteur d’initialisation est toujours de 16 octets (les octets au-delà de 16 sont ignorés).

HMAC

Introduit dans : v25.12.0

Calcule le HMAC (code d'authentification de message basé sur une fonction de hachage) du message donné à l'aide de l'algorithme de hachage spécifié et de la clé secrète.

Algorithmes de hachage pris en charge :

  • 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

Syntaxe

HMAC(mode, message, key)

Arguments

  • mode — Nom de l’algorithme de hachage (insensible à la casse). Pris en charge : md5, sha1, sha224, sha256, sha384, sha512. String
  • message — Message à authentifier. String
  • key — Clé secrète pour HMAC. String

Valeur renvoyée

Renvoie une chaîne binaire contenant l’empreinte HMAC. String

Exemples

HMAC-SHA256 basique

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

Différents algorithmes de hachage

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

Mode insensible à la casse

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

Introduit dans : v20.12.0

Déchiffre des données chiffrées par la fonction AES_ENCRYPT de MySQL.

Produit le même texte en clair que decrypt pour les mêmes entrées. Lorsque key ou iv sont plus longs que la normale, aes_decrypt_mysql s’aligne sur le comportement de aes_decrypt dans MySQL : il « replie » key et ignore les bits excédentaires de IV.

Prend en charge les modes de déchiffrement suivants :

  • 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

Syntaxe

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

Arguments

  • mode — Mode de déchiffrement. String
  • ciphertext — Texte chiffré à déchiffrer. String
  • key — Clé de déchiffrement. String
  • iv — Facultatif. Vecteur d'initialisation. String

Valeur renvoyée

Renvoie la chaîne déchiffrée. String

Exemples

Déchiffrer des données 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

Introduit dans : v20.12.0

Chiffre le texte de la même façon que la fonction AES_ENCRYPT de MySQL. Le texte chiffré obtenu peut être déchiffré avec la fonction AES_DECRYPT de MySQL. Produit le même texte chiffré que la fonction encrypt pour les mêmes entrées. Lorsque key ou iv sont plus longs que prévu, aes_encrypt_mysql reproduit le comportement de aes_encrypt de MySQL : il « replie » key et ignore les bits excédentaires de iv.

Les modes de chiffrement pris en charge sont :

  • 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

Syntaxe

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

Arguments

  • mode — Mode de chiffrement. String
  • plaintext — Texte en clair à chiffrer. String
  • key — Clé de chiffrement. Si la clé est plus longue que nécessaire pour mode, un repliement de clé spécifique à MySQL est appliqué. String
  • iv — Facultatif. Vecteur d’initialisation. Seuls les 16 premiers octets sont pris en compte. String

Valeur renvoyée

Chaîne binaire chiffrée. String

Exemples

Comparaison d’entrées identiques

-- Given equal input encrypt and aes_encrypt_mysql produce the same ciphertext:
SELECT encrypt('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv') = aes_encrypt_mysql('aes-256-ofb', 'Secret', '12345678910121314151617181920212', 'iviviviviviviviv') AS ciphertexts_equal;
┌─ciphertexts_equal─┐
│                 1 │
└───────────────────┘

Le chiffrement échoue avec une clé trop longue

-- But encrypt fails when key or iv is longer than expected:
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').

Compatibilité MySQL

-- aes_encrypt_mysql produces MySQL-compatible output:
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123')) AS ciphertext;
┌─ciphertext───┐
│ 24E9E4966469 │
└──────────────┘

Un IV plus long donne le même résultat

-- Notice how supplying even longer IV produces the same result
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123456')) AS ciphertext
┌─ciphertext───┐
│ 24E9E4966469 │
└──────────────┘

decrypt

Introduit dans : v20.12.0

Cette fonction déchiffre une chaîne binaire chiffrée en AES à l’aide des modes suivants :

  • 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

Syntaxe

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

Arguments

  • mode — Mode de déchiffrement. String
  • ciphertext — Texte chiffré à déchiffrer. String
  • key — Clé de déchiffrement. String
  • iv — Vecteur d’initialisation. Obligatoire pour les modes -gcm, facultatif pour les autres. String
  • aad — Données authentifiées supplémentaires. Le déchiffrement échoue si cette valeur est incorrecte. Fonctionne uniquement avec les modes -gcm ; pour les autres, provoque une exception. String

Valeur renvoyée

Renvoie le texte en clair. String

Exemples

Déchiffrement correct de données chiffrées

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

Déchiffrement erroné de données chiffrées

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

Introduit dans : v20.12.0

Chiffre le texte en clair en texte chiffré à l’aide d’AES dans l’un des modes suivants :

  • 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

Syntaxe

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

Arguments

  • mode — Mode de chiffrement. String
  • plaintext — Texte en clair à chiffrer. String
  • key — Clé de chiffrement. String
  • iv — Vecteur d’initialisation. Obligatoire pour les modes -gcm, facultatif pour les autres. String
  • aad — Données authentifiées supplémentaires. Elles ne sont pas chiffrées, mais elles influent sur le déchiffrement. Ne fonctionne qu’avec les modes -gcm ; pour les autres, une exception est levée. String

Valeur renvoyée

Renvoie le texte chiffré sous forme de chaîne binaire. String

Exemples

Exemple de chiffrement

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

Exemple en mode 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

Introduit dans : v22.10.0

Similaire à la fonction decrypt, mais renvoie NULL si le déchiffrement échoue en cas d’utilisation d’une clé incorrecte.

Syntaxe

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

Arguments

  • mode — Mode de déchiffrement. String
  • ciphertext — Texte chiffré à déchiffrer. String
  • key — Clé de déchiffrement. String
  • iv — Facultatif. Vecteur d’initialisation. Obligatoire pour les modes -gcm, facultatif pour les autres modes. String
  • aad — Facultatif. Données authentifiées supplémentaires. Le déchiffrement échoue si cette valeur est incorrecte. Fonctionne uniquement avec les modes -gcm ; pour les autres modes, génère une exception. String

Valeur renvoyée

Renvoie la chaîne déchiffrée, ou NULL si le déchiffrement échoue. Nullable(String)

Exemples

Créer une table et insérer des données

-- Let's create a table where user_id is the unique user id, encrypted is an encrypted string field, iv is an initial vector for decrypt/encrypt.
-- Assume that users know their id and the key to decrypt the encrypted field:
CREATE TABLE decrypt_null
(
    dt DateTime,
    user_id UInt32,
    encrypted String,
    iv String
)
ENGINE = MergeTree;

-- Insert some data:
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');

-- Try decrypt with one key
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