الاسم¶

EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, EC_GROUP_new_from_params, EC_GROUP_to_params, EC_GROUP_new_from_ecparameters, EC_GROUP_new_from_ecpkparameters, EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name_ex, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve, EC_GROUP_get_curve, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves, OSSL_EC_curve_nid2name - دوال لإنشاء وتدمير كائنات EC_GROUP

موجز¶

 #include <openssl/ec.h>
 EC_GROUP *EC_GROUP_new_from_params(const OSSL_PARAM params[],
                                    OSSL_LIB_CTX *libctx, const char *propq);
 OSSL_PARAM *EC_GROUP_to_params(const EC_GROUP *group, OSSL_LIB_CTX *libctx,
                                const char *propq, BN_CTX *bnctx);
 EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params);
 EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params);
 void EC_GROUP_free(EC_GROUP *group);
 EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a,
                                  const BIGNUM *b, BN_CTX *ctx);
 EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a,
                                   const BIGNUM *b, BN_CTX *ctx);
 EC_GROUP *EC_GROUP_new_by_curve_name_ex(OSSL_LIB_CTX *libctx, const char *propq,
                                         int nid);
 EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
 int EC_GROUP_set_curve(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a,
                        const BIGNUM *b, BN_CTX *ctx);
 int EC_GROUP_get_curve(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b,
                        BN_CTX *ctx);
 ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group,
                                         ECPARAMETERS *params);
 ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group,
                                             ECPKPARAMETERS *params);
 size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
 const char *OSSL_EC_curve_nid2name(int nid);

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

 EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
 void EC_GROUP_clear_free(EC_GROUP *group);
 int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p,
                            const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
 int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p,
                            BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
 int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p,
                             const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
 int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p,
                             BIGNUM *a, BIGNUM *b, BN_CTX *ctx);

الوصف¶

داخل المكتبة يوجد شكلان من المنحنيات الإهليلجية ذات الاهتمام. الشكل الأول هو تلك المعرفة فوق الحقل الأولي Fp. عناصر Fp هي الأعداد الصحيحة من 0 إلى p-1، حيث p عدد أولي. يعطينا هذا معادلة منحنى إهليلجي منقحة كما يلي:

y^2 mod p = x^3 +ax + b mod p

الشكل الثاني هو تلك المعرفة فوق حقل ثنائي F2^m حيث عناصر الحقل هي أعداد صحيحة بطول m بت كحد أقصى. لهذا الشكل، تُعدل معادلة المنحنى الإهليلجي إلى:

y^2 + xy = x^3 + ax^2 + b (حيث b != 0)

تُنفذ العمليات في حقل ثنائي بالنسبة إلى كثيرة حدود غير قابلة للاختزال. جميع هذه المنحنيات مع OpenSSL تستخدم ثلاثية الحدود أو خماسية الحدود لهذا المعامل.

على الرغم من إهماله منذ OpenSSL 3.0 ولا ينبغي استخدامه بعد الآن، يمكن بناء منحنى جديد باستدعاء EC_GROUP_new()، باستخدام التنفيذ المقدم من meth (انظر EC_GFp_simple_method(3)) ومرتبط بسياق المكتبة ctx (انظر OSSL_LIB_CTX(3)). قد يكون معامل ctx NULL وفي هذه الحالة يُستخدم سياق المكتبة المبدئي. من الضروري بعد ذلك استدعاء EC_GROUP_set_curve() لتعيين معاملات المنحنى. ينبغي للتطبيقات بدلاً من ذلك استخدام أحد منشئات EC_GROUP_new_* الأخرى.

EC_GROUP_new_from_params() ينشئ مجموعة بمعاملات محددة بواسطة params. يُستخدم سياق المكتبة libctx (انظر OSSL_LIB_CTX(3)) وسلسلة استعلام الخاصية propq لجلب الخوارزميات من المزودين. قد يكون params إما قائمة بمعاملات صريحة أو مجموعة مسماة. قد تكون قيم ctx و propq NULL. تُوصف params التي يمكن استخدامها في EVP_PKEY-EC(7).

EC_GROUP_to_params ينشئ مصفوفة OSSL_PARAM بالمعاملات المقابلة التي تصف EC_GROUP المعطى. قد تحتوي المعاملات الناتجة على معاملات تصف منحنى مسماً أو صريحاً اعتماداً على EC_GROUP. يُستخدم سياق المكتبة libctx (انظر OSSL_LIB_CTX(3)) وسلسلة استعلام الخاصية propq لجلب الخوارزميات من المزودين. bnctx هو BN_CTX مخصص مسبقاً اختياري (لتوفير تكلفة تخصيص وتحرير البنية في حلقة). قد تكون قيم libctx و propq و bnctx NULL. المتصل مسؤول عن تحرير مؤشر OSSL_PARAM المُعاد.

EC_GROUP_new_from_ecparameters() ينشئ مجموعة من params المحددة و EC_GROUP_new_from_ecpkparameters() ينشئ مجموعة من PK المحددة params.

EC_GROUP_set_curve() يعين معاملات المنحنى p و a و b. لمنحنى فوق Fp، p هو العدد الأولي للحقل. لمنحنى فوق F2^m، يمثل p كثيرة الحدود غير القابلة للاختزال - كل بت يمثل حداً في كثيرة الحدود. لذلك، سيكون هناك إما ثلاثة أو خمسة بتات مضبوطة اعتماداً على ما إذا كانت كثيرة الحدود ثلاثية أو خماسية. في كلتا الحالتين، يمثل a و b المعاملين a و b من المعادلة ذات الصلة المقدمة أعلاه.

EC_group_get_curve() يحصل على معاملات المنحنى المضبوطة سابقاً.

EC_GROUP_set_curve_GFp() و EC_GROUP_set_curve_GF2m() هما مرادفان لـ EC_GROUP_set_curve(). عُرفتا للتوافق مع الإصدارات السابقة فقط ولا ينبغي استخدامهما.

EC_GROUP_get_curve_GFp() و EC_GROUP_get_curve_GF2m() هما مرادفان لـ EC_GROUP_get_curve(). عُرفتا للتوافق مع الإصدارات السابقة فقط ولا ينبغي استخدامهما.

تُعد الدالتان EC_GROUP_new_curve_GFp() و EC_GROUP_new_curve_GF2m() اختصارين لاستدعاء الدالة EC_GROUP_new() ثم الدالة EC_GROUP_set_curve(). ستُستخدم طريقة تنفيذ مبدئية مناسبة.

بينما يمكن استخدام المكتبة لإنشاء أي منحنى باستخدام الدوال الموصوفة أعلاه، فإن هناك أيضاً عدداً من المنحنيات المُعرفة مسبقاً والمتاحة للاستخدام. وللحصول على قائمة بجميع المنحنيات المُعرفة مسبقاً، استدعِ الدالة EC_get_builtin_curves(). ينبغي أن يكون الوسيط r مصفوفة من بنى EC_builtin_curve بحجم nitems. وستقوم الدالة بملء المصفوفة r بالمعلومات المتعلقة بالمنحنيات المدمجة. إذا كان nitems أقل من العدد الإجمالي للمنحنيات المتاحة، فستُرجع الدالة منحنيات بعدد nitems الأولى فقط، وإلا فسيُوفر العدد الإجمالي للمنحنيات. القيمة المُرجعة هي العدد الإجمالي للمنحنيات المتاحة (سواء جرى ملؤها في r أم لا). وتمرير قيمة NULL للوسيط r، أو ضبط nitems على 0، لن يفعل شيئاً سوى إرجاع العدد الإجمالي للمنحنيات المتاحة. تُعرف بنية EC_builtin_curve على النحو التالي:

 typedef struct {
        int nid;
        const char *comment;
        } EC_builtin_curve;

لكل عنصر EC_builtin_curve مُعرّف صحيح فريد (nid)، وسلسلة تعليق readable بشرية تصف المنحنى.

لبناء منحنى مدمج، استخدم الدالة EC_GROUP_new_by_curve_name_ex() وقدّم nid للمنحنى المراد بناؤه، وسياق المكتبة المرتبط المستخدم في ctx (انظر OSSL_LIB_CTX(3)) وأي سلسلة استعلام خاصية في propq. قد تكون قيمة ctx NULL وفي هذه الحالة يُستخدم سياق المكتبة المبدئي. قد تكون قيمة propq NULL أيضًا.

EC_GROUP_new_by_curve_name() مماثلة لـ EC_GROUP_new_by_curve_name_ex() باستثناء أن سياق المكتبة المبدئي يُستخدم دائمًا مع سلسلة استعلام خاصية NULL.

EC_GROUP_free() تُحرّر الذاكرة المرتبطة بـ EC_GROUP. إذا كان group NULL، لا يُفعل شيء.

EC_GROUP_clear_free() مُهملة: كانت تهدف إلى تدمير أي بيانات حساسة محفوظة داخل EC_GROUP ثم تحرير ذاكرتها، ولكن بما أن جميع البيانات المخزنة في EC_GROUP عامة على أي حال، فهذه الدالة غير ضرورية. يمكن استبدال استخدامها بأمان بـ EC_GROUP_free(). إذا كان group NULL، لا يُفعل شيء.

OSSL_EC_curve_nid2name() تُحوّل nid منحنى إلى الاسم المقابل.

القيم المُرجعة¶

جميع دوال EC_GROUP_new* تُعيد مؤشرًا إلى المجموعة المُنشأة حديثًا، أو NULL عند الخطأ.

EC_get_builtin_curves() تُعيد عدد المنحنيات المدمجة المتاحة.

EC_GROUP_set_curve_GFp(), EC_GROUP_get_curve_GFp(), EC_GROUP_set_curve_GF2m(), EC_GROUP_get_curve_GF2m() تُعيد 1 عند النجاح أو 0 عند الخطأ.

OSSL_EC_curve_nid2name() تُعيد ثابت سلسلة محارف، أو NULL عند الخطأ.

انظر أيضًا¶

crypto(7), EC_GROUP_copy(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3), OSSL_LIB_CTX(3), EVP_PKEY-EC(7)

التاريخ¶

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

• EC_GROUP_new() أُهملت في OpenSSL 3.0.

  EC_GROUP_new_by_curve_name_ex() و EC_GROUP_new_from_params() أُضيفتا في OpenSSL 3.0.

• EC_GROUP_clear_free() أُهملت في OpenSSL 3.0؛ استخدم EC_GROUP_free() بدلاً منها.

•  EC_GROUP_set_curve_GFp()، EC_GROUP_get_curve_GFp()،
   EC_GROUP_set_curve_GF2m() و EC_GROUP_get_curve_GF2m() أُهملت في
   OpenSSL 3.0؛ استخدم EC_GROUP_set_curve() و EC_GROUP_get_curve() بدلاً منها.
      

حقوق النسخ¶

حقوق النشر 2013-2024 مؤلفو مشروع OpenSSL. جميع الحقوق محفوظة.

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

ترجمة¶

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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