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