EVP_ENCRYPTINIT(3ssl)

الاسم
EVP_CIPHER_fetch, EVP_CIPHER_up_ref, EVP_CIPHER_free, EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free, EVP_CIPHER_CTX_dup, EVP_CIPHER_CTX_copy, EVP_EncryptInit_ex, EVP_EncryptInit_ex2, EVP_EncryptUpdate, EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptInit_ex2, EVP_DecryptUpdate, EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherInit_ex2, EVP_CipherInit_SKEY, EVP_CipherUpdate, EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit, EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal, EVP_Cipher, EVP_CIPHER_can_pipeline, EVP_CipherPipelineEncryptInit, EVP_CipherPipelineDecryptInit, EVP_CipherPipelineUpdate, EVP_CipherPipelineFinal, EVP_get_cipherbyname, EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_is_a, EVP_CIPHER_get0_name, EVP_CIPHER_get0_description, EVP_CIPHER_names_do_all, EVP_CIPHER_get0_provider, EVP_CIPHER_get_nid, EVP_CIPHER_get_params, EVP_CIPHER_gettable_params, EVP_CIPHER_get_block_size, EVP_CIPHER_get_key_length, EVP_CIPHER_get_iv_length, EVP_CIPHER_get_flags, EVP_CIPHER_get_mode, EVP_CIPHER_get_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_get0_cipher, EVP_CIPHER_CTX_get1_cipher, EVP_CIPHER_CTX_get0_name, EVP_CIPHER_CTX_get_nid, EVP_CIPHER_CTX_get_params, EVP_CIPHER_gettable_ctx_params, EVP_CIPHER_CTX_gettable_params, EVP_CIPHER_CTX_set_params, EVP_CIPHER_settable_ctx_params, EVP_CIPHER_CTX_settable_params, EVP_CIPHER_CTX_get_block_size, EVP_CIPHER_CTX_get_key_length, EVP_CIPHER_CTX_get_iv_length, EVP_CIPHER_CTX_get_tag_length, EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_set_flags, EVP_CIPHER_CTX_clear_flags, EVP_CIPHER_CTX_test_flags, EVP_CIPHER_CTX_get_type, EVP_CIPHER_CTX_get_mode, EVP_CIPHER_CTX_get_num, EVP_CIPHER_CTX_set_num, EVP_CIPHER_CTX_is_encrypting, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_CIPHER_do_all_provided, EVP_CIPHER_nid, EVP_CIPHER_name, EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_encrypting, EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_tag_length, EVP_CIPHER_CTX_num, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_mode - EVP cipher routines

