الاسم¶

EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_named_curve, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field, EC_GROUP_get_field_type - دوال لمعالجة كائنات EC_GROUP

موجز¶

 #include <openssl/ec.h>
 int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
 EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
 int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator,
                            const BIGNUM *order, const BIGNUM *cofactor);
 const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
 int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
 const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);
 int EC_GROUP_order_bits(const EC_GROUP *group);
 int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
 const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group);
 const BIGNUM *EC_GROUP_get0_field(const EC_GROUP *group);
 void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
 int EC_GROUP_get_curve_name(const EC_GROUP *group);
 void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
 int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
 void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
 point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *group);
 unsigned char *EC_GROUP_get0_seed(const EC_GROUP *group);
 size_t EC_GROUP_get_seed_len(const EC_GROUP *group);
 size_t EC_GROUP_set_seed(EC_GROUP *group, const unsigned char *, size_t len);
 int EC_GROUP_get_degree(const EC_GROUP *group);
 int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
 int EC_GROUP_check_named_curve(const EC_GROUP *group, int nist_only,
                                BN_CTX *ctx);
 int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
 int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);
 int EC_GROUP_get_basis_type(const EC_GROUP *group);
 int EC_GROUP_get_trinomial_basis(const EC_GROUP *group, unsigned int *k);
 int EC_GROUP_get_pentanomial_basis(const EC_GROUP *group, unsigned int *k1,
                                    unsigned int *k2, unsigned int *k3);
 int EC_GROUP_get_field_type(const EC_GROUP *group);

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

 const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);

الوصف¶

EC_GROUP_copy() تنسخ المنحنى src إلى dst. يجب أن يستخدم كل من src و dst نفس EC_METHOD.

EC_GROUP_dup() تنشئ كائن EC_GROUP جديد وتنسخ المحتوى من src إلى كائن EC_GROUP المنشأ حديثًا.

EC_GROUP_method_of() تحصل على EC_METHOD لـ group. أُهملت هذه الدالة في OpenSSL 3.0، لأن EC_METHOD لم يعد مفهومًا عامًا.

EC_GROUP_set_generator() تضبط معاملات المنحنى التي يجب أن يتفق عليها جميع المشاركين باستخدام المنحنى. تتضمن هذه المعاملات المُولِّد و الترتيب و المعامل المشترك. المُولِّد هو نقطة محددة جيدًا على المنحنى اختيرت للعمليات التعمية. الأعداد الصحيحة المستخدمة في ضرب النقاط ستكون بين 0 و n-1 حيث n هو الترتيب. الترتيب مضروبًا في المعامل المشترك يعطي عدد النقاط على المنحنى.

EC_GROUP_get0_generator() تُرجع المُولِّد لـ group المُحدد.

EC_GROUP_get_order() تسترجع ترتيب group وتنسخ قيمته إلى order. تفشل في حال لم يكن group مهيأ بالكامل (أي، لم يُضبط ترتيبه أو ضُبط على صفر).

EC_GROUP_get_cofactor() تسترجع المعامل المشترك لـ group وتنسخ قيمته إلى cofactor. تفشل في حال لم يكن group مهيأ بالكامل أو إذا لم يُضبط المعامل المشترك (أو ضُبط على صفر).

الدالتان EC_GROUP_set_curve_name() و EC_GROUP_get_curve_name() تضبطان وتسترجعان NID للمنحنى على التوالي (انظر EC_GROUP_new(3)). إذا لم يكن للمنحنى NID مرتبط به، فستُرجع EC_GROUP_get_curve_name NID_undef.

