src/include/crypto/encrypt.h

   1 /*
   2  *  Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Contact: Krzysztof Jackiewicz <k.jackiewicz@samsung.com>
   5  *
   6  *  Licensed under the Apache License, Version 2.0 (the "License");
   7  *  you may not use this file except in compliance with the License.
   8  *  You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *  Unless required by applicable law or agreed to in writing, software
  13  *  distributed under the License is distributed on an "AS IS" BASIS,
  14  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *  See the License for the specific language governing permissions and
  16  *  limitations under the License
  17  */
  18
  19 /**
  20  * @file encrypt.h
  21  * @brief
  22  */
  23
  24 #ifndef ENCRYPT_H
  25 #define ENCRYPT_H
  26
  27 #include <stddef.h>
  28 #include <crypto/types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @defgroup  Advanced-Encryption-Symmetric  Advanced API for the symmetric encryption.
  36  *
  37  * TODO: extended description and examples.
  38  *
  39  * TODO: Let's describe how to set additional params (like GCM, CCM)
  40  *
  41  * @{
  42  */
  43
  44 /**
  45  * @brief crypto_encrypt_init  Initializes an encryption context.
  46  *
  47  * @param[out] ctx      Newly created context (must be freed with @see crypto_ctx_free).
  48  * @param[in]  algo     Encryption algorithm that will be used.
  49  * @param[in]  bcm      Chaining mode that will be used.
  50  * @param[in]  sym_key  Symmetric key that will be used.
  51  * @param[in]  iv       Initialization vector that will be used.
  52  *
  53  * @return 0 on success, negative on error (@see error.h).
  54  */
  55 int crypto_encrypt_init(crypto_ctx_h *ctx,
  56                         crypto_enc_algo_e algo,
  57                         crypto_block_cipher_mode_e bcm,
  58                         const crypto_key_h sym_key,
  59                         const crypto_key_h iv);
  60
  61 /**
  62  * @brief crypto_encrypt_update  Encrypts chunk of the data.
  63  *
  64  * @param[in,out] ctx         Context created by @see crypto_encrypt_init.
  65  * @param[in]     plain       Plain text to be encrypted.
  66  * @param[in]     plain_len   Length of the plain text.
  67  * @param[out]    cipher      Buffer for the encrypted data (must be allocated by client, @see crypto_get_output_length).
  68  * @param[out]    cipher_len  Length of the encrypted data, actual number of bytes written will be returned here.
  69  *
  70  * @return 0 on success, negative on error (@see error.h).
  71  */
  72 int crypto_encrypt_update(crypto_ctx_h ctx,
  73                           const char *plain,
  74                           size_t plain_len,
  75                           char *cipher,
  76                           size_t *cipher_len);
  77
  78 /**
  79  * @brief crypto_encrypt_final  Encrypts the final chunk of the data.
  80  *
  81  * @param[in,out] ctx         A valid encrypt context.
  82  * @param[out]    cipher      Final piece of the encrypted data (must be allocated by client, @see crypto_get_block_length).
  83  * @param[out]    cipher_len  Length of the final piece, actual number of bytes written will be returned here.
  84  *
  85  * @return 0 on success, negative on error (@see error.h).
  86  */
  87 int crypto_encrypt_final(crypto_ctx_h ctx,
  88                          char *cipher,
  89                          size_t *cipher_len);
  90
  91 /**
  92  * @brief crypto_decrypt_init  Initializes an decryption context.
  93  *
  94  * @param[out] ctx      Newly created context (must be freed with @see crypto_ctx_free).
  95  * @param[in]  algo     Encryption algorithm that was used to encrypt the data.
  96  * @param[in]  bcm      Chaining mode that was used to encrypt the data.
  97  * @param[in]  sym_key  Symmetric key that was used to encrypt the data.
  98  * @param[in]  iv       Initialization vector that was used to encrypt the data.
  99  *
 100  * @return 0 on success, negative on error (@see error.h).
 101  */
 102 int crypto_decrypt_init(crypto_ctx_h *ctx,
 103                         crypto_enc_algo_e algo,
 104                         crypto_block_cipher_mode_e bcm,
 105                         const crypto_key_h sym_key,
 106                         const crypto_key_h iv);
 107
 108 /**
 109  * @brief crypto_decrypt_update Decrypts chunk of the data.
 110  *
 111  * @param[in,out] ctx         Context created by @see crypto_decrypt_init.
 112  * @param[in]     cipher      Cipher text to be decrypted.
 113  * @param[in]     cipher_len  Length of the cipher text.
 114  * @param[out]    plain       Buffer for the decrypted data (must be allocated by client, @see crypto_get_output_length).
 115  * @param[out]    plain_len   Length of the decrypted data, actual number of bytes written will be returned here.
 116  *
 117  * @return 0 on success, negative on error (@see error.h).
 118  */
 119 int crypto_decrypt_update(crypto_ctx_h ctx,
 120                           const char *cipher,
 121                           size_t cipher_len,
 122                           char *plain,
 123                           size_t *plain_len);
 124
 125 /**
 126  * @brief crypto_decrypt_final  Decrypts the final chunk of the data.
 127  *
 128  * @param[in,out] ctx        A valid decrypt context.
 129  * @param[out]    plain      Final piece of the decrypted data (must be allocated by client, @see crypto_get_block_length).
 130  * @param[out]    plain_len  Length of the final piece, actual number of bytes written will be returned here.
 131  *
 132  * @return 0 on success, negative on error (@see error.h).
 133  */
 134 int crypto_decrypt_final(crypto_ctx_h ctx,
 135                          char *plain,
 136                          size_t *plain_len);
 137
 138 /**@}*/
 139
 140 /**
 141  * @defgroup  Advanced-Encryption-Asymmetric  Advanced API for the asymmetric encryption.
 142  *
 143  * TODO: extended description and examples.
 144  *
 145  * TODO: Seal does more than just encrypt. It first generates the encryption key and IV,
 146  * then encrypts whole message using this key (and selected symmetric algorithm).
 147  * Finally it encrypts symmetric key with public key.
 148  *
 149  * @{
 150  */
 151
 152 /**
 153  * @brief crypto_seal_init  Initializes an asymmetric encryption context.
 154  *
 155  * @param[out] ctx      Newly created context (must be freed with @see crypto_ctx_free).
 156  * @param[in]  pub_key  Public key of the peer that will receive the encrypted data.
 157  * @param[in]  algo     Symmetric algorithm that will be used.
 158  * @param[in]  bcm      Block chaining mode for the symmetric algorithm.
 159  * @param[out] sym_key  Generated symmetric key that will be used. It is encrypted with peer's public key.
 160  * @param[out] iv       Generated initialization vector that will be used.
 161  *
 162  * @return 0 on success, negative on error (@see error.h).
 163  */
 164 int crypto_seal_init(crypto_ctx_h *ctx,
 165                      const crypto_key_h pub_key,
 166                      crypto_enc_algo_e algo,
 167                      crypto_block_cipher_mode_e bcm,
 168                      crypto_key_h *sym_key,
 169                      crypto_key_h *iv);
 170
 171 /**
 172  * @brief crypto_seal_update  Encrypts piece of the data.
 173  *
 174  * @param[in,out] ctx         Context created by @see crypto_seal_init.
 175  * @param[in]     plain       Plain text to be encrypted.
 176  * @param[in]     plain_len   Length of the plain text.
 177  * @param[out]    cipher      Buffer for the encrypted data (must be allocated by client, @see crypto_get_output_length).
 178  * @param[out]    cipher_len  Length of the encrypted data, actual number of bytes written will be returned here.
 179  *
 180  * @return 0 on success, negative on error (@see error.h).
 181  */
 182 int crypto_seal_update(crypto_ctx_h ctx,
 183                        const char *plain,
 184                        size_t plain_len,
 185                        char *cipher,
 186                        size_t *cipher_len);
 187
 188 /**
 189  * @brief crypto_seal_final  Encrypts the final piece of the data.
 190  *
 191  * @param[in,out] ctx         A valid seal context.
 192  * @param[out]    cipher      Final piece of the encrypted data (must be allocated by client, @see crypto_get_block_length).
 193  * @param[out]    cipher_len  Length of the final piece, actual number of bytes written will be returned here.
 194  *
 195  * @return 0 on success, negative on error (@see error.h).
 196  */
 197 int crypto_seal_final(crypto_ctx_h ctx,
 198                       char *cipher,
 199                       size_t *cipher_len);
 200
 201 /**
 202  * @brief crypto_open_init  Initializes an asymmetric decryption context.
 203  *
 204  * @param[out] ctx      Newly created context. Must be freed by @see crypto_ctx_free.
 205  * @param[in]  prv_key  Private key, part of the pair that was used for the encryption.
 206  * @param[in]  algo     Symmetric algorithm that was used for the encryption.
 207  * @param[in]  bcm      Block chaining mode for the symmetric algorithm.
 208  * @param[in]  sym_key  Symmetric key, encrypted with the public key, that was used to encrypt the data.
 209  * @param[in]  iv       Initialization vector that was used for the encryption.
 210  *
 211  * @return 0 on success, negative on error (@see error.h).
 212  */
 213 int crypto_open_init(crypto_ctx_h *ctx,
 214                      const crypto_key_h prv_key,
 215                      crypto_enc_algo_e algo,
 216                      crypto_block_cipher_mode_e bcm,
 217                      const crypto_key_h sym_key,
 218                      const crypto_key_h iv);
 219
 220 /**
 221  * @brief crypto_open_update  Decrypts piece of the data.
 222  *
 223  * @param[in,out] ctx         Context created by @see crypto_open_init.
 224  * @param[in]     cipher      Cipher text to be decrypted.
 225  * @param[in]     cipher_len  Length of the cipher text.
 226  * @param[out]    plain       Buffer for the decrypted data (must be allocated by client, @see crypto_get_output_length).
 227  * @param[out]    plain_len   Length of the decrypted data, actual number of bytes written will be returned here.
 228  *
 229  * @return 0 on success, negative on error (@see error.h).
 230  */
 231 int crypto_open_update(crypto_ctx_h ctx,
 232                        const char *cipher,
 233                        size_t cipher_len,
 234                        char *plain,
 235                        size_t *plain_len);
 236
 237 /**
 238  * @brief crypto_open_final Decrypts last chunk of sealed message.
 239  *
 240  * @param[in,out] ctx        A valid open context.
 241  * @param[out]    plain      Final piece of the decrypted data (must be allocated by client, @see crypto_get_block_length).
 242  * @param[out]    plain_len  Length of the final piece, actual number of bytes written will be returned here.
 243  *
 244  * @return 0 on success, negative on error (@see error.h).
 245  */
 246 int crypto_open_final(crypto_ctx_h ctx,
 247                       char *plain,
 248                       size_t *plain_len);
 249
 250 /**@}*/
 251 #ifdef __cplusplus
 252 } /* extern */
 253 #endif
 254
 255 #endif /* ENCRYPT_H */