mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-07 16:14:52 +00:00

DOCSUP-3845: documented new encrypt and decrypt functions (#16930 )

* Added first draft of description

* Added toc_priority

* Updated description

* Updated documentation

* Added examples

* Fixed links

* variable fixes

* minor fixes

* added translation

* fixed typos in translation

* changed toc_title in translation

* minor change

* added various fixes

* fixed typos

* Deleted unnecessary file

* Deleted extra files

Co-authored-by: George <gyuton@yandex-team.ru>

2020-11-17 17:05:33 +03:00

14 KiB

Raw Blame History

toc_priority	toc_title
67	Encryption

Encryption functions

These functions implement encryption and decryption of data with AES (Advanced Encryption Standard) algorithm.

Key length depends on encryption mode. It is 16, 24, and 32 bytes long for -128-, -196-, and -256- modes respectively.

Initialization vector length is always 16 bytes (bytes in excess of 16 are ignored).

Note that these functions work slowly.

encrypt

This function encrypts data using these modes:

aes-128-ecb, aes-192-ecb, aes-256-ecb
aes-128-cbc, aes-192-cbc, aes-256-cbc
aes-128-cfb1, aes-192-cfb1, aes-256-cfb1
aes-128-cfb8, aes-192-cfb8, aes-256-cfb8
aes-128-cfb128, aes-192-cfb128, aes-256-cfb128
aes-128-ofb, aes-192-ofb, aes-256-ofb
aes-128-gcm, aes-192-gcm, aes-256-gcm

Syntax

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

Parameters

mode — Encryption mode. String.
plaintext — Text thats need to be encrypted. String.
key — Encryption key. String.
iv — Initialization vector. Required for -gcm modes, optinal for others. String.
aad — Additional authenticated data. It isn't encrypted, but it affects decryption. Works only in -gcm modes, for others would throw an exception. String.

Returned value

Ciphered String. String.

Examples

Create this table:

Query:

CREATE TABLE encryption_test
(
    input String,
    key String DEFAULT unhex('fb9958e2e897ef3fdb49067b51a24af645b3626eed2f9ea1dc7fd4dd71b7e38f9a68db2a3184f952382c783785f9d77bf923577108a88adaacae5c141b1576b0'),
    iv String DEFAULT unhex('8CA3554377DFF8A369BC50A89780DD85'),
    key32 String DEFAULT substring(key, 1, 32),
    key24 String DEFAULT substring(key, 1, 24),
    key16 String DEFAULT substring(key, 1, 16)
) Engine = Memory;

Insert this data:

Query:

INSERT INTO encryption_test (input) VALUES (''), ('text'), ('What Is ClickHouse?');

Example without iv:

Query:

SELECT 'aes-128-ecb' AS mode, hex(encrypt(mode, input, key16)) FROM encryption_test;

Result:

┌─mode────────┬─hex(encrypt('aes-128-ecb', input, key16))────────────────────────┐
│ aes-128-ecb │ 4603E6862B0D94BBEC68E0B0DF51D60F                                 │
│ aes-128-ecb │ 3004851B86D3F3950672DE7085D27C03                                 │
│ aes-128-ecb │ E807F8C8D40A11F65076361AFC7D8B68D8658C5FAA6457985CAA380F16B3F7E4 │
└─────────────┴──────────────────────────────────────────────────────────────────┘

Example with iv:

Query:

SELECT 'aes-256-ctr' AS mode, hex(encrypt(mode, input, key32, iv)) FROM encryption_test;

Result:

┌─mode────────┬─hex(encrypt('aes-256-ctr', input, key32, iv))─┐
│ aes-256-ctr │                                               │
│ aes-256-ctr │ 7FB039F7                                      │
│ aes-256-ctr │ 5CBD20F7ABD3AC41FCAA1A5C0E119E2B325949        │
└─────────────┴───────────────────────────────────────────────┘

Example with -gcm:

Query:

SELECT 'aes-256-gcm' AS mode, hex(encrypt(mode, input, key32, iv)) FROM encryption_test;

Result:

┌─mode────────┬─hex(encrypt('aes-256-gcm', input, key32, iv))──────────────────────────┐
│ aes-256-gcm │ E99DBEBC01F021758352D7FBD9039EFA                                       │
│ aes-256-gcm │ 8742CE3A7B0595B281C712600D274CA881F47414                               │
│ aes-256-gcm │ A44FD73ACEB1A64BDE2D03808A2576EDBB60764CC6982DB9AF2C33C893D91B00C60DC5 │
└─────────────┴────────────────────────────────────────────────────────────────────────┘

Example with -gcm mode and with aad:

Query:

SELECT 'aes-192-gcm' AS mode, hex(encrypt(mode, input, key24, iv, 'AAD')) FROM encryption_test;

Result:

┌─mode────────┬─hex(encrypt('aes-192-gcm', input, key24, iv, 'AAD'))───────────────────┐
│ aes-192-gcm │ 04C13E4B1D62481ED22B3644595CB5DB                                       │
│ aes-192-gcm │ 9A6CF0FD2B329B04EAD18301818F016DF8F77447                               │
│ aes-192-gcm │ B961E9FD9B940EBAD7ADDA75C9F198A40797A5EA1722D542890CC976E21113BBB8A7AA │
└─────────────┴────────────────────────────────────────────────────────────────────────┘

aes_encrypt_mysql

Compatible with mysql encryption and can be decrypted with AES_DECRYPT function.

Supported encryption modes:

aes-128-ecb, aes-192-ecb, aes-256-ecb
aes-128-cbc, aes-192-cbc, aes-256-cbc
aes-128-cfb1, aes-192-cfb1, aes-256-cfb1
aes-128-cfb8, aes-192-cfb8, aes-256-cfb8
aes-128-cfb128, aes-192-cfb128, aes-256-cfb128
aes-128-ofb, aes-192-ofb, aes-256-ofb

Syntax

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

Parameters

mode — Encryption mode. String.
plaintext — Text that needs to be encrypted. String.
key — Encryption key. String.
iv — Initialization vector. Optinal. String.

Returned value

Ciphered String. String.

Examples

Create this table:

Query:

CREATE TABLE encryption_test
(
    input String,
    key String DEFAULT unhex('fb9958e2e897ef3fdb49067b51a24af645b3626eed2f9ea1dc7fd4dd71b7e38f9a68db2a3184f952382c783785f9d77bf923577108a88adaacae5c141b1576b0'),
    iv String DEFAULT unhex('8CA3554377DFF8A369BC50A89780DD85'),
    key32 String DEFAULT substring(key, 1, 32),
    key24 String DEFAULT substring(key, 1, 24),
    key16 String DEFAULT substring(key, 1, 16)
) Engine = Memory;

Insert this data:

Query:

INSERT INTO encryption_test (input) VALUES (''), ('text'), ('What Is ClickHouse?');

Example without iv:

Query:

SELECT 'aes-128-cbc' AS mode, hex(aes_encrypt_mysql(mode, input, key32)) FROM encryption_test;

Result:

┌─mode────────┬─hex(aes_encrypt_mysql('aes-128-cbc', input, key32))──────────────┐
│ aes-128-cbc │ FEA8CFDE6EE2C6E7A2CC6ADDC9F62C83                                 │
│ aes-128-cbc │ 78B16CD4BE107660156124C5FEE6454A                                 │
│ aes-128-cbc │ 67C0B119D96F18E2823968D42871B3D179221B1E7EE642D628341C2B29BA2E18 │
└─────────────┴──────────────────────────────────────────────────────────────────┘

Example with iv:

Query:

SELECT 'aes-256-cfb128' AS mode, hex(aes_encrypt_mysql(mode, input, key32, iv)) FROM encryption_test;

Result:

┌─mode───────────┬─hex(aes_encrypt_mysql('aes-256-cfb128', input, key32, iv))─┐
│ aes-256-cfb128 │                                                            │
│ aes-256-cfb128 │ 7FB039F7                                                   │
│ aes-256-cfb128 │ 5CBD20F7ABD3AC41FCAA1A5C0E119E2BB5174F                     │
└────────────────┴────────────────────────────────────────────────────────────┘

decrypt

This function decrypts data using these modes:

aes-128-ecb, aes-192-ecb, aes-256-ecb
aes-128-cbc, aes-192-cbc, aes-256-cbc
aes-128-cfb1, aes-192-cfb1, aes-256-cfb1
aes-128-cfb8, aes-192-cfb8, aes-256-cfb8
aes-128-cfb128, aes-192-cfb128, aes-256-cfb128
aes-128-ofb, aes-192-ofb, aes-256-ofb
aes-128-gcm, aes-192-gcm, aes-256-gcm

Syntax

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

Parameters

mode — Decryption mode. String.
ciphertext — Encrypted text that needs to be decrypted. String.
key — Decryption key. String.
iv — Initialization vector. Required for -gcm modes, optinal for others. String.
aad — Additional authenticated data. Won't decrypt if this value is incorrect. Works only in -gcm modes, for others would throw an exception. String.

Returned value

Decrypted String. String.

Examples

Create this table:

Query:

CREATE TABLE encryption_test
(
    input String,
    key String DEFAULT unhex('fb9958e2e897ef3fdb49067b51a24af645b3626eed2f9ea1dc7fd4dd71b7e38f9a68db2a3184f952382c783785f9d77bf923577108a88adaacae5c141b1576b0'),
    iv String DEFAULT unhex('8CA3554377DFF8A369BC50A89780DD85'),
    key32 String DEFAULT substring(key, 1, 32),
    key24 String DEFAULT substring(key, 1, 24),
    key16 String DEFAULT substring(key, 1, 16)
) Engine = Memory;

Insert this data:

Query:

INSERT INTO encryption_test (input) VALUES (''), ('text'), ('What Is ClickHouse?');

Query:


SELECT 'aes-128-ecb' AS mode, decrypt(mode, encrypt(mode, input, key16), key16) FROM encryption_test;

Result:

┌─mode────────┬─decrypt('aes-128-ecb', encrypt('aes-128-ecb', input, key16), key16)─┐
│ aes-128-ecb │                                                                     │
│ aes-128-ecb │ text                                                                │
│ aes-128-ecb │ What Is ClickHouse?                                                 │
└─────────────┴─────────────────────────────────────────────────────────────────────┘

aes_decrypt_mysql

Compatible with mysql encryption and decrypts data encrypted with AES_ENCRYPT function.

Supported decryption modes:

aes-128-ecb, aes-192-ecb, aes-256-ecb
aes-128-cbc, aes-192-cbc, aes-256-cbc
aes-128-cfb1, aes-192-cfb1, aes-256-cfb1
aes-128-cfb8, aes-192-cfb8, aes-256-cfb8
aes-128-cfb128, aes-192-cfb128, aes-256-cfb128
aes-128-ofb, aes-192-ofb, aes-256-ofb

Syntax

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

Parameters

mode — Decryption mode. String.
ciphertext — Encrypted text that needs to be decrypted. String.
key — Decryption key. String.
iv — Initialization vector. Optinal. String.

Returned value

Decrypted String. String.

Examples

Create this table:

Query:

CREATE TABLE encryption_test
(
    input String,
    key String DEFAULT unhex('fb9958e2e897ef3fdb49067b51a24af645b3626eed2f9ea1dc7fd4dd71b7e38f9a68db2a3184f952382c783785f9d77bf923577108a88adaacae5c141b1576b0'),
    iv String DEFAULT unhex('8CA3554377DFF8A369BC50A89780DD85'),
    key32 String DEFAULT substring(key, 1, 32),
    key24 String DEFAULT substring(key, 1, 24),
    key16 String DEFAULT substring(key, 1, 16)
) Engine = Memory;

Insert this data:

Query:

INSERT INTO encryption_test (input) VALUES (''), ('text'), ('What Is ClickHouse?');

Query:

SELECT 'aes-128-cbc' AS mode, aes_decrypt_mysql(mode, aes_encrypt_mysql(mode, input, key), key) FROM encryption_test;

Result:

┌─mode────────┬─aes_decrypt_mysql('aes-128-cbc', aes_encrypt_mysql('aes-128-cbc', input, key), key)─┐
│ aes-128-cbc │                                                                                     │
│ aes-128-cbc │ text                                                                                │
│ aes-128-cbc │ What Is ClickHouse?                                                                 │
└─────────────┴─────────────────────────────────────────────────────────────────────────────────────┘

Original article

14 KiB Raw Blame History

Encryption functions

encrypt

aes_encrypt_mysql

decrypt

aes_decrypt_mysql

14 KiB

Raw Blame History