srtp.h

Go to the documentation of this file.

/*
 * srtp.h
 *
 * interface to libsrtp
 *
 * David A. McGrew
 * Cisco Systems, Inc.
 */
/*
 *  
 * Copyright (c) 2001-2006, Cisco Systems, Inc.
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 *   Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * 
 *   Redistributions in binary form must reproduce the above
 *   copyright notice, this list of conditions and the following
 *   disclaimer in the documentation and/or other materials provided
 *   with the distribution.
 * 
 *   Neither the name of the Cisco Systems, Inc. nor the names of its
 *   contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */


#ifndef SRTP_H
#define SRTP_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP
 */

#define SRTP_MASTER_KEY_LEN 30

/*
 * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP
 */
#define SRTP_MAX_KEY_LEN      64

/*
 * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP
 */

#define SRTP_MAX_TAG_LEN 16 

#define SRTP_MAX_TRAILER_LEN SRTP_MAX_TAG_LEN 

/*
 * SRTP_AEAD_SALT_LEN is the length of the SALT values used with 
 * GCM mode.  GCM mode requires an IV.  The SALT value is used
 * as part of the IV formation logic applied to each RTP packet.
 */
#define SRTP_AEAD_SALT_LEN  12
#define SRTP_AES_128_GCM_KEYSIZE_WSALT   SRTP_AEAD_SALT_LEN + 16
#define SRTP_AES_192_GCM_KEYSIZE_WSALT   SRTP_AEAD_SALT_LEN + 24
#define SRTP_AES_256_GCM_KEYSIZE_WSALT   SRTP_AEAD_SALT_LEN + 32

/*
 * an srtp_hdr_t represents the srtp header
 *
 * in this implementation, an srtp_hdr_t is assumed to be 32-bit aligned
 * 
 * (note that this definition follows that of RFC 1889 Appendix A, but
 * is not identical)
 */
 
#ifndef WORDS_BIGENDIAN

/*
 * srtp_hdr_t represents an RTP or SRTP header.  The bit-fields in
 * this structure should be declared "unsigned int" instead of 
 * "unsigned char", but doing so causes the MS compiler to not
 * fully pack the bit fields.
 */

typedef struct {
  unsigned char cc:4;   /* CSRC count             */
  unsigned char x:1;    /* header extension flag  */
  unsigned char p:1;    /* padding flag           */
  unsigned char version:2; /* protocol version    */
  unsigned char pt:7;   /* payload type           */
  unsigned char m:1;    /* marker bit             */
  uint16_t seq;     /* sequence number        */
  uint32_t ts;      /* timestamp              */
  uint32_t ssrc;    /* synchronization source */
} srtp_hdr_t;

#else /*  BIG_ENDIAN */

typedef struct {
  unsigned char version:2; /* protocol version    */
  unsigned char p:1;    /* padding flag           */
  unsigned char x:1;    /* header extension flag  */
  unsigned char cc:4;   /* CSRC count             */
  unsigned char m:1;    /* marker bit             */
  unsigned char pt:7;   /* payload type           */
  uint16_t seq;     /* sequence number        */
  uint32_t ts;      /* timestamp              */
  uint32_t ssrc;    /* synchronization source */
} srtp_hdr_t;

#endif

typedef struct {
  uint16_t profile_specific;    /* profile-specific info               */
  uint16_t length;              /* number of 32-bit words in extension */
} srtp_hdr_xtnd_t;


/*
 * srtcp_hdr_t represents a secure rtcp header 
 *
 * in this implementation, an srtcp header is assumed to be 32-bit
 * alinged
 */

#ifndef WORDS_BIGENDIAN

typedef struct {
  unsigned char rc:5;       /* reception report count */
  unsigned char p:1;        /* padding flag           */
  unsigned char version:2;  /* protocol version       */
  unsigned char pt:8;       /* payload type           */
  uint16_t len;         /* length                 */
  uint32_t ssrc;            /* synchronization source */
} srtcp_hdr_t;

typedef struct {
  unsigned int index:31;    /* srtcp packet index in network order! */
  unsigned int e:1;         /* encrypted? 1=yes */
  /* optional mikey/etc go here */
  /* and then the variable-length auth tag */
} srtcp_trailer_t;


#else /*  BIG_ENDIAN */

