EC_POINT_NEW(3SSL)

الاسم
EC_POINT_set_Jprojective_coordinates_GFp، EC_POINT_point2buf، EC_POINT_new، EC_POINT_free، EC_POINT_clear_free، EC_POINT_copy، EC_POINT_dup، EC_POINT_method_of، EC_POINT_set_to_infinity، EC_POINT_get_Jprojective_coordinates_GFp، EC_POINT_set_affine_coordinates، EC_POINT_get_affine_coordinates، EC_POINT_set_compressed_coordinates، EC_POINT_set_affine_coordinates_GFp، EC_POINT_get_affine_coordinates_GFp، EC_POINT_set_compressed_coordinates_GFp، EC_POINT_set_affine_coordinates_GF2m، EC_POINT_get_affine_coordinates_GF2m، EC_POINT_set_compressed_coordinates_GF2m، EC_POINT_point2oct، EC_POINT_oct2point، EC_POINT_point2bn، EC_POINT_bn2point، EC_POINT_point2hex، EC_POINT_hex2point - دوال لإنشاء وتدمير ومعالجة كائنات EC_POINT

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

 EC_POINT *EC_POINT_new(const EC_GROUP *group);
 void EC_POINT_free(EC_POINT *point);
 void EC_POINT_clear_free(EC_POINT *point);
 int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
 EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
 int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
 int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,
                                     const BIGNUM *x, const BIGNUM *y,
                                     BN_CTX *ctx);
 int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p,
                                     BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
 int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p,
                                         const BIGNUM *x, int y_bit,
                                         BN_CTX *ctx);
 size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
                           point_conversion_form_t form,
                           unsigned char *buf, size_t len, BN_CTX *ctx);
 size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point,
                           point_conversion_form_t form,
                           unsigned char **pbuf, BN_CTX *ctx);
 int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
                        const unsigned char *buf, size_t len, BN_CTX *ctx);
 char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p,
                          point_conversion_form_t form, BN_CTX *ctx);
 EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex,
                              EC_POINT *p, BN_CTX *ctx);

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

 const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
 int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
                                              EC_POINT *p,
                                              const BIGNUM *x, const BIGNUM *y,
                                              const BIGNUM *z, BN_CTX *ctx);
 int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
                                              const EC_POINT *p,
                                              BIGNUM *x, BIGNUM *y, BIGNUM *z,
                                              BN_CTX *ctx);
 int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
                                         const BIGNUM *x, const BIGNUM *y,
                                         BN_CTX *ctx);
 int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
                                         const EC_POINT *p,
                                         BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
 int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group,
                                             EC_POINT *p,
                                             const BIGNUM *x, int y_bit,
                                             BN_CTX *ctx);
 int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
                                          const BIGNUM *x, const BIGNUM *y,
                                          BN_CTX *ctx);
 int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
                                          const EC_POINT *p,
                                          BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
 int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group,
                                              EC_POINT *p,
                                              const BIGNUM *x, int y_bit,
                                              BN_CTX *ctx);
 BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p,
                           point_conversion_form_t form, BIGNUM *bn,
                           BN_CTX *ctx);
 EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn,
                             EC_POINT *p, BN_CTX *ctx);

الوصف
يمثل هيكل EC_POINT نقطة على منحنى. تُنشأ نقطة جديدة باستدعاء الدالة EC_POINT_new() وتوفير كائن group الذي ترتبط به النقطة.

تحرر EC_POINT_free() الذاكرة المرتبطة بـ EC_POINT. إذا كان point NULL، لا يُفعل شيء.

تدمر EC_POINT_clear_free() أي بيانات حساسة محفوظة داخل EC_POINT ثم تحرر ذاكرتها. إذا كان point NULL، لا يُفعل شيء.

تنسخ EC_POINT_copy() النقطة src إلى dst. يجب أن يستخدم كل من src و dst نفس EC_METHOD.

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

تحصل EC_POINT_method_of() على EC_METHOD المرتبط بـ point. أُهملت هذه الدالة في OpenSSL 3.0، لأن EC_METHOD لم يعد مفهومًا عامًا.

النقطة الصالحة على منحنى هي النقطة الخاصة عند اللانهاية. تُضبط النقطة لتكون عند اللانهاية باستدعاء EC_POINT_set_to_infinity().

