tinydtls  0.8.6
Data Fields
dtls_handler_t Struct Reference

#include <dtls.h>

Data Fields

int(* write )(struct dtls_context_t *ctx, session_t *session, uint8 *buf, size_t len)
 
int(* read )(struct dtls_context_t *ctx, session_t *session, uint8 *buf, size_t len)
 
int(* event )(struct dtls_context_t *ctx, session_t *session, dtls_alert_level_t level, unsigned short code)
 
int(* get_psk_info )(struct dtls_context_t *ctx, const session_t *session, dtls_credentials_type_t type, const unsigned char *desc, size_t desc_len, unsigned char *result, size_t result_length)
 
int(* get_ecdsa_key )(struct dtls_context_t *ctx, const session_t *session, const dtls_ecdsa_key_t **result)
 
int(* verify_ecdsa_key )(struct dtls_context_t *ctx, const session_t *session, const unsigned char *other_pub_x, const unsigned char *other_pub_y, size_t key_size)
 

Detailed Description

This structure contains callback functions used by tinydtls to communicate with the application. At least the write function must be provided. It is called by the DTLS state machine to send packets over the network. The read function is invoked to deliver decrypted and verfified application data. The third callback is an event handler function that is called when alert messages are encountered or events generated by the library have occured.

Definition at line 74 of file dtls.h.

Field Documentation

int(* dtls_handler_t::event) (struct dtls_context_t *ctx, session_t *session, dtls_alert_level_t level, unsigned short code)

The event handler is called when a message from the alert protocol is received or the state of the DTLS session changes.

Parameters
ctxThe current dtls context.
sessionThe session object that was affected.
levelThe alert level or 0 when an event ocurred that is not an alert.
codeValues less than 256 indicate alerts, while 256 or greater indicate internal DTLS session changes.
Returns
ignored

Definition at line 119 of file dtls.h.

int(* dtls_handler_t::get_ecdsa_key) (struct dtls_context_t *ctx, const session_t *session, const dtls_ecdsa_key_t **result)

Called during handshake to get the server's or client's ecdsa key used to authenticate this server or client in this session. If found, the key must be stored in result and the return value must be 0. If not found, result is undefined and the return value must be less than zero.

If ECDSA should not be supported, set this pointer to NULL.

Implement this if you want to provide your own certificate to the other peer. This is mandatory for a server providing ECDSA support and optional for a client. A client doing DTLS client authentication has to implementing this callback.

Parameters
ctxThe current dtls context.
sessionThe session where the key will be used.
resultMust be set to the key object to used for the given session.
Returns
0 if result is set, or less than zero on error.

Definition at line 174 of file dtls.h.

int(* dtls_handler_t::get_psk_info) (struct dtls_context_t *ctx, const session_t *session, dtls_credentials_type_t type, const unsigned char *desc, size_t desc_len, unsigned char *result, size_t result_length)

Called during handshake to get information related to the psk key exchange. The type of information requested is indicated by type which will be one of DTLS_PSK_HINT, DTLS_PSK_IDENTITY, or DTLS_PSK_KEY. The called function must store the requested item in the buffer result of size result_length. On success, the function must return the actual number of bytes written to result, of a value less than zero on error. The parameter desc may contain additional request information (e.g. the psk_identity for which a key is requested when type == DTLS_PSK_KEY.

Parameters
ctxThe current dtls context.
sessionThe session where the key will be used.
typeThe type of the requested information.
descAdditional request information
desc_lenThe actual length of desc.
resultMust be filled with the requested information.
result_lengthMaximum size of result.
Returns
The number of bytes written to result or a value less than zero on error.

Definition at line 145 of file dtls.h.

int(* dtls_handler_t::read) (struct dtls_context_t *ctx, session_t *session, uint8 *buf, size_t len)

Called from dtls_handle_message() deliver application data that was received on the given session. The data is delivered only after decryption and verification have succeeded.

Parameters
ctxThe current DTLS context.
sessionThe session object, including the address of the data's origin.
bufThe received data packet.
lenThe actual length of buf.
Returns
ignored

Definition at line 104 of file dtls.h.

int(* dtls_handler_t::verify_ecdsa_key) (struct dtls_context_t *ctx, const session_t *session, const unsigned char *other_pub_x, const unsigned char *other_pub_y, size_t key_size)

Called during handshake to check the peer's pubic key in this session. If the public key matches the session and should be considerated valid the return value must be 0. If not valid, the return value must be less than zero.

If ECDSA should not be supported, set this pointer to NULL.

Implement this if you want to verify the other peers public key. This is mandatory for a DTLS client doing based ECDSA authentication. A server implementing this will request the client to do DTLS client authentication.

Parameters
ctxThe current dtls context.
sessionThe session where the key will be used.
other_pub_xx component of the public key.
other_pub_yy component of the public key.
Returns
0 if public key matches, or less than zero on error. error codes: return dtls_alert_fatal_create(DTLS_ALERT_BAD_CERTIFICATE); return dtls_alert_fatal_create(DTLS_ALERT_UNSUPPORTED_CERTIFICATE); return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_REVOKED); return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_EXPIRED); return dtls_alert_fatal_create(DTLS_ALERT_CERTIFICATE_UNKNOWN); return dtls_alert_fatal_create(DTLS_ALERT_UNKNOWN_CA);

Definition at line 204 of file dtls.h.

int(* dtls_handler_t::write) (struct dtls_context_t *ctx, session_t *session, uint8 *buf, size_t len)

Called from dtls_handle_message() to send DTLS packets over the network. The callback function must use the network interface denoted by session->ifindex to send the data.

Parameters
ctxThe current DTLS context.
sessionThe session object, including the address of the remote peer where the data shall be sent.
bufThe data to send.
lenThe actual length of buf.
Returns
The callback function must return the number of bytes that were sent, or a value less than zero to indicate an error.

Definition at line 89 of file dtls.h.


The documentation for this struct was generated from the following file: