src/libtls/tls_protection.h

   1 /*
   2  * Copyright (C) 2010 Martin Willi
   3  * Copyright (C) 2010 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_protection tls_protection
  18  * @{ @ingroup libtls
  19  */
  20
  21 #ifndef TLS_PROTECTION_H_
  22 #define TLS_PROTECTION_H_
  23
  24 #include <library.h>
  25
  26 typedef struct tls_protection_t tls_protection_t;
  27
  28 #include "tls.h"
  29 #include "tls_alert.h"
  30 #include "tls_compression.h"
  31
  32 /**
  33  * TLS record protocol protection layer.
  34  */
  35 struct tls_protection_t {
  36
  37         /**
  38          * Process a protected TLS record, pass it to upper layers.
  39          *
  40          * @param type          type of the TLS record to process
  41          * @param data          associated TLS record data
  42          * @return
  43          *                                      - SUCCESS if TLS negotiation complete
  44          *                                      - FAILED if TLS handshake failed
  45          *                                      - NEED_MORE if more invocations to process/build needed
  46          */
  47         status_t (*process)(tls_protection_t *this,
  48                                                 tls_content_type_t type, chunk_t data);
  49
  50         /**
  51          * Query upper layer for TLS record, build protected record.
  52          *
  53          * @param type          type of the built TLS record
  54          * @param data          allocated data of the built TLS record
  55          * @return
  56          *                                      - SUCCESS if TLS negotiation complete
  57          *                                      - FAILED if TLS handshake failed
  58          *                                      - NEED_MORE if upper layers have more records to send
  59          *                                      - INVALID_STATE if more input records required
  60          */
  61         status_t (*build)(tls_protection_t *this,
  62                                           tls_content_type_t *type, chunk_t *data);
  63
  64         /**
  65          * Set a new cipher, including encryption and integrity algorithms.
  66          *
  67          * @param inbound       TRUE to use cipher for inbound data, FALSE for outbound
  68          * @param signer        new signer to use, gets owned by protection layer
  69          * @param crypter       new crypter to use, gets owned by protection layer
  70          * @param iv            initial IV for crypter, gets owned by protection layer
  71          */
  72         void (*set_cipher)(tls_protection_t *this, bool inbound, signer_t *signer,
  73                                            crypter_t *crypter, chunk_t iv);
  74
  75         /**
  76          * Set the TLS version negotiated, used for MAC calculation.
  77          *
  78          * @param version       TLS version negotiated
  79          */
  80         void (*set_version)(tls_protection_t *this, tls_version_t version);
  81
  82         /**
  83          * Destroy a tls_protection_t.
  84          */
  85         void (*destroy)(tls_protection_t *this);
  86 };
  87
  88 /**
  89  * Create a tls_protection instance.
  90  *
  91  * @param compression           compression layer of TLS stack
  92  * @param alert                         TLS alert handler
  93  * @return                                      TLS protection layer.
  94  */
  95 tls_protection_t *tls_protection_create(tls_compression_t *compression,
  96                                                                                 tls_alert_t *alert);
  97
  98 #endif /** TLS_PROTECTION_H_ @}*/