Source/charon/encoding/payloads/encryption_payload.h

   1 /**
   2  * @file encryption_payload.h
   3  *
   4  * @brief Interface of encryption_payload_t.
   5  */
   6
   7 /*
   8  * Copyright (C) 2005 Jan Hutter, Martin Willi
   9  * Hochschule fuer Technik Rapperswil
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU General Public License as published by the
  13  * Free Software Foundation; either version 2 of the License, or (at your
  14  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  18  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  19  * for more details.
  20  */
  21
  22 #ifndef ENCRYPTION_PAYLOAD_H_
  23 #define ENCRYPTION_PAYLOAD_H_
  24
  25 #include <types.h>
  26 #include <crypto/crypters/crypter.h>
  27 #include <crypto/signers/signer.h>
  28 #include <encoding/payloads/payload.h>
  29 #include <utils/linked_list.h>
  30
  31 /**
  32  * Encrpytion payload length in bytes without IV and following data.
  33  *
  34  * @ingroup payloads
  35  */
  36 #define ENCRYPTION_PAYLOAD_HEADER_LENGTH 4
  37
  38
  39 typedef struct encryption_payload_t encryption_payload_t;
  40
  41 /**
  42  * @brief The encryption payload as described in RFC section 3.14.
  43  *
  44  * Before any crypt/decrypt/sign/verify operation can occur,
  45  * the transforms must be set. After that, a parsed encryption payload
  46  * can be decrypted, which also will parse the contained payloads.
  47  * Encryption is done the same way, added payloads will get generated
  48  * and then encrypted.
  49  * For signature building, there is the FULL packet needed. Meaning it
  50  * must be builded after generation of all payloads and the encryption
  51  * of the encryption payload.
  52  * Signature verificatin is done before decryption.
  53  *
  54  * @b Constructors:
  55  * - encryption_payload_create()
  56  *
  57  * @ingroup payloads
  58  */
  59 struct encryption_payload_t {
  60         /**
  61          * Implements payload_t interface.
  62          */
  63         payload_t payload_interface;
  64
  65         /**
  66          * @brief Creates an iterator for all contained payloads.
  67          *
  68          * @warning iterator_t object has to get destroyed by the caller.
  69          *
  70          * @param this                  calling encryption_payload_t object
  71          * @param[in] forward   iterator direction (TRUE: front to end)
  72          * return                               created iterator_t object
  73          */
  74          iterator_t *(*create_payload_iterator) (encryption_payload_t *this, bool forward);
  75
  76         /**
  77          * @brief Adds a payload to this encryption payload.
  78          *
  79          * @param this                  calling encryption_payload_t object
  80          * @param payload               payload_t object to add
  81          */
  82         void (*add_payload) (encryption_payload_t *this, payload_t *payload);
  83
  84         /**
  85          * @brief Reove the last payload in the contained payload list.
  86          *
  87          * @param this                  calling encryption_payload_t object
  88          * @param[out] payload  removed payload
  89          * @return
  90          *                                              - SUCCESS, or
  91          *                                              - NOT_FOUND if list empty
  92          */
  93         status_t (*remove_first_payload) (encryption_payload_t *this, payload_t **payload);
  94
  95         /**
  96          * @brief Get the number of payloads.
  97          *
  98          * @param this                  calling encryption_payload_t object
  99          * @return                              number of contained payloads
 100          */
 101         size_t (*get_payload_count) (encryption_payload_t *this);
 102
 103         /**
 104          * @brief Set transforms to use.
 105          *
 106          * To decryption, encryption, signature building and verifying,
 107          * the payload needs a crypter and a signer object.
 108          *
 109          * @warning Do NOT call this function again after encryption, since
 110          * the signer must be the same while encrypting and signature building!
 111          *
 112          * @param this                  calling encryption_payload_t
 113          * @param crypter               crypter_t to use for data de-/encryption
 114          * @param signer                signer_t to use for data signing/verifying
 115          */
 116         void (*set_transforms) (encryption_payload_t *this, crypter_t *crypter, signer_t *signer);
 117
 118         /**
 119          * @brief Generate and encrypt contained payloads.
 120          *
 121          * This function generates the content for added payloads
 122          * and encrypts them. Signature is not built, since we need
 123          * additional data (the full message).
 124          *
 125          * @param this                  calling encryption_payload_t
 126          * @return
 127          *                                              - SUCCESS, or
 128          *                                              - INVALID_STATE if transforms not set
 129          */
 130         status_t (*encrypt) (encryption_payload_t *this);
 131
 132         /**
 133          * @brief Decrypt and parse contained payloads.
 134          *
 135          * This function decrypts the contained data. After,
 136          * the payloads are parsed internally and are accessible
 137          * via the iterator.
 138          *
 139          * @param this                  calling encryption_payload_t
 140          * @return
 141          *                                              - SUCCESS, or
 142          *                                              - INVALID_STATE if transforms not set, or
 143          *                                              - FAILED if data is invalid
 144          */
 145         status_t (*decrypt) (encryption_payload_t *this);
 146
 147         /**
 148          * @brief Build the signature.
 149          *
 150          * The signature is built over the FULL message, so the header
 151          * and every payload (inclusive this one) must already be generated.
 152          * The generated message is supplied via the data paramater.
 153          *
 154          * @param this                  calling encryption_payload_t
 155          * @param data                  chunk contains the already generated message
 156          * @return
 157          *                                              - SUCCESS, or
 158          *                                              - INVALID_STATE if transforms not set
 159          */
 160         status_t (*build_signature) (encryption_payload_t *this, chunk_t data);
 161
 162         /**
 163          * @brief Verify the signature.
 164          *
 165          * Since the signature is built over the full message, we need
 166          * this data to do the verification. The message data
 167          * is supplied via the data argument.
 168          *
 169          * @param this                  calling encryption_payload_t
 170          * @param data                  chunk contains the message
 171          * @return
 172          *                                              - SUCCESS, or
 173          *                                              - FAILED if signature invalid, or
 174          *                                              - INVALID_STATE if transforms not set
 175          */
 176         status_t (*verify_signature) (encryption_payload_t *this, chunk_t data);
 177
 178         /**
 179          * @brief Destroys an encryption_payload_t object.
 180          *
 181          * @param this                  encryption_payload_t object to destroy
 182          */
 183         void (*destroy) (encryption_payload_t *this);
 184 };
 185
 186 /**
 187  * @brief Creates an empty encryption_payload_t object.
 188  *
 189  * @return encryption_payload_t object
 190  *
 191  * @ingroup payloads
 192  */
 193 encryption_payload_t *encryption_payload_create();
 194
 195
 196 #endif /*ENCRYPTION_PAYLOAD_H_*/