trap-manager: Wait for install to finish before uninstalling
[strongswan.git] / src / libtls / tls_aead.h
1 /*
2 * Copyright (C) 2014 Martin Willi
3 * Copyright (C) 2014 revosec AG
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup tls_aead tls_aead
18 * @{ @ingroup tls
19 */
20
21 #ifndef TLS_AEAD_H_
22 #define TLS_AEAD_H_
23
24 typedef struct tls_aead_t tls_aead_t;
25
26 #include "tls.h"
27
28 /**
29 * TLS specific AEAD interface, includes padding.
30 *
31 * As TLS uses sign-then-encrypt instead of the more modern encrypt-then-sign,
32 * we can't directly abstract traditional transforms using our aead_t interface.
33 * With traditional transforms, the AEAD operation has to manage padding, as
34 * the MAC is calculated over unpadded data.
35 */
36 struct tls_aead_t {
37
38 /**
39 * Encrypt and sign a TLS record.
40 *
41 * The plain data chunk gets freed on success, and the data chunk
42 * gets updated with a new allocation of the encrypted data.
43 * If next_iv is given, it must contain the IV for this operation. It
44 * gets updated to the IV for the next record.
45 *
46 * @param version TLS version
47 * @param type TLS content type
48 * @param seq record sequence number
49 * @param data data to encrypt, encryption result
50 * @return TRUE if successfully encrypted
51 */
52 bool (*encrypt)(tls_aead_t *this, tls_version_t version,
53 tls_content_type_t type, uint64_t seq, chunk_t *data);
54
55 /**
56 * Decrypt and verify a TLS record.
57 *
58 * The passed encrypted data chunk gets updated to the decrypted record
59 * length, decryption is done inline.
60 *
61 * @param version TLS version
62 * @param type TLS content type
63 * @param seq record sequence number
64 * @param data data to decrypt, decrypted result
65 * @return TRUE if successfully decrypted
66 */
67 bool (*decrypt)(tls_aead_t *this, tls_version_t version,
68 tls_content_type_t type, uint64_t seq, chunk_t *data);
69
70 /**
71 * Get the authentication key size.
72 *
73 * @return key size, in bytes, 0 if not used
74 */
75 size_t (*get_mac_key_size)(tls_aead_t *this);
76
77 /**
78 * Get the encryption key size, if used.
79 *
80 * @return key size, in bytes, 0 if not used
81 */
82 size_t (*get_encr_key_size)(tls_aead_t *this);
83
84 /**
85 * Get the size of implicit IV (or AEAD salt), if used.
86 *
87 * @return IV/salt size, in bytes, 0 if not used
88 */
89 size_t (*get_iv_size)(tls_aead_t *this);
90
91 /**
92 * Set the keys used by an AEAD transform.
93 *
94 * @param mac authentication key, if used
95 * @param encr encryption key, if used
96 * @param iv initial implicit IV or AEAD salt, if any
97 * @return TRUE if key valid and set
98 */
99 bool (*set_keys)(tls_aead_t *this, chunk_t mac, chunk_t ecnr, chunk_t iv);
100
101 /**
102 * Destroy a tls_aead_t.
103 */
104 void (*destroy)(tls_aead_t *this);
105 };
106
107 /**
108 * Create a tls_aead instance using traditional transforms, explicit IV.
109 *
110 * An explicit IV means that the IV is prepended to each TLS record. This is
111 * the mechanism used in TLS 1.1 and newer.
112 *
113 * @param mac integrity protection algorithm
114 * @param encr encryption algorithm
115 * @param encr_size encryption key size, in bytes
116 * @return TLS AEAD transform
117 */
118 tls_aead_t *tls_aead_create_explicit(integrity_algorithm_t mac,
119 encryption_algorithm_t encr, size_t encr_size);
120
121 /**
122 * Create a tls_aead instance using traditional transforms, implicit IV.
123 *
124 * An implicit IV uses a first IV derived from the TLS keymat, which then
125 * gets replaced by the last encrypted records tail. This is the mechanism
126 * used for TLS 1.0 and older.
127 *
128 * @param mac integrity protection algorithm
129 * @param encr encryption algorithm
130 * @param encr_size encryption key size, in bytes
131 * @return TLS AEAD transform
132 */
133 tls_aead_t *tls_aead_create_implicit(integrity_algorithm_t mac,
134 encryption_algorithm_t encr, size_t encr_size);
135
136 /**
137 * Create a tls_aead instance using NULL encryption.
138 *
139 * As no IV is involved with null encryption, this AEAD works with any
140 * version of TLS.
141 *
142 * @param mac integrity protection algorithm
143 * @return TLS AEAD transform
144 */
145 tls_aead_t *tls_aead_create_null(integrity_algorithm_t mac);
146
147 /**
148 * Create a tls_aead instance using real a AEAD cipher.
149 *
150 * @param encr AEAD encryption algorithm
151 * @param encr_size encryption key size, in bytes
152 * @return TLS AEAD transform
153 */
154 tls_aead_t *tls_aead_create_aead(encryption_algorithm_t encr, size_t encr_size);
155
156 #endif /** TLS_AEAD_H_ @}*/