تصف الإحداثيات الأفينية لنقطة ما النقطة من حيث موضعي x و y. تضبط الدالة EC_POINT_set_affine_coordinates() إحداثيات x و y للنقطة p المعرفة على المنحنى المعطى في group. تضبط الدالة EC_POINT_get_affine_coordinates() x و y، أي منهما قد يكون NULL، إلى الإحداثيات المقابلة لـ p.

الدوال EC_POINT_set_affine_coordinates_GFp() و EC_POINT_set_affine_coordinates_GF2m() هي مرادفات لـ EC_POINT_set_affine_coordinates(). عُرّفت للتوافق العكسي فقط ولا ينبغي استخدامها.

الدوال EC_POINT_get_affine_coordinates_GFp() و EC_POINT_get_affine_coordinates_GF2m() هي مرادفات لـ EC_POINT_get_affine_coordinates(). عُرّفت للتوافق العكسي فقط ولا ينبغي استخدامها.

بالإضافة إلى الإحداثيات الأفينية، يمكن وصف النقطة بدلاً من ذلك بدلالة إحداثياتها الإسقاطية اليعقوبية (لمنحنيات Fp فقط). تُعبر الإحداثيات الإسقاطية اليعقوبية كثلاث قيم x و y و z. العمل في نظام الإحداثيات هذا يوفر عمليات ضرب نقاط أكثر كفاءة. يوجد تطابق بين الإحداثيات الإسقاطية اليعقوبية والإحداثيات الأفينية. يمكن كتابة الإحداثي الإسقاطي اليعقوبي (x, y, z) كإحداثي أفيني كـ (x/(z^2), y/(z^3)). التحويل من الإحداثيات الأفينية إلى الإحداثيات الإسقاطية اليعقوبية بسيط. يُطبق الإحداثي (x, y) إلى (x, y, 1). على الرغم من إهمالها في OpenSSL 3.0 ولا ينبغي استخدامها بعد الآن، لتعيين أو الحصول على الإحداثيات الإسقاطية في الإصدارات الأقدم استخدم EC_POINT_set_Jprojective_coordinates_GFp() و EC_POINT_get_Jprojective_coordinates_GFp() على التوالي. يجب أن تستخدم الإصدارات الحديثة بدلاً من ذلك EC_POINT_set_affine_coordinates() و EC_POINT_get_affine_coordinates()، مع إجراء التحويل يدويًا باستخدام الخرائط أعلاه في مثل هذه الظروف النادرة.

يمكن أيضًا وصف النقاط بدلالة إحداثياتها المضغوطة. لنقطة (x, y)، لأي قيمة معطاة لـ x بحيث تكون النقطة على المنحنى، سيكون هناك دائمًا قيمتان محتملتان فقط لـ y. لذلك، يمكن تعيين نقطة باستخدام الدالة EC_POINT_set_compressed_coordinates() حيث x هو الإحداثي x و y_bit هو قيمة 0 أو 1 لتحديد أي من القيمتين المحتملتين لـ y ينبغي استخدامها.

الدوال EC_POINT_set_compressed_coordinates_GFp() و EC_POINT_set_compressed_coordinates_GF2m() هي مرادفات لـ EC_POINT_set_compressed_coordinates(). عُرّفت للتوافق العكسي فقط ولا ينبغي استخدامها.

بالإضافة إلى ذلك، يمكن تحويل EC_POINT من وإلى تمثيلات خارجية متنوعة. الشكل الثماني هو الترميز الثنائي لبنية ECPoint (كما هو معرف في RFC5480 والمستخدم في الشهادات وسجلات TLS): فقط الثمانيات المحتوية موجودة، ولا يتم تضمين وسم OCTET STRING وطوله. شكل BIGNUM هو الشكل الثماني المفسر كعدد صحيح كبير النهاية محول إلى بنية BIGNUM. الشكل السداسي عشري هو الشكل الثماني المحول إلى سلسلة محارف منتهية بـ NULL حيث كل محرف هو إحدى القيم القابلة للطباعة 0-9 أو A-F (أو a-f).

الدوال EC_POINT_point2oct() و EC_POINT_oct2point() و EC_POINT_point2bn() و EC_POINT_bn2point() و EC_POINT_point2hex() و EC_POINT_hex2point() تحول من وإلى EC_POINTs للتنسيقات: الثماني و BIGNUM والسداسي عشري على التوالي.

