1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/srtp/src/include/ekt.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,201 @@
1.4 +/*
1.5 + * ekt.h
1.6 + *
1.7 + * interface to Encrypted Key Transport for SRTP
1.8 + *
1.9 + * David McGrew
1.10 + * Cisco Systems, Inc.
1.11 + */
1.12 +/*
1.13 + *
1.14 + * Copyright (c) 2001-2005 Cisco Systems, Inc.
1.15 + * All rights reserved.
1.16 + *
1.17 + * Redistribution and use in source and binary forms, with or without
1.18 + * modification, are permitted provided that the following conditions
1.19 + * are met:
1.20 + *
1.21 + * Redistributions of source code must retain the above copyright
1.22 + * notice, this list of conditions and the following disclaimer.
1.23 + *
1.24 + * Redistributions in binary form must reproduce the above
1.25 + * copyright notice, this list of conditions and the following
1.26 + * disclaimer in the documentation and/or other materials provided
1.27 + * with the distribution.
1.28 + *
1.29 + * Neither the name of the Cisco Systems, Inc. nor the names of its
1.30 + * contributors may be used to endorse or promote products derived
1.31 + * from this software without specific prior written permission.
1.32 + *
1.33 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.34 + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.35 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
1.36 + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
1.37 + * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
1.38 + * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1.39 + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1.40 + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.41 + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1.42 + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
1.43 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
1.44 + * OF THE POSSIBILITY OF SUCH DAMAGE.
1.45 + *
1.46 + */
1.47 +
1.48 +
1.49 +
1.50 +/*
1.51 + * EKT implementation strategy
1.52 + *
1.53 + * use stream_template approach
1.54 + *
1.55 + * in srtp_unprotect, when a new stream appears, check if template has
1.56 + * EKT defined, and if it does, then apply EKT processing
1.57 + *
1.58 + * question: will we want to allow key-sharing templates in addition
1.59 + * to EKT templates? could define a new ssrc_type_t that's associated
1.60 + * with an EKT, e.g. ssrc_any_ekt.
1.61 + *
1.62 + *
1.63 + */
1.64 +
1.65 +#ifndef EKT_H
1.66 +#define EKT_H
1.67 +
1.68 +#ifdef __cplusplus
1.69 +extern "C" {
1.70 +#endif
1.71 +
1.72 +#include "srtp_priv.h"
1.73 +
1.74 +#define EKT_CIPHER_DEFAULT 1
1.75 +#define EKT_CIPHER_AES_128_ECB 1
1.76 +#define EKT_CIPHER_AES_192_KEY_WRAP 2
1.77 +#define EKT_CIPHER_AES_256_KEY_WRAP 3
1.78 +
1.79 +typedef uint16_t ekt_spi_t;
1.80 +
1.81 +
1.82 +unsigned
1.83 +ekt_octets_after_base_tag(ekt_stream_t ekt);
1.84 +
1.85 +/*
1.86 + * an srtp_policy_t structure can contain a pointer to an
1.87 + * ekt_policy_t structure
1.88 + *
1.89 + * this structure holds all of the high level EKT information, and it
1.90 + * is passed into libsrtp to indicate what policy should be in effect
1.91 + */
1.92 +
1.93 +typedef struct ekt_policy_ctx_t {
1.94 + ekt_spi_t spi; /* security parameter index */
1.95 + uint8_t ekt_cipher_type;
1.96 + uint8_t *ekt_key;
1.97 + struct ekt_policy_ctx_t *next_ekt_policy;
1.98 +} ekt_policy_ctx_t;
1.99 +
1.100 +
1.101 +/*
1.102 + * an ekt_data_t structure holds the data corresponding to an ekt key,
1.103 + * spi, and so on
1.104 + */
1.105 +
1.106 +typedef struct ekt_data_t {
1.107 + ekt_spi_t spi;
1.108 + uint8_t ekt_cipher_type;
1.109 + aes_expanded_key_t ekt_enc_key;
1.110 + aes_expanded_key_t ekt_dec_key;
1.111 + struct ekt_data_t *next_ekt_data;
1.112 +} ekt_data_t;
1.113 +
1.114 +/*
1.115 + * an srtp_stream_ctx_t can contain an ekt_stream_ctx_t
1.116 + *
1.117 + * an ekt_stream_ctx_t structure holds all of the EKT information for
1.118 + * a specific SRTP stream
1.119 + */
1.120 +
1.121 +typedef struct ekt_stream_ctx_t {
1.122 + ekt_data_t *data;
1.123 + uint16_t isn; /* initial sequence number */
1.124 + uint8_t encrypted_master_key[SRTP_MAX_KEY_LEN];
1.125 +} ekt_stream_ctx_t;
1.126 +
1.127 +
1.128 +
1.129 +err_status_t
1.130 +ekt_alloc(ekt_stream_t *stream_data, ekt_policy_t policy);
1.131 +
1.132 +err_status_t
1.133 +ekt_stream_init(ekt_stream_t e,
1.134 + ekt_spi_t spi,
1.135 + void *ekt_key,
1.136 + unsigned ekt_cipher_type);
1.137 +
1.138 +err_status_t
1.139 +ekt_stream_init_from_policy(ekt_stream_t e, ekt_policy_t p);
1.140 +
1.141 +
1.142 +
1.143 +err_status_t
1.144 +srtp_stream_init_from_ekt(srtp_stream_t stream,
1.145 + const void *srtcp_hdr,
1.146 + unsigned pkt_octet_len);
1.147 +
1.148 +
1.149 +void
1.150 +ekt_write_data(ekt_stream_t ekt,
1.151 + uint8_t *base_tag,
1.152 + unsigned base_tag_len,
1.153 + int *packet_len,
1.154 + xtd_seq_num_t pkt_index);
1.155 +
1.156 +/*
1.157 + * We handle EKT by performing some additional steps before
1.158 + * authentication (copying the auth tag into a temporary location,
1.159 + * zeroizing the "base tag" field in the packet)
1.160 + *
1.161 + * With EKT, the tag_len parameter is actually the base tag
1.162 + * length
1.163 + */
1.164 +
1.165 +err_status_t
1.166 +ekt_tag_verification_preproces(uint8_t *pkt_tag,
1.167 + uint8_t *pkt_tag_copy,
1.168 + unsigned tag_len);
1.169 +
1.170 +err_status_t
1.171 +ekt_tag_verification_postproces(uint8_t *pkt_tag,
1.172 + uint8_t *pkt_tag_copy,
1.173 + unsigned tag_len);
1.174 +
1.175 +
1.176 +/*
1.177 + * @brief EKT pre-processing for srtcp tag generation
1.178 + *
1.179 + * This function does the pre-processing of the SRTCP authentication
1.180 + * tag format. When EKT is used, it consists of writing the Encrypted
1.181 + * Master Key, the SRTP ROC, the Initial Sequence Number, and SPI
1.182 + * fields. The Base Authentication Tag field is set to the all-zero
1.183 + * value
1.184 + *
1.185 + * When EKT is not used, this function is a no-op.
1.186 + *
1.187 + */
1.188 +
1.189 +err_status_t
1.190 +srtp_stream_srtcp_auth_tag_generation_preprocess(const srtp_stream_t *s,
1.191 + uint8_t *pkt_tag,
1.192 + unsigned pkt_octet_len);
1.193 +
1.194 +/* it's not clear that a tag_generation_postprocess function is needed */
1.195 +
1.196 +err_status_t
1.197 +srtcp_auth_tag_generation_postprocess(void);
1.198 +
1.199 +
1.200 +#ifdef __cplusplus
1.201 +}
1.202 +#endif
1.203 +
1.204 +#endif /* EKT_H */