موجز
 #include <openssl/evp.h>

 EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                              const char *properties);
 int EVP_CIPHER_up_ref(EVP_CIPHER *cipher);
 void EVP_CIPHER_free(EVP_CIPHER *cipher);
 EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
 int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx);
 void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
 EVP_CIPHER_CTX *EVP_CIPHER_CTX_dup(const EVP_CIPHER_CTX *in);
 int EVP_CIPHER_CTX_copy(EVP_CIPHER_CTX *out, const EVP_CIPHER_CTX *in);

 int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                        ENGINE *impl, const unsigned char *key, const unsigned char *iv);
 int EVP_EncryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                         const unsigned char *key, const unsigned char *iv,
                         const OSSL_PARAM params[]);
 int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
                       int *outl, const unsigned char *in, int inl);
 int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);

 int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                        ENGINE *impl, const unsigned char *key, const unsigned char *iv);
 int EVP_DecryptInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                         const unsigned char *key, const unsigned char *iv,
                         const OSSL_PARAM params[]);
 int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
                       int *outl, const unsigned char *in, int inl);
 int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);

 int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                       ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);
 int EVP_CipherInit_ex2(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                        const unsigned char *key, const unsigned char *iv,
                        int enc, const OSSL_PARAM params[]);
 int EVP_CipherInit_SKEY(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *cipher,
                         EVP_SKEY *skey, const unsigned char *iv, size_t iv_len,
                         int enc, const OSSL_PARAM params[]);
 int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
                      int *outl, const unsigned char *in, int inl);
 int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);

 int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                     const unsigned char *key, const unsigned char *iv);
 int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);

 int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                     const unsigned char *key, const unsigned char *iv);
 int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);

 int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
                    const unsigned char *key, const unsigned char *iv, int enc);
 int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);

 int EVP_Cipher(EVP_CIPHER_CTX *ctx, unsigned char *out,
                const unsigned char *in, unsigned int inl);

 int EVP_CIPHER_can_pipeline(const EVP_CIPHER *cipher, int enc);
 int EVP_CipherPipelineEncryptInit(EVP_CIPHER_CTX *ctx,
                                   const EVP_CIPHER *cipher,
                                   const unsigned char *key, size_t keylen,
                                   size_t numpipes,
                                   const unsigned char **iv, size_t ivlen);
 int EVP_CipherPipelineDecryptInit(EVP_CIPHER_CTX *ctx,
                                   const EVP_CIPHER *cipher,
                                   const unsigned char *key, size_t keylen,
                                   size_t numpipes,
                                   const unsigned char **iv, size_t ivlen);
 int EVP_CipherPipelineUpdate(EVP_CIPHER_CTX *ctx,
                              unsigned char **out, size_t *outl,
                              const size_t *outsize,
                              const unsigned char **in, const size_t *inl);
 int EVP_CipherPipelineFinal(EVP_CIPHER_CTX *ctx,
                             unsigned char **outm, size_t *outl,
                             const size_t *outsize);

 int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
 int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
 int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int cmd, int p1, void *p2);
 int EVP_CIPHER_CTX_rand_key(EVP_CIPHER_CTX *ctx, unsigned char *key);
 void EVP_CIPHER_CTX_set_flags(EVP_CIPHER_CTX *ctx, int flags);
 void EVP_CIPHER_CTX_clear_flags(EVP_CIPHER_CTX *ctx, int flags);
 int EVP_CIPHER_CTX_test_flags(const EVP_CIPHER_CTX *ctx, int flags);

 const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
 const EVP_CIPHER *EVP_get_cipherbynid(int nid);
 const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);

 int EVP_CIPHER_get_nid(const EVP_CIPHER *e);
 int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name);
 int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher,
                             void (*fn)(const char *name, void *data),
                             void *data);
 const char *EVP_CIPHER_get0_name(const EVP_CIPHER *cipher);
 const char *EVP_CIPHER_get0_description(const EVP_CIPHER *cipher);
 const OSSL_PROVIDER *EVP_CIPHER_get0_provider(const EVP_CIPHER *cipher);
 int EVP_CIPHER_get_block_size(const EVP_CIPHER *e);
 int EVP_CIPHER_get_key_length(const EVP_CIPHER *e);
 int EVP_CIPHER_get_iv_length(const EVP_CIPHER *e);
 unsigned long EVP_CIPHER_get_flags(const EVP_CIPHER *e);
 unsigned long EVP_CIPHER_get_mode(const EVP_CIPHER *e);
 int EVP_CIPHER_get_type(const EVP_CIPHER *cipher);

 const EVP_CIPHER *EVP_CIPHER_CTX_get0_cipher(const EVP_CIPHER_CTX *ctx);
 EVP_CIPHER *EVP_CIPHER_CTX_get1_cipher(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_nid(const EVP_CIPHER_CTX *ctx);
 const char *EVP_CIPHER_CTX_get0_name(const EVP_CIPHER_CTX *ctx);

 int EVP_CIPHER_get_params(EVP_CIPHER *cipher, OSSL_PARAM params[]);
 int EVP_CIPHER_CTX_set_params(EVP_CIPHER_CTX *ctx, const OSSL_PARAM params[]);
 int EVP_CIPHER_CTX_get_params(EVP_CIPHER_CTX *ctx, OSSL_PARAM params[]);
 const OSSL_PARAM *EVP_CIPHER_gettable_params(const EVP_CIPHER *cipher);
 const OSSL_PARAM *EVP_CIPHER_settable_ctx_params(const EVP_CIPHER *cipher);
 const OSSL_PARAM *EVP_CIPHER_gettable_ctx_params(const EVP_CIPHER *cipher);
 const OSSL_PARAM *EVP_CIPHER_CTX_settable_params(EVP_CIPHER_CTX *ctx);
 const OSSL_PARAM *EVP_CIPHER_CTX_gettable_params(EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_block_size(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_key_length(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_iv_length(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_tag_length(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_type(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_mode(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_get_num(const EVP_CIPHER_CTX *ctx);
 int EVP_CIPHER_CTX_set_num(EVP_CIPHER_CTX *ctx, int num);
 int EVP_CIPHER_CTX_is_encrypting(const EVP_CIPHER_CTX *ctx);

 int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
 int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);

 void EVP_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,
                                 void (*fn)(EVP_CIPHER *cipher, void *arg),
                                 void *arg);

 #define EVP_CIPHER_nid EVP_CIPHER_get_nid
 #define EVP_CIPHER_name EVP_CIPHER_get0_name
 #define EVP_CIPHER_block_size EVP_CIPHER_get_block_size
 #define EVP_CIPHER_key_length EVP_CIPHER_get_key_length
 #define EVP_CIPHER_iv_length EVP_CIPHER_get_iv_length
 #define EVP_CIPHER_flags EVP_CIPHER_get_flags
 #define EVP_CIPHER_mode EVP_CIPHER_get_mode
 #define EVP_CIPHER_type EVP_CIPHER_get_type
 #define EVP_CIPHER_CTX_encrypting EVP_CIPHER_CTX_is_encrypting
 #define EVP_CIPHER_CTX_nid EVP_CIPHER_CTX_get_nid
 #define EVP_CIPHER_CTX_block_size EVP_CIPHER_CTX_get_block_size
 #define EVP_CIPHER_CTX_key_length EVP_CIPHER_CTX_get_key_length
 #define EVP_CIPHER_CTX_iv_length EVP_CIPHER_CTX_get_iv_length
 #define EVP_CIPHER_CTX_tag_length EVP_CIPHER_CTX_get_tag_length
 #define EVP_CIPHER_CTX_num EVP_CIPHER_CTX_get_num
 #define EVP_CIPHER_CTX_type EVP_CIPHER_CTX_get_type
 #define EVP_CIPHER_CTX_mode EVP_CIPHER_CTX_get_mode

الدالة التالية أصبحت مهجورة منذ OpenSSL 3.0، ويمكن إخفاؤها تمامًا عبر تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);

الدالة التالية أصبحت مهجورة منذ OpenSSL 1.1.0، ويمكن إخفاؤها تمامًا عبر تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 int EVP_CIPHER_CTX_flags(const EVP_CIPHER_CTX *ctx);

الوصف
إجراءات التشفير EVP هي واجهة عالية المستوى لبعض المُعمِّيات المتناظرة.

النوع EVP_CIPHER هو بنية لتنفيذ طريقة التشفير.

EVP_CIPHER_fetch()
    يجلب تنفيذ التشفير لـ algorithm المُعطى من أي مزود يوفره، ضمن المعايير المُعطاة بواسطة properties. راجع "ALGORITHM FETCHING" في crypto(7) لمزيد من المعلومات.

    يجب تحرير القيمة المُرجَعة في النهاية باستخدام EVP_CIPHER_free().

    بُنى EVP_CIPHER المجلوبة مُعدودة المرجع.

EVP_CIPHER_up_ref()
    يزيد عدد المرجع لبنية EVP_CIPHER.

EVP_CIPHER_free()
    يخفض عدد المرجع لبنية EVP_CIPHER المجلوبة. إذا انخفض عدد المرجع إلى 0، تُحرر البنية. إذا كانت الوسيطة NULL، لا يُفعل شيء.

EVP_CIPHER_CTX_new()
    يخصص ويُعيد سياق تشفير.

EVP_CIPHER_CTX_free()
    يمسح كل المعلومات من سياق التشفير ويحرر أي ذاكرة مُخصصة مرتبطة به، بما في ذلك ctx نفسه. يجب استدعاء هذه الدالة بعد اكتمال جميع العمليات باستخدام التشفير حتى لا تبقى المعلومات الحساسة في الذاكرة. إذا كانت الوسيطة NULL، لا يُفعل شيء.

EVP_CIPHER_CTX_dup()
    يمكن استخدامها لنسخ حالة التشفير من in. هذا مفيد لتجنب استدعاءات EVP_CIPHER_fetch() المتعددة أو إذا كانت كميات كبيرة من البيانات ستُغذى وتختلف فقط في البايتات القليلة الأخيرة.

EVP_CIPHER_CTX_copy()
    يمكن استخدامها لنسخ حالة التشفير من in إلى out.

EVP_CIPHER_CTX_ctrl()
    هذه طريقة قديمة. EVP_CIPHER_CTX_set_params() و EVP_CIPHER_CTX_get_params() هما الآلية التي يجب استخدامها لتعيين وجلب المعاملات التي يستخدمها المزودون.

    ينفذ إجراءات تحكم خاصة بالتشفير على السياق ctx. يُشار إلى أمر التحكم في cmd وأي وسائط إضافية في p1 و p2. يجب استدعاء EVP_CIPHER_CTX_ctrl() بعد EVP_CipherInit_ex2(). قد تنطبق قيود أخرى حسب نوع التحكم وتنفيذ التشفير.

    إذا صادف استخدام هذه الدالة مع EVP_CIPHER مجلوب، فستترجم عناصر التحكم المعروفة لـ OpenSSL إلى معاملات OSSL_PARAM(3) بمفاتيح مُعرفة بواسطة OpenSSL وتستدعي EVP_CIPHER_CTX_get_params() أو EVP_CIPHER_CTX_set_params() حسب ما يناسب كل أمر تحكم.

    انظر "CONTROLS" أدناه لمزيد من المعلومات، بما في ذلك الترجمات التي تُجرى.

EVP_CIPHER_get_params()
    يسترجع قائمة params المطلوبة للخوارزمية من CIPHER cipher. راجع "PARAMETERS" أدناه لمزيد من المعلومات.

EVP_CIPHER_CTX_get_params()
    يسترجع قائمة params المطلوبة من سياق CIPHER ctx. راجع "PARAMETERS" أدناه لمزيد من المعلومات.

EVP_CIPHER_CTX_set_params()
    يضبط قائمة params في سياق CIPHER ctx. راجع "PARAMETERS" أدناه لمزيد من المعلومات.

EVP_CIPHER_gettable_params()
    احصل على مصفوفة OSSL_PARAM(3) ثابتة تصف المعاملات القابلة للاسترجاع التي يمكن استخدامها مع EVP_CIPHER_get_params().

EVP_CIPHER_gettable_ctx_params() و EVP_CIPHER_CTX_gettable_params()
    احصل على مصفوفة OSSL_PARAM(3) ثابتة تصف المعاملات القابلة للاسترجاع التي يمكن استخدامها مع EVP_CIPHER_CTX_get_params(). تُعيد EVP_CIPHER_gettable_ctx_params() المعاملات التي يمكن استرجاعها من الخوارزمية، بينما تُعيد EVP_CIPHER_CTX_gettable_params() المعاملات التي يمكن استرجاعها في الحالة الحالية للسياق.

EVP_CIPHER_settable_ctx_params() و EVP_CIPHER_CTX_settable_params()
    احصل على مصفوفة OSSL_PARAM(3) ثابتة تصف المعاملات القابلة للضبط التي يمكن استخدامها مع EVP_CIPHER_CTX_set_params(). تُعيد EVP_CIPHER_settable_ctx_params() المعاملات التي يمكن ضبطها من الخوارزمية، بينما تُعيد EVP_CIPHER_CTX_settable_params() المعاملات التي يمكن ضبطها في الحالة الحالية للسياق.

EVP_EncryptInit_ex2()
    يُعدّ سياق التشفير ctx للتشفير باستخدام المُعمِّي type. ctx يجب ألا يكون NULL. يُوفَّر type عادةً باستدعاء EVP_CIPHER_fetch(). يمكن أيضًا تعيين type باستخدام دوال قديمة مثل EVP_aes_256_cbc()، لكن هذا لا يُوصى به للتطبيقات الجديدة. key هو المفتاح المتناظر المستخدم و iv هو IV المستخدم (إذا لزم الأمر)، ويعتمد العدد الفعلي للبايتات المستخدمة للمفتاح و IV على المُعمِّي. سيتم تعيين المعاملات params على السياق بعد التهيئة. من الممكن تعيين جميع المعاملات إلى NULL باستثناء type في استدعاء أولي وتوفير المعاملات المتبقية في استدعاءات لاحقة، جميعها لها type مضبوط على NULL. يُفعل ذلك عندما لا تكون معاملات المُعمِّي المبدئية مناسبة. بالنسبة لـ EVP_CIPH_GCM_MODE، سيُولَّد IV داخليًا إذا لم يُحدد.

EVP_EncryptInit_ex()
    هذه الدالة القديمة مشابهة لـ EVP_EncryptInit_ex2() عندما يكون impl NULL. سيُستخدم تنفيذ type من محرك impl إذا كان موجودًا.

EVP_EncryptUpdate()
    يُعمِّي inl بايت من المخزن المؤقت in ويكتب النسخة المُعمَّاة إلى out. قد تشير المؤشرات out و in إلى نفس الموقع، وفي هذه الحالة سيتم التشفير في المكان. ومع ذلك، يُضمن عمل التشفير في المكان فقط إذا عالج سياق التشفير (ctx) البيانات بمضاعفات حجم الكتلة. إذا احتوى السياق على كتلة بيانات غير كاملة من عمليات سابقة، سيفشل التشفير في المكان. ctx يجب ألا يكون NULL.

    إذا أشار out و in إلى مواقع مختلفة، يجب أن يكون المخزنان المؤقتان منفصلين، وإلا فقد تفشل العملية أو تكون النتيجة غير محددة.

    يمكن استدعاء هذه الدالة عدة مرات لتشفير كتل متتالية من البيانات. تعتمد كمية البيانات المكتوبة على محاذاة الكتلة للبيانات المُعمَّاة. بالنسبة لمعظم المُعمِّيات والأنماط، يمكن أن تكون كمية البيانات المكتوبة أي شيء من صفر بايت إلى (inl + cipher_block_size - 1) بايت. بالنسبة لأنماط المُعمِّي الملتف، يمكن أن تكون كمية البيانات المكتوبة أي شيء من صفر بايت إلى (inl + cipher_block_size) بايت. بالنسبة للمُعمِّيات التدفقية، يمكن أن تكون كمية البيانات المكتوبة أي شيء من صفر بايت إلى inl بايت. وبالتالي، يجب أن يحتوي المخزن المؤقت المشار إليه بواسطة out على مساحة كافية للعملية المنفذة. يُوضع العدد الفعلي للبايتات المكتوبة في outl.

    إذا كان الحشو مفعّلاً (المبدئي)، فإن EVP_EncryptFinal_ex() يُعمِّي البيانات "النهائية"، أي أي بيانات متبقية في كتلة جزئية. يستخدم حشو الكتلة القياسي (المعروف بحشو PKCS) كما هو موصوف في قسم الملاحظات أدناه. تُكتب البيانات النهائية المُعمَّاة إلى out الذي يجب أن يحتوي على مساحة كافية لكتلة مُعمِّي واحدة. يُوضع عدد البايتات المكتوبة في outl. بعد استدعاء هذه الدالة، تنتهي عملية التشفير ولا ينبغي إجراء استدعاءات أخرى لـ EVP_EncryptUpdate().

    إذا كان الحشو معطلاً، فإن EVP_EncryptFinal_ex() لن يُعمِّي أي بيانات إضافية وسيُرجع خطأً إذا بقيت أي بيانات في كتلة جزئية: أي إذا لم يكن الطول الإجمالي للبيانات مضاعفًا لحجم الكتلة.

EVP_DecryptInit_ex2()، EVP_DecryptInit_ex()، EVP_DecryptUpdate() و EVP_DecryptFinal_ex()
    هذه الدوال هي عمليات فك التشفير المقابلة. ستُرجع EVP_DecryptFinal() رمز خطأ إذا كان الحشو مفعّلاً والكتلة النهائية غير منسقة بشكل صحيح. المعاملات والقيود مطابقة لعمليات التشفير. ctx يجب ألا يكون NULL.

EVP_CipherInit_ex2()، EVP_CipherInit_ex()، EVP_CipherUpdate() و EVP_CipherFinal_ex()
    يمكن استخدام هذه الدوال لفك التشفير أو التشفير. تعتمد العملية المنفذة على قيمة المعامل enc. يجب تعيينها إلى 1 للتشفير، و0 لفك التشفير، و-1 لترك القيمة دون تغيير (القيمة الفعلية لـ 'enc' تُوفَّر في استدعاء سابق).

EVP_CipherInit_SKEY()
    هذه الدالة مشابهة لـ EVP_CipherInit_ex2() لكنها تقبل كائن مفتاح متناظر من النوع EVP_SKEY كمفتاح.

EVP_CIPHER_CTX_reset()
    يمسح جميع المعلومات من سياق المُعمِّي ويُحرر أي ذاكرة مخصصة مرتبطة به، باستثناء ctx نفسه. يجب استدعاء هذه الدالة في أي وقت يُعاد فيه استخدام ctx بواسطة سلسلة استدعاءات أخرى من EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal().

EVP_EncryptInit()، EVP_DecryptInit() و EVP_CipherInit()
    تتصرف بطريقة مشابهة لـ EVP_EncryptInit_ex()، EVP_DecryptInit_ex() و EVP_CipherInit_ex() باستثناء أنه إذا لم يكن type مُعمِّيًا مُستحضَرًا، فإنها تستخدم التنفيذ المبدئي لـ type.

EVP_EncryptFinal()، EVP_DecryptFinal() و EVP_CipherFinal()
    مطابق لـ EVP_EncryptFinal_ex() و EVP_DecryptFinal_ex() و EVP_CipherFinal_ex(). في الإصدارات السابقة، كانت تنظف ctx أيضًا، لكن هذا لم يعد يُفعل ويجب استدعاء EVP_CIPHER_CTX_cleanup() لتحرير أي موارد للسياق.

EVP_Cipher()
    يُعمي أو يفك تعمية مقدار أقصاه inl بايت من in ويترك النتيجة في out.

    للمُعمِّيات القديمة - إذا لم يكن للمُعمِّي العَلَم EVP_CIPH_FLAG_CUSTOM_CIPHER مضبوطًا، فيجب أن يكون inl مضاعفًا لـ EVP_CIPHER_get_block_size(). إذا لم يكن كذلك، فالنتيجة غير معرفة. إذا كان للمُعمِّي ذلك العَلَم مضبوطًا، فيمكن أن يكون inl بأي حجم.

    بسبب قيود عقد واجهة برمجة التطبيقات لهذه الدالة، لا ينبغي استخدامها في التطبيقات، يُرجى النظر في استخدام EVP_CipherUpdate() و EVP_CipherFinal_ex() بدلاً من ذلك.

EVP_CIPHER_can_pipeline()
    تتحقق هذه الدالة مما إذا كان EVP_CIPHER الذي جُلب باستخدام EVP_CIPHER_fetch() يدعم خط أنابيب المُعمِّي. إذا كان المُعمِّي يدعم خط الأنابيب، فإنها تُرجع 1، وإلا 0. سترجع هذه الدالة 0 للمُعمِّيات غير المجلوبة مثل EVP_aes_128_gcm(). لا توجد حاليًا أي مُعمِّيات مدمجة تدعم خط الأنابيب.

    يدعم دعم خط أنابيب المُعمِّي للتطبيق إرسال قطع متعددة من البيانات في مجموعة واحدة من استدعاءات EVP_CipherUpdate()/EVP_CipherFinal، مما يسمح للتنفيذ المقدم بالاستفادة من الحوسبة المتوازية. هذا مفيد للمسرعات العتادية حيث يوزع خط الأنابيب زمن الانتظار على قطع متعددة.

    للمُعمِّيات غير المجلوبة، يمكن استدعاء EVP_CipherPipelineEncryptInit() أو EVP_CipherPipelineDecryptInit() مباشرة، والتي ستقوم بجلب وإرجاع خطأ إذا لم يُعثر على تنفيذ يدعم خط الأنابيب.

EVP_CipherPipelineEncryptInit() و EVP_CipherPipelineDecryptInit() و EVP_CipherPipelineUpdate() و EVP_CipherPipelineFinal()
    يمكن استخدام هذه الدوال لإجراء عمليات تعمية أو فك تعمية متعددة بالتوازي. يمكن استدعاء EVP_CIPHER_can_pipeline() للتحقق مما إذا كان المُعمِّي يدعم خط الأنابيب. هذه الدوال مماثلة لـ EVP_EncryptInit_ex2() و EVP_DecryptInit_ex2() و EVP_CipherUpdate() و EVP_CipherFinal() لكنها تأخذ مصفوفة من المؤشرات لـ iv ومخازن الإدخال والإخراج.

    المفتاح key، بطول keylen، هو المفتاح المتناظر المستخدم. يُحدد المعامل numpipes عدد العمليات المتوازية التي ستُجرى. لا يمكن أن يتجاوز numpipes EVP_MAX_PIPES. المعامل iv هو مصفوفة من مؤشرات المخازن، تحتوي على IVs. يجب أن يكون حجم المصفوفة مساويًا لـ numpipes. يجب أن يكون حجم كل مخزن IV مساويًا لـ ivlen. عندما لا يُقدم IV، يجب أن يكون iv NULL، بدلاً من مصفوفة من مؤشرات NULL. تأخذ المعاملات in مصفوفة من مؤشرات المخازن، كل منها يشير إلى مخزن يحتوي على بيانات الإدخال. يمكن أن تكون المخازن بأحجام مختلفة. المعامل inl هو مصفوفة من size_t، كل منها يُحدد حجم مخزن الإدخال المقابل. المعاملات out و outm هي مصفوفات من مؤشرات المخازن، كل منها يشير إلى مخزن حيث ستُكتب بيانات الإخراج. المعامل outsize هو مصفوفة من size_t، كل منها يُحدد حجم مخزن الإخراج المقابل. المعامل outl هو مصفوفة من size_t ستُحدث بحجم بيانات الإخراج المكتوبة في مخزن الإخراج المقابل. لمتطلبات حجم مخازن الإخراج، انظر وصف EVP_CipherUpdate().

    يمكن استدعاء الدالة EVP_CipherPipelineUpdate() عدة مرات لتعمية كتل متتالية من البيانات. لبيانات AAD، يجب أن يكون المعامل out و outsize NULL، بدلاً من مصفوفة من مؤشرات NULL.

EVP_get_cipherbyname() و EVP_get_cipherbynid() و EVP_get_cipherbyobj()
    تُرجع بنية EVP_CIPHER عند تمرير اسم مُعمِّي، أو NID لمُعمِّي، أو بنية ASN1_OBJECT على التوالي.

    سترجع EVP_get_cipherbyname() NULL للخوارزميات مثل "AES-128-SIV" و "AES-128-CBC-CTS" و "CAMELLIA-128-CBC-CTS" التي كانت سابقًا لا يمكن الوصول إليها إلا عبر واجهات منخفضة المستوى.

    الدالة EVP_get_cipherbyname() موجودة للتوافق العكسي مع OpenSSL قبل الإصدار 3 وتختلف عن الدالة EVP_CIPHER_fetch() لأنها لا تحاول "جلب" تنفيذ للمُعمِّي. بالإضافة إلى ذلك، فهي تعرف فقط المُعمِّيات المدمجة في OpenSSL والتي لها NID مرتبط. وبالمثل، تُرجع EVP_get_cipherbynid() و EVP_get_cipherbyobj() كائنات بدون تنفيذ مرتبط.

    عند استخدام كائنات المُعمِّي التي أرجعتها هذه الدوال (مثل في استدعاء EVP_EncryptInit_ex())، سيُجلب تنفيذ للمُعمِّي ضمنيًا من المزودين المحملين. قد يفشل هذا الجلب إذا لم يتوفر تنفيذ مناسب. استخدم EVP_CIPHER_fetch() بدلاً من ذلك لجلب الخوارزمية وتنفيذ مرتبط من مزود بشكل صريح.

    انظر "ALGORITHM FETCHING" في crypto(7) لمزيد من المعلومات حول الجلب.

    لا تحتاج كائنات المُعمِّي التي أرجعتها هذه الدوال إلى تحرير باستخدام EVP_CIPHER_free().

EVP_CIPHER_get_nid() و EVP_CIPHER_CTX_get_nid()
    تُرجع NID المُعمِّي عند تمرير بنية EVP_CIPHER أو EVP_CIPHER_CTX. قيمة NID الفعلية هي قيمة داخلية قد لا يكون لها مُعرّف كائن مطابق. تُرجع NID_undef في حال كان nid غير معروف أو إذا لم يُهيّأ المُعمِّي بشكل صحيح عبر استدعاء EVP_CipherInit.

EVP_CIPHER_CTX_set_flags() و EVP_CIPHER_CTX_clear_flags() و EVP_CIPHER_CTX_test_flags()
    يضبط ويمسح ويختبر أعلام ctx. انظر "FLAGS" أدناه لمزيد من المعلومات.

    بالنسبة للمُعمّيات المُقدّمة، يجب استدعاء EVP_CIPHER_CTX_set_flags() فقط بعد تعيين المُعمّي المُستَرجَع إلى ctx. يُوصى باستخدام "PARAMETERS" بدلاً من ذلك.

EVP_CIPHER_CTX_set_padding()
    يُفعّل أو يُعطّل الحشو. يجب استدعاء هذه الدالة بعد إعداد السياق للتشفير أو فك التشفير باستخدام EVP_EncryptInit_ex2() أو EVP_DecryptInit_ex2() أو EVP_CipherInit_ex2() أو EVP_CipherInit_SKEY(). مبدئيًا، تُحشى عمليات التشفير باستخدام حشو الكتل القياسي، ويُفحص الحشو ويُزال عند فك التشفير. إذا كان المعامل pad صفرًا، فلا يُجرى أي حشو، ويجب أن يكون إجمالي كمية البيانات المُعمّاة أو المُفكّكة مضاعفًا لحجم الكتلة، وإلا سيحدث خطأ. x يجب ألا يكون NULL.

EVP_CIPHER_get_key_length() و EVP_CIPHER_CTX_get_key_length()
    تُرجع طول مفتاح المُعمّي عند تمرير بنية EVP_CIPHER أو EVP_CIPHER_CTX. الثابت EVP_MAX_KEY_LENGTH هو أقصى طول مفتاح لجميع المُعمّيات. ملاحظة: على الرغم من أن EVP_CIPHER_get_key_length() ثابت لمُعمّي معين، إلا أن قيمة EVP_CIPHER_CTX_get_key_length() قد تختلف للمُعمّيات ذات طول المفتاح المتغير.

EVP_CIPHER_CTX_set_key_length()
    يُعيِّن طول مفتاح سياق المُعمّي. إذا كان المُعمّي بطول مفتاح ثابت، فإن محاولة تعيين طول المفتاح إلى أي قيمة غير القيمة الثابتة تُعد خطأ.

EVP_CIPHER_get_iv_length() و EVP_CIPHER_CTX_get_iv_length()
    تُرجع طول IV للمُعمّي عند تمرير EVP_CIPHER أو EVP_CIPHER_CTX. تُرجع صفرًا إذا كان المُعمّي لا يستخدم IV، أو إذا لم يُهيّأ المُعمّي بعد داخل EVP_CIPHER_CTX، أو إذا كان المُعمّي المُمرَّر NULL. الثابت EVP_MAX_IV_LENGTH هو أقصى طول IV لجميع المُعمّيات.

EVP_CIPHER_CTX_get_tag_length()
    تُرجع طول العلامة لمُعمّي AEAD عند تمرير EVP_CIPHER_CTX. تُرجع صفرًا إذا كان المُعمّي لا يدعم علامة. تُرجع قيمة مبدئية إذا لم يُعيَّن طول العلامة.

EVP_CIPHER_get_block_size() و EVP_CIPHER_CTX_get_block_size()
    تُرجع حجم الكتلة لمُعمّي عند تمرير بنية EVP_CIPHER أو EVP_CIPHER_CTX. الثابت EVP_MAX_BLOCK_LENGTH هو أيضًا أقصى طول كتلة لجميع المُعمّيات. تُرجع القيمة 0 إذا كان، مع EVP_CIPHER_get_block_size()، المُعمّي e هو NULL، أو، مع EVP_CIPHER_CTX_get_block_size()، السياق ctx هو NULL أو لم يُهيّأ بشكل صحيح باستدعاء EVP_CipherInit.

EVP_CIPHER_get_type() و EVP_CIPHER_CTX_get_type()
    تُرجع نوع المُعمّي أو السياق المُمرَّر. هذا "النوع" هو NID الفعلي لمُعرّف كائن المُعمّي، وبالتالي يتجاهل معاملات المُعمّي (RC2 بطول 40 بت وRC2 بطول 128 بت لهما نفس NID). إذا لم يكن للمُعمّي مُعرّف كائن أو لا يدعم ASN1، فستُرجع هذه الدالة NID_undef.

EVP_CIPHER_is_a()
    تُرجع 1 إذا كان cipher تطبيقًا لخوارزمية قابلة للتعرّف عليها باستخدام name، وإلا تُرجع 0. إذا كان cipher مُعمّيًا قديمًا (أي أنه قيمة مُرجَعة من دوال مثل EVP_aes128() بدلاً من نتيجة EVP_CIPHER_fetch())، فسيُؤخذ في الاعتبار فقط أسماء المُعمّيات المُسجّلة مع سياق المكتبة المبدئي (انظر OSSL_LIB_CTX(3)).

EVP_CIPHER_get0_name() و EVP_CIPHER_CTX_get0_name()
    تُرجع اسم المُعمّي أو السياق المُمرَّر. بالنسبة للمُعمّيات المُستَرجَعة ذات الأسماء المتعددة، يُرجع واحد منها فقط. انظر أيضًا EVP_CIPHER_names_do_all(). cipher يجب ألا يكون NULL.

EVP_CIPHER_names_do_all()
    يجتاز جميع الأسماء لـ cipher، ويستدعي fn مع كل اسم و data. هذا مفيد فقط مع EVP_CIPHER المُستَرجَعة.

EVP_CIPHER_get0_description()
    تُرجع وصفًا للمُعمّي، مخصصًا للعرض والاستهلاك البشري. الوصف متروك لتطبيق المُعمّي.

EVP_CIPHER_get0_provider()
    تُرجع مؤشر OSSL_PROVIDER إلى المُزوّد الذي يُطبّق EVP_CIPHER المُعطى.

EVP_CIPHER_CTX_get0_cipher()
    تُرجع بنية EVP_CIPHER عند تمرير بنية EVP_CIPHER_CTX. EVP_CIPHER_CTX_get1_cipher() مماثلة باستثناء أن الملكية تُنقل إلى المُستدعي. تُرجع كلتا الدالتين NULL عند الخطأ.

EVP_CIPHER_get_mode() و EVP_CIPHER_CTX_get_mode()
    أرجع نمط المُعمِّي الكتلي: EVP_CIPH_ECB_MODE، EVP_CIPH_CBC_MODE، EVP_CIPH_CFB_MODE، EVP_CIPH_OFB_MODE، EVP_CIPH_CTR_MODE، EVP_CIPH_GCM_MODE، EVP_CIPH_CCM_MODE، EVP_CIPH_XTS_MODE، EVP_CIPH_WRAP_MODE، EVP_CIPH_OCB_MODE أو EVP_CIPH_SIV_MODE. إذا كان المُعمِّي مُعمِّي تدفق، فسيُرجَع EVP_CIPH_STREAM_CIPHER.

EVP_CIPHER_get_flags()
    أرجع أي أعلام مرتبطة بالمُعمِّي. انظر "FLAGS" لقائمة بالأعلام المُعرَّفة حاليًا.

EVP_CIPHER_CTX_get_num() و EVP_CIPHER_CTX_set_num()
    يحصل أو يعيّن المُعامل "num" الخاص بالمُعمِّي لـ ctx المرتبط. تستخدم المُعمِّيات المضمنة هذا عادةً لتتبع مقدار الكتلة الأساسية الحالية التي "استُخدمت" بالفعل.

EVP_CIPHER_CTX_is_encrypting()
    يُبلغ عما إذا كان ctx يُستخدم للتعمية أو فك التعمية.

EVP_CIPHER_CTX_flags()
    كليّة مهملة تستدعي "EVP_CIPHER_get_flags(EVP_CIPHER_CTX_get0_cipher(ctx))". لا تستخدمها.

EVP_CIPHER_param_to_asn1()
    يُعيّن "المُعامل" AlgorithmIdentifier بناءً على المُعمِّي المُمرَّر. سيتضمن هذا عادةً أي مُعاملات و IV. يجب تعيين IV المُعمِّي (إن وُجد) عند إجراء هذه الاستدعاء. يجب إجراء هذه الاستدعاء قبل أن يُستخدم المُعمِّي فعليًا (قبل أي استدعاءات EVP_EncryptUpdate()، EVP_DecryptUpdate() على سبيل المثال). قد تفشل هذه الدالة إذا لم يكن للمُعمِّي أي دعم ASN1، أو إذا مُرِّر إليها مُعمِّي غير مُهيَّأ.

EVP_CIPHER_asn1_to_param()
    يُعيّن مُعاملات المُعمِّي بناءً على "مُعامل" ASN1 AlgorithmIdentifier. يعتمد التأثير الدقيق على المُعمِّي. في حالة RC2، على سبيل المثال، سيُعيّن IV وطول المفتاح الفعّال. يجب استدعاء هذه الدالة بعد تعيين نوع المُعمِّي الأساسي ولكن قبل تعيين المفتاح. على سبيل المثال، سيُستدعى EVP_CipherInit() مع تعيين IV والمفتاح إلى NULL، ثم يُستدعى EVP_CIPHER_asn1_to_param() وأخيرًا EVP_CipherInit() مرة أخرى مع جميع المُعاملات باستثناء المفتاح المُعيَّن إلى NULL. من الممكن أن تفشل هذه الدالة إذا لم يكن للمُعمِّي أي دعم ASN1 أو إذا تعذر تعيين المُعاملات (على سبيل المثال، طول المفتاح الفعّال لـ RC2 غير مدعوم).

EVP_CIPHER_CTX_rand_key()
    يُولّد مفتاحًا عشوائيًا بالطول المناسب بناءً على سياق المُعمِّي. يمكن لـ EVP_CIPHER توفير روتين توليد مفتاح عشوائي خاص به لدعم مفاتيح ذات شكل محدد. يجب أن يشير key إلى مخزن مؤقت لا يقل حجمه عن القيمة المُرجَعة بواسطة EVP_CIPHER_CTX_get_key_length().

EVP_CIPHER_do_all_provided()
    يجتاز جميع المُعمِّيات المُنفَّذة بواسطة جميع المزوّدات المُنشَّطة في سياق المكتبة المُعطى libctx، وبالنسبة لكل تنفيذ، يستدعي الدالة المُعطاة fn مع طريقة التنفيذ و arg المُعطى كوسيطة.

المعاملات
انظر OSSL_PARAM(3) لمعلومات حول تمرير المعاملات.

  مُعاملات EVP_CIPHER القابلة للحصول
عند استدعاء EVP_CIPHER_fetch()، فإنه يستدعي داخليًا EVP_CIPHER_get_params() ويخبئ النتائج.

يمكن استخدام EVP_CIPHER_get_params() مع مفاتيح OSSL_PARAM(3) التالية:

"mode" (OSSL_CIPHER_PARAM_MODE) <عدد صحيح غير مُوقَّع>
    يحصل على النمط لخوارزمية المُعمِّي المرتبطة cipher. انظر "EVP_CIPHER_get_mode() و EVP_CIPHER_CTX_get_mode()" لقائمة الأنماط الصالحة. استخدم EVP_CIPHER_get_mode() لاسترداد القيمة المُخبَّأة.

"keylen" (OSSL_CIPHER_PARAM_KEYLEN) <عدد صحيح غير مُوقَّع>
    يحصل على طول المفتاح لخوارزمية المُعمِّي المرتبطة cipher. استخدم EVP_CIPHER_get_key_length() لاسترداد القيمة المُخبَّأة.

"ivlen" (OSSL_CIPHER_PARAM_IVLEN) <عدد صحيح غير مُوقّع>
    يحصل على طول IV لخوارزمية التعمية المرتبطة cipher. استخدم EVP_CIPHER_get_iv_length() لاسترجاع القيمة المخبأة.

"blocksize" (OSSL_CIPHER_PARAM_BLOCK_SIZE) <عدد صحيح غير مُوقّع>
    يحصل على حجم الكتلة لخوارزمية التعمية المرتبطة cipher. يجب أن يكون حجم الكتلة 1 لمعميات التدفق. لاحظ أن حجم الكتلة لمعمٍ قد يختلف عن حجم الكتلة للأولية الأساسية للتعمية/فك التعمية. على سبيل المثال، AES في وضع CTR له حجم كتلة 1 (لأنه يعمل مثل معمي تدفق)، على الرغم من أن AES له حجم كتلة 16. استخدم EVP_CIPHER_get_block_size() لاسترجاع القيمة المخبأة.

"aead" (OSSL_CIPHER_PARAM_AEAD) <عدد صحيح>
    يحصل على 1 إذا كانت هذه خوارزمية تعمية AEAD، وإلا يحصل على 0. استخدم (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_AEAD_CIPHER) لاسترجاع القيمة المخبأة.

"custom-iv" (OSSL_CIPHER_PARAM_CUSTOM_IV) <عدد صحيح>
    يحصل على 1 إذا كانت خوارزمية التعمية cipher تملك IV مخصص، وإلا يحصل على 0. يُترك تخزين وتهيئة IV بالكامل للتنفيذ، إذا استُخدم IV مخصص. استخدم (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_CUSTOM_IV) لاسترجاع القيمة المخبأة.

"cts" (OSSL_CIPHER_PARAM_CTS) <عدد صحيح>
    يحصل على 1 إذا كانت خوارزمية التعمية cipher تستخدم سرقة النص المُعمّى، وإلا يحصل على 0. يُستخدم هذا حالياً للإشارة إلى أن المُعمّي هو لمرة واحدة يسمح فقط باستدعاء واحد لـ EVP_CipherUpdate(). استخدم (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_CTS) لاسترجاع القيمة المخبأة.

"tls-multi" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK) <عدد صحيح>
    يحصل على 1 إذا كانت خوارزمية التعمية cipher تدعم تداخل الكتل التعموية، وإلا يحصل على 0. التداخل هو تحسين ينطبق فقط على معميات TLS معينة. استخدم (EVP_CIPHER_get_flags(cipher) & EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK) لاسترجاع القيمة المخبأة.

"has-randkey" (OSSL_CIPHER_PARAM_HAS_RANDKEY) <عدد صحيح>
    يحصل على 1 إذا كانت خوارزمية التشفير cipher تدعم معامل EVP_CIPHER_CTX القابل للحصول عليه OSSL_CIPHER_PARAM_RANDOM_KEY. فقط DES و3DES يضبطان هذا على 1، وجميع المُعمِّيات الأخرى في OpenSSL تُرجع 0.

"فك-التعمية-فقط" (OSSL_CIPHER_PARAM_DECRYPT_ONLY) <عدد صحيح
    يحصل على 1 إذا كان تنفيذ خوارزمية التشفير cipher يدعم فقط عملية فك التشفير مثل مُعمِّيات 3DES في موفر fips. وإلا يحصل على 0 أو قد لا يكون المعامل موجودًا على الإطلاق.

  معاملات EVP_CIPHER_CTX القابلة للحصول عليها والتعيين
يمكن استخدام مفاتيح OSSL_PARAM(3) التالية مع كل من EVP_CIPHER_CTX_get_params() وEVP_CIPHER_CTX_set_params().

"الحشو" (OSSL_CIPHER_PARAM_PADDING) <عدد صحيح غير موقع>
    يحصل على أو يعيّن وضع الحشو لسياق التشفير ctx. يُفعّل الحشو إذا كانت القيمة 1، ويُعطّل إذا كانت القيمة 0. انظر أيضًا EVP_CIPHER_CTX_set_padding().

"العدد" (OSSL_CIPHER_PARAM_NUM) <عدد صحيح غير موقع>
    يحصل على أو يعيّن معامل "العدد" الخاص بالتشفير لسياق التشفير ctx. تستخدم المُعمِّيات المدمجة هذا عادةً لتتبع مقدار الكتلة الأساسية الحالية التي "استُخدمت" بالفعل. انظر أيضًا EVP_CIPHER_CTX_get_num() وEVP_CIPHER_CTX_set_num().

"keylen" (OSSL_CIPHER_PARAM_KEYLEN) <عدد صحيح غير مُوقَّع>
    يحصل على أو يعيّن طول المفتاح لسياق التشفير ctx. يجب ألا يتجاوز طول معامل "keylen" طول size_t. انظر أيضًا EVP_CIPHER_CTX_get_key_length() وEVP_CIPHER_CTX_set_key_length().

"الوسم" (OSSL_CIPHER_PARAM_AEAD_TAG) <سلسلة ثمانية>
    يحصل على أو يعيّن وسم AEAD لسياق التشفير المرتبط ctx. انظر "واجهة AEAD" في EVP_EncryptInit(3).

"وسم-الخط-الأنابيب" (OSSL_CIPHER_PARAM_PIPELINE_AEAD_TAG) <مؤشر ثماني>
    يحصل على أو يعيّن وسم AEAD عند استخدام خط أنابيب التشفير. يجب أن يشير المؤشر إلى مصفوفة من المخازن المؤقتة، حيث يُقرأ أو يُكتب وسم aead. يجب أن يكون حجم المصفوفة مساويًا لـ numpipes المستخدم في EVP_CipherPipelineEncryptInit() أو EVP_CipherPipelineDecryptInit().

"بتات-المفتاح" (OSSL_CIPHER_PARAM_RC2_KEYBITS) <عدد صحيح غير موقع>
    يحصل أو يضبط keybits الفعالة المستخدمة لمعمّي RC2. يجب ألا يتجاوز طول معامل "keybits" طول size_t.

"rounds" (OSSL_CIPHER_PARAM_ROUNDS) <عدد صحيح غير مُوقَّع>
    يحصل أو يضبط عدد الجولات المستخدمة لمعمّي. يُستخدم هذا بواسطة معمّي RC5.

"algorithm-id" (OSSL_CIPHER_PARAM_ALGORITHM_ID) <سلسلة ثمانيات>
    يُستخدم للحصول على AlgorithmIdentifier المُرمَّز بـ DER من تطبيق المعمّي. دوال مثل EVP_PKEY_CTX_get_algor(3) تستخدم هذا المعامل.

"algorithm-id-params" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS) <سلسلة ثمانيات>
    يُستخدم لتمرير معامل AlgorithmIdentifier المُرمَّز بـ DER إلى أو من تطبيق المعمّي. دوال مثل EVP_CIPHER_CTX_set_algor_params(3) و EVP_CIPHER_CTX_get_algor_params(3) تستخدم هذا المعامل.

"alg_id_params" (OSSL_CIPHER_PARAM_ALGORITHM_ID_PARAMS_OLD) <سلسلة ثمانيات>
    اسم مستعار مُهمَل لـ "algorithm-id-params"، يُستخدم فقط بواسطة EVP_CIPHER_param_to_asn1(3) و EVP_CIPHER_asn1_to_param(3).

"cts_mode" (OSSL_CIPHER_PARAM_CTS_MODE) <سلسلة UTF8>
    يحصل أو يضبط وضع سرقة نص المعمّي. لجميع الأوضاع، حجم المخرجات هو نفس حجم المدخلات. يجب أن يكون طول المدخلات أكبر من أو يساوي حجم الكتلة. (حجم الكتلة لـ AES و CAMELLIA هو 16 بايت).

    القيم الصالحة للوضع هي:

    "CS1"
        البديل NIST لسرقة نص المعمّي. لأطوال المدخلات التي هي مضاعفات حجم الكتلة، يكون مكافئًا لاستخدام معمّي "AES-XXX-CBC" أو "CAMELLIA-XXX-CBC"، وإلا فإن كتلة نص المعمّي قبل الأخيرة هي كتلة جزئية.

    "CS2"
        بالنسبة لأطوال الإدخال التي تكون مضاعفات حجم الكتلة، فإنها تعادل استخدام المُعمِّي "AES-XXX-CBC" أو "CAMELLIA-XXX-CBC"، وإلا فهي نفس وضع "CS3".

    "CS3"
        المتغير Kerberos5 لسرقة نص المُعمِّي الذي يُبدل دائمًا آخر كتلة نص معمّي مع الكتلة السابقة (والتي قد تكون كتلة جزئية أو كاملة حسب طول الإدخال). إذا كان طول الإدخال كتلة كاملة واحدة تمامًا، فإن هذا يعادل استخدام المُعمِّي "AES-XXX-CBC" أو "CAMELLIA-XXX-CBC".

    المبدئي هو "CS1". هذا مدعوم فقط لـ "AES-128-CBC-CTS"، "AES-192-CBC-CTS"، "AES-256-CBC-CTS"، "CAMELLIA-128-CBC-CTS"، "CAMELLIA-192-CBC-CTS" و "CAMELLIA-256-CBC-CTS".

"tls1multi_interleave" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) <عدد صحيح غير موقع>
    يُعيِّن أو يحصل على عدد السجلات المُرسلة دفعة واحدة لعملية مُعمِّي متعدد الكتل tls1 (إما 4 أو 8 سجلات).

  معاملات EVP_CIPHER_CTX القابلة للحصول
يمكن استخدام مفاتيح OSSL_PARAM(3) التالية مع EVP_CIPHER_CTX_get_params():

"ivlen" (OSSL_CIPHER_PARAM_IVLEN و <OSSL_CIPHER_PARAM_AEAD_IVLEN) <عدد صحيح غير موقع>
    يحصل على طول IV لسياق المُعمِّي ctx. يجب ألا يتجاوز طول معامل "ivlen" طول size_t. انظر أيضًا EVP_CIPHER_CTX_get_iv_length().

"iv" (OSSL_CIPHER_PARAM_IV) <سلسلة ثمانية أو مؤشر ثماني>
    يحصل على IV المُستخدم لتهيئة سياق المُعمِّي المرتبط ctx. انظر أيضًا EVP_CIPHER_CTX_get_original_iv().

"updated-iv" (OSSL_CIPHER_PARAM_UPDATED_IV) <سلسلة ثمانية أو مؤشر ثماني>
    يحصل على حالة pseudo-IV المُحدَّثة لسياق المُعمِّي المرتبط، على سبيل المثال، كتلة النص المُعمَّي السابقة لوضع CBC أو قيمة IV المُعمَّاة تكراريًا لوضع OFB. لاحظ أن الوصول عبر المؤشر الثماني مُهمَل ويُوفَّر فقط للتوافق العكسي مع واجهات برمجة تطبيقات libcrypto التاريخية. انظر أيضًا EVP_CIPHER_CTX_get_updated_iv().

"randkey" (OSSL_CIPHER_PARAM_RANDOM_KEY) <سلسلة ثمانية>
    يحصل على مفتاح مُولَّد آليًا خاص بالتطبيق لسياق المُعمِّي المرتبط ctx. هذا مدعوم حاليًا فقط بواسطة DES و 3DES (اللتان تضبطان المفتاح على تكافؤ فردي).

"taglen" (OSSL_CIPHER_PARAM_AEAD_TAGLEN) <عدد صحيح غير مُوقَّع>
    يحصل على طول الوسم المستخدم لمعمّي AEAD لسياق المُعمِّي المرتبط ctx. يحصل على قيمة مبدئية إذا لم يُضبط. لا يجب أن يتجاوز طول معامل "taglen" طول size_t. انظر أيضًا EVP_CIPHER_CTX_get_tag_length().

"tlsaadpad" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD) <عدد صحيح غير مُوقَّع>
    يحصل على طول الوسم الذي يُضاف إلى سجل TLS لوسم AEAD لسياق المُعمِّي المرتبط ctx. لا يجب أن يتجاوز طول معامل "tlsaadpad" طول size_t.

"tlsivgen" (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN) <سلسلة محارف ثمانية>
    يحصل على حقل الاستدعاء المُولَّد للتعمية. يمكن استدعاؤه فقط بعد ضبط "tlsivfixed". يُستخدم هذا فقط لوضع GCM.

"tls1multi_enclen" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN) <عدد صحيح غير مُوقَّع>
    يحصل على الطول الإجمالي للسجل المُعاد من عملية "tls1multi_enc".

