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
sessionIdsessionId used for secure CoAP transport.
void emberCloseDtlsConnectionReturn ( uint8_t  sessionId,
EmberStatus  status 
)
Parameters
sessionIdsessionId 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
flags1 = server, 0 = client (possibly other info later)
sessionIdsessionId used for secure CoAP transport
localAddresslocal IPv6 address
remoteAddressremote IPv6 address
localPortlocal port
remotePortremote 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
payloadCoAP payload to be sent securely
payloadLengthpayload length
localAddresslocal IPv6 address
localPortlocal port
remoteAddressremote IPv6 address
remotePortremote port
transmitHandlerDatasession ID of the secure connection (see emberDtlsSecureSessionEstablished or emberGetSecureDtlsSessionId above)
void emberGetSecureDtlsSessionId ( const EmberIpv6Address remoteAddress,
uint16_t  localPort,
uint16_t  remotePort 
)
Parameters
remoteAddressremote IPv6 address
localPortlocal port
remotePortremote port
void emberGetSecureDtlsSessionIdReturn ( uint8_t  sessionId,
const EmberIpv6Address remoteAddress,
uint16_t  localPort,
uint16_t  remotePort 
)
Parameters
sessionIdsessionId used for secure CoAP transport
remoteAddressremote IPv6 address
localPortlocal port
remotePortremote 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
dtlsModeDTLS connection mode (see EMBER_DTLS_MODE_* above)
remoteAddressIPv6 address of the server
localPortlocal port
remotePortremote port
void emberOpenDtlsConnectionReturn ( uint32_t  result,
const EmberIpv6Address remoteAddress,
uint16_t  localPort,
uint16_t  remotePort 
)
Parameters
resulterror 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)
remoteAddressIPv6 address of the server
localPortlocal port
remotePortremote port
void emberSetDtlsDeviceCertificate ( const CertificateAuthority **  certAuthority,
const DeviceCertificate deviceCert 
)
Parameters
certAuthoritythe certificate authority
deviceCertthe 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
keythe pre-shared key
keyLengthlength
remoteAddressIPv6 address of peer
void emberSetDtlsPresharedKeyReturn ( EmberStatus  status)
Parameters
result
  • ::status An EmberStatus value