تُستخدم قيمة asn1_flag لتحديد ما إذا كان ترميز المنحنى يستخدم معاملات صريحة أو منحنى مسمى باستخدام ASN1 OID: العديد من التطبيقات تدعم فقط الشكل الأخير. إذا كانت asn1_flag هي OPENSSL_EC_NAMED_CURVE فسيُستخدم شكل المنحنى المسمى ويجب أن يكون للمعاملات NID منحنى مسمى مقابل مضبوط. إذا كانت asn1_flags هي OPENSSL_EC_EXPLICIT_CURVE فتُرمَّز المعاملات بشكل صريح. الدالتان EC_GROUP_get_asn1_flag() و EC_GROUP_set_asn1_flag() تسترجعان وتضبطان حالة asn1_flag للمنحنى. ملاحظة: أُضيف OPENSSL_EC_EXPLICIT_CURVE في OpenSSL 1.1.0، للإصدارات السابقة من OpenSSL يجب استخدام القيمة 0 بدلاً من ذلك. قبل OpenSSL 1.1.0 كان الشكل المبدئي هو استخدام المعاملات الصريحة (بمعنى أن التطبيقات كان عليها ضبط شكل المنحنى المسمى بشكل صريح) في OpenSSL 1.1.0 وما بعده، شكل المنحنى المسمى هو المبدئي.

point_conversion_form للمنحنى يتحكم في كيفية ترميز بيانات EC_POINT كـ ASN1 كما هو معرف في X9.62 (ECDSA). point_conversion_form_t هو تعداد (enum) معرّف كالتالي:

 typedef enum {
        /** تُرمز النقطة على هيئة z||x، حيث تحدد الثمانية (octet) z
         * أي حلول المعادلة التربيعية تكون y */
        POINT_CONVERSION_COMPRESSED = 2,
        /** تُرمز النقطة على هيئة z||x||y، حيث z هي الثمانية 0x04 */
        POINT_CONVERSION_UNCOMPRESSED = 4,
        /** تُرمز النقطة على هيئة z||x||y، حيث تحدد الثمانية z
         * أي حلول المعادلة التربيعية تكون y */
        POINT_CONVERSION_HYBRID = 6
 } point_conversion_form_t;

بالنسبة لـ POINT_CONVERSION_UNCOMPRESSED، يُرمَّز النقطة كثمانية بتات تشير إلى أن الصيغة غير المضغوطة قد استُخدمت، متبوعةً بثمانيات x، ثم بثمانيات y.

بالنسبة لأي إحداثي x معطى لنقطة على منحنى، يمكن اشتقاق قيمتين محتملتين لـ y. بالنسبة لـ POINT_CONVERSION_COMPRESSED، تُرمَّز النقطة كثمانية بتات تشير إلى أن الصيغة المضغوطة قد استُخدمت وأي من الحلين المحتملين لـ y قد استُخدم، متبوعةً بثمانيات x.

بالنسبة لـ POINT_CONVERSION_HYBRID، تُرمَّز النقطة كثمانية بتات تشير إلى أن الصيغة الهجينة قد استُخدمت وأي من الحلين المحتملين لـ y قد استُخدم، متبوعةً بثمانيات x، ثم بثمانيات y.

الدالتان EC_GROUP_set_point_conversion_form() و EC_GROUP_get_point_conversion_form() تضبطان وتستعيدان point_conversion_form للمنحنى على التوالي.

يُعرِّف المعيار ANSI X9.62 (معيار ECDSA) طريقة لتوليد معامل المنحنى b من رقم عشوائي. يوفر هذا مزايا حيث أن المعامل الذي يُحصل عليه بهذه الطريقة من غير المرجح أن يكون عرضة لهجمات ذات أغراض خاصة، أو يحتوي على أي أبواب خلفية. إذا كانت البذرة موجودة لمنحنى، فإن المعامل b قد وُلد بطريقة قابلة للتحقق باستخدام تلك البذرة. لا تستخدم مكتبة OpenSSL EC قيمة البذرة هذه ولكنها تمكنك من فحصها باستخدام EC_GROUP_get0_seed(). يُعيد هذا مؤشرًا إلى كتلة ذاكرة تحتوي على البذرة التي استُخدمت. يمكن الحصول على طول كتلة الذاكرة باستخدام EC_GROUP_get_seed_len(). يوفر عدد من المنحنيات المضمنة داخل المكتبة قيم بذور يمكن الحصول عليها. من الممكن أيضًا تعيين بذرة مخصصة باستخدام EC_GROUP_set_seed() وتمرير مؤشر إلى كتلة ذاكرة، مع طول البذرة. مرة أخرى، لن تستخدم مكتبة EC قيمة البذرة هذه، على الرغم من أنها ستحفظ في أي اتصالات قائمة على ASN1.

