برنامج الأمان الآمن للاستخدام على الإنترنت

تتضمّن هذه الوحدة دوالًا تتحكم في اتصال CoAP Secure (CoAP عبر DTLS).

ملخّص

تتوفّر الدوال في هذه الوحدة عند تفعيل ميزة CoAP Secure API (OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE).

أنواع المحددات

otHandleCoapSecureClientConnect)(bool aConnected, void *aContext) typedef
void(*
يتم استدعاء المؤشر عند تغيير حالة اتصال DTLS.

الدوال

otCoapSecureAddBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)
void
لإضافة مورد خاضع للحظر إلى خادم CoAP Secure.
otCoapSecureAddResource(otInstance *aInstance, otCoapResource *aResource)
void
إضافة مورد إلى خادم CoAP Secure.
otCoapSecureConnect(otInstance *aInstance, const otSockAddr *aSockAddr, otHandleCoapSecureClientConnect aHandler, void *aContext)
لإعداد جلسة DTLS مع نظير.
otCoapSecureDisconnect(otInstance *aInstance)
void
يتم إيقاف اتصال DTLS.
otCoapSecureGetPeerCertificateBase64(otInstance *aInstance, unsigned char *aPeerCert, size_t *aCertLength, size_t aCertBufferSize)
عرض شهادة x509 لشهادة Base 44 المشفّرة.
otCoapSecureIsConnected(otInstance *aInstance)
bool
يشير إلى ما إذا كانت جلسة DTLS متصلة أم لا.
otCoapSecureIsConnectionActive(otInstance *aInstance)
bool
يشير إلى ما إذا كانت جلسة DTLS نشطة أم لا.
otCoapSecureRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)
void
يؤدي هذا الخيار إلى إزالة مورد قد تم حظره من خادم CoAP Secure.
otCoapSecureRemoveResource(otInstance *aInstance, otCoapResource *aResource)
void
يؤدي هذا الإجراء إلى إزالة مورد من خادم CoAP Secure.
otCoapSecureSendRequest(otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext)
يتم إرسال طلب CoAP عبر اتصال DTLS آمن.
otCoapSecureSendRequestBlockWise(otInstance *aInstance, otMessage *aMessage, otCoapResponseHandler aHandler, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook, otCoapBlockwiseReceiveHook aReceiveHook)
يُرسِل طلب CoAP الحظر على اتصال DTLS الآمن.
otCoapSecureSendResponse(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo)
يتم إرسال استجابة CoAP من خادم CoAP Secure.
otCoapSecureSendResponseBlockWise(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook)
تُرسِل استجابة CoAP بحكمة من خادم CoAP Secure.
otCoapSecureSetCaCertificateChain(otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
void
تضبط مراجع التصديق ذات المستوى الأعلى الموثوق بها.
otCoapSecureSetCertificate(otInstance *aInstance, const uint8_t *aX509Cert, uint32_t aX509Length, const uint8_t *aPrivateKey, uint32_t aPrivateKeyLength)
void
لضبط شهادة X509 للجهاز المحلي باستخدام مفتاح خاص مقابل لجلسة DTLS باستخدام DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8.
otCoapSecureSetClientConnectedCallback(otInstance *aInstance, otHandleCoapSecureClientConnect aHandler, void *aContext)
void
لضبط معاودة الاتصال المتصلة لتوضيح العميل عندما يتصل أحد البرامج بخادم CoAP Secure.
otCoapSecureSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext)
void
لضبط المعالج التلقائي لطلبات أمان بروتوكول CoAP التي لم تتم معالجتها.
otCoapSecureSetPsk(otInstance *aInstance, const uint8_t *aPsk, uint16_t aPskLength, const uint8_t *aPskIdentity, uint16_t aPskIdLength)
void
تعيّن المفتاح المشترك مسبقًا (PSK) ومجموعة الرموز DTLS_PSK_WITH_AES_128_CCM_8.
otCoapSecureSetSslAuthMode(otInstance *aInstance, bool aVerifyPeerCertificate)
void
لضبط وضع المصادقة للاتصال الآمن.
otCoapSecureStart(otInstance *aInstance, uint16_t aPort)
يبدأ هذا الإعداد خدمة CoAP Secure.
otCoapSecureStop(otInstance *aInstance)
void
تعمل هذه السياسة على إيقاف خادم CoAP Secure.

أنواع المحددات

otHandleCoapSecureClientConnect