"tls1multi_maxbufsz" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE) <عدد صحيح غير مُوقَّع>
    يحصل على أقصى طول سجل لعملية معمّي متعدد الكتل TLS1. لا يجب أن يتجاوز طول معامل "tls1multi_maxbufsz" طول size_t.

"tls1multi_aadpacklen" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) <عدد صحيح غير مُوقَّع>
    يحصل على نتيجة تشغيل عملية "tls1multi_aad".

"tls-mac" (OSSL_CIPHER_PARAM_TLS_MAC) <مؤشر ثماني>
    يُستخدم لتمرير بيانات MAC الخاصة بـ TLS.

"fips-indicator" (OSSL_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) <عدد صحيح>
    يُستخدم هذا الخيار من قبل موفر FIPS الخاص بـ OpenSSL.

    دالة استرجاع تُرجع 1 إذا كانت العملية معتمدة من FIPS، أو 0 بخلاف ذلك. يُمكن استخدامها بعد استدعاء عملية تعمية نهائية مثل EVP_EncryptFinal_ex(). قد تُرجع 0 إذا تم تعيين خيار "encrypt-check" إلى 0.

"iv-generated" (OSSL_CIPHER_PARAM_AEAD_IV_GENERATED) <عدد صحيح غير موقع>
    مؤشر يُرجع 1 إذا تم إنشاء IV داخليًا أثناء التعمية، أو O بخلاف ذلك. يُمكن استخدامه من قبل معميات GCM بعد استدعاء عملية تعمية نهائية مثل EVP_EncryptFinal_ex(). يجب على GCM إنشاء IV داخليًا إذا لم يُحدد IV أثناء استدعاء تهيئة التعمية مثل EVP_CipherInit_ex(). راجع FIPS 140-3 IG C.H للحصول على معلومات متعلقة بمتطلبات IV.

  معاملات EVP_CIPHER_CTX القابلة للضبط
