DTLS API
Thread Stack API Reference > Messaging

Macros

#define EMBER_DTLS_MODE_CERT 0x01
Define the various modes of a DTLS connection.
#define EMBER_DTLS_MODE_PSK 0x02
#define EMBER_DTLS_MODE_PKEY 0x04

Typedefs

typedef uint8_t EmberDtlsMode

Functions

void emberSetDtlsDeviceCertificate (const CertificateAuthority **certAuthority, const DeviceCertificate *deviceCert)
Set a device certificate to be used to create a certificate based secure session on the application. The expected arguments are DER encoded X.509 certificates. If this succeeds, emberSetDtlsDeviceCertificateReturn should return 0.
void emberSetDtlsDeviceCertificateReturn (uint32_t result)
Provides the result of a call to emberSetDtlsDeviceCertificate() .
void emberSetDtlsPresharedKey (const uint8_t *key, uint8_t keyLength, const EmberIpv6Address *remoteAddress)
Set a key to be used to create a PSK based secure session on the application. The maximum length of the key is 32 bytes.
void emberSetDtlsPresharedKeyReturn ( EmberStatus status)
Provides the result of a call to emberSetDtlsPresharedKey() .
void emberOpenDtlsConnection ( EmberDtlsMode dtlsMode, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Establish a DTLS connection with a peer on the Thread network. When established, this session can be used to send secure CoAP data. The device requesting the connection acts as a DTLS client.
void emberOpenDtlsConnectionReturn (uint32_t result, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Provides the result of a call to emberOpenDtlsConnection() .
void emberDtlsSecureSessionEstablished (uint8_t flags, uint8_t sessionId, const EmberIpv6Address *localAddress, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Indicates to the application that a secure connection was successfully established.
void emberGetSecureDtlsSessionId (const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Request the session ID given connection parameters.
void emberGetSecureDtlsSessionIdReturn (uint8_t sessionId, const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Provides the result of a call to emberGetSecureDtlsSessionId() .
void emberCloseDtlsConnection (uint8_t sessionId)
Close a currently active secure session on the application. When successful, emberCloseDtlsConnectionReturn should be called on both ends of the connection with EMBER_SUCCESS .
void emberCloseDtlsConnectionReturn (uint8_t sessionId, EmberStatus status)
Provides the result of a call to emberCloseDtlsConnection() , or indicates that the connection was closed on the other end.
bool emberDtlsTransmitHandler (const uint8_t *payload, uint16_t payloadLength, const EmberIpv6Address *localAddress, uint16_t localPort, const EmberIpv6Address *remoteAddress, uint16_t remotePort, void *transmitHandlerData)
Public DTLS transmit handler to be set in emberCoapSend. The secure payload is delivered via emberProcessCoap on the other end, with a matching session ID in the transmitHandlerData of its CoapRequestInfo. See emberProcessCoap ( stack/include/coap.h )

Detailed Description

See dtls.h for source code.

Macro Definition Documentation

#define EMBER_DTLS_MODE_CERT   0x01

Note: Please configure either the CERT or PSK modes, as the public key option is currently unavailable.

#define EMBER_DTLS_MODE_PKEY   0x04
#define EMBER_DTLS_MODE_PSK   0x02

Typedef Documentation

typedef uint8_t EmberDtlsMode

Function Documentation

void emberCloseDtlsConnection ( uint8_t sessionId )
Parameters
sessionId sessionId used for secure CoAP transport.
void emberCloseDtlsConnectionReturn ( uint8_t sessionId,
EmberStatus status
)
Parameters
sessionId sessionId used for secure CoAP transport.
status
void emberDtlsSecureSessionEstablished ( uint8_t flags,
uint8_t sessionId,
const EmberIpv6Address * localAddress,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
flags 1 = server, 0 = client (possibly other info later)
sessionId sessionId used for secure CoAP transport
localAddress local IPv6 address
remoteAddress remote IPv6 address
localPort local port
remotePort remote port
bool emberDtlsTransmitHandler ( const uint8_t * payload,
uint16_t payloadLength,
const EmberIpv6Address * localAddress,
uint16_t localPort,
const EmberIpv6Address * remoteAddress,
uint16_t remotePort,
void * transmitHandlerData
)
Parameters
payload CoAP payload to be sent securely
payloadLength payload length
localAddress local IPv6 address
localPort local port
remoteAddress remote IPv6 address
remotePort remote port
transmitHandlerData session ID of the secure connection (see emberDtlsSecureSessionEstablished or emberGetSecureDtlsSessionId above)
void emberGetSecureDtlsSessionId ( const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
remoteAddress remote IPv6 address
localPort local port
remotePort remote port
void emberGetSecureDtlsSessionIdReturn ( uint8_t sessionId,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
sessionId sessionId used for secure CoAP transport
remoteAddress remote IPv6 address
localPort local port
remotePort remote port
void emberOpenDtlsConnection ( EmberDtlsMode dtlsMode,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)

(For DotDot applications, the local port and remote port are both EMBER_COAP_SECURE_PORT )

Parameters
dtlsMode DTLS connection mode (see EMBER_DTLS_MODE_* above)
remoteAddress IPv6 address of the server
localPort local port
remotePort remote port
void emberOpenDtlsConnectionReturn ( uint32_t result,
const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
result error code
  • an EmberStatus value if using Silicon Labs TLS
  • an mbed TLS error code if using mbed TLS library (see mbedtls:include/mbedtls/ssl.h)
remoteAddress IPv6 address of the server
localPort local port
remotePort remote port
void emberSetDtlsDeviceCertificate ( const CertificateAuthority ** certAuthority,
const DeviceCertificate * deviceCert
)
Parameters
certAuthority the certificate authority
deviceCert the certificate
void emberSetDtlsDeviceCertificateReturn ( uint32_t result )
Parameters
result
  • ::0 The certificate was set successfully.
  • ::result error code
    • an EmberStatus value if using Silicon Labs TLS
    • an mbed TLS error code if using mbed TLS library (see mbedtls:include/mbedtls/ssl.h)
void emberSetDtlsPresharedKey ( const uint8_t * key,
uint8_t keyLength,
const EmberIpv6Address * remoteAddress
)

Note: Up to 32 pre-shared keys can be stored.

If this succeeds, emberSetDtlsPresharedKeyReturn will return EMBER_SUCCESS. Otherwise, a failure status is indicated.

Parameters
key the pre-shared key
keyLength length
remoteAddress IPv6 address of peer
void emberSetDtlsPresharedKeyReturn ( EmberStatus status )
Parameters
result
  • ::status An EmberStatus value