void(* otHandleCoapSecureClientConnect)(bool aConnected, void *aContext)

يتم استدعاء المؤشر عند تغيير حالة اتصال DTLS.

التفاصيل
المَعلمات
[in] aConnected
صحيح، إذا تم إنشاء اتصال، يتم إعداده على "false".
[in] aContext
مؤشر للمعلومات السياقية العشوائية.

الدوال

otCoapSecureAddBlockWiseResource

void otCoapSecureAddBlockWiseResource(
  otInstance *aInstance,
  otCoapBlockwiseResource *aResource
)

لإضافة مورد خاضع للحظر إلى خادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aResource
مؤشر إلى المورد

otCoapSecureAddResource

void otCoapSecureAddResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

إضافة مورد إلى خادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aResource
مؤشر إلى المورد

otCoapSecureConnect

otError otCoapSecureConnect(
  otInstance *aInstance,
  const otSockAddr *aSockAddr,
  otHandleCoapSecureClientConnect aHandler,
  void *aContext
)

لإعداد جلسة DTLS مع نظير.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aSockAddr
مؤشر إلى عنوان المقبس البعيد.
[in] aHandler
مؤشر لدالة سيتم طلبها عند تغيير حالة اتصال DTLS.
[in] aContext
مؤشر للمعلومات السياقية العشوائية.
قيم الإرجاع
OT_ERROR_NONE
تم بدء اتصال DTLS بنجاح.

otCoapsecureإلغاء الربط

void otCoapSecureDisconnect(
  otInstance *aInstance
)

يتم إيقاف اتصال DTLS.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.

otCoapSecureGetPeerCertificateBase64

otError otCoapSecureGetPeerCertificateBase64(
  otInstance *aInstance,
  unsigned char *aPeerCert,
  size_t *aCertLength,
  size_t aCertBufferSize
)

عرض شهادة x509 لشهادة Base 44 المشفّرة.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[out] aPeerCert
مؤشر إلى المخزن المؤقت للشهادة بترميز Base64.
[out] aCertLength
طول شهادة الأقراص Base64 المشفّرة.
[in] aCertBufferSize
حجم المخزن المؤقت لـ aPeerCert.
قيم الإرجاع
OT_ERROR_INVALID_STATE
غير متصل حتى الآن.
OT_ERROR_NONE
الحصول على شهادة زميل بنجاح
OT_ERROR_NO_BUFS
لا يمكن تخصيص الذاكرة للشهادة.

otCoapSecureIsConnected

bool otCoapSecureIsConnected(
  otInstance *aInstance
)

يشير إلى ما إذا كانت جلسة DTLS متصلة أم لا.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
قيم الإرجاع
TRUE
تم الاتصال بجلسة DTLS.
FALSE
جلسة DTLS غير متصلة.

otCoapSecureIsConnectionActive

bool otCoapSecureIsConnectionActive(
  otInstance *aInstance
)

يشير إلى ما إذا كانت جلسة DTLS نشطة أم لا.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
قيم الإرجاع
TRUE
في حال كانت جلسة بروتوكول أمان طبقة النقل لمخطّطات البيانات (DTLS) نشطة
FALSE
في حال لم تكن جلسة بروتوكول أمان طبقة النقل لمخطّطات البيانات (DTLS) نشطة.

otCoapSecureRemoveBlockWiseResource

void otCoapSecureRemoveBlockWiseResource(
  otInstance *aInstance,
  otCoapBlockwiseResource *aResource
)

يؤدي هذا الخيار إلى إزالة مورد قد تم حظره من خادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aResource
مؤشر إلى المورد

otCoapSecureRemoveResource

void otCoapSecureRemoveResource(
  otInstance *aInstance,
  otCoapResource *aResource
)

يؤدي هذا الإجراء إلى إزالة مورد من خادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aResource
مؤشر إلى المورد

otCoapSecureSendRequest

otError otCoapSecureSendRequest(
  otInstance *aInstance,
  otMessage *aMessage,
  otCoapResponseHandler aHandler,
  void *aContext
)

يتم إرسال طلب CoAP عبر اتصال DTLS آمن.