يمكن استخدام المفاتيح OSSL_PARAM(3) التالية مع EVP_CIPHER_CTX_set_params():

"mackey" (OSSL_CIPHER_PARAM_AEAD_MAC_KEY) <سلسلة ثمانية>
    يضبط مفتاح MAC المستخدم من قبل معميات AEAD المركبة مثل AES-CBC-HMAC-SHA256.

"speed" (OSSL_CIPHER_PARAM_SPEED) <عدد صحيح غير موقع>
    يضبط خيار السرعة لسياق التعمية المرتبط. هذا مدعوم فقط من قبل معميات AES SIV التي تمنع العمليات المتعددة مبدئيًا. ضبط "speed" إلى 1 يسمح بإجراء عملية تعمية أو فك تعمية أخرى. يُستخدم هذا لاختبار الأداء.

"use-bits" (OSSL_CIPHER_PARAM_USE_BITS) <عدد صحيح غير موقع>
    يحدد ما إذا كان طول الإدخال inl المُمرر إلى EVP_EncryptUpdate() وEVP_DecryptUpdate() وEVP_CipherUpdate() هو عدد البتات أم عدد البايتات. تعيين "use-bits" إلى 1 يستخدم البتات. المبدئي هو بالبايتات. يُستخدم هذا فقط لمعميات CFB1.

    يمكن تعيين هذا باستخدام EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPH_FLAG_LENGTH_BITS).