EC_GROUP_get_degree() يحصل على درجة الحقل. لحقول Fp سيكون هذا عدد البتات في p. لحقول F2^m سيكون هذا القيمة m.

EC_GROUP_get_field_type() يُحدد نوع الحقل الذي تدعمه بنية EC_GROUP، والذي سيكون إما F2^m أو Fp.

الدالة EC_GROUP_check_discriminant() تحسب المميز للمنحنى وتتحقق من صحته. لمنحنى معرَّف على Fp يُعطى المميز بالصيغة 4*a^3 + 27*b^2 بينما لمنحنيات F2^m المميز هو ببساطة b. في كلتا الحالتين، لكي يكون المنحنى صحيحًا، يجب أن يكون المميز غير صفري.

الدالة EC_GROUP_check() تتصرف بالطريقة التالية: بالنسبة للمزود المبدئي لـ OpenSSL، تؤدي عددًا من الفحوصات على منحنى للتحقق من صحته. تشمل الفحوصات المُجراة التحقق من أن المميز غير صفري؛ وأنه قد عُرف مولد؛ وأن المولد يقع على المنحنى وله الترتيب الصحيح. بالنسبة لمزود OpenSSL FIPS، تستخدم EC_GROUP_check_named_curve() للامتثال لـ SP800-56Ar3.

الدالة EC_GROUP_check_named_curve() تُحدد ما إذا كانت معاملات نطاق المجموعة تطابق أحد المنحنيات المدمجة المدعومة من المكتبة. يُرجع اسم المنحنى كـ NID إذا تطابق. إذا عُدِّلت معاملات نطاق المجموعة، فلن يُوجد تطابق. إذا كان اسم المنحنى للمجموعة المُعطاة هو NID_undef (مثلًا، أُنشئت باستخدام معاملات صريحة بدون اسم منحنى)، يمكن استخدام هذه الطريقة للبحث عن اسم المنحنى الذي يطابق معاملات نطاق المجموعة. المنحنيات المدمجة تحتوي على أسماء مستعارة، بحيث يمكن لعدة NID أن تُرسم لنفس معاملات النطاق. لمثل هذه المنحنيات، غير مُحدد أي من الأسماء المستعارة سيُرجَع إذا كان اسم المنحنى للمجموعة المُعطاة هو NID_undef. إذا كان nist_only هو 1، سيبحث فقط عن المنحنيات المعتمدة من NIST، وإلا يبحث في جميع المنحنيات المدمجة. يمكن تمرير كائن BN_CTX في المعامل ctx. المعامل ctx قد يكون NULL.

EC_GROUP_cmp() يقارن a و b لتحديد ما إذا كانا يمثلان نفس المنحنى أم لا.

الدوال EC_GROUP_get_basis_type() و EC_GROUP_get_trinomial_basis() و EC_GROUP_get_pentanomial_basis() يجب أن تُستدعى فقط للمنحنيات المعرَّفة على حقل F2^m. تُجرى عمليات الجمع والضرب داخل حقل F2^m باستخدام دالة كثيرة حدود غير قابلة للاختزال f(x). هذه الدالة إما ثلاثية الحدود من الشكل:

f(x) = x^m + x^k + 1 مع m > k >= 1

أو خماسية الحدود من الشكل:

f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 مع m > k3 > k2 > k1 >= 1

الدالة EC_GROUP_get_basis_type() تُعيد NID يُحدد ما إذا كانت ثلاثية الحدود أو خماسية الحدود قيد الاستخدام للحقل. الدالة EC_GROUP_get_trinomial_basis() يجب أن تُستدعى فقط حيث f(x) من الشكل ثلاثي الحدود، وتُعيد قيمة k. بالمثل، الدالة EC_GROUP_get_pentanomial_basis() يجب أن تُستدعى فقط حيث f(x) من الشكل خماسي الحدود، وتُعيد قيم k1 و k2 و k3 على التوالي.

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

الدوال التالية تُعيد 1 عند النجاح أو 0 عند الخطأ: EC_GROUP_copy() و EC_GROUP_set_generator() و EC_GROUP_check() و EC_GROUP_check_discriminant() و EC_GROUP_get_trinomial_basis() و EC_GROUP_get_pentanomial_basis().