typedef struct {
  unsigned char version:2;  /* protocol version       */
  unsigned char p:1;        /* padding flag           */
  unsigned char rc:5;       /* reception report count */
  unsigned char pt:8;       /* payload type           */
  uint16_t len;         /* length                 */
  uint32_t ssrc;            /* synchronization source */
} srtcp_hdr_t;

typedef struct {
  unsigned int version:2;  /* protocol version                     */
  unsigned int p:1;        /* padding flag                         */
  unsigned int count:5;    /* varies by packet type                */
  unsigned int pt:8;       /* payload type                         */
  uint16_t length;         /* len of uint32s of packet less header */
} rtcp_common_t;

typedef struct {
  unsigned int e:1;         /* encrypted? 1=yes */
  unsigned int index:31;    /* srtcp packet index */
  /* optional mikey/etc go here */
  /* and then the variable-length auth tag */
} srtcp_trailer_t;

#endif



typedef uint32_t srtp_cipher_type_id_t; 

typedef uint32_t srtp_auth_type_id_t;

/*
 * @brief srtp_err_status_t defines error codes.
 *
 * The enumeration srtp_err_status_t defines error codes.  Note that the
 * value of srtp_err_status_ok is equal to zero, which can simplify error
 * checking somewhat.
 *
 */
typedef enum {
  srtp_err_status_ok           = 0,  
  srtp_err_status_fail         = 1,  
  srtp_err_status_bad_param    = 2,  
  srtp_err_status_alloc_fail   = 3,  
  srtp_err_status_dealloc_fail = 4,  
  srtp_err_status_init_fail    = 5,  
  srtp_err_status_terminus     = 6,  
  srtp_err_status_auth_fail    = 7,  
  srtp_err_status_cipher_fail  = 8,  
  srtp_err_status_replay_fail  = 9,  
  srtp_err_status_replay_old   = 10, 
  srtp_err_status_algo_fail    = 11, 
  srtp_err_status_no_such_op   = 12, 
  srtp_err_status_no_ctx       = 13, 
  srtp_err_status_cant_check   = 14, 
  srtp_err_status_key_expired  = 15, 
  srtp_err_status_socket_err   = 16, 
  srtp_err_status_signal_err   = 17, 
  srtp_err_status_nonce_bad    = 18, 
  srtp_err_status_read_fail    = 19, 
  srtp_err_status_write_fail   = 20, 
  srtp_err_status_parse_err    = 21, 
  srtp_err_status_encode_err   = 22, 
  srtp_err_status_semaphore_err = 23,
  srtp_err_status_pfkey_err    = 24  
} srtp_err_status_t;

typedef struct srtp_stream_ctx_t_ srtp_stream_ctx_t;
typedef struct srtp_ctx_t_ srtp_ctx_t;

/* 
 * nota bene: since libSRTP doesn't support the use of the MKI, the
 * SRTP_MAX_TRAILER_LEN value is just the maximum tag length
 */

typedef enum {
  sec_serv_none          = 0, 
  sec_serv_conf          = 1, 
  sec_serv_auth          = 2, 
  sec_serv_conf_and_auth = 3  
} srtp_sec_serv_t;

typedef struct srtp_crypto_policy_t {
  srtp_cipher_type_id_t cipher_type;    
  int              cipher_key_len; 
  srtp_auth_type_id_t   auth_type;      
  int              auth_key_len;   
  int              auth_tag_len;   
  srtp_sec_serv_t  sec_serv;       
} srtp_crypto_policy_t;


typedef enum { 
  ssrc_undefined    = 0,  
  ssrc_specific     = 1,  
  ssrc_any_inbound  = 2, 
  ssrc_any_outbound = 3  
} srtp_ssrc_type_t;

typedef struct { 
  srtp_ssrc_type_t type;  
  unsigned int     value; 
} srtp_ssrc_t;


typedef struct srtp_ekt_policy_ctx_t *srtp_ekt_policy_t;


typedef struct srtp_ekt_stream_ctx_t *srtp_ekt_stream_t;


typedef struct srtp_policy_t {
  srtp_ssrc_t   ssrc;        
  srtp_crypto_policy_t rtp;    
  srtp_crypto_policy_t rtcp;   
  unsigned char *key;          
  srtp_ekt_policy_t ekt;       
  unsigned long window_size;   
  int        allow_repeat_tx;  
  int *enc_xtn_hdr;            
  int enc_xtn_hdr_count;       
  struct srtp_policy_t *next;  
} srtp_policy_t;