الدالة EC_POINT_point2oct() تُعمِّي نقطة المنحنى المعطاة p كسلسلة محارف ثمانية في المخزن المؤقت buf بحجم len، باستخدام صيغة التحويل المحددة form. يتوافق الترميز مع القسم 2.3.3 من معيار SECG SEC 1 ("تعمية المنحنيات الإهليلجية"). وبالمثل، الدالة EC_POINT_oct2point() تفك ترميز نقطة منحنى إلى p من سلسلة المحارف الثمانية الموجودة في المخزن المؤقت المعطى buf بحجم len، متوافقة مع القسم 2.3.4 من معيار SECG SEC 1 ("تعمية المنحنيات الإهليلجية").

الدوال EC_POINT_point2hex() و EC_POINT_point2bn() تحول نقطة p، على التوالي، إلى تمثيل سداسي عشري أو BIGNUM لنفس ترميز الدالة EC_POINT_point2oct(). والعكس، بشكل مشابه للدالة EC_POINT_oct2point()، الدوال EC_POINT_hex2point() و EC_POINT_point2bn() تفك ترميز التمثيل السداسي العشري أو BIGNUM إلى EC_POINT p.

لاحظ أنه، وفقًا للمعيار، ترميز سلسلة المحارف الثمانية لنقطة اللانهاية لمنحنى معين ثابت على ثمانية واحدة قيمتها صفر، والعكس، ثمانية واحدة بحجم صفر تُفك ترميزها كنقطة اللانهاية.

يجب تزويد الدالة EC_POINT_point2oct() بمخزن مؤقت طويل بما يكفي لتخزين الصيغة الثمانية. توفر القيمة المعادة عدد الثمانيات المخزنة. استدعاء الدالة بمخزن مؤقت NULL لن يُجري التحويل ولكنه سيظل يُعيد طول المخزن المؤقت المطلوب.

الدالة EC_POINT_point2buf() تخصص مخزنًا مؤقتًا بطول مناسب وتكتب EC_POINT إليه بصيغة ثمانية. يُكتب المخزن المؤقت المخصص إلى *pbuf ويُعاد طوله. يجب على المستدعي تحرير المخزن المؤقت المخصص باستدعاء OPENSSL_free(). بما أن قيمة المخزن المؤقت المخصص تُكتب إلى *pbuf، فإن المعامل pbuf يجب ألا يكون NULL.

الدالة EC_POINT_point2hex() تخصص ذاكرة كافية لتخزين السلسلة السداسية العشرية. تقع على عاتق المستدعي مسؤولية تحرير هذه الذاكرة باستدعاء لاحق لـ OPENSSL_free().

القيم المُرجعة
EC_POINT_new() و EC_POINT_dup() تُعيدان EC_POINT المخصص حديثًا أو NULL عند الخطأ.

الدوال التالية تُعيد 1 عند النجاح أو 0 عند الخطأ: EC_POINT_copy(), EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates_GFp(), EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GF2m() و EC_POINT_oct2point().

EC_POINT_method_of تُعيد EC_METHOD المرتبط بـ EC_POINT المُقدم.

EC_POINT_point2oct() و EC_POINT_point2buf() تُعيدان طول المخزن المؤقت المطلوب أو 0 عند الخطأ.

EC_POINT_point2bn() تُعيد المؤشر إلى BIGNUM المُقدم، أو NULL عند الخطأ.

EC_POINT_bn2point() تُعيد المؤشر إلى EC_POINT المُقدم، أو NULL عند الخطأ.

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

EC_POINT_hex2point() تُعيد المؤشر إلى EC_POINT المُقدم، أو NULL عند الخطأ.

انظر أيضًا
crypto(7), EC_GROUP_new(3), EC_GROUP_copy(3), EC_POINT_add(3), EC_KEY_new(3), EC_GFp_simple_method(3), d2i_ECPKParameters(3)

التاريخ
EC_POINT_method_of(), EC_POINT_set_Jprojective_coordinates_GFp(), EC_POINT_get_Jprojective_coordinates_GFp(), EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), EC_POINT_set_compressed_coordinates_GFp(), EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), EC_POINT_set_compressed_coordinates_GF2m(), EC_POINT_point2bn(), و EC_POINT_bn2point() أُهملت في OpenSSL 3.0.

EC_POINT_set_affine_coordinates, EC_POINT_get_affine_coordinates, و EC_POINT_set_compressed_coordinates أُضيفت في OpenSSL 1.1.1.

حقوق النسخ
حقوق النشر 2013-2023 لمؤلفي مشروع 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.