src/libipsec/esp_context.h

   1 /*
   2  * Copyright (C) 2012-2013 Tobias Brunner
   3  * Copyright (C) 2012 Giuliano Grassi
   4  * Copyright (C) 2012 Ralf Sager
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup esp_context esp_context
  20  * @{ @ingroup libipsec
  21  */
  22
  23 #ifndef ESP_CONTEXT_H_
  24 #define ESP_CONTEXT_H_
  25
  26 #include <library.h>
  27 #include <crypto/aead.h>
  28
  29 typedef struct esp_context_t esp_context_t;
  30
  31 /**
  32  *  ESP context, handles sequence numbers and maintains cryptographic primitives
  33  */
  34 struct esp_context_t {
  35
  36         /**
  37          * Get AEAD wrapper or method to encrypt/decrypt/authenticate ESP packets.
  38          *
  39          * @return                              AEAD wrapper of method
  40          */
  41         aead_t *(*get_aead)(esp_context_t *this);
  42
  43         /**
  44          * Get the current outbound ESP sequence number or the highest authenticated
  45          * inbound sequence number.
  46          *
  47          * @return                      current sequence number, in host byte order
  48          */
  49         u_int32_t (*get_seqno)(esp_context_t *this);
  50
  51         /**
  52          * Allocate the next outbound ESP sequence number.
  53          *
  54          * @param seqno         the sequence number, in host byte order
  55          * @return                      FALSE if the sequence number cycled or inbound context
  56          */
  57         bool (*next_seqno)(esp_context_t *this, u_int32_t *seqno);
  58
  59         /**
  60          * Verify an ESP sequence number.  Checks whether a packet with this
  61          * sequence number was already received, using the anti-replay window.
  62          * This operation does not modify the internal state.  After the sequence
  63          * number is successfully verified and the ESP packet is authenticated,
  64          * set_authenticated_seqno() should be called.
  65          *
  66          * @param seqno         the sequence number to verify, in host byte order
  67          * @return                      TRUE when sequence number is valid
  68          */
  69         bool (*verify_seqno)(esp_context_t *this, u_int32_t seqno);
  70
  71         /**
  72          * Adds a sequence number that was successfully verified and
  73          * authenticated.  A user MUST call verify_seqno() immediately before
  74          * calling this method.
  75          *
  76          * @param seqno         verified and authenticated seq number in host byte order
  77          */
  78         void (*set_authenticated_seqno)(esp_context_t *this,
  79                                                                         u_int32_t seqno);
  80
  81         /**
  82          * Destroy an esp_context_t
  83          */
  84         void (*destroy)(esp_context_t *this);
  85
  86 };
  87
  88 /**
  89  * Create an esp_context_t instance
  90  *
  91  * @param enc_alg               encryption algorithm
  92  * @param enc_key               encryption key
  93  * @param int_alg               integrity protection algorithm
  94  * @param int_key               integrity protection key
  95  * @param inbound               TRUE to create an inbound ESP context
  96  * @return                              ESP context instance, or NULL if creation fails
  97  */
  98 esp_context_t *esp_context_create(int enc_alg, chunk_t enc_key, int int_alg,
  99                                                                   chunk_t int_key, bool inbound);
 100
 101 #endif /** ESP_CONTEXT_H_ @}*/
 102