خدمة CoAP الآمنة

تشمل هذه الوحدة وظائف تتحكم في اتصال CoAP الآمن (COAP عبر DTLS).

الملخّص

الدوال المتوفّرة في هذه الوحدة متاحة عند تفعيل ميزة واجهة برمجة تطبيقات CoAP الآمنة (OPENTHREAD_CONFIG_COAP_SECURE_API_ENABLE).

مواقد الخط

otHandleCoapSecureClientConnect)(bool aConnected, void *aContext) مَعلمة typetype
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)
تعرض هذه الطريقة تشفير base64 للشهادة x509 المشابهة.
otCoapSecureIsConnected(otInstance *aInstance)
bool
تشير هذه الطريقة إلى ما إذا كانت جلسة DTLS متصلة أم لا.
otCoapSecureIsConnectionActive(otInstance *aInstance)
bool
تشير هذه الطريقة إلى ما إذا كانت جلسة DTLS نشطة أم لا.
otCoapSecureRemoveBlockWiseResource(otInstance *aInstance, otCoapBlockwiseResource *aResource)
void
تزيل هذه الدالة مورد حظر الحظر من خادم CoAP الآمن.
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 الآمن.
otCoapSecureSendResponseBlockWise(otInstance *aInstance, otMessage *aMessage, const otMessageInfo *aMessageInfo, void *aContext, otCoapBlockwiseTransmitHook aTransmitHook)
ترسل هذه الدالة حظر CoAP على مستوى الحظر من خادم CoAP الآمن.
otCoapSecureSetCaCertificateChain(otInstance *aInstance, const uint8_t *aX509CaCertificateChain, uint32_t aX509CaCertChainLength)
void
تحدد هذه الطريقة شهادات CA ذات المستوى الأعلى.
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.
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
تحدد هذه الطريقة وضع المصادقة للاتصال الآمن لـ coap.
otCoapSecureStart(otInstance *aInstance, uint16_t aPort)
تبدأ هذه الدالة خدمة CoAP Secure.
otCoapSecureStop(otInstance *aInstance)
void
توقف هذه الدالة خادم خادم CoAP الآمن.

مواقد الخط

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
)

تعرض هذه الطريقة تشفير base64 للشهادة x509 المشابهة.

التفاصيل
المعلَمات
[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 الآمن.

التفاصيل
المعلَمات
[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 آمن.

إذا كان من المتوقع الرد على الطلب، يجب تقديم معلومات عن الدالة والسياق المعنيّ. في حال عدم توقُّع استجابة، يجب أن تكون هذه الوسيطات فارغة. إذا لم يتم ضبط "معرِّف الرسالة" في رأس الرسالة (يساوي 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 آمن.

تتوفر هذه الدالة عند تفعيل ضبط OpenGLيجب أن يتم ضبط تهيئة {7}CREATE_CONFIG_COAP_BlockWISE_TRANSFER_ENABLE.

إذا كان من المتوقع الرد على الطلب، يجب تقديم معلومات عن الدالة والسياق المعنيّ. في حال عدم توقُّع استجابة، يجب أن تكون هذه الوسيطات فارغة. إذا لم يتم ضبط "معرِّف الرسالة" في رأس الرسالة (يساوي 0)، ستحدِّد هذه الدالة "معرِّف رسالة" فريدًا للرسالة.

التفاصيل
المعلَمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aMessage
إشارة إلى الرسالة المطلوب إرسالها.
[in] aHandler
مؤشر دالة يتم استدعاؤه عند استقبال الردود أو انتهاء المهلة.
[in] aContext
مؤشر لمعلومات السياق العشوائية.
[in] aTransmitHook
مؤشر دالة يتم استدعاءه في استقبال استجابة Block1.
[in] aReceiveHook
مؤشر دالة يتم استدعاءه في استقبال استجابة Block2.
قيم الإرجاع
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 الآمن.

التفاصيل
المعلَمات
[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 الآمن.

تتوفر هذه الدالة عند تفعيل ضبط OpenGLيجب أن يتم ضبط تهيئة {7}CREATE_CONFIG_COAP_BlockWISE_TRANSFER_ENABLE.

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

otCoapSecureSetCaCertificateChain

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

تحدد هذه الطريقة شهادات CA ذات المستوى الأعلى.

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

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

التفاصيل
المعلَمات
[in] aInstance
مؤشر إلى مثيل OpenThread.
[in] aX509CaCertificateChain
مؤشر إلى سلسلة CA X509 بتنسيق 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.

التفاصيل
المعلَمات
[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
)

تحدد هذه الطريقة وضع المصادقة للاتصال الآمن لـ coap.

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

التفاصيل
المعلَمات
[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 الآمن.

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

وحدات ماكرو

OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

منفذ CoAP الآمن التلقائي، كما هو محدد في RFC 7252.

المراجع

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