ASN1_TIME_SET(3SSL)

الاسم
ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set, ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj, ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check, ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string, ASN1_TIME_set_string_X509, ASN1_TIME_normalize, ASN1_TIME_to_tm, ASN1_TIME_print, ASN1_TIME_print_ex, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print, ASN1_TIME_diff, ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t, ASN1_TIME_compare, ASN1_TIME_to_generalizedtime, ASN1_TIME_dup, ASN1_UTCTIME_dup, ASN1_GENERALIZEDTIME_dup - دوال وقت ASN.1

موجز
 ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
 ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
 ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
                                                time_t t);

 ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,
                          long offset_sec);
 ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,
                                int offset_day, long offset_sec);
 ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,
                                                time_t t, int offset_day,
                                                long offset_sec);

 int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
 int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
 int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
 int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,
                                     const char *str);

 int ASN1_TIME_normalize(ASN1_TIME *s);

 int ASN1_TIME_check(const ASN1_TIME *t);
 int ASN1_UTCTIME_check(const ASN1_UTCTIME *t);
 int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);

 int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
 int ASN1_TIME_print_ex(BIO *bp, const ASN1_TIME *tm, unsigned long flags);
 int ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s);
 int ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s);

 int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);
 int ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from,
                    const ASN1_TIME *to);

 int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);
 int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);

 int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);

 ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t,
                                                    ASN1_GENERALIZEDTIME **out);

 ASN1_TIME *ASN1_TIME_dup(const ASN1_TIME *t);
 ASN1_UTCTIME *ASN1_UTCTIME_dup(const ASN1_UTCTIME *t);
 ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_dup(const ASN1_GENERALIZEDTIME *t);

الوصف
تضبط الدوال ASN1_TIME_set() و ASN1_UTCTIME_set() و ASN1_GENERALIZEDTIME_set() البنية s إلى الوقت الممثل بقيمة time_t t. إذا كان s فارغًا (NULL)، يُخصص بنية وقت جديدة وتُعاد.

تضبط الدوال ASN1_TIME_adj() و ASN1_UTCTIME_adj() و ASN1_GENERALIZEDTIME_adj() بنية الوقت s إلى الوقت الممثل بالوقت offset_day و offset_sec بعد قيمة time_t t. يمكن أن تكون قيم offset_day أو offset_sec سالبة لضبط وقت قبل t. يمكن أن تتجاوز قيمة offset_sec أيضًا عدد الثواني في اليوم. إذا كان s فارغًا (NULL)، تُخصص بنية جديدة وتُعاد.

تضبط الدوال ASN1_TIME_set_string() و ASN1_UTCTIME_set_string() و ASN1_GENERALIZEDTIME_set_string() بنية الوقت s إلى الوقت الممثل بالسلسلة str التي يجب أن تكون بصيغة وقت ASN.1 المناسبة (على سبيل المثال YYMMDDHHMMSSZ أو YYYYMMDDHHMMSSZ). إذا كان s فارغًا (NULL)، تُجري هذه الدالة فحصًا للصيغة على str فقط. تُنسخ السلسلة str إلى s.

تضبط ASN1_TIME_set_string_X509() بنية ASN1_TIME s إلى الوقت الممثل بالسلسلة str التي يجب أن تكون بصيغة الوقت المناسبة التي يتطلبها RFC 5280، مما يعني أنها تسمح فقط بـ YYMMDDHHMMSSZ و YYYYMMDDHHMMSSZ (تُرفض الثانية الكبيسة)، ولا يُسمح بأي صيغة وقت ASN.1 أخرى. إذا كان s فارغًا (NULL)، تُجري هذه الدالة فحصًا للصيغة على str فقط.

تحول الدالة ASN1_TIME_normalize() ASN1_GENERALIZEDTIME أو ASN1_UTCTIME إلى قيمة وقت يمكن استخدامها في شهادة. يجب استخدامها بعد دوال ASN1_TIME_set_string() وقبل دوال ASN1_TIME_print() للحصول على نتائج متسقة (أي GMT).

تفحص الدوال ASN1_TIME_check() و ASN1_UTCTIME_check() و ASN1_GENERALIZEDTIME_check() بناء جملة بنية الوقت s.

تطبع الدوال ASN1_TIME_print() و ASN1_UTCTIME_print() و ASN1_GENERALIZEDTIME_print() بنية الوقت s إلى BIO b بصيغة قابلة للقراءة البشرية. ستكون بالصيغة MMM DD HH:MM:SS[.s*] YYYY GMT، على سبيل المثال "Feb 3 00:55:52 2015 GMT"، والتي لا تتضمن سطرًا جديدًا. إذا كانت بنية الوقت ذات صيغة غير صالحة، تطبع "Bad time value" وتُعيد خطأ. قد يتضمن ناتج الوقت المعمم جزءًا كسريًا بعد الثانية.

