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