> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > وثائق دوال التشفير # دوال التشفير تُنفِّذ هذه الدوال تشفير البيانات وفك تشفيرها باستخدام خوارزمية AES ‏(Advanced Encryption Standard). يعتمد طول المفتاح على وضع التشفير: `16` و`24` و`32` بايتًا لأوضاع `-128-` و`-196-` و`-256-` على الترتيب. يكون طول متجه التهيئة دائمًا 16 بايتًا (وتُتجاهل البايتات التي تتجاوز 16). {/*AUTOGENERATED_START*/}
## 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 **الصيغة** ```sql theme={null} HMAC(mode, message, key) ``` **الوسائط** * `mode` — اسم خوارزمية التجزئة (غير حساس لحالة الأحرف). الخوارزميات المدعومة: md5, sha1, sha224, sha256, sha384, sha512. [`String`](/ar/reference/data-types/string) * `message` — الرسالة المطلوب توثيقها. [`String`](/ar/reference/data-types/string) * `key` — المفتاح السري لـ HMAC. [`String`](/ar/reference/data-types/string) **القيمة المُعادة** تعيد سلسلة ثنائية تحتوي على بصمة HMAC. [`String`](/ar/reference/data-types/string) **أمثلة** **HMAC-SHA256 الأساسي** ```sql title=Query theme={null} SELECT hex(HMAC('sha256', 'The quick brown fox jumps over the lazy dog', 'secret_key')); ``` ```response title=Response theme={null} ┌─hex(HMAC('sha256', 'The quick brown fox jumps over the lazy dog', 'secret_key'))─┐ │ 31FD15FA0F61FD40DC09D919D4AA5B4141A0B27C1D51E74A6789A890AAAA187C │ └──────────────────────────────────────────────────────────────────────────────────┘ ``` **خوارزميات تجزئة مختلفة** ```sql title=Query theme={null} 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 title=Response theme={null} ┌─hmac_md5─────────────────────────┬─hmac_sha1────────────────────────────────┬─hmac_sha256──────────────────────────────────────────────────────┐ │ 4E4748E62B463521F6775FBF921234B5 │ 2088DF74D5F2146B48146CAF4965377E9D0BE3A4 │ 6E9EF29B75FFFC5B7ABAE527D58FDADB2FE42E7219011976917343065F58ED4A │ └──────────────────────────────────┴──────────────────────────────────────────┴──────────────────────────────────────────────────────────────────┘ ``` **وضع عدم التفريق بين حالة الأحرف** ```sql title=Query theme={null} SELECT hmac('SHA256', 'message', 'key') = HMAC('sha256', 'message', 'key') AS same_result, HMAC('SHA256', 'message', 'key') = Hmac('Sha256', 'message', 'key') AS also_same; ``` ```response title=Response theme={null} ┌─same_result─┬─also_same─┐ │ 1 │ 1 │ └─────────────┴───────────┘ ```
## aes\_decrypt\_mysql
أُضيف في: v20.12.0 يفك تشفير البيانات التي شُفّرت باستخدام الدالة [`AES_ENCRYPT`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html#function_aes-encrypt) في MySQL. وينتج النص الواضح نفسه الذي تنتجه [`decrypt`](#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 **البنية** ```sql theme={null} aes_decrypt_mysql(mode, ciphertext, key[, iv]) ``` **المعاملات** * `mode` — وضع فك التشفير. [`String`](/ar/reference/data-types/string) * `ciphertext` — نص مشفّر يجب فك تشفيره. [`String`](/ar/reference/data-types/string) * `key` — مفتاح فك التشفير. [`String`](/ar/reference/data-types/string) * `iv` — اختياري. متجه التهيئة. [`String`](/ar/reference/data-types/string) **القيمة المُعادة** تُرجِع قيمة String بعد فك تشفيرها. [`String`](/ar/reference/data-types/string) **أمثلة** **فك تشفير بيانات MySQL** ```sql title=Query theme={null} -- 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 title=Response theme={null} ┌─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 **الصيغة** ```sql theme={null} aes_encrypt_mysql(mode, plaintext, key[, iv]) ``` **الوسائط** * `mode` — وضع التشفير. [`String`](/ar/reference/data-types/string) * `plaintext` — النص الصريح المطلوب تشفيره. [`String`](/ar/reference/data-types/string) * `key` — مفتاح التشفير. إذا كان المفتاح أطول مما يتطلبه `mode`، فسيُطبَّق طيّ المفتاح الخاص بـ MySQL. [`String`](/ar/reference/data-types/string) * `iv` — اختياري. متجه التهيئة. لا يُؤخذ في الاعتبار إلا أول 16 بايت. [`String`](/ar/reference/data-types/string) **القيمة المُعادة** سلسلة ثنائية تمثل النص المُشفَّر. [`String`](/ar/reference/data-types/string) **أمثلة** **مقارنة المدخلات المتطابقة** ```sql title=Query theme={null} -- 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 title=Response theme={null} ┌─ciphertexts_equal─┐ │ 1 │ └───────────────────┘ ``` **فشل التشفير عند استخدام مفتاح طويل** ```sql title=Query theme={null} -- But encrypt fails when key or iv is longer than expected: SELECT encrypt('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123'); ``` ```response title=Response theme={null} 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** ```sql title=Query theme={null} -- aes_encrypt_mysql produces MySQL-compatible output: SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123')) AS ciphertext; ``` ```response title=Response theme={null} ┌─ciphertext───┐ │ 24E9E4966469 │ └──────────────┘ ``` **يؤدي IV الأطول إلى النتيجة نفسها** ```sql title=Query theme={null} -- Notice how supplying even longer IV produces the same result SELECT hex(aes_encrypt_mysql('aes-256-ofb', 'Secret', '123456789101213141516171819202122', 'iviviviviviviviv123456')) AS ciphertext ``` ```response title=Response theme={null} ┌─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 **البنية** ```sql theme={null} decrypt(mode, ciphertext, key[, iv, aad]) ``` **الوسائط** * `mode` — وضع فك التشفير. [`String`](/ar/reference/data-types/string) * `ciphertext` — النص المشفّر المطلوب فك تشفيره. [`String`](/ar/reference/data-types/string) * `key` — مفتاح فك التشفير. [`String`](/ar/reference/data-types/string) * `iv` — متجه التهيئة. مطلوب لأوضاع `-gcm`، واختياري لغيرها. [`String`](/ar/reference/data-types/string) * `aad` — البيانات الإضافية الموثَّقة. لن يتم فك التشفير إذا كانت هذه القيمة غير صحيحة. يعمل فقط مع أوضاع `-gcm`، أما مع غيرها فيُطلق استثناءً. [`String`](/ar/reference/data-types/string) **القيمة المُعادة** يعيد النص الصريح بعد فك التشفير. [`String`](/ar/reference/data-types/string) **أمثلة** **فك تشفير البيانات المشفّرة بشكل صحيح** ```sql title=Query theme={null} -- Re-using the table from the encrypt function example SELECT comment, hex(secret) FROM encryption_test; ``` ```response title=Response theme={null} ┌─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 │ └──────────────────────────────────┴──────────────────────────────────┘ ``` **فك تشفير البيانات المشفّرة بطريقة غير صحيحة** ```sql title=Query theme={null} SELECT comment, decrypt('aes-256-cfb128', secret, '12345678910121314151617181920212') AS plaintext FROM encryption_test ``` ```response title=Response theme={null} -- 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 **البنية** ```sql theme={null} encrypt(mode, plaintext, key[, iv, aad]) ``` **الوسيطات** * `mode` — وضع التشفير. [`String`](/ar/reference/data-types/string) * `plaintext` — النص الصريح المراد تشفيره. [`String`](/ar/reference/data-types/string) * `key` — مفتاح التشفير. [`String`](/ar/reference/data-types/string) * `iv` — متجه التهيئة. وهو مطلوب لأوضاع `-gcm`، واختياري لغيرها. [`String`](/ar/reference/data-types/string) * `aad` — بيانات إضافية موثَّقة. لا تُشفَّر، لكنها تؤثر في عملية فك التشفير. تعمل فقط في أوضاع `-gcm`، أما في غيرها فترفع استثناءً. [`String`](/ar/reference/data-types/string) **القيمة المعادة** تعيد نصًا ثنائيًا مشفّرًا. [`String`](/ar/reference/data-types/string) **أمثلة** **مثال على التشفير** ```sql title=Query theme={null} 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 title=Response theme={null} ┌─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** ```sql title=Query theme={null} 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 title=Response theme={null} ┌─comment──────────────┬─hex(secret)──────────────────────────────────┐ │ aes-256-gcm │ A8A3CCBC6426CFEEB60E4EAE03D3E94204C1B09E0254 │ │ aes-256-gcm with AAD │ A8A3CCBC6426D9A1017A0A932322F1852260A4AD6837 │ └──────────────────────┴──────────────────────────────────────────────┘ ```
## tryDecrypt
استُحدثت في: v22.10.0 تشبه الدالة `decrypt`، لكنها تُرجع `NULL` إذا فشل فك التشفير عند استخدام المفتاح الخاطئ. **الصيغة** ```sql theme={null} tryDecrypt(mode, ciphertext, key[, iv, aad]) ``` **المعاملات** * `mode` — وضع فك التشفير. [`String`](/ar/reference/data-types/string) * `ciphertext` — النص المشفّر المطلوب فك تشفيره. [`String`](/ar/reference/data-types/string) * `key` — مفتاح فك التشفير. [`String`](/ar/reference/data-types/string) * `iv` — اختياري. متجه التهيئة. مطلوب لأوضاع `-gcm`، واختياري للأوضاع الأخرى. [`String`](/ar/reference/data-types/string) * `aad` — اختياري. بيانات إضافية موثَّقة. لن تنجح عملية فك التشفير إذا كانت هذه القيمة غير صحيحة. يعمل فقط في أوضاع `-gcm`، وفي الأوضاع الأخرى يُطلِق استثناءً. [`String`](/ar/reference/data-types/string) **القيمة المعادة** يعيد String بعد فك تشفيره، أو `NULL` إذا فشلت عملية فك التشفير. [`Nullable(String)`](/ar/reference/data-types/nullable) **أمثلة** **إنشاء جدول وإدراج البيانات** ```sql title=Query theme={null} -- 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 title=Response theme={null} ┌──────────────────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 │ ᴺᵁᴸᴸ │ └─────────────────────┴─────────┴────────┘ ```