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