api/yaca/yaca_seal.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 yaca_seal.h
  21  * @brief
  22  */
  23
  24 #ifndef YACA_SEAL_H
  25 #define YACA_SEAL_H
  26
  27 #include <stddef.h>
  28 #include <yaca_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @defgroup  Advanced-Encryption-Asymmetric  Advanced API for the asymmetric encryption.
  36  *
  37  * TODO: extended description and examples.
  38  *
  39  * @remarks Seal does more than just encrypt. It first generates the encryption key and IV,
  40  *          then encrypts whole message using this key (and selected symmetric algorithm).
  41  *          Finally it encrypts symmetric key with public key.
  42  *
  43  * @{
  44  */
  45
  46 /**
  47  * @brief  Initializes an asymmetric encryption context.
  48  *
  49  * @since_tizen 3.0
  50  *
  51  * @param[out] ctx           Newly created context (must be freed with yaca_ctx_free())
  52  * @param[in]  pub_key       Public key of the peer that will receive the encrypted data
  53  * @param[in]  algo          Symmetric algorithm that will be used
  54  * @param[in]  bcm           Block chaining mode for the symmetric algorithm
  55  * @param[in]  sym_key_bits  Symmetric key length (in bits) that will be generated
  56  * @param[out] sym_key       Generated symmetric key that will be used,
  57  *                           it is encrypted with peer's public key
  58  * @param[out] iv            Generated initialization vector that will be used
  59  *
  60  * @return #YACA_ERROR_NONE on success, negative on error
  61  * @retval #YACA_ERROR_NONE Successful
  62  * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
  63  *                                      incorrect algo, bcm, sym_key_bits, invalid pub_key)
  64  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  65  * @retval #YACA_ERROR_INTERNAL Internal error
  66  *
  67  * @see #yaca_enc_algo_e
  68  * @see #yaca_block_cipher_mode_e
  69  * @see yaca_seal_update()
  70  * @see yaca_seal_final()
  71  */
  72 int yaca_seal_init(yaca_ctx_h *ctx,
  73                    const yaca_key_h pub_key,
  74                    yaca_enc_algo_e algo,
  75                    yaca_block_cipher_mode_e bcm,
  76                    yaca_key_bits_e sym_key_bits,
  77                    yaca_key_h *sym_key,
  78                    yaca_key_h *iv);
  79
  80 /**
  81  * @brief  Encrypts piece of the data.
  82  *
  83  * @since_tizen 3.0
  84  *
  85  * @param[in,out] ctx         Context created by yaca_seal_init()
  86  * @param[in]     plain       Plain text to be encrypted
  87  * @param[in]     plain_len   Length of the plain text
  88  * @param[out]    cipher      Buffer for the encrypted data
  89  *                            (must be allocated by client, see yaca_get_output_length())
  90  * @param[out]    cipher_len  Length of the encrypted data,
  91  *                            actual number of bytes written will be returned here
  92  *
  93  * @return #YACA_ERROR_NONE on success, negative on error
  94  * @retval #YACA_ERROR_NONE Successful
  95  * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0,
  96  *                                      incorrect context)
  97  * @retval #YACA_ERROR_INTERNAL Internal error
  98  *
  99  * @see yaca_seal_init()
 100  * @see yaca_seal_final()
 101  */
 102 int yaca_seal_update(yaca_ctx_h ctx,
 103                      const char *plain,
 104                      size_t plain_len,
 105                      char *cipher,
 106                      size_t *cipher_len);
 107
 108 /**
 109  * @brief  Encrypts the final piece of the data.
 110  *
 111  * @since_tizen 3.0
 112  *
 113  * @param[in,out] ctx         A valid seal context
 114  * @param[out]    cipher      Final piece of the encrypted data
 115  *                            (must be allocated by client, see yaca_get_block_length())
 116  * @param[out]    cipher_len  Length of the final piece,
 117  *                            actual number of bytes written will be returned here
 118  *
 119  * @return #YACA_ERROR_NONE on success, negative on error
 120  * @retval #YACA_ERROR_NONE Successful
 121  * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
 122  *                                      incorrect context)
 123  * @retval #YACA_ERROR_INTERNAL Internal error
 124  *
 125  * @see yaca_seal_init()
 126  * @see yaca_seal_update()
 127  */
 128 int yaca_seal_final(yaca_ctx_h ctx,
 129                     char *cipher,
 130                     size_t *cipher_len);
 131
 132 /**
 133  * @brief  Initializes an asymmetric decryption context.
 134  *
 135  * @since_tizen 3.0
 136  *
 137  * @param[out] ctx           Newly created context (must be freed by yaca_ctx_free())
 138  * @param[in]  prv_key       Private key, part of the pair that was used for the encryption
 139  * @param[in]  algo          Symmetric algorithm that was used for the encryption
 140  * @param[in]  bcm           Block chaining mode for the symmetric algorithm
 141  * @param[in]  sym_key_bits  Symmetric key length (in bits) that was used for the encryption
 142  * @param[in]  sym_key       Symmetric key, encrypted with the public key,
 143  *                           that was used to encrypt the data
 144  * @param[in]  iv            Initialization vector that was used for the encryption
 145  *
 146  * @return #YACA_ERROR_NONE on success, negative on error
 147  * @retval #YACA_ERROR_NONE Successful
 148  * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
 149  *                                      incorrect algo, bcm, sym_key_bits,
 150  *                                      invalid prv_key, sym_key or iv)
 151  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 152  * @retval #YACA_ERROR_INTERNAL Internal error
 153  *
 154  * @see #yaca_enc_algo_e
 155  * @see #yaca_block_cipher_mode_e
 156  * @see yaca_open_update()
 157  * @see yaca_open_final()
 158  */
 159 int yaca_open_init(yaca_ctx_h *ctx,
 160                    const yaca_key_h prv_key,
 161                    yaca_enc_algo_e algo,
 162                    yaca_block_cipher_mode_e bcm,
 163                    yaca_key_bits_e sym_key_bits,
 164                    const yaca_key_h sym_key,
 165                    const yaca_key_h iv);
 166
 167 /**
 168  * @brief  Decrypts piece of the data.
 169  *
 170  * @since_tizen 3.0
 171  *
 172  * @param[in,out] ctx         Context created by yaca_open_init()
 173  * @param[in]     cipher      Cipher text to be decrypted
 174  * @param[in]     cipher_len  Length of the cipher text
 175  * @param[out]    plain       Buffer for the decrypted data
 176  *                            (must be allocated by client, see yaca_get_output_length())
 177  * @param[out]    plain_len   Length of the decrypted data,
 178  *                            actual number of bytes written will be returned here
 179  *
 180  * @return #YACA_ERROR_NONE on success, negative on error
 181  * @retval #YACA_ERROR_NONE Successful
 182  * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL, 0,
 183  *                                      incorrect context)
 184  * @retval #YACA_ERROR_INTERNAL Internal error
 185  *
 186  * @see yaca_open_init()
 187  * @see yaca_open_final()
 188  */
 189 int yaca_open_update(yaca_ctx_h ctx,
 190                      const char *cipher,
 191                      size_t cipher_len,
 192                      char *plain,
 193                      size_t *plain_len);
 194
 195 /**
 196  * @brief  Decrypts last chunk of sealed message.
 197  *
 198  * @since_tizen 3.0
 199  *
 200  * @param[in,out] ctx        A valid open context
 201  * @param[out]    plain      Final piece of the decrypted data
 202  *                           (must be allocated by client, see yaca_get_block_length())
 203  * @param[out]    plain_len  Length of the final piece,
 204  *                           actual number of bytes written will be returned here
 205  *
 206  * @return #YACA_ERROR_NONE on success, negative on error
 207  * @retval #YACA_ERROR_NONE Successful
 208  * @retval #YACA_ERROR_INVALID_ARGUMENT Required parameters have bogus values (NULL,
 209  *                                      incorrect context)
 210  * @retval #YACA_ERROR_INTERNAL Internal error
 211  *
 212  * @see yaca_open_init()
 213  * @see yaca_open_update()
 214  */
 215 int yaca_open_final(yaca_ctx_h ctx,
 216                     char *plain,
 217                     size_t *plain_len);
 218
 219 /**@}*/
 220
 221 #ifdef __cplusplus
 222 } /* extern */
 223 #endif
 224
 225 #endif /* YACA_SEAL_H */