إذا كان من المتوقّع تلقّي ردّ على طلب، يجب تقديم معلومات حول الدالة والسياق. إذا لم يكن من المتوقع الحصول على رد، يجب أن تكون هذه الوسيطات عبارة عن مؤشرات NULL. إذا لم يتم ضبط رقم تعريف الرسالة في العنوان (يساوي 0)، ستخصِّص هذه الدالة رقم تعريف الرسالة الفريد للرسالة.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aMessage
إشارة إلى الرسالة المطلوب إرسالها
[in] aHandler
مؤشر داعم يجب طلبه عند استقبال الاستجابة أو انتهاء المهلة
[in] aContext
مؤشر للمعلومات السياقية العشوائية.
قيم الإرجاع
OT_ERROR_NONE
تم إرسال رسالة CoAP بنجاح.
OT_ERROR_NO_BUFS
تعذّر تخصيص بيانات إعادة الإرسال.
OT_ERROR_INVALID_STATE
لم يتم إعداد اتصال DTLS.

otCoapSecureSendRequestBlockWise

otError otCoapSecureSendRequestBlockWise(
  otInstance *aInstance,
  otMessage *aMessage,
  otCoapResponseHandler aHandler,
  void *aContext,
  otCoapBlockwiseTransmitHook aTransmitHook,
  otCoapBlockwiseReceiveHook aReceiveHook
)

يُرسِل طلب CoAP الحظر على اتصال DTLS الآمن.

متاح عند تفعيل الإعداد OPENThread_CONFIG_COAP_BLOCKWISE_Transfer_ENABLE.

إذا كان من المتوقّع تلقّي ردّ على طلب، يجب تقديم معلومات حول الدالة والسياق. إذا لم يكن من المتوقع الحصول على رد، يجب أن تكون هذه الوسيطات عبارة عن مؤشرات NULL. إذا لم يتم ضبط رقم تعريف الرسالة في العنوان (يساوي 0)، ستخصِّص هذه الدالة رقم تعريف الرسالة الفريد للرسالة.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aMessage
إشارة إلى الرسالة المطلوب إرسالها
[in] aHandler
مؤشر داعم يجب طلبه عند استقبال الاستجابة أو انتهاء المهلة
[in] aContext
مؤشر للمعلومات السياقية العشوائية.
[in] aTransmitHook
مؤشر دالّة تُسمى عند استقبال الرد على الحظر 1.
[in] aReceiveHook
مؤشر دالّة تُسمى عند استقبال الاستجابة من الحظر 2.
قيم الإرجاع
OT_ERROR_NONE
تم إرسال رسالة CoAP بنجاح.
OT_ERROR_NO_BUFS
تعذّر تخصيص بيانات إعادة الإرسال.
OT_ERROR_INVALID_STATE
لم يتم إعداد اتصال DTLS.

otCoapSecureSendResponse

otError otCoapSecureSendResponse(
  otInstance *aInstance,
  otMessage *aMessage,
  const otMessageInfo *aMessageInfo
)

يتم إرسال استجابة CoAP من خادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aMessage
مؤشر على استجابة CoAP للإرسال
[in] aMessageInfo
مؤشر إلى معلومات الرسالة المرتبطة بـ aMessage.
قيم الإرجاع
OT_ERROR_NONE
تمت إضافة رسالة استجابة CoAP بنجاح.
OT_ERROR_NO_BUFS
لا تتوفّر مخازن مؤقتة كافية لإرسال استجابة CoAP.

otCoapSecureSendResponseBlockWise

otError otCoapSecureSendResponseBlockWise(
  otInstance *aInstance,
  otMessage *aMessage,
  const otMessageInfo *aMessageInfo,
  void *aContext,
  otCoapBlockwiseTransmitHook aTransmitHook
)

تُرسِل استجابة CoAP بحكمة من خادم CoAP Secure.

متاح عند تفعيل الإعداد OPENThread_CONFIG_COAP_BLOCKWISE_Transfer_ENABLE.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aMessage
مؤشر على استجابة CoAP للإرسال
[in] aMessageInfo
مؤشر إلى معلومات الرسالة المرتبطة بـ aMessage.
[in] aContext
مؤشر للمعلومات السياقية العشوائية. قد تكون فارغة في حال عدم استخدامها.
[in] aTransmitHook
مؤشر دالّة تُسمى عند استقبال طلب الحظر 1.
قيم الإرجاع
OT_ERROR_NONE
تمت إضافة رسالة استجابة CoAP بنجاح.
OT_ERROR_NO_BUFS
لا تتوفّر مخازن مؤقتة كافية لإرسال استجابة CoAP.

otCoapSecureSetCaCertificateChain