typedef srtp_ctx_t *srtp_t;


typedef srtp_stream_ctx_t *srtp_stream_t;



srtp_err_status_t srtp_init(void);

srtp_err_status_t srtp_shutdown(void);

srtp_err_status_t srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr);
         
srtp_err_status_t srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr);


srtp_err_status_t srtp_create(srtp_t *session, const srtp_policy_t *policy);


srtp_err_status_t srtp_add_stream(srtp_t session, const srtp_policy_t *policy);


srtp_err_status_t srtp_remove_stream(srtp_t session, unsigned int ssrc);

srtp_err_status_t srtp_update(srtp_t session, const srtp_policy_t *policy);

srtp_err_status_t srtp_update_stream(srtp_t session, const srtp_policy_t *policy);

void srtp_crypto_policy_set_rtp_default(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_rtcp_default(srtp_crypto_policy_t *p);

#define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80(p) srtp_crypto_policy_set_rtp_default(p)


void srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(srtp_crypto_policy_t *p);



void srtp_crypto_policy_set_aes_cm_128_null_auth(srtp_crypto_policy_t *p);


void srtp_crypto_policy_set_null_cipher_hmac_sha1_80(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_null_cipher_hmac_null(srtp_crypto_policy_t *p);


void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(srtp_crypto_policy_t *p);


void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_cm_256_null_auth(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_gcm_128_8_auth(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_gcm_256_8_auth(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_gcm_128_8_only_auth(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_gcm_256_8_only_auth(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_gcm_128_16_auth(srtp_crypto_policy_t *p);

void srtp_crypto_policy_set_aes_gcm_256_16_auth(srtp_crypto_policy_t *p);


srtp_err_status_t srtp_dealloc(srtp_t s);


/*
 * @brief identifies a particular SRTP profile 
 *
 * An srtp_profile_t enumeration is used to identify a particular SRTP
 * profile (that is, a set of algorithms and parameters).  These
 * profiles are defined in the DTLS-SRTP draft.
 */

typedef enum {
  srtp_profile_reserved           = 0,
  srtp_profile_aes128_cm_sha1_80  = 1,
  srtp_profile_aes128_cm_sha1_32  = 2,
  srtp_profile_aes256_cm_sha1_80  = 3,
  srtp_profile_aes256_cm_sha1_32  = 4,
  srtp_profile_null_sha1_80       = 5,
  srtp_profile_null_sha1_32       = 6,
} srtp_profile_t;


srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtp(srtp_crypto_policy_t *policy, srtp_profile_t profile);




srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtcp(srtp_crypto_policy_t *policy, srtp_profile_t profile);

unsigned int
srtp_profile_get_master_key_length(srtp_profile_t profile);


unsigned int
srtp_profile_get_master_salt_length(srtp_profile_t profile);

void
srtp_append_salt_to_key(unsigned char *key, unsigned int bytes_in_key,
                unsigned char *salt, unsigned int bytes_in_salt);



srtp_err_status_t srtp_protect_rtcp(srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len);

srtp_err_status_t srtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len);

void
srtp_set_user_data(srtp_t ctx, void *data);

void*
srtp_get_user_data(srtp_t ctx);

typedef enum { 
  event_ssrc_collision,    
  event_key_soft_limit,    
  event_key_hard_limit,    
  event_packet_index_limit 
} srtp_event_t;

typedef struct srtp_event_data_t {
  srtp_t        session;  
  srtp_stream_t stream;   
  srtp_event_t  event;    
} srtp_event_data_t;

typedef void (srtp_event_handler_func_t)(srtp_event_data_t *data);

srtp_err_status_t srtp_install_event_handler(srtp_event_handler_func_t func);

const char *srtp_get_version_string(void);

unsigned int srtp_get_version(void);

srtp_err_status_t srtp_set_debug_module(char *mod_name, int v);

srtp_err_status_t srtp_list_debug_modules(void);


/* in host order, so outside the #if */
#define SRTCP_E_BIT      0x80000000
/* for byte-access */
#define SRTCP_E_BYTE_BIT 0x80
#define SRTCP_INDEX_MASK 0x7fffffff

#ifdef __cplusplus
}
#endif

#endif /* SRTP_H */