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