diff --git a/docs/en/sql-reference/functions/encryption-functions.md b/docs/en/sql-reference/functions/encryption-functions.md index 642c8643c16..a7e82e94d2c 100644 --- a/docs/en/sql-reference/functions/encryption-functions.md +++ b/docs/en/sql-reference/functions/encryption-functions.md @@ -294,6 +294,74 @@ Result: Notice how only a portion of the data was properly decrypted, and the rest is gibberish since either `mode`, `key`, or `iv` were different upon encryption. +## tryDecrypt + +Similar to `decrypt`, but returns NULL if decryption fail because of using wrong key. + +**Examples** + +Let's create a table with `user_id` is unique user id, `encrypted` is an encrypted string field, `iv` is intitial vector for decrypt/encrypt. Assume that users know their id and the key to decrypt the encrypted field: + +```sql +CREATE TABLE decrypt_null ( + dt DateTime, + user_id UInt32, + encrypted String, + iv String +) ENGINE = Memory; +``` + +Insert some data: + +```sql +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'); +``` + +Query with `decrypt`: + +```sql +SELECT + dt, + user_id, + decrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) AS value +FROM decrypt_null +ORDER BY user_id ASC +``` + +Result: + +``` +0 rows in set. Elapsed: 0.329 sec. + +Received exception from server (version 22.10.1): +Code: 454. DB::Exception: Received from localhost:24071. DB::Exception: Failed to decrypt. OpenSSL error code: 0: while executing 'FUNCTION decrypt('aes-256-gcm' :: 4, encrypted :: 2, 'keykeykeykeykeykeykeykeykeykey02' :: 5, iv :: 3) -> decrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) String : 6'. (OPENSSL_ERROR) + +``` + +Query with `tryDecrypt`: + +```sql +SELECT + dt, + user_id, + tryDecrypt('aes-256-gcm', encrypted, 'keykeykeykeykeykeykeykeykeykey02', iv) AS value +FROM decrypt_null +ORDER BY user_id ASC +``` + +Result: + +``` +┌──────────────────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 │ ᴺᵁᴸᴸ │ +└─────────────────────┴─────────┴────────┘ +``` + ## aes_decrypt_mysql Compatible with mysql encryption and decrypts data encrypted with [AES_ENCRYPT](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_aes-encrypt) function.