void otCoapSecureSetCaCertificateChain(
  otInstance *aInstance,
  const uint8_t *aX509CaCertificateChain,
  uint32_t aX509CaCertChainLength
)

تضبط مراجع التصديق ذات المستوى الأعلى الموثوق بها.

وهي مطلوبة للتحقق من شهادة برنامج التطبيقات المشابهة.

وضع DTLS "ECDHE ECDSA with AES 128 CCM 8" للتطبيق CoAPS.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aX509CaCertificateChain
مؤشر إلى سلسلة X509 CA بتنسيق PEM.
[in] aX509CaCertChainLength
طول السلسلة.

otCoapSecureSetCertificate

void otCoapSecureSetCertificate(
  otInstance *aInstance,
  const uint8_t *aX509Cert,
  uint32_t aX509Length,
  const uint8_t *aPrivateKey,
  uint32_t aPrivateKeyLength
)

لضبط شهادة X509 للجهاز المحلي باستخدام مفتاح خاص مقابل لجلسة DTLS باستخدام DTLS_ECDHE_ECDSA_WITH_AES_128_CCM_8.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aX509Cert
مؤشر لشهادة X509 بتنسيق PEM.
[in] aX509Length
طول الشهادة.
[in] aPrivateKey
مؤشر للمفتاح الخاص المنسّق في برنامج PEM.
[in] aPrivateKeyLength
طول المفتاح الخاص.

otCoapSecureSetClientConnectedCallback

void otCoapSecureSetClientConnectedCallback(
  otInstance *aInstance,
  otHandleCoapSecureClientConnect aHandler,
  void *aContext
)

لضبط معاودة الاتصال المتصلة لتوضيح العميل عندما يتصل أحد البرامج بخادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aHandler
مؤشر لدالة سيتم طلبها بعد إنشاء اتصال بروتوكول أمان طبقة النقل لمخطّطات البيانات (DTLS).
[in] aContext
مؤشر للمعلومات السياقية العشوائية. قد تكون فارغة في حال عدم استخدامها.

otCoapSecureSetDefaultHandler

void otCoapSecureSetDefaultHandler(
  otInstance *aInstance,
  otCoapRequestHandler aHandler,
  void *aContext
)

لضبط المعالج التلقائي لطلبات أمان بروتوكول CoAP التي لم تتم معالجتها.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aHandler
مؤشر دالة سيتم طلبه عند وصول طلب لم تتم معالجته.
[in] aContext
مؤشر للمعلومات السياقية العشوائية. قد تكون فارغة في حال عدم استخدامها.

otCoapSecureSetPsk

void otCoapSecureSetPsk(
  otInstance *aInstance,
  const uint8_t *aPsk,
  uint16_t aPskLength,
  const uint8_t *aPskIdentity,
  uint16_t aPskIdLength
)

تعيّن المفتاح المشترك مسبقًا (PSK) ومجموعة الرموز DTLS_PSK_WITH_AES_128_CCM_8.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aPsk
مؤشر PSK
[in] aPskLength
طول PSK
[in] aPskIdentity
اسم هوية PSK
[in] aPskIdLength
طول هوية PSK

otCoapSecureSetSslAuthMode

void otCoapSecureSetSslAuthMode(
  otInstance *aInstance,
  bool aVerifyPeerCertificate
)

لضبط وضع المصادقة للاتصال الآمن.

إيقاف أو تفعيل التحقّق من شهادة النظير يجب طلبها قبل البدء.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aVerifyPeerCertificate
صحيح، للتحقق من شهادة الشبكة المشابهة.

otCoapSecureStart

otError otCoapSecureStart(
  otInstance *aInstance,
  uint16_t aPort
)

يبدأ هذا الإعداد خدمة CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aPort
منفذ UDP المحلي لربطه
قيم الإرجاع
OT_ERROR_NONE
تم بدء تشغيل خادم CoAP Secure بنجاح.

otCoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

تعمل هذه السياسة على إيقاف خادم CoAP Secure.

التفاصيل
المَعلمات
[in] aInstance
مؤشر إلى مثيل OpenThread.

وحدات ماكرو

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

منفذ CoAP الآمن التلقائي، على النحو المحدَّد في RFC 7252.

الموارد

تبدأ مواضيع مراجع واجهة برمجة تطبيقات OpenThread من رمز المصدر، وهو متاح على GitHub. للحصول على مزيد من المعلومات أو للمساهمة في المستندات، يمكنك الاطّلاع على المراجع.