Return to tls_aead.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libtls

strongswan 5.9.2

    1: /*
    2:  * Copyright (C) 2020 Tobias Brunner
    3:  * HSR Hochschule fuer Technik Rapperswil
    4:  *
    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
   50: 	 * @param type			TLS content type (may be changed)
   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,
   56: 					tls_content_type_t *type, uint64_t seq, chunk_t *data);
   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
   65: 	 * @param type			TLS content type (may be changed)
   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,
   71: 					tls_content_type_t *type, uint64_t seq, chunk_t *data);
   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:  *
  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:  *
  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: 
  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: 
  176: #endif /** TLS_AEAD_H_ @}*/