"tls-version" (OSSL_CIPHER_PARAM_TLS_VERSION) <عدد صحيح>
    يُعيِّن إصدار TLS.

"tls-mac-size" (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <عدد صحيح غير مُوقَّع>
    يُعيِّن حجم MAC لـ TLS.

"tlsaad" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) <سلسلة ثمانيات>
    يُعيِّن معلومات AAD لـ TLSv1.2 لسياق التعمية المرتبط ctx. معلومات AAD لـ TLSv1.2 طولها دائمًا 13 بايت وهي كما هو مُعرَّف لحقل "additional_data" الموصوف في القسم 6.2.3.3 من RFC5246.

"tlsivfixed" (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED) <سلسلة ثمانيات>
    يُعيِّن الجزء الثابت من IV لتعمية AEAD المُستخدمة في تعمية/فك تعمية سجل TLS لسياق التعمية المرتبط. تعمية/فك تعمية سجل TLS تحدث دائمًا "في المكان" بحيث تكون مخازن الإدخال والإخراج دائمًا في نفس موقع الذاكرة. IVs لـ AEAD في TLSv1.2 تتكون من جزء "ثابت" ضمني وجزء صريح يختلف مع كل سجل. تعيين IV ثابت لـ TLS يُغيِّر التعمية لتعمية/فك تعمية سجلات TLS. تُعمَّى/تُفك تعمية سجلات TLS باستخدام استدعاء واحد لـ OSSL_FUNC_cipher_cipher لكل سجل. لفك تعمية سجل، ستكون البايتات الأولى من مخزن الإدخال هي الجزء الصريح من IV والبايتات الأخيرة من مخزن الإدخال ستكون علامة AEAD. طول الجزء الصريح من IV وطول العلامة سيعتمدان على التعمية المُستخدمة وسيُعرَّفان في RFC لمجموعة التعمية ذات الصلة. للسماح بفك التعمية "في المكان"، يجب كتابة مخرجات النص الصريح إلى نفس الموقع في مخزن الإخراج الذي قُرئ منه حمولة النص المُعمَّى، أي مباشرة بعد IV الصريح.

    عند تعمية سجل، يجب أن تكون البايتات الأولى من مخزن الإدخال فارغة لإتاحة مساحة لـ IV الصريح، وكذلك البايتات الأخيرة حيث ستُكتب العلامة. سيتضمن طول مخزن الإدخال طول IV الصريح والحمولة وبايتات العلامة. يجب على تطبيق التعمية توليد IV الصريح وكتابته في بداية مخزن الإخراج، وإجراء تعمية "في المكان" للحمولة وكتابتها إلى مخزن الإخراج، وأخيرًا إضافة العلامة إلى نهاية مخزن الإخراج.

    سواءً عند التعمية أو فك التعمية، يجب أن تكون القيمة المكتوبة إلى *outl في استدعاء OSSL_FUNC_cipher_cipher هي طول الحمولة باستثناء طول IV الصريح وطول العلامة.

"tlsivinv" (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV) <سلسلة ثمانيات>
    يُعيِّن حقل الاستدعاء المُستخدم لفك التعمية. يمكن استدعاؤه فقط بعد تعيين "tlsivfixed". يُستخدم هذا فقط لوضع GCM.

"tls1multi_enc" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) <سلسلة ثمانيات>
    يُشغّل عملية تعمية TLS1 متعددة الكتل لمعمٍ واعٍ بـTLS1 يدعم إرسال 4 أو 8 سجلات دفعة واحدة. يُنفّذ المُعمّي مرحلتي MAC والتعمية ويُشكّل رؤوس السجلات بنفسه. يُزوّد "tls1multi_enc" مخزن الإخراج لعملية التعمية، ويجب أيضًا ضبط "tls1multi_encin" و"tls1multi_interleave" لتزويد القيم لعملية التعمية.

"tls1multi_encin" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) <سلسلة ثمانية>
    يُزوّد البيانات المراد تعميتها لعملية معمّي متعدد الكتل TLS1.

"tls1multi_maxsndfrag" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT) <عدد صحيح غير مُوقّع>
    يضبط الحجم الأقصى لشظية الإرسال لعملية معمّي متعدد الكتل TLS1. يجب ضبطه قبل استخدام "tls1multi_maxbufsz". يجب ألا يتجاوز طول معامل "tls1multi_maxsndfrag" طول size_t.

"tls1multi_aad" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) <سلسلة ثمانية>
    يضبط البيانات الإضافية المُوثّقة المستخدمة في عملية معمّي متعدد الكتل TLS1. تتكون البيانات المُزوّدة من 13 بايت من بيانات السجل تحتوي على: البايتات 0-7: الرقم التسلسلي للسجل الأول البايت 8: نوع السجل البايت 9-10: إصدار البروتوكول البايت 11-12: طول الإدخال (دائمًا 0)

    يجب أيضًا ضبط "tls1multi_interleave" لهذه العملية.

"xts_standard" (OSSL_CIPHER_PARAM_XTS_STANDARD) <سلسلة UTF8>
    يضبط معيار XTS لاستخدامه مع خوارزمية SM4-XTS. لوضع XTS تطبيقان، أحدهما مُوحّد في IEEE Std. 1619-2007 ويُستخدم على نطاق واسع (مثل XTS AES)، والآخر مُقترح مؤخرًا (GB/T 17964-2021 المُنفّذ في مايو 2022) ويُستخدم حاليًا فقط في SM4.

    الفرق الرئيسي بينهما هو الضرب بالعنصر البدائي α لحساب قيم التعديل. لاحظ IEEE Std 1619-2007 أن الضرب "هو إزاحة لليسار لكل بايت بمقدار بت واحد مع حمل ينتشر من بايت إلى التالي"، مما يعني أنه في كل بايت، البت الأيسر هو البت الأكثر أهمية. لكن في GB/T 17964-2021، البت الأيمن هو البت الأكثر أهمية، وبالتالي يصبح الضرب إزاحة لليمين لكل بايت بمقدار بت واحد مع حمل ينتشر من بايت إلى التالي.

    القيم الصالحة للوضع هي:

    "GB"
        البديل GB/T 17964-2021 لخوارزمية SM4-XTS.

    "IEEE"
        البديل IEEE Std. 1619-2007 لخوارزمية SM4-XTS.

    القيمة المبدئية هي "GB".

