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  *
  38  * @remarks  Seal does more than just encrypt. It first generates the encryption key and IV,
  39  *           then encrypts whole message using this key (and selected symmetric algorithm).
  40  *           Finally it encrypts symmetric key with public key.
  41  *
  42  * @{
  43  */
  44
  45 /**
  46  * @brief  Initializes an asymmetric encryption context and generates symmetric key and IV.
  47  *
  48  * @remarks  Generated symmetric key is encrypted with public key,
  49  *           so can be ONLY used with yaca_open_initialize(). It can be exported,
  50  *           but after import it can be ONLY used with yaca_open_initialize() as well.
  51  *
  52  * @since_tizen 3.0
  53  *
  54  * @param[out] ctx              Newly created context (must be freed with yaca_context_destroy())
  55  * @param[in]  pub_key          Public key of the peer that will receive the encrypted data
  56  * @param[in]  algo             Symmetric algorithm that will be used
  57  * @param[in]  bcm              Block chaining mode for the symmetric algorithm
  58  * @param[in]  sym_key_bit_len  Symmetric key length (in bits) that will be generated
  59  * @param[out] sym_key          Generated symmetric key that will be used,
  60  *                              it is encrypted with peer's public key
  61  *                              (must be freed with yaca_key_destroy())
  62  * @param[out] iv               Generated initialization vector that will be used
  63  *                              (must be freed with yaca_key_destroy())
  64  *
  65  * @return #YACA_ERROR_NONE on success, negative on error
  66  * @retval #YACA_ERROR_NONE Successful
  67  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
  68  *                                       invalid algo, bcm, sym_key_bit_len or pub_key)
  69  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  70  * @retval #YACA_ERROR_INTERNAL Internal error
  71  *
  72  * @see #yaca_encrypt_algorithm_e
  73  * @see #yaca_block_cipher_mode_e
  74  * @see #yaca_key_bit_length_e
  75  * @see yaca_seal_update()
  76  * @see yaca_seal_finalize()
  77  * @see yaca_open_initialize()
  78  * @see yaca_key_destroy()
  79  * @see yaca_context_destroy()
  80  */
  81 int yaca_seal_initialize(yaca_context_h *ctx,
  82                          const yaca_key_h pub_key,
  83                          yaca_encrypt_algorithm_e algo,
  84                          yaca_block_cipher_mode_e bcm,
  85                          size_t sym_key_bit_len,
  86                          yaca_key_h *sym_key,
  87                          yaca_key_h *iv);
  88
  89 /**
  90  * @brief  Encrypts piece of the data.
  91  *
  92  * @since_tizen 3.0
  93  *
  94  * @param[in,out] ctx             Context created by yaca_seal_initialize()
  95  * @param[in]     plaintext       Plaintext to be encrypted
  96  * @param[in]     plaintext_len   Length of the plaintext
  97  * @param[out]    ciphertext      Buffer for the encrypted data
  98  *                                (must be allocated by client, see yaca_context_get_output_length())
  99  * @param[out]    ciphertext_len  Length of the encrypted data,
 100  *                                actual number of bytes written will be returned here
 101  *
 102  * @return #YACA_ERROR_NONE on success, negative on error
 103  * @retval #YACA_ERROR_NONE Successful
 104  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 105  *                                       invalid context)
 106  * @retval #YACA_ERROR_INTERNAL Internal error
 107  *
 108  * @see yaca_seal_initialize()
 109  * @see yaca_seal_finalize()
 110  * @see yaca_context_get_output_length()
 111  */
 112 int yaca_seal_update(yaca_context_h ctx,
 113                      const char *plaintext,
 114                      size_t plaintext_len,
 115                      char *ciphertext,
 116                      size_t *ciphertext_len);
 117
 118 /**
 119  * @brief  Encrypts the final piece of the data.
 120  *
 121  * @since_tizen 3.0
 122  *
 123  * @param[in,out] ctx             A valid seal context
 124  * @param[out]    ciphertext      Final piece of the encrypted data
 125  *                                (must be allocated by client, see yaca_context_get_output_length())
 126  * @param[out]    ciphertext_len  Length of the final piece,
 127  *                                actual number of bytes written will be returned here
 128  *
 129  * @return #YACA_ERROR_NONE on success, negative on error
 130  * @retval #YACA_ERROR_NONE Successful
 131  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 132  *                                       invalid context)
 133  * @retval #YACA_ERROR_INTERNAL Internal error
 134  *
 135  * @see yaca_seal_initialize()
 136  * @see yaca_seal_update()
 137  * @see yaca_context_get_output_length()
 138  */
 139 int yaca_seal_finalize(yaca_context_h ctx,
 140                        char *ciphertext,
 141                        size_t *ciphertext_len);
 142
 143 /**
 144  * @brief  Initializes an asymmetric decryption context.
 145  *
 146  * @since_tizen 3.0
 147  *
 148  * @param[out] ctx              Newly created context (must be freed by yaca_context_destroy())
 149  * @param[in]  prv_key          Private key, part of the pair that was used for the encryption
 150  * @param[in]  algo             Symmetric algorithm that was used for the encryption
 151  * @param[in]  bcm              Block chaining mode for the symmetric algorithm
 152  * @param[in]  sym_key_bit_len  Symmetric key length (in bits) that was used for the encryption
 153  * @param[in]  sym_key          Symmetric key, encrypted with the public key,
 154  *                              that was used to encrypt the data
 155  * @param[in]  iv               Initialization vector that was used for the encryption
 156  *
 157  * @return #YACA_ERROR_NONE on success, negative on error
 158  * @retval #YACA_ERROR_NONE Successful
 159  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, invalid
 160  *                                       algo, bcm, sym_key_bit_len, prv_key, sym_key or iv)
 161  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 162  * @retval #YACA_ERROR_INTERNAL Internal error
 163  *
 164  * @see #yaca_encrypt_algorithm_e
 165  * @see #yaca_block_cipher_mode_e
 166  * @see #yaca_key_bit_length_e
 167  * @see yaca_open_update()
 168  * @see yaca_open_finalize()
 169  * @see yaca_context_destroy()
 170  */
 171 int yaca_open_initialize(yaca_context_h *ctx,
 172                          const yaca_key_h prv_key,
 173                          yaca_encrypt_algorithm_e algo,
 174                          yaca_block_cipher_mode_e bcm,
 175                          size_t sym_key_bit_len,
 176                          const yaca_key_h sym_key,
 177                          const yaca_key_h iv);
 178
 179 /**
 180  * @brief  Decrypts piece of the data.
 181  *
 182  * @since_tizen 3.0
 183  *
 184  * @param[in,out] ctx             Context created by yaca_open_initialize()
 185  * @param[in]     ciphertext      Ciphertext to be decrypted
 186  * @param[in]     ciphertext_len  Length of the ciphertext
 187  * @param[out]    plaintext       Buffer for the decrypted data
 188  *                                (must be allocated by client, see yaca_context_get_output_length())
 189  * @param[out]    plaintext_len   Length of the decrypted data,
 190  *                                actual number of bytes written will be returned here
 191  *
 192  * @return #YACA_ERROR_NONE on success, negative on error
 193  * @retval #YACA_ERROR_NONE Successful
 194  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 195  *                                       invalid context)
 196  * @retval #YACA_ERROR_INTERNAL Internal error
 197  *
 198  * @see yaca_open_initialize()
 199  * @see yaca_open_finalize()
 200  * @see yaca_context_get_output_length()
 201  */
 202 int yaca_open_update(yaca_context_h ctx,
 203                      const char *ciphertext,
 204                      size_t ciphertext_len,
 205                      char *plaintext,
 206                      size_t *plaintext_len);
 207
 208 /**
 209  * @brief  Decrypts last chunk of sealed message.
 210  *
 211  * @since_tizen 3.0
 212  *
 213  * @param[in,out] ctx            A valid open context
 214  * @param[out]    plaintext      Final piece of the decrypted data
 215  *                               (must be allocated by client, see yaca_context_get_output_length())
 216  * @param[out]    plaintext_len  Length of the final piece,
 217  *                               actual number of bytes written will be returned here
 218  *
 219  * @return #YACA_ERROR_NONE on success, negative on error
 220  * @retval #YACA_ERROR_NONE Successful
 221  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 222  *                                       invalid context)
 223  * @retval #YACA_ERROR_INTERNAL Internal error
 224  *
 225  * @see yaca_open_initialize()
 226  * @see yaca_open_update()
 227  * @see yaca_context_get_output_length()
 228  */
 229 int yaca_open_finalize(yaca_context_h ctx,
 230                        char *plaintext,
 231                        size_t *plaintext_len);
 232
 233 /**@}*/
 234
 235 #ifdef __cplusplus
 236 } /* extern */
 237 #endif
 238
 239 #endif /* YACA_SEAL_H */