dtls.h File Reference

DTLS/SRTP processing (headers) More...

#include <inttypes.h>
#include <glib.h>
#include "rtp.h"
#include "rtpsrtp.h"
#include "sctp.h"
#include "refcount.h"
#include "dtls-bio.h"

Include dependency graph for dtls.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	janus_dtls_srtp
	Janus DTLS-SRTP handle. More...

Typedefs
typedef enum janus_dtls_role	janus_dtls_role
	DTLS roles.
typedef enum janus_dtls_state	janus_dtls_state
	DTLS state.
typedef struct janus_dtls_srtp	janus_dtls_srtp
	Janus DTLS-SRTP handle.

Enumerations
enum	janus_dtls_role { JANUS_DTLS_ROLE_ACTPASS = -1 , JANUS_DTLS_ROLE_SERVER , JANUS_DTLS_ROLE_CLIENT }
	DTLS roles. More...
enum	janus_dtls_state { JANUS_DTLS_STATE_FAILED = -1 , JANUS_DTLS_STATE_CREATED , JANUS_DTLS_STATE_TRYING , JANUS_DTLS_STATE_CONNECTED }
	DTLS state. More...

Functions
const char *	janus_get_ssl_version (void)
	Helper method to return info on the crypto library and its version.
gint	janus_dtls_srtp_init (const char *server_pem, const char *server_key, const char *password, const char *ciphers, guint16 timeout, gboolean rsa_private_key, gboolean accept_selfsigned)
	DTLS stuff initialization.
void	janus_dtls_srtp_cleanup (void)
	Method to cleanup DTLS stuff before exiting.
gchar *	janus_dtls_get_local_fingerprint (void)
	Method to return a string representation (SHA-256) of the certificate fingerprint.
gboolean	janus_dtls_are_selfsigned_certs_ok (void)
	Method to check whether DTLS self-signed certificates are ok (default) or not.
janus_dtls_srtp *	janus_dtls_srtp_create (void *component, janus_dtls_role role)
	Create a janus_dtls_srtp instance.
void	janus_dtls_srtp_handshake (janus_dtls_srtp *dtls)
	Start a DTLS handshake.
int	janus_dtls_srtp_create_sctp (janus_dtls_srtp *dtls)
	Create an SCTP association, for data channels.
void	janus_dtls_srtp_incoming_msg (janus_dtls_srtp *dtls, char *buf, uint16_t len)
	Handle an incoming DTLS message.
void	janus_dtls_srtp_send_alert (janus_dtls_srtp *dtls)
	Send an alert on a janus_dtls_srtp instance.
void	janus_dtls_srtp_destroy (janus_dtls_srtp *dtls)
	Destroy a janus_dtls_srtp instance.
void	janus_dtls_callback (const SSL *ssl, int where, int ret)
	DTLS alert callback (http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html)
int	janus_dtls_verify_callback (int preverify_ok, X509_STORE_CTX *ctx)
	DTLS certificate verification callback (http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html)
gboolean	janus_dtls_retry (gpointer stack)
	DTLS retransmission timer.
const gchar *	janus_get_dtls_srtp_state (janus_dtls_state state)
	Helper method to get a string representation of a Janus DTLS state.
const gchar *	janus_get_dtls_srtp_role (janus_dtls_role role)
	Helper method to get a string representation of a DTLS role.
const gchar *	janus_get_dtls_srtp_profile (int profile)
	Helper method to get a string representation of an SRTP profile.
gboolean	janus_is_dtls (char *buf)
	Helper method to demultiplex DTLS from other protocols.

Detailed Description

DTLS/SRTP processing (headers)

Author

Lorenzo Miniero loren.nosp@m.zo@m.nosp@m.eetec.nosp@m.ho.c.nosp@m.om

Copyright

GNU General Public License v3

Implementation (based on OpenSSL and libsrtp) of the DTLS/SRTP transport. The code takes care of the DTLS handshake between peers and the server, and sets the proper SRTP and SRTCP context up accordingly. A DTLS alert from a peer is notified to the plugin handling him/her by means of the hangup_media callback.

Protocols

Typedef Documentation

janus_dtls_role

typedef enum janus_dtls_role janus_dtls_role

DTLS roles.

janus_dtls_srtp

typedef struct janus_dtls_srtp janus_dtls_srtp

Janus DTLS-SRTP handle.

janus_dtls_state

typedef enum janus_dtls_state janus_dtls_state

DTLS state.

Enumeration Type Documentation

janus_dtls_role

enum janus_dtls_role

DTLS roles.

Enumerator
JANUS_DTLS_ROLE_ACTPASS
JANUS_DTLS_ROLE_SERVER
JANUS_DTLS_ROLE_CLIENT

janus_dtls_state

enum janus_dtls_state

DTLS state.

Enumerator
JANUS_DTLS_STATE_FAILED
JANUS_DTLS_STATE_CREATED
JANUS_DTLS_STATE_TRYING
JANUS_DTLS_STATE_CONNECTED

Function Documentation

janus_dtls_are_selfsigned_certs_ok()

gboolean janus_dtls_are_selfsigned_certs_ok

(

void

)

Method to check whether DTLS self-signed certificates are ok (default) or not.

janus_dtls_callback()

void janus_dtls_callback	(	const SSL *	ssl,
		int	where,
		int	ret )

DTLS alert callback (http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html)

Parameters