EC_GROUP_dup() تُعيد مؤشرًا إلى المنحنى المكرر، أو NULL عند الخطأ.

EC_GROUP_method_of() تُعيد تطبيق EC_METHOD المستخدم للمنحنى المعطى أو NULL عند الخطأ.

EC_GROUP_get0_generator() تُعيد المولد للمنحنى المعطى أو NULL عند الخطأ.

EC_GROUP_get_order() تُعيد 0 إذا لم يُعيّن الترتيب (أو عُيّن إلى صفر) لـ group أو إذا فشلت النسخة إلى order، وإلا تُعيد 1.

EC_GROUP_get_cofactor() تُعيد 0 إذا لم يُعيّن العامل المشترك (أو عُيّن إلى صفر) لـ group أو إذا فشلت النسخة إلى cofactor، وإلا تُعيد 1.

EC_GROUP_get_curve_name() تُعيد اسم المنحنى (NID) لـ group أو ستُعيد NID_undef إذا لم يُرتبط أي اسم منحنى.

EC_GROUP_get_asn1_flag() تُعيد علم ASN1 لـ group المحدد.

EC_GROUP_get_point_conversion_form() تُرجع point_conversion_form للمجموعة group.

EC_GROUP_get_degree() تُرجع الدرجة للمجموعة group أو 0 إذا كانت العملية غير مدعومة من قبل تطبيق المجموعة الأساسي.

EC_GROUP_get_field_type() تُرجع إما NID_X9_62_prime_field للمنحنيات الأولية أو NID_X9_62_characteristic_two_field للمنحنيات الثنائية؛ هذه القيم مُعرَّفة في ملف الرأس <openssl/obj_mac.h>.

EC_GROUP_check_named_curve() تُرجع nid للمنحنى المُسمَّى المطابق، وإلا تُرجع 0 لعدم وجود تطابق، أو -1 عند الخطأ.

EC_GROUP_get0_order() تُرجع مؤشرًا داخليًا لترتيب المجموعة. EC_GROUP_order_bits() تُرجع عدد البتات في ترتيب المجموعة. EC_GROUP_get0_cofactor() تُرجع مؤشرًا داخليًا لعامل المشاركة للمجموعة. EC_GROUP_get0_field() تُرجع مؤشرًا داخليًا لحقل المجموعة. للمنحنيات فوق GF(p)، هذا هو المعامل؛ للمنحنيات فوق GF(2^m)، هذا هو متعدد الحدود غير القابل للاختزال الذي يُعرِّف الحقل.

EC_GROUP_get0_seed() تُرجع مؤشرًا للبذرة التي استُخدمت لتوليد المعامل b، أو NULL إذا لم تُحدد البذرة. EC_GROUP_get_seed_len() تُرجع طول البذرة أو 0 إذا لم تُحدد البذرة.

EC_GROUP_set_seed() تُرجع طول البذرة التي وُضعت. إذا كانت البذرة المُقدَّمة NULL، أو طول البذرة المُقدَّم 0، ستكون القيمة المُرجعة 1. عند الخطأ تُرجع 0.

EC_GROUP_cmp() تُرجع 0 إذا كانت المنحنيات متساوية، 1 إذا لم تكن متساوية، أو -1 عند الخطأ.

EC_GROUP_get_basis_type() تُرجع القيم NID_X9_62_tpBasis أو NID_X9_62_ppBasis (كما هو مُعرَّف في <openssl/obj_mac.h>) لثلاثي الحدود أو خماسي الحدود على التوالي. بدلاً من ذلك، في حالة حدوث خطأ تُرجع 0.

انظر أيضًا¶

crypto(7), EC_GROUP_new(3), EC_POINT_new(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

التاريخ¶

EC_GROUP_method_of() أُهملت في OpenSSL 3.0. EC_GROUP_get0_field(), EC_GROUP_check_named_curve() و EC_GROUP_get_field_type() أُضيفت في OpenSSL 3.0. EC_GROUP_get0_order(), EC_GROUP_order_bits() و EC_GROUP_get0_cofactor() أُضيفت في OpenSSL 1.1.0.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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