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 uint8_t *identity, uint8_t identityLength, 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.
uint8_t emberGetSecureDtlsSessionId (const EmberIpv6Address *remoteAddress, uint16_t localPort, uint16_t remotePort)
Request the session ID given connection parameters.
uint8_t emberGetDtlsConnectionNextSessionId (uint8_t sessionId)
Request the next session ID following the given one. If EMBER_NULL_SESSION_ID is passed, then the first session ID is returned.
EmberStatus emberGetDtlsConnectionPeerAddressBySessionId (const uint8_t sessionId, EmberIpv6Address *remoteAddress)
Request the address associated with a particular session.
EmberStatus emberGetDtlsConnectionPeerPortBySessionId (const uint8_t sessionId, uint16_t *remotePort)
Request the port associated with a particular session.
EmberStatus emberGetDtlsConnectionPeerPublicKeyBySessionId (const uint8_t sessionId, uint8_t *publicKey, const uint16_t publicKeyMaxSize, uint16_t *publicKeySize)
Request the public key associated with a particular session.
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)
uint8_t emberGetDtlsConnectionNextSessionId ( uint8_t sessionId )
Parameters
sessionId session ID to be followed
EmberStatus emberGetDtlsConnectionPeerAddressBySessionId ( const uint8_t sessionId,
EmberIpv6Address * remoteAddress
)
Parameters
sessionId session ID of interest
remoteAddress remote address used in session
EmberStatus emberGetDtlsConnectionPeerPortBySessionId ( const uint8_t sessionId,
uint16_t * remotePort
)
Parameters
sessionId session ID of interest
remotePort remote port used in session
EmberStatus emberGetDtlsConnectionPeerPublicKeyBySessionId ( const uint8_t sessionId,
uint8_t * publicKey,
const uint16_t publicKeyMaxSize,
uint16_t * publicKeySize
)
Parameters
sessionId session ID of interest
publicKey Array that will store the public key
publicKeyMaxSize Maximum size of the array
publickeySize Size of the array in use
uint8_t emberGetSecureDtlsSessionId ( const EmberIpv6Address * remoteAddress,
uint16_t localPort,
uint16_t remotePort
)
Parameters
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 uint8_t * identity,
uint8_t identityLength,
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 key length
key the pre-shared identity
keyLength identity length
remoteAddress IPv6 address of peer
void emberSetDtlsPresharedKeyReturn ( EmberStatus status )
Parameters
result
  • ::status An EmberStatus value