[in]	ssl	SSL instance where the alert occurred
[in]	where	The context where the event occurred
[in]	ret	The error code

janus_dtls_get_local_fingerprint()

gchar * janus_dtls_get_local_fingerprint

(

void

)

Method to return a string representation (SHA-256) of the certificate fingerprint.

janus_dtls_retry()

gboolean janus_dtls_retry

(

gpointer

stack

)

DTLS retransmission timer.

As libnice is going to actually send and receive data, OpenSSL cannot handle retransmissions by itself: this timed callback (g_source_set_callback) deals with this.

Parameters

[in]

stack

Opaque pointer to the janus_dtls_srtp instance to use

Returns

true if a retransmission is still needed, false otherwise

janus_dtls_srtp_cleanup()

void janus_dtls_srtp_cleanup

(

void

)

Method to cleanup DTLS stuff before exiting.

janus_dtls_srtp_create()

janus_dtls_srtp * janus_dtls_srtp_create	(	void *	component,
		janus_dtls_role	role )

Create a janus_dtls_srtp instance.

Parameters

[in]	component	Opaque pointer to the component owning that will use the stack
[in]	role	The role of the DTLS stack (client/server)

Returns

A new janus_dtls_srtp instance if successful, NULL otherwise

janus_dtls_srtp_create_sctp()

int janus_dtls_srtp_create_sctp

(

janus_dtls_srtp *

dtls

)

Create an SCTP association, for data channels.

Note

This is a separate method as, with renegotiations, it might happen that data channels are not created right away, right after the DTLS handshake has been completed, but only later, when DTLS is already up

Parameters

[in]

dtls

The janus_dtls_srtp instance to setup SCTP on

Returns

0 in case of success, a negative integer otherwise

janus_dtls_srtp_destroy()

void janus_dtls_srtp_destroy

(

janus_dtls_srtp *

dtls

)

Destroy a janus_dtls_srtp instance.

Parameters

[in]

dtls

The janus_dtls_srtp instance to destroy

janus_dtls_srtp_handshake()

void janus_dtls_srtp_handshake

(

janus_dtls_srtp *

dtls

)

Start a DTLS handshake.

Parameters

[in]

dtls

The janus_dtls_srtp instance to start the handshake on

janus_dtls_srtp_incoming_msg()

void janus_dtls_srtp_incoming_msg	(	janus_dtls_srtp *	dtls,
		char *	buf,
		uint16_t	len )

Handle an incoming DTLS message.

Parameters

[in]	dtls	The janus_dtls_srtp instance to start the handshake on
[in]	buf	The DTLS message data
[in]	len	The DTLS message data length

janus_dtls_srtp_init()

gint janus_dtls_srtp_init	(	const char *	server_pem,
		const char *	server_key,
		const char *	password,
		const char *	ciphers,
		guint16	timeout,
		gboolean	rsa_private_key,
		gboolean	accept_selfsigned )

DTLS stuff initialization.

Parameters

[in]	server_pem	Path to the certificate to use
[in]	server_key	Path to the key to use
[in]	password	Password needed to use the key, if any
[in]	ciphers	DTLS ciphers to use (will use hardcoded defaults, if NULL)
[in]	timeout	DTLS timeout base, in ms, to use for retransmissions (ignored if not using BoringSSL)
[in]	rsa_private_key	Whether RSA certificates should be generated, instead of NIST P-256
[in]	accept_selfsigned	Whether to accept self-signed certificates (default) or enforce validation

Returns

0 in case of success, a negative integer on errors

janus_dtls_srtp_send_alert()

void janus_dtls_srtp_send_alert

(

janus_dtls_srtp *

dtls

)

Send an alert on a janus_dtls_srtp instance.

Parameters

[in]

dtls

The janus_dtls_srtp instance to send the alert on

janus_dtls_verify_callback()

int janus_dtls_verify_callback	(	int	preverify_ok,
		X509_STORE_CTX *	ctx )

DTLS certificate verification callback (http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html)

This method always returns 1 (true), in order not to fail when a certificate verification is requested. This is especially needed because all certificates used for DTLS in WebRTC are self signed, and as such a formal verification would fail.

Parameters

[in]	preverify_ok	Whether the verification of the certificate was passed
[in]	ctx	context used for the certificate verification

janus_get_dtls_srtp_profile()

const gchar * janus_get_dtls_srtp_profile

(

int

profile

)

Helper method to get a string representation of an SRTP profile.

Parameters

[in]

profile

The SRTP profile as exported by a DTLS-SRTP handshake

Returns

A string representation of the profile

janus_get_dtls_srtp_role()

const gchar * janus_get_dtls_srtp_role

(

janus_dtls_role

role

)

Helper method to get a string representation of a DTLS role.

Parameters

[in]

role

The DTLS role

Returns

A string representation of the role

janus_get_dtls_srtp_state()

const gchar * janus_get_dtls_srtp_state

(

janus_dtls_state

state

)

Helper method to get a string representation of a Janus DTLS state.

Parameters

[in]

state

The Janus DTLS state

Returns

A string representation of the state

janus_get_ssl_version()

const char * janus_get_ssl_version

(

void

)

Helper method to return info on the crypto library and its version.

Returns

A pointer to a static string with the version

janus_is_dtls()

gboolean janus_is_dtls

(

char *

buf

)

Helper method to demultiplex DTLS from other protocols.

Parameters

[in]

buf

Buffer to inspect