ความปลอดภัยสําหรับ CoAP

โมดูลนี้ประกอบด้วยฟังก์ชันที่ควบคุมการสื่อสารของ CoAP Secure (CoAP over DTLS)

สรุป

ฟังก์ชันในโมดูลนี้พร้อมใช้งานเมื่อเปิดใช้ฟีเจอร์ API ความปลอดภัย CoAP (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)
แสดงผลใบรับรอง peer x509 base64 ที่เข้ารหัส
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
ตั้งค่า 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 Secure
otCoapSecureSetDefaultHandler(otInstance *aInstance, otCoapRequestHandler aHandler, void *aContext)
void
ตั้งค่าเครื่องจัดการเริ่มต้นสําหรับคําขอ CoAP Secure ที่ไม่มีการจัดการ
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 Secure
otCoapSecureStart(otInstance *aInstance, uint16_t aPort)
เริ่มต้นบริการ CoAP Secure
otCoapSecureStop(otInstance *aInstance)
void
หยุดเซิร์ฟเวอร์ CoAP Secure

ประเภทคําสั่ง

otHandleCoapSecureClientConnect

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

ระบบจะเรียกตัวชี้เมื่อสถานะการเชื่อมต่อ DTLS เปลี่ยนไป

รายละเอียด
พารามิเตอร์
[in] aConnected
"จริง" หากการเชื่อมต่อถูกสร้างขึ้น จะเป็น "เท็จ" หากไม่เป็นเช่นนั้น
[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
)

แสดงผลใบรับรอง peer x509 base64 ที่เข้ารหัส

รายละเอียด
พารามิเตอร์
[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
ตัวชี้ฟังก์ชันที่ถูกเรียกใช้ในการตอบสนองของ Block1
[in] aReceiveHook
ตัวชี้ฟังก์ชันที่ถูกเรียกใช้ในการตอบสนองของ Block2
แสดงผลค่า
OT_ERROR_NONE
ส่งข้อความ CoAP สําเร็จแล้ว
OT_ERROR_NO_BUFS
จัดสรรข้อมูลการส่งซ้ําไม่สําเร็จ
OT_ERROR_INVALID_STATE
การเชื่อมต่อ DTLS ไม่เริ่มขึ้น

คําตอบของ OTCoapSecureSend

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
ตัวชี้ฟังก์ชันที่ถูกเรียกใช้ในการตอบรับคําขอ 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
ตัวชี้ไปยังเชน PEM ที่จัดรูปแบบแล้วของ X509
[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 Secure ที่ไม่มีการจัดการ

รายละเอียด
พารามิเตอร์
[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 Identity

OTCoapSecureSetSslAuthMode

void otCoapSecureSetSslAuthMode(
  otInstance *aInstance,
  bool aVerifyPeerCertificate
)

ตั้งค่าโหมดการตรวจสอบสิทธิ์สําหรับการเชื่อมต่อแบบ Coap Secure

ปิดใช้หรือเปิดใช้การยืนยันของใบรับรองแอปเทียบเท่า ต้องเรียกก่อนเริ่ม

รายละเอียด
พารามิเตอร์
[in] aInstance
ตัวชี้ไปยังอินสแตนซ์ OpenThread
[in] aVerifyPeerCertificate
เป็น "จริง" เพื่อยืนยันใบรับรองการเพียร์

เริ่มCoapSecureStart

otError otCoapSecureStart(
  otInstance *aInstance,
  uint16_t aPort
)

เริ่มต้นบริการ CoAP Secure

รายละเอียด
พารามิเตอร์
[in] aInstance
ตัวชี้ไปยังอินสแตนซ์ OpenThread
[in] aPort
พอร์ต UDP ที่จะเชื่อมโยง
แสดงผลค่า
OT_ERROR_NONE
เริ่มต้นเซิร์ฟเวอร์ CoAP Secure สําเร็จแล้ว

หยุดการใช้งาน CoapSecureStop

void otCoapSecureStop(
  otInstance *aInstance
)

หยุดเซิร์ฟเวอร์ CoAP Secure

รายละเอียด
พารามิเตอร์
[in] aInstance
ตัวชี้ไปยังอินสแตนซ์ OpenThread

มาโคร

พอร์ต OT_DEFAULT_COAP_SECURE_PORT

 OT_DEFAULT_COAP_SECURE_PORT 5684

พอร์ตที่ปลอดภัยของ CoAP เริ่มต้น ตามที่ระบุไว้ใน RFC 7252

แหล่งข้อมูล

หัวข้ออ้างอิง OpenThread API มาจากซอร์สโค้ด ซึ่งพร้อมใช้งานใน GitHub ดูข้อมูลเพิ่มเติมหรือมีส่วนร่วมในเอกสารประกอบได้ที่แหล่งข้อมูล