"encrypt-check" (OSSL_CIPHER_PARAM_FIPS_ENCRYPT_CHECK) <عدد صحيح>
    يُستخدم هذا الخيار من قبل موفر FIPS الخاص بـ OpenSSL.

    إذا كان مطلوبًا، يجب تعيين هذا المعامل مبكرًا عبر دالة تهيئة تعمية مثل EVP_EncryptInit_ex2(). القيمة المبدئية 1 تُسبب خطأً عند تشغيل عملية تعمية. تعيين هذا إلى 0 سيتجاهل الخطأ ويُعيِّن "مؤشر fips" المعتمد إلى 0. هذا الخيار يُخلّ بالامتثال لـ FIPS إذا تسبب في إرجاع "مؤشر fips" المعتمد القيمة 0.

عناصر التحكم
التوافقات من معرفات EVP_CIPHER_CTX_ctrl() إلى المعاملات مُدرجة في القسم التالي. راجع قسم "المعاملات" لمزيد من التفاصيل.

يمكن استخدام EVP_CIPHER_CTX_ctrl() لإرسال عناصر التحكم القياسية التالية:

EVP_CTRL_AEAD_SET_IVLEN و EVP_CTRL_GET_IVLEN
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() و EVP_CIPHER_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "ivlen" (OSSL_CIPHER_PARAM_IVLEN).

EVP_CTRL_AEAD_SET_IV_FIXED
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "tlsivfixed" (OSSL_CIPHER_PARAM_AEAD_TLS1_IV_FIXED).

EVP_CTRL_AEAD_SET_MAC_KEY
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "mackey" (OSSL_CIPHER_PARAM_AEAD_MAC_KEY).

EVP_CTRL_AEAD_SET_TAG و EVP_CTRL_AEAD_GET_TAG
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() و EVP_CIPHER_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "tag" (OSSL_CIPHER_PARAM_AEAD_TAG).

EVP_CTRL_CCM_SET_L
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "ivlen" (OSSL_CIPHER_PARAM_IVLEN) بقيمة (15 - L)

EVP_CTRL_COPY
    لا يوجد تعيين OSSL_PARAM لهذا. استخدم EVP_CIPHER_CTX_copy() بدلاً من ذلك.

EVP_CTRL_GCM_SET_IV_INV
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "tlsivinv" (OSSL_CIPHER_PARAM_AEAD_TLS1_SET_IV_INV).

EVP_CTRL_RAND_KEY
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "randkey" (OSSL_CIPHER_PARAM_RANDOM_KEY).

EVP_CTRL_SET_KEY_LENGTH
    عند استخدامه مع EVP_CIPHER مُسترد، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "keylen" (OSSL_CIPHER_PARAM_KEYLEN).

EVP_CTRL_SET_RC2_KEY_BITS و EVP_CTRL_GET_RC2_KEY_BITS
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() و EVP_CIPHER_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "keybits" (OSSL_CIPHER_PARAM_RC2_KEYBITS).

EVP_CTRL_SET_RC5_ROUNDS و EVP_CTRL_GET_RC5_ROUNDS
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() و EVP_CIPHER_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "rounds" (OSSL_CIPHER_PARAM_ROUNDS).

EVP_CTRL_SET_SPEED
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "speed" (OSSL_CIPHER_PARAM_SPEED).

EVP_CTRL_GCM_IV_GEN
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "tlsivgen" (OSSL_CIPHER_PARAM_AEAD_TLS1_GET_IV_GEN).

EVP_CTRL_AEAD_TLS1_AAD
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح "tlsaad" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD) متبوعًا بـ EVP_CIPHER_CTX_get_params() بمفتاح "tlsaadpad" (OSSL_CIPHER_PARAM_AEAD_TLS1_AAD_PAD).

EVP_CTRL_TLS1_1_MULTIBLOCK_MAX_BUFSIZE
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() مع عنصر OSSL_PARAM(3) بمفتاح OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_SEND_FRAGMENT متبوعًا بـ EVP_CIPHER_CTX_get_params() بمفتاح "tls1multi_maxbufsz" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_MAX_BUFSIZE).

EVP_CTRL_TLS1_1_MULTIBLOCK_AAD
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() مع عناصر OSSL_PARAM(3) بمفاتيح "tls1multi_aad" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD) و "tls1multi_interleave" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) متبوعًا بـ EVP_CIPHER_CTX_get_params() بمفاتيح "tls1multi_aadpacklen" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_AAD_PACKLEN) و "tls1multi_interleave" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE).

EVP_CTRL_TLS1_1_MULTIBLOCK_ENCRYPT
    عند استخدامها مع EVP_CIPHER مأخوذ، تُستدعى EVP_CIPHER_CTX_set_params() مع عناصر OSSL_PARAM(3) بمفاتيح "tls1multi_enc" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC) و "tls1multi_encin" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_IN) و "tls1multi_interleave" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_INTERLEAVE) متبوعًا بـ EVP_CIPHER_CTX_get_params() بمفتاح "tls1multi_enclen" (OSSL_CIPHER_PARAM_TLS1_MULTIBLOCK_ENC_LEN).

الأعلام
يمكن استخدام EVP_CIPHER_CTX_set_flags() و EVP_CIPHER_CTX_clear_flags() و EVP_CIPHER_CTX_test_flags() لمعالجة واختبار أعلام EVP_CIPHER_CTX هذه:

EVP_CIPH_NO_PADDING
    مُستخدم بواسطة EVP_CIPHER_CTX_set_padding().

    انظر أيضًا "معاملات EVP_CIPHER_CTX القابلة للجلب والإعداد" "padding"

EVP_CIPH_FLAG_LENGTH_BITS
    انظر "معاملات EVP_CIPHER_CTX القابلة للإعداد" "use-bits".

EVP_CIPHER_CTX_FLAG_WRAP_ALLOW
    مُستخدم للأغراض القديمة فقط. كان هذا العلم بحاجة إلى التعيين للإشارة إلى أن المُعمِّي تعامل مع اللف.

يستخدم EVP_CIPHER_flags() الأعلام التالية التي لها تعيينات إلى "معاملات EVP_CIPHER القابلة للجلب":

EVP_CIPH_FLAG_AEAD_CIPHER
    انظر "معاملات EVP_CIPHER القابلة للجلب" "aead".

EVP_CIPH_CUSTOM_IV
    انظر "معاملات EVP_CIPHER القابلة للجلب" "custom-iv".

EVP_CIPH_FLAG_CTS
    انظر "معاملات EVP_CIPHER القابلة للاستحصال" "cts".

EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK;
    انظر "معاملات EVP_CIPHER القابلة للاستحصال" "tls-multi".

EVP_CIPH_RAND_KEY
    انظر "معاملات EVP_CIPHER القابلة للاستحصال" "has-randkey".

EVP_CIPHER_flags() تستخدم الأعلام التالية لأغراض الإرث فقط:

EVP_CIPH_VARIABLE_LENGTH
EVP_CIPH_FLAG_CUSTOM_CIPHER
EVP_CIPH_ALWAYS_CALL_INIT
EVP_CIPH_CTRL_INIT
EVP_CIPH_CUSTOM_KEY_LENGTH
EVP_CIPH_CUSTOM_COPY
EVP_CIPH_FLAG_DEFAULT_ASN1
    انظر EVP_CIPHER_meth_set_flags(3) لمزيد من المعلومات المتعلقة بالأعلام أعلاه.

القيم المُرجعة
EVP_CIPHER_fetch() تُرجع مؤشرًا إلى EVP_CIPHER عند النجاح وNULL عند الفشل.

EVP_CIPHER_up_ref() تُرجع 1 عند النجاح أو 0 بخلاف ذلك.

EVP_CIPHER_CTX_new() تُرجع مؤشرًا إلى EVP_CIPHER_CTX مُنشأ حديثًا عند النجاح وNULL عند الفشل.

EVP_CIPHER_CTX_dup() تُرجع EVP_CIPHER_CTX جديدًا إذا نجحت أو NULL عند الفشل.

EVP_CIPHER_CTX_copy() تُرجع 1 إذا نجحت أو 0 عند الفشل.

EVP_EncryptInit_ex2() وEVP_EncryptUpdate() وEVP_EncryptFinal_ex() تُرجع 1 عند النجاح و0 عند الفشل.

EVP_DecryptInit_ex2() وEVP_DecryptUpdate() تُرجع 1 عند النجاح و0 عند الفشل. EVP_DecryptFinal_ex() تُرجع 0 إذا فشل فك التعمية أو 1 عند النجاح.

EVP_CipherInit_ex2() وEVP_CipherInit_SKEY() وEVP_CipherUpdate() تُرجع 1 عند النجاح و0 عند الفشل. EVP_CipherFinal_ex() تُرجع 0 لفشل التعمية/فك التعمية أو 1 عند النجاح.

EVP_Cipher() تُرجع 1 عند النجاح و<= 0 عند الفشل، إذا لم يُضبط العلم EVP_CIPH_FLAG_CUSTOM_CIPHER للمُعمِّي، أو إذا لم يُهيأ المُعمِّي عبر استدعاء لـ EVP_CipherInit_ex2. EVP_Cipher() تُرجع عدد البايتات المكتوبة إلى out للتعمية/فك التعمية، أو عدد البايتات المُوثَّقة في استدعاء يُحدد AAD لمُعمِّي AEAD، إذا ضُبط العلم EVP_CIPH_FLAG_CUSTOM_CIPHER للمُعمِّي.

EVP_CIPHER_can_pipeline() تُرجع 1 إذا أمكن استخدام المُعمِّي في خط أنابيب، 0 بخلاف ذلك.

EVP_CipherPipelineEncryptInit() وEVP_CipherPipelineDecryptInit() تُرجع 1 عند النجاح و0 عند الفشل.

EVP_CipherPipelineUpdate() وEVP_CipherPipelineFinal() تُرجع 1 عند النجاح و0 عند الفشل.

EVP_CIPHER_CTX_reset() تُرجع 1 عند النجاح و0 عند الفشل.

EVP_get_cipherbyname() وEVP_get_cipherbynid() وEVP_get_cipherbyobj() تُرجع بنية EVP_CIPHER أو NULL عند الخطأ.

EVP_CIPHER_get_nid() وEVP_CIPHER_CTX_get_nid() تُرجع NID.

EVP_CIPHER_get_block_size() و EVP_CIPHER_CTX_get_block_size() يُرجعان حجم الكتلة، أو 0 عند الخطأ.

EVP_CIPHER_get_key_length() و EVP_CIPHER_CTX_get_key_length() يُرجعان طول المفتاح.

EVP_CIPHER_CTX_set_padding() يُرجع دائمًا 1.

EVP_CIPHER_get_iv_length() و EVP_CIPHER_CTX_get_iv_length() يُرجعان طول IV، صفر إذا لم يستخدم المُعمِّي IV وقيمة سالبة عند الخطأ.

EVP_CIPHER_CTX_get_tag_length() يُرجع طول الوسم أو صفر إذا لم يستخدم المُعمِّي وسمًا.

EVP_CIPHER_get_type() و EVP_CIPHER_CTX_get_type() يُرجعان NID لمُعرِّف كائن المُعمِّي أو NID_undef إذا لم يكن له مُعرِّف كائن مُعرَّف.

EVP_CIPHER_CTX_cipher() يُرجع بنية EVP_CIPHER.

EVP_CIPHER_CTX_get_num() يُرجع قيمة num غير سالبة أو EVP_CTRL_RET_UNSUPPORTED إذا لم يدعم التنفيذ الاستدعاء أو عند أي خطأ آخر.

EVP_CIPHER_CTX_set_num() يُرجع 1 عند النجاح و0 إذا لم يدعم التنفيذ الاستدعاء أو عند أي خطأ آخر.

EVP_CIPHER_CTX_is_encrypting() يُرجع 1 إذا كان ctx مُهيَّأً للتشفير و0 خلاف ذلك.

