netwerk/srtp/src/include/ekt.h

   1 /*
   2  * ekt.h
   3  *
   4  * interface to Encrypted Key Transport for SRTP
   5  *
   6  * David McGrew
   7  * Cisco Systems, Inc.
   8  */
   9 /*
  10  *
  11  * Copyright (c) 2001-2005 Cisco Systems, Inc.
  12  * All rights reserved.
  13  *
  14  * Redistribution and use in source and binary forms, with or without
  15  * modification, are permitted provided that the following conditions
  16  * are met:
  17  *
  18  *   Redistributions of source code must retain the above copyright
  19  *   notice, this list of conditions and the following disclaimer.
  20  *
  21  *   Redistributions in binary form must reproduce the above
  22  *   copyright notice, this list of conditions and the following
  23  *   disclaimer in the documentation and/or other materials provided
  24  *   with the distribution.
  25  *
  26  *   Neither the name of the Cisco Systems, Inc. nor the names of its
  27  *   contributors may be used to endorse or promote products derived
  28  *   from this software without specific prior written permission.
  29  *
  30  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  31  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  32  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  33  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  34  * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  35  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  36  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  37  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  38  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  39  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  40  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  41  * OF THE POSSIBILITY OF SUCH DAMAGE.
  42  *
  43  */
  44
  45
  46
  47 /*
  48  * EKT implementation strategy
  49  *
  50  * use stream_template approach
  51  *
  52  * in srtp_unprotect, when a new stream appears, check if template has
  53  * EKT defined, and if it does, then apply EKT processing
  54  *
  55  * question: will we want to allow key-sharing templates in addition
  56  * to EKT templates?  could define a new ssrc_type_t that's associated
  57  * with an EKT, e.g.  ssrc_any_ekt.
  58  *
  59  *
  60  */
  61
  62 #ifndef EKT_H
  63 #define EKT_H
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 #include "srtp_priv.h"
  70
  71 #define EKT_CIPHER_DEFAULT           1
  72 #define EKT_CIPHER_AES_128_ECB       1
  73 #define EKT_CIPHER_AES_192_KEY_WRAP  2
  74 #define EKT_CIPHER_AES_256_KEY_WRAP  3
  75
  76 typedef uint16_t ekt_spi_t;
  77
  78
  79 unsigned
  80 ekt_octets_after_base_tag(ekt_stream_t ekt);
  81
  82 /*
  83  * an srtp_policy_t structure can contain a pointer to an
  84  * ekt_policy_t structure
  85  *
  86  * this structure holds all of the high level EKT information, and it
  87  * is passed into libsrtp to indicate what policy should be in effect
  88  */
  89
  90 typedef struct ekt_policy_ctx_t {
  91   ekt_spi_t  spi;     /* security parameter index */
  92   uint8_t    ekt_cipher_type;
  93   uint8_t   *ekt_key;
  94   struct ekt_policy_ctx_t *next_ekt_policy;
  95 } ekt_policy_ctx_t;
  96
  97
  98 /*
  99  * an ekt_data_t structure holds the data corresponding to an ekt key,
 100  * spi, and so on
 101  */
 102
 103 typedef struct ekt_data_t {
 104   ekt_spi_t spi;
 105   uint8_t ekt_cipher_type;
 106   aes_expanded_key_t ekt_enc_key;
 107   aes_expanded_key_t ekt_dec_key;
 108   struct ekt_data_t *next_ekt_data;
 109 } ekt_data_t;
 110
 111 /*
 112  * an srtp_stream_ctx_t can contain an ekt_stream_ctx_t
 113  *
 114  * an ekt_stream_ctx_t structure holds all of the EKT information for
 115  * a specific SRTP stream
 116  */
 117
 118 typedef struct ekt_stream_ctx_t {
 119   ekt_data_t *data;
 120   uint16_t    isn;     /* initial sequence number  */
 121   uint8_t     encrypted_master_key[SRTP_MAX_KEY_LEN];
 122 } ekt_stream_ctx_t;
 123
 124
 125
 126 err_status_t
 127 ekt_alloc(ekt_stream_t *stream_data, ekt_policy_t policy);
 128
 129 err_status_t
 130 ekt_stream_init(ekt_stream_t e,
 131                 ekt_spi_t spi,
 132                 void *ekt_key,
 133                 unsigned ekt_cipher_type);
 134
 135 err_status_t
 136 ekt_stream_init_from_policy(ekt_stream_t e, ekt_policy_t p);
 137
 138
 139
 140 err_status_t
 141 srtp_stream_init_from_ekt(srtp_stream_t stream,
 142                           const void *srtcp_hdr,
 143                           unsigned pkt_octet_len);
 144
 145
 146 void
 147 ekt_write_data(ekt_stream_t ekt,
 148                uint8_t *base_tag,
 149                unsigned base_tag_len,
 150                int *packet_len,
 151                xtd_seq_num_t pkt_index);
 152
 153 /*
 154  * We handle EKT by performing some additional steps before
 155  * authentication (copying the auth tag into a temporary location,
 156  * zeroizing the "base tag" field in the packet)
 157  *
 158  * With EKT, the tag_len parameter is actually the base tag
 159  * length
 160  */
 161
 162 err_status_t
 163 ekt_tag_verification_preproces(uint8_t *pkt_tag,
 164                                uint8_t *pkt_tag_copy,
 165                                unsigned tag_len);
 166
 167 err_status_t
 168 ekt_tag_verification_postproces(uint8_t *pkt_tag,
 169                                 uint8_t *pkt_tag_copy,
 170                                 unsigned tag_len);
 171
 172
 173 /*
 174  * @brief EKT pre-processing for srtcp tag generation
 175  *
 176  * This function does the pre-processing of the SRTCP authentication
 177  * tag format.  When EKT is used, it consists of writing the Encrypted
 178  * Master Key, the SRTP ROC, the Initial Sequence Number, and SPI
 179  * fields.  The Base Authentication Tag field is set to the all-zero
 180  * value
 181  *
 182  * When EKT is not used, this function is a no-op.
 183  *
 184  */
 185
 186 err_status_t
 187 srtp_stream_srtcp_auth_tag_generation_preprocess(const srtp_stream_t *s,
 188                                                  uint8_t *pkt_tag,
 189                                                  unsigned pkt_octet_len);
 190
 191 /* it's not clear that a tag_generation_postprocess function is needed */
 192
 193 err_status_t
 194 srtcp_auth_tag_generation_postprocess(void);
 195
 196
 197 #ifdef __cplusplus
 198 }
 199 #endif
 200
 201 #endif /* EKT_H */