دوال التشفير

وثائق دوال التشفير

تُنفِّذ هذه الدوال تشفير البيانات وفك تشفيرها باستخدام خوارزمية AES ‏(Advanced Encryption Standard).

يعتمد طول المفتاح على وضع التشفير: 16 و24 و32 بايتًا لأوضاع -128- و-196- و-256- على الترتيب.

يكون طول متجه التهيئة دائمًا 16 بايتًا (وتُتجاهل البايتات التي تتجاوز 16).

​

HMAC

استُحدث في: v25.12.0

يحسب HMAC ‏(رمز توثيق الرسائل المعتمد على التجزئة) للرسالة المحددة باستخدام خوارزمية التجزئة والمفتاح السري المحددين.

خوارزميات التجزئة المدعومة:

• blake2b512
• blake2s256
• md4
• md5
• md5-sha1
• mdc2
• ripemd (أسماء بديلة: RIPEMD160, ripemd)
• ripemd160
• rmd160 (أسماء بديلة: RIPEMD160, rmd160)
• sha1
• sha224
• sha256
• sha3-224
• sha3-256
• sha3-384
• sha3-512
• sha384
• sha512
• sha512-224
• sha512-256
• shake128
• shake256
• sm3
• ssl3-md5 (أسماء بديلة: MD5, ssl3-md5)
• ssl3-sha1 (أسماء بديلة: SHA1, ssl3-sha1)
• whirlpool

الصيغة

HMAC(mode, message, key)

الوسائط

• mode — اسم خوارزمية التجزئة (غير حساس لحالة الأحرف). الخوارزميات المدعومة: md5, sha1, sha224, sha256, sha384, sha512. String
• message — الرسالة المطلوب توثيقها. String
• key — المفتاح السري لـ HMAC. String

القيمة المُعادة

تعيد سلسلة ثنائية تحتوي على بصمة HMAC. String

أمثلة

HMAC-SHA256 الأساسي

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

خوارزميات تجزئة مختلفة

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

وضع عدم التفريق بين حالة الأحرف

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

أُضيف في: v20.12.0

يفك تشفير البيانات التي شُفّرت باستخدام الدالة AES_ENCRYPT في MySQL.

وينتج النص الواضح نفسه الذي تنتجه decrypt عند استخدام المدخلات نفسها. وعندما يكون key أو iv أطول من المعتاد، فإن aes_decrypt_mysql يلتزم بسلوك aes_decrypt في MySQL، أي “طيّ” key وتجاهل البتات الزائدة في IV.

يدعم أوضاع فك التشفير التالية:

• 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

البنية

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

المعاملات

• mode — وضع فك التشفير. String
• ciphertext — نص مشفّر يجب فك تشفيره. String
• key — مفتاح فك التشفير. String
• iv — اختياري. متجه التهيئة. String

القيمة المُعادة

تُرجِع قيمة String بعد فك تشفيرها. String

أمثلة

فك تشفير بيانات MySQL

Query

-- 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

Response

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

​

aes_encrypt_mysql

قُدِّمت في: v20.12.0

تشفّر النص بالطريقة نفسها التي تعمل بها الدالة AES_ENCRYPT في MySQL. يمكن فك تشفير النص المشفّر الناتج باستخدام الدالة AES_DECRYPT في MySQL. وتُنتج النص المشفّر نفسه الذي تُنتجه الدالة encrypt للمدخلات نفسها. عندما يكون key أو iv أطول من المعتاد، تلتزم aes_encrypt_mysql بما تفعله aes_encrypt في MySQL، أي “طيّ” key وتجاهل البتات الزائدة في iv.

أوضاع التشفير المدعومة هي:

• 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_encrypt_mysql(mode, plaintext, key[, iv])

الوسائط

• mode — وضع التشفير. String
• plaintext — النص الصريح المطلوب تشفيره. String
• key — مفتاح التشفير. إذا كان المفتاح أطول مما يتطلبه mode، فسيُطبَّق طيّ المفتاح الخاص بـ MySQL. String
• iv — اختياري. متجه التهيئة. لا يُؤخذ في الاعتبار إلا أول 16 بايت. String

القيمة المُعادة

سلسلة ثنائية تمثل النص المُشفَّر. String

أمثلة

مقارنة المدخلات المتطابقة

Query

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

Response

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

فشل التشفير عند استخدام مفتاح طويل

Query

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

التوافق مع MySQL

Query

-- aes_encrypt_mysql produces MySQL-compatible output:
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123')) AS ciphertext;

Response

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

يؤدي IV الأطول إلى النتيجة نفسها

Query

-- Notice how supplying even longer IV produces the same result
SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123456')) AS ciphertext

Response

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

​

decrypt

أُضيفت في: v20.12.0

تفك هذه الدالة تشفير سلسلة ثنائية مشفّرة بخوارزمية AES باستخدام الأوضاع التالية:

• 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

البنية

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

الوسائط

• mode — وضع فك التشفير. String
• ciphertext — النص المشفّر المطلوب فك تشفيره. String
• key — مفتاح فك التشفير. String
• iv — متجه التهيئة. مطلوب لأوضاع -gcm، واختياري لغيرها. String
• aad — البيانات الإضافية الموثَّقة. لن يتم فك التشفير إذا كانت هذه القيمة غير صحيحة. يعمل فقط مع أوضاع -gcm، أما مع غيرها فيُطلق استثناءً. String

القيمة المُعادة

يعيد النص الصريح بعد فك التشفير. String

أمثلة

فك تشفير البيانات المشفّرة بشكل صحيح

Query

-- Re-using the table from the encrypt function example
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 │
└──────────────────────────────────┴──────────────────────────────────┘

فك تشفير البيانات المشفّرة بطريقة غير صحيحة

Query

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

Response

-- 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.
┌─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

أُضيفت في: v20.12.0

تُشفِّر نصًا صريحًا إلى نص مشفّر باستخدام AES بأحد الأوضاع التالية:

• 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

البنية

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

الوسيطات

• mode — وضع التشفير. String
• plaintext — النص الصريح المراد تشفيره. String
• key — مفتاح التشفير. String
• iv — متجه التهيئة. وهو مطلوب لأوضاع -gcm، واختياري لغيرها. String
• aad — بيانات إضافية موثَّقة. لا تُشفَّر، لكنها تؤثر في عملية فك التشفير. تعمل فقط في أوضاع -gcm، أما في غيرها فترفع استثناءً. String

القيمة المعادة

تعيد نصًا ثنائيًا مشفّرًا. String

أمثلة

مثال على التشفير

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

مثال على نمط 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

استُحدثت في: v22.10.0

تشبه الدالة decrypt، لكنها تُرجع NULL إذا فشل فك التشفير عند استخدام المفتاح الخاطئ.

الصيغة

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

المعاملات

• mode — وضع فك التشفير. String
• ciphertext — النص المشفّر المطلوب فك تشفيره. String
• key — مفتاح فك التشفير. String
• iv — اختياري. متجه التهيئة. مطلوب لأوضاع -gcm، واختياري للأوضاع الأخرى. String
• aad — اختياري. بيانات إضافية موثَّقة. لن تنجح عملية فك التشفير إذا كانت هذه القيمة غير صحيحة. يعمل فقط في أوضاع -gcm، وفي الأوضاع الأخرى يُطلِق استثناءً. String

القيمة المعادة

يعيد String بعد فك تشفيره، أو NULL إذا فشلت عملية فك التشفير. Nullable(String)

أمثلة

إنشاء جدول وإدراج البيانات

Query

-- 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

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