EVP_CIPHER_param_to_asn1() و EVP_CIPHER_asn1_to_param() يُرجعان أكبر من صفر للنجاح وصفرًا أو عددًا سالبًا عند الفشل.

EVP_CIPHER_CTX_rand_key() يُرجع 1 للنجاح وصفرًا أو عددًا سالبًا للفشل.

EVP_CIPHER_names_do_all() يُرجع 1 إذا استُدعي رد النداء لجميع الأسماء. قيمة إرجاع 0 تعني أن رد النداء لم يُستدعَ لأي اسم.

EVP_CIPHER_get_params() و EVP_CIPHER_CTX_get_params() و EVP_CIPHER_CTX_set_params() يُرجعان 1 للنجاح و0 للفشل.

سرد المُعمِّيات
جميع الخوارزميات لها طول مفتاح ثابت ما لم يُذكر خلاف ذلك.

ارجع إلى "انظر أيضًا" للحصول على القائمة الكاملة للمُعمِّيات المتاحة عبر واجهة EVP.

EVP_enc_null()
    مُعمِّي فارغ: لا يفعل شيئًا.

واجهة AEAD
واجهة EVP لأوضاع التعمية المُوثَّق مع البيانات المرتبطة (AEAD) تم تغييرها بشكل طفيف، ويتم دعم العديد من عمليات ctrl الإضافية اعتمادًا على الوضع المُحدد.

لتحديد بيانات مُوثَّقة إضافية (AAD)، يجب إجراء استدعاء لـ EVP_CipherUpdate() أو EVP_EncryptUpdate() أو EVP_DecryptUpdate() مع تعيين معامل الإخراج out إلى NULL. في هذه الحالة، عند النجاح، يتم تعيين المعامل outl إلى عدد وحدات البايت الخاصة بـ AAD التي تمت معالجتها في ذلك الاستدعاء (أي قيمة inl)، ولا يتضمن أي وحدات بايت من النص العادي أو النص المُعمَّى تمت معالجتها بواسطة استدعاءات أخرى.

إذا لم يتم استخدام AAD، يمكن حذف هذا الاستدعاء. راجع الملاحظات الخاصة بالوضع أدناه لأي استثناءات.

عند فك التعمية، تشير القيمة المُرجَعة من EVP_DecryptFinal() أو EVP_CipherFinal() إلى ما إذا كانت العملية ناجحة. إذا لم تشير إلى النجاح، فقد فشلت عملية الاستيثاق، ويجب عدم استخدام أي بيانات إخراج لأنها تالفة.

يرجى ملاحظة أن عدد وحدات البايت المُوثَّقة المُرجَعة بواسطة EVP_CipherUpdate() يعتمد على المُعمِّي المستخدم. المُعمِّيات التدفقية، مثل ChaCha20 أو المُعمِّيات في وضع GCM، يمكنها التعامل مع بايت واحد في كل مرة، مما يؤدي إلى حجم "كتلة" فعال يبلغ 1. على العكس، يجب على المُعمِّيات في وضع OCB معالجة البيانات كتلة واحدة في كل مرة، ويتم إرجاع حجم الكتلة.

بغض النظر عن الحجم المُرجَع، من الآمن تمرير بيانات غير مُبطَّنة إلى استدعاء EVP_CipherUpdate() في عملية واحدة.

  وضعا GCM وOCB
يتم دعم عناصر ctrl التالية في وضعي GCM وOCB.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
    يضبط طول IV. يمكن إجراء هذا الاستدعاء فقط قبل تحديد IV. إذا لم يتم استدعاؤه، يتم استخدام طول IV مبدئي.

    بالنسبة لـ GCM AES وOCB AES، المبدئي هو 12 (أي 96 بت). بالنسبة لوضع OCB، الحد الأقصى هو 15.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
    يكتب "taglen" بايت من قيمة الوسم إلى المخزن المُشار إليه بواسطة "tag". يمكن إجراء هذا الاستدعاء فقط عند تعمية البيانات وبعد معالجة جميع البيانات (مثلًا بعد استدعاء EVP_EncryptFinal()).

    بالنسبة لـ OCB، يجب أن يكون "taglen" إما 16 أو القيمة المُحددة سابقًا عبر EVP_CTRL_AEAD_SET_TAG.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
    عند فك التعمية، يضبط هذا الاستدعاء الوسم المتوقع إلى "taglen" بايت من "tag". يجب أن يكون "taglen" بين 1 و16 شاملًا. يجب ضبط الوسم قبل أي استدعاء لـ EVP_DecryptFinal() أو EVP_DecryptFinal_ex().

    بالنسبة لـ GCM، هذا الاستدعاء صالح فقط عند فك تعمية البيانات.

    بالنسبة لـ OCB، هذا الاستدعاء صالح عند فك تعمية البيانات لضبط الوسم المتوقع، وعند التعمية لضبط طول الوسم المطلوب.

    في وضع OCB، استدعاء هذا مع تعيين "tag" إلى "NULL" يضبط طول الوسم. يمكن ضبط طول الوسم فقط قبل تحديد IV. إذا لم يتم استدعاء هذا قبل ضبط IV، فسيتم استخدام طول وسم مبدئي.

    بالنسبة لـ OCB AES، طول الوسم المبدئي هو 16 (أي 128 بت). وهو أيضًا أقصى طول وسم لـ OCB.

  وضع CCM
واجهة EVP لوضع CCM مشابهة لواجهة وضع GCM ولكن مع بعض المتطلبات الإضافية وقيم ctrl مختلفة.

بالنسبة لوضع CCM، يجب تمرير الطول الإجمالي للنص الصريح أو النص المُعمَّى إلى EVP_CipherUpdate() أو EVP_EncryptUpdate() أو EVP_DecryptUpdate() مع ضبط معاملي الإخراج والإدخال (in و out) على NULL وتمرير الطول في معامل inl.

تُدعم عناصر التحكم ctrl التالية في وضع CCM.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
    يُجرى هذا الاستدعاء لتعيين قيمة الوسم CCM المتوقعة عند فك التعمية أو طول الوسم (مع ضبط معامل "tag" على NULL) عند التعمية. يُشار غالبًا إلى طول الوسم بالرمز M. إذا لم يُعيّن، تُستخدم قيمة مبدئية (12 لـ AES). عند فك التعمية، يجب تعيين الوسم قبل تمرير البيانات المراد فك تعميتها، ولكن كما في وضعي GCM و OCB، يمكن تعيينه بعد تمرير البيانات المُوثقة الإضافية (انظر "واجهة AEAD").

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
    يُعيّن قيمة L لوضع CCM. إذا لم تُعيّن، تُستخدم قيمة مبدئية (8 لـ AES).

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
    يُعيّن طول العدد العشوائي (IV) لوضع CCM. يمكن إجراء هذا الاستدعاء فقط قبل تحديد قيمة العدد العشوائي. يُعطى طول العدد العشوائي بالعلاقة 15 - L، لذا فهو 7 مبدئيًا لـ AES.

  وضع SIV
يندرج كل من المُعمّيين AES-SIV و AES-GCM-SIV تحت هذا الوضع.

بالنسبة لمُعمّيات وضع SIV، يُعدّل سلوك واجهة EVP بشكل طفيف وتُدعم عدة عمليات تحكم إضافية.

لتحديد أي بيانات مُوثقة إضافية (AAD) و/أو عدد عشوائي، يجب إجراء استدعاء لـ EVP_CipherUpdate() أو EVP_EncryptUpdate() أو EVP_DecryptUpdate() مع ضبط معامل الإخراج out على NULL.

ينص RFC5297 على أن العدد العشوائي هو آخر جزء من AAD قبل حدوث التعمية/فك التعمية الفعلي. لا تفرق واجهة API بين العدد العشوائي و AAD الآخر.

عند فك التعمية، تشير قيمة الإرجاع لـ EVP_DecryptFinal() أو EVP_CipherFinal() إلى نجاح العملية. إذا لم تُشر إلى النجاح، فقد فشلت عملية الاستيثاق ويجب عدم استخدام أي بيانات إخراج لأنها تالفة.

لا تخزن واجهة API متجه التهيئة الاصطناعي (SIV) في النص المُعمَّى. بدلاً من ذلك، يُخزن كوسم داخل EVP_CIPHER_CTX. يجب استرداد SIV من السياق بعد التعمية، وتعيينه في السياق قبل فك التعمية.

يختلف هذا عن RFC5297 في أن مخرجات التعمية من عملية التعمية، ومدخلات التعمية إلى عملية فك التعمية، لا تحتوي على SIV. يعني هذا أيضًا أن أطوال النص الصريح والنص المُعمَّى متطابقة.

تُدعم عناصر التحكم التالية في وضع SIV، وتُستخدم للحصول على متجه التهيئة الاصطناعي وتعيينه:

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
    يكتب taglen بايت من قيمة الوسم (متجه التهيئة الاصطناعي) إلى المخزن المؤقت المُشار إليه بواسطة tag. يمكن إجراء هذا الاستدعاء فقط عند تعمية البيانات وبعد معالجة جميع البيانات (مثلًا بعد استدعاء EVP_EncryptFinal()). بالنسبة لوضع SIV، يجب أن يكون taglen مساويًا لـ 16.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
    يُعيّن الوسم المتوقع (متجه التهيئة الاصطناعي) إلى taglen بايت من tag. هذا الاستدعاء قانوني فقط عند فك تعمية البيانات ويجب إجراؤه قبل معالجة أي بيانات (مثلًا قبل أي استدعاءات EVP_DecryptUpdate()). بالنسبة لوضع SIV، يجب أن يكون taglen مساويًا لـ 16.

يقوم وضع SIV بتمريرين على بيانات الإدخال، وبالتالي، يجب إجراء استدعاء واحد فقط لـ EVP_CipherUpdate() أو EVP_EncryptUpdate() أو EVP_DecryptUpdate() مع ضبط out على قيمة غير NULL. لا يلزم استدعاء EVP_DecryptFinal() أو EVP_CipherFinal()، ولكنه سيشير إلى نجاح عملية التحديث.

  ChaCha20-Poly1305
الضوابط ctrl التالية مدعومة لخوارزمية ChaCha20-Poly1305 AEAD.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL)
    يضبط طول nonce. هذه الاستدعاء أصبح زائدًا الآن لأن القيمة الصالحة الوحيدة هي الطول المبدئي 12 (أي 96 بت). قبل OpenSSL 3.0، كان يمكن استخدام nonce أقل من 12 بايت لوسادة iv آليًا بأصفار بادئة لجعل طوله 12 بايت.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
    يكتب "taglen" بايت من قيمة الوسم إلى المخزن المُشار إليه بواسطة "tag". يمكن إجراء هذا الاستدعاء فقط عند تعمية البيانات وبعد معالجة جميع البيانات (مثلًا بعد استدعاء EVP_EncryptFinal()).

    يجب أن يكون "taglen" المحدد هنا 16 (POLY1305_BLOCK_SIZE، أي 128 بت) أو أقل.

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag)
    يضبط الوسم المتوقع إلى "taglen" بايت من "tag". يمكن ضبط طول الوسم فقط قبل تحديد IV. يجب أن يكون "taglen" بين 1 و16 (POLY1305_BLOCK_SIZE) شاملًا. هذا الاستدعاء صالح فقط عند فك تعمية البيانات.

ملاحظات
حيثما أمكن، يجب استخدام واجهة EVP للمُعمِّيات المتناظرة بدلاً من الواجهات منخفضة المستوى. وذلك لأن الكود يصبح شفافًا تجاه المُعمِّي المستخدم وأكثر مرونة بكثير. بالإضافة إلى ذلك، تضمن واجهة EVP استخدام تسريع تعمية خاص بالمنصة مثل AES-NI (الواجهات منخفضة المستوى لا توفر هذا الضمان).

يعمل حشو PKCS بإضافة n بايت حشو بقيمة n لجعل الطول الإجمالي للبيانات المُعمَّاة مضاعفًا لحجم الكتلة. يُضاف الحشو دائمًا، لذا إذا كانت البيانات مضاعفًا لحجم الكتلة بالفعل، فإن n سيساوي حجم الكتلة. على سبيل المثال، إذا كان حجم الكتلة 8 ويجب تعمية 11 بايت، فسيُضاف 5 بايت حشو بقيمة 5.

عند فك التعمية، يُفحص الكتلة النهائية لمعرفة ما إذا كانت بالشكل الصحيح.