توفر ASN1_TIME_print_ex() flags لتحديد صيغة ناتج التاريخ والوقت. يمكن أن تكون إما ASN1_DTFLGS_RFC822 أو ASN1_DTFLGS_ISO8601.

ASN1_TIME_to_tm() تحوِّل الوقت s إلى بنية tm القياسية. إذا كان s فارغًا (NULL)، يُحوَّل الوقت الحالي. وقت الخرج هو GMT. تُضبط حقول tm_sec و tm_min و tm_hour و tm_mday و tm_wday و tm_yday و tm_mon و tm_year من بنية tm إلى القيم الصحيحة، بينما تُضبط جميع الحقول الأخرى إلى 0. إذا كان tm فارغًا (NULL)، تؤدي هذه الدالة فحص تنسيق على s فقط. إذا كان s بتنسيق Generalized مع ثوانٍ كسرية، مثل YYYYMMDDHHMMSS.SSSZ، تُفقد الثواني الكسرية أثناء تحويل s إلى بنية tm.

ASN1_TIME_diff() تضبط *pday و *psec على فرق الوقت بين from و to. إذا مثَّل to وقتًا لاحقًا من from، يكون أحد أو كلا (تبعًا لفرق الوقت) من *pday و *psec موجبًا. إذا مثَّل to وقتًا أسبق من from، يكون أحد أو كلا من *pday و *psec سالبًا. إذا مثَّل to و from نفس الوقت، يكون *pday و *psec كلاهما صفرًا. إذا كان كل من *pday و *psec غير صفري، يكون لهما دائمًا نفس الإشارة. تكون قيمة *psec دائمًا أقل من عدد الثواني في اليوم. إذا كان from أو to فارغًا (NULL)، يُستخدم الوقت الحالي.

تقارن الدالتان ASN1_TIME_cmp_time_t() و ASN1_UTCTIME_cmp_time_t() بين الوقتين الممثلين ببنية الوقت s و time_t t.

تقارن الدالة ASN1_TIME_compare() بين الوقتين الممثلين ببنيتي الوقت a و b.

تحوِّل الدالة ASN1_TIME_to_generalizedtime() ASN1_TIME إلى ASN1_GENERALIZEDTIME، بغض النظر عن السنة. إذا كان أي من out أو *out فارغًا (NULL)، يُخصص كائن جديد ويجب تحريره بعد الاستخدام.

تنسخ الدوال ASN1_TIME_dup() و ASN1_UTCTIME_dup() و ASN1_GENERALIZEDTIME_dup() بنية الوقت t وتُعيد النتيجة المنسوخة على التوالي.

ملاحظات
هيكل ASN1_TIME يُطابق هيكل ASN.1 Time المُعرّف في RFC5280 وغيره. دوال ضبط الوقت تتبع القواعد المُوضّحة في RFC5280: إذا أمكن تمثيل التاريخ باستخدام UTCTime يُستخدم، وإلا يُستخدم GeneralizedTime.

الهياكل ASN1_TIME و ASN1_UTCTIME و ASN1_GENERALIZEDTIME تُعرَض كـ ASN1_STRING داخلياً ويمكن تحريرها باستخدام ASN1_STRING_free().

هيكل ASN1_TIME يمكنه تمثيل السنوات من 0000 إلى 9999 لكن لا تُبذل محاولة لتصحيح تغييرات التقويم القديمة (مثلاً من التقويم اليولياني إلى الغريغوري).

ASN1_UTCTIME محدود بنطاق سنوات من 1950 إلى 2049.

بعض التطبيقات تُضيف أوقات الإزاحة مباشرة إلى قيمة time_t وتُمرر النتائج إلى ASN1_TIME_set() (أو ما يعادله). هذا قد يُسبب مشاكل لأن قيمة time_t قد تفيض على بعض الأنظمة مما يُنتج نتائج غير متوقعة. التطبيقات الجديدة يجب أن تستخدم ASN1_TIME_adj() بدلاً من ذلك وتُمرر قيمة الإزاحة في المعاملين offset_sec و offset_day بدلاً من التلاعب المباشر بقيمة time_t.

ASN1_TIME_adj() قد يُغير النوع من ASN1_GENERALIZEDTIME إلى ASN1_UTCTIME، أو العكس، بناءً على السنة الناتجة. ASN1_GENERALIZEDTIME_adj() و ASN1_UTCTIME_adj() لن يُعدّلا نوع الهيكل المُعاد.

يُوصى باستخدام الدوال التي تبدأ بـ ASN1_TIME بدلاً من تلك التي تبدأ بـ ASN1_UTCTIME أو ASN1_GENERALIZEDTIME. الدوال التي تبدأ بـ ASN1_UTCTIME و ASN1_GENERALIZEDTIME تعمل فقط على تنسيق الوقت المحدد ذلك. الدوال التي تبدأ بـ ASN1_TIME ستعمل على أي من التنسيقين.

