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 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
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)
uint8_t emberGetDtlsConnectionNextSessionId ( uint8_t  sessionId)
Parameters
sessionIdsession ID to be followed
EmberStatus emberGetDtlsConnectionPeerPublicKeyBySessionId ( const uint8_t  sessionId,
uint8_t *  publicKey,
const uint16_t  publicKeyMaxSize,
uint16_t *  publicKeySize 
)
Parameters
sessionIdsession ID of interest
publicKeyArray that will store the public key
publicKeyMaxSizeMaximum size of the array
publickeySizeSize of the array in use
uint8_t emberGetSecureDtlsSessionId ( const EmberIpv6Address remoteAddress,
uint16_t  localPort,
uint16_t  remotePort 
)
Parameters
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 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
keythe pre-shared key
keyLengthkey length
keythe pre-shared identity
keyLengthidentity length
remoteAddressIPv6 address of peer
void emberSetDtlsPresharedKeyReturn ( EmberStatus  status)
Parameters
result
  • ::status An EmberStatus value