على الرغم من أن عملية فك التعمية يمكن أن تُنتج خطأ إذا كان الحشو مفعّلاً، إلا أنها ليست اختبارًا قويًا لصحة بيانات الإدخال أو المفتاح. كتلة عشوائية لديها فرصة أفضل من 1 من 256 لتكون بالتنسيق الصحيح، والمشاكل في بيانات الإدخال في وقت سابق لن تُنتج خطأ فك تعمية نهائي.

إذا كان الحشو معطلاً، فإن عملية فك التعمية ستنجح دائمًا إذا كان المبلغ الإجمالي للبيانات المُفككة مضاعفًا لحجم الكتلة.

الدوال EVP_EncryptInit() وEVP_EncryptInit_ex() وEVP_EncryptFinal() وEVP_DecryptInit() وEVP_DecryptInit_ex() وEVP_CipherInit() وEVP_CipherInit_ex() وEVP_CipherFinal() قديمة ولكنها محفوظة للتوافق مع الكود الموجود. يجب أن يستخدم الكود الجديد EVP_EncryptInit_ex2() وEVP_EncryptFinal_ex() وEVP_DecryptInit_ex2() وEVP_DecryptFinal_ex() وEVP_CipherInit_ex2() وEVP_CipherFinal_ex() لأنها يمكنها إعادة استخدام سياق موجود دون تخصيصه وتحريره في كل استدعاء.

هناك بعض الاختلافات بين الدالتين EVP_CipherInit() وEVP_CipherInit_ex()، مهمة في بعض الظروف. تملأ EVP_CipherInit() كائن السياق المُمرر بالأصفار. كنتيجة، لا تسمح EVP_CipherInit() بالتهيئة خطوة بخطوة للسياق عندما يُمرر key وiv في استدعاءات منفصلة. يعني هذا أيضًا أن الأعلام المُضبطة للسياق تُزال، وهو مهم بشكل خاص للعلم EVP_CIPHER_CTX_FLAG_WRAP_ALLOW الذي يُعالج بشكل خاص في EVP_CipherInit_ex().

تجاهل إرجاعات الفشل لدوال تهيئة EVP_CIPHER_CTX يمكن أن يؤدي إلى سلوك غير محدد لاحقًا عند استدعاء الدوال التي تحدث أو تُنهي السياق. الاستدعاءات الصالحة الوحيدة على EVP_CIPHER_CTX عندما تفشل التهيئة هي استدعاءات تحاول تهيئة أخرى للسياق أو تحرير السياق.

EVP_get_cipherbynid() وEVP_get_cipherbyobj() مُنفذتان كوحدات ماكرو.

العلل
يشير EVP_MAX_KEY_LENGTH وEVP_MAX_IV_LENGTH فقط إلى المُعمِّيات الداخلية بأطوال مفاتيح مبدئية. إذا تجاوزت المُعمِّيات المخصصة هذه القيم، تكون النتائج غير متوقعة. وذلك لأنه أصبحت ممارسة قياسية تعريف مفتاح عام كمصفوفة unsigned char ثابتة تحتوي على EVP_MAX_KEY_LENGTH بايت.

كود ASN1 غير مكتمل (وأحيانًا غير دقيق)؛ تم اختباره فقط لبعض المُعمِّيات الشائعة S/MIME (RC2, DES, triple DES) في وضع CBC.

أمثلة
تعمية سلسلة محارف باستخدام IDEA:

 int do_crypt(char *outfile)
 {
     unsigned char outbuf[1024];
     int outlen, tmplen;
     /*
      * Bogus key and IV: we'd normally set these from
      * another source.
      */
     unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
     unsigned char iv[] = {1,2,3,4,5,6,7,8};
     char intext[] = "Some Crypto Text";
     EVP_CIPHER_CTX *ctx;
     FILE *out;

     ctx = EVP_CIPHER_CTX_new();
     if (!EVP_EncryptInit_ex2(ctx, EVP_idea_cbc(), key, iv, NULL)) {
         /* Error */
         EVP_CIPHER_CTX_free(ctx);
         return 0;
     }

     if (!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) {
         /* Error */
         EVP_CIPHER_CTX_free(ctx);
         return 0;
     }
     /*
      * Buffer passed to EVP_EncryptFinal() must be after data just
      * encrypted to avoid overwriting it.
      */
     if (!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) {
         /* Error */
         EVP_CIPHER_CTX_free(ctx);
         return 0;
     }
     outlen += tmplen;
     EVP_CIPHER_CTX_free(ctx);
     /*
      * Need binary mode for fopen because encrypted data is
      * binary data. Also cannot use strlen() on it because
      * it won't be NUL terminated and may contain embedded
      * NULs.
      */
     out = fopen(outfile, "wb");
     if (out == NULL) {
         /* Error */
         return 0;
     }
     fwrite(outbuf, 1, outlen, out);
     fclose(out);
     return 1;
 }

يمكن فك تعمية النص المُعمَّى من المثال أعلاه باستخدام أداة openssl مع سطر الأوامر (معروض على سطرين للتوضيح):

 openssl idea -d \
     -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 <filename

مثال عام لدوال التعمية وفك التعمية باستخدام الإدخال/الإخراج من الملفات وAES128 بمفتاح 128-بت:

 int do_crypt(FILE *in, FILE *out, int do_encrypt)
 {
     /* Allow enough space in output buffer for additional block */
     unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
     int inlen, outlen;
     EVP_CIPHER_CTX *ctx;
     /*
      * Bogus key and IV: we'd normally set these from
      * another source.
      */
     unsigned char key[] = "0123456789abcdeF";
     unsigned char iv[] = "1234567887654321";

     /* Don't set key or IV right away; we want to check lengths */
     ctx = EVP_CIPHER_CTX_new();
     if (!EVP_CipherInit_ex2(ctx, EVP_aes_128_cbc(), NULL, NULL,
                             do_encrypt, NULL)) {
         /* Error */
         EVP_CIPHER_CTX_free(ctx);
         return 0;
     }
     OPENSSL_assert(EVP_CIPHER_CTX_get_key_length(ctx) == 16);
     OPENSSL_assert(EVP_CIPHER_CTX_get_iv_length(ctx) == 16);

     /* Now we can set key and IV */
     if (!EVP_CipherInit_ex2(ctx, NULL, key, iv, do_encrypt, NULL)) {
         /* Error */
         EVP_CIPHER_CTX_free(ctx);
         return 0;
     }

     for (;;) {
         inlen = fread(inbuf, 1, 1024, in);
         if (inlen <= 0)
             break;
         if (!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) {
             /* Error */
             EVP_CIPHER_CTX_free(ctx);
             return 0;
         }
         fwrite(outbuf, 1, outlen, out);
     }
     if (!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) {
         /* Error */
         EVP_CIPHER_CTX_free(ctx);
         return 0;
     }
     fwrite(outbuf, 1, outlen, out);

     EVP_CIPHER_CTX_free(ctx);
     return 1;
 }

التعمية باستخدام AES-CBC بمفتاح 256-بت مع سرقة النص المُعمَّى "CS1".

 int encrypt(const unsigned char *key, const unsigned char *iv,
             const unsigned char *msg, size_t msg_len, unsigned char *out)
 {
    /*
     * This assumes that key size is 32 bytes and the iv is 16 bytes.
     * For ciphertext stealing mode the length of the ciphertext "out" will be
     * the same size as the plaintext size "msg_len".
     * The "msg_len" can be any size >= 16.
     */
     int ret = 0, encrypt = 1, outlen, len;
     EVP_CIPHER_CTX *ctx = NULL;
     EVP_CIPHER *cipher = NULL;
     OSSL_PARAM params[2];

     ctx = EVP_CIPHER_CTX_new();
     cipher = EVP_CIPHER_fetch(NULL, "AES-256-CBC-CTS", NULL);
     if (ctx == NULL || cipher == NULL)
         goto err;

     /*
      * The default is "CS1" so this is not really needed,
      * but would be needed to set either "CS2" or "CS3".
      */
     params[0] = OSSL_PARAM_construct_utf8_string(OSSL_CIPHER_PARAM_CTS_MODE,
                                                  "CS1", 0);
     params[1] = OSSL_PARAM_construct_end();

     if (!EVP_CipherInit_ex2(ctx, cipher, key, iv, encrypt, params))
         goto err;

     /* NOTE: CTS mode does not support multiple calls to EVP_CipherUpdate() */
     if (!EVP_CipherUpdate(ctx, out, &outlen, msg, msg_len))
         goto err;
      if (!EVP_CipherFinal_ex(ctx, out + outlen, &len))
         goto err;
     ret = 1;
 err:
     EVP_CIPHER_free(cipher);
     EVP_CIPHER_CTX_free(ctx);
     return ret;
 }

انظر أيضًا
evp(7), property(7), "جلب الخوارزمية" في crypto(7), provider-cipher(7), life_cycle-cipher(7)

المُعمِّيات المدعومة مُدرجة في:

EVP_aes_128_gcm(3), EVP_aria_128_gcm(3), EVP_bf_cbc(3), EVP_camellia_128_ecb(3), EVP_cast5_cbc(3), EVP_chacha20(3), EVP_des_cbc(3), EVP_desx_cbc(3), EVP_idea_cbc(3), EVP_rc2_cbc(3), EVP_rc4(3), EVP_rc5_32_12_16_cbc(3), EVP_seed_cbc(3), EVP_sm4_cbc(3),

التاريخ
دعم وضع OCB أُضيف في OpenSSL 1.1.0.

EVP_CIPHER_CTX جُعل معتمًا في OpenSSL 1.1.0. كنتيجة، ظهرت EVP_CIPHER_CTX_reset() واختفت EVP_CIPHER_CTX_cleanup(). بقيت EVP_CIPHER_CTX_init() كاسم مستعار لـ EVP_CIPHER_CTX_reset().

الدالة EVP_CIPHER_CTX_cipher() أُهملت في OpenSSL 3.0؛ استخدم EVP_CIPHER_CTX_get0_cipher() بدلاً منها.

الدوال EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2(), EVP_CipherInit_ex2(), EVP_CIPHER_fetch(), EVP_CIPHER_free(), EVP_CIPHER_up_ref(), EVP_CIPHER_CTX_get0_cipher(), EVP_CIPHER_CTX_get1_cipher(), EVP_CIPHER_get_params(), EVP_CIPHER_CTX_set_params(), EVP_CIPHER_CTX_get_params(), EVP_CIPHER_gettable_params(), EVP_CIPHER_settable_ctx_params(), EVP_CIPHER_gettable_ctx_params(), EVP_CIPHER_CTX_settable_params() و EVP_CIPHER_CTX_gettable_params() أُضيفت في 3.0.

أُعيدت تسمية الدوال EVP_CIPHER_nid() وEVP_CIPHER_name() وEVP_CIPHER_block_size() وEVP_CIPHER_key_length() وEVP_CIPHER_iv_length() وEVP_CIPHER_flags() وEVP_CIPHER_mode() وEVP_CIPHER_type() وEVP_CIPHER_CTX_nid() وEVP_CIPHER_CTX_block_size() وEVP_CIPHER_CTX_key_length() وEVP_CIPHER_CTX_iv_length() وEVP_CIPHER_CTX_tag_length() وEVP_CIPHER_CTX_num() وEVP_CIPHER_CTX_type() وEVP_CIPHER_CTX_mode() لتضمين "get" أو "get0" في أسمائها في OpenSSL 3.0، على التوالي. حُفظت الأسماء القديمة كوحدات ماكرو بديلة غير مهملة.

أُعيدت تسمية الدالة EVP_CIPHER_CTX_encrypting() إلى EVP_CIPHER_CTX_is_encrypting() في OpenSSL 3.0. حُفظ الاسم القديم كوحدة ماكرو بديلة غير مهملة.

أُهملت وحدة الماكرو EVP_CIPHER_CTX_flags() في OpenSSL 1.1.0.

EVP_CIPHER_CTX_dup() أُضيفت في OpenSSL 3.2.

EVP_CipherInit_SKEY() أُضيفت في OpenSSL 3.5.

قبل OpenSSL 3.5، كان تمرير ctx فارغ إلى EVP_CIPHER_CTX_get_block_size() يؤدي إلى إلغاء مرجع مؤشر فارغ، بدلاً من قيمة إرجاع 0 تشير إلى خطأ.

حقوق النسخ
حقوق النشر 2000-2026 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.