المستخدمون المُلمّون بـ RFC822 يجب أن يلاحظوا أنه عند تحديد العلامة ASN1_DTFLGS_RFC822 سيتم تنسيق السنة كما هو مُوثّق أعلاه، أي باستخدام 4 أرقام، وليس 2 كما هو مُحدّد في RFC822.

العلل
ASN1_TIME_print() و ASN1_UTCTIME_print() و ASN1_GENERALIZEDTIME_print() لا تطبع المنطقة الزمنية: إما تطبع "GMT" أو لا شيء. لكن جميع الشهادات المُتوافقة مع RFC5280 وغيره تستخدم GMT على أي حال.

ASN1_TIME_print() و ASN1_TIME_print_ex() و ASN1_UTCTIME_print() و ASN1_GENERALIZEDTIME_print() لا تُميّز إذا فشلت بسبب خطأ I/O أو تنسيق وقت غير صالح.

استخدم دالة ASN1_TIME_normalize() لتطبيع قيمة الوقت قبل الطباعة للحصول على نتائج GMT.

القيم المُرجعة
ASN1_TIME_set() و ASN1_UTCTIME_set() و ASN1_GENERALIZEDTIME_set() و ASN1_TIME_adj() و ASN1_UTCTIME_adj() و ASN1_GENERALIZEDTIME_set() تُعيد مؤشراً إلى هيكل وقت أو NULL إذا حدث خطأ.

ASN1_TIME_set_string() و ASN1_UTCTIME_set_string() و ASN1_GENERALIZEDTIME_set_string() و ASN1_TIME_set_string_X509() تُعيد 1 إذا تم ضبط قيمة الوقت بنجاح و0 خلاف ذلك.

ASN1_TIME_normalize() تُعيد 1 عند النجاح، و0 عند الخطأ.

ASN1_TIME_check() و ASN1_UTCTIME_check و ASN1_GENERALIZEDTIME_check() تُعيد 1 إذا كان الهيكل صحيحاً نحوياً و0 خلاف ذلك.

ASN1_TIME_print() و ASN1_UTCTIME_print() و ASN1_GENERALIZEDTIME_print() تُعيد 1 إذا تم طباعة الوقت بنجاح و0 إذا حدث خطأ I/O أو حدث خطأ (خطأ I/O أو تنسيق وقت غير صالح).

ASN1_TIME_to_tm() تُعيد 1 إذا تم تحليل الوقت بنجاح و0 إذا حدث خطأ (تنسيق وقت غير صالح).

ASN1_TIME_diff() تُعيد 1 للنجاح و0 للفشل. يمكن أن تفشل إذا كان هيكل الوقت المُمرّر يحتوي على نحو غير صالح، على سبيل المثال.

ASN1_TIME_cmp_time_t() و ASN1_UTCTIME_cmp_time_t() تُعيد -1 إذا كان s قبل t، و0 إذا كان s يساوي t، أو 1 إذا كان s بعد t. -2 تُعاد عند الخطأ.

ASN1_TIME_compare() تُعيد -1 إذا كان a قبل b، و0 إذا كان a يساوي b، أو 1 إذا كان a بعد b. -2 تُعاد عند الخطأ.

ASN1_TIME_to_generalizedtime() تُرجع مؤشرًا إلى بنية الوقت المناسبة عند النجاح أو NULL إذا حدث خطأ.

ASN1_TIME_dup() و ASN1_UTCTIME_dup() و ASN1_GENERALIZEDTIME_dup() تُرجع مؤشرًا إلى بنية وقت أو NULL إذا حدث خطأ.

أمثلة
اضبط بنية الوقت على ساعة واحدة بعد الوقت الحالي واطبعها:

 #include <time.h>
 #include <openssl/asn1.h>

 ASN1_TIME *tm;
 time_t t;
 BIO *b;

 t = time(NULL);
 tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
 b = BIO_new_fp(stdout, BIO_NOCLOSE);
 ASN1_TIME_print(b, tm);
 ASN1_STRING_free(tm);
 BIO_free(b);

حدد إذا كان وقت ما لاحقًا أو أسبق من الوقت الحالي:

 int day, sec;

 if (!ASN1_TIME_diff(&day, &sec, NULL, to))
     /* Invalid time format */

 if (day > 0 || sec > 0)
     printf("Later\n");
 else if (day < 0 || sec < 0)
     printf("Sooner\n");
 else
     printf("Same\n");

التاريخ
الدالة ASN1_TIME_to_tm() أُضيفت في OpenSSL 1.1.1. الدالة ASN1_TIME_set_string_X509() أُضيفت في OpenSSL 1.1.1. الدالة ASN1_TIME_normalize() أُضيفت في OpenSSL 1.1.1. الدالة ASN1_TIME_cmp_time_t() أُضيفت في OpenSSL 1.1.1. الدالة ASN1_TIME_compare() أُضيفت في OpenSSL 1.1.1.

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