api/yaca/yaca_simple.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_simple.h
  21  * @brief
  22  */
  23
  24 #ifndef YACA_SIMPLE_H
  25 #define YACA_SIMPLE_H
  26
  27 #include <stddef.h>
  28 #include <yaca_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @defgroup  Simple-API  Simple API.
  36  *
  37  *  @remarks  This is simple API.
  38  *            Design constraints:
  39  *            - All operations are single-shot (no streaming possible)
  40  *            - Context is not used
  41  *            - For now only digest and symmetric ciphers are supported
  42  *            - GCM and CCM chaining is not supported
  43  *            - All outputs are allocated by the library
  44  *
  45  * @{
  46  */
  47
  48 /**
  49  * @brief  Calculate a digest of a buffer.
  50  *
  51  * @since_tizen 3.0
  52  *
  53  * @remarks  The @a digest should be freed using yaca_free()
  54  *
  55  * @param[in]  algo        Digest algorithm (select #YACA_DIGEST_SHA256 if unsure)
  56  * @param[in]  data        Data from which the digest is to be calculated
  57  * @param[in]  data_len    Length of the data. Can be 0.
  58  * @param[out] digest      Message digest, will be allocated by the library
  59  * @param[out] digest_len  Length of message digest (depends on algorithm)
  60  *
  61  * @return #YACA_ERROR_NONE on success, negative on error
  62  * @retval #YACA_ERROR_NONE Successful
  63  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
  64  *                                       invalid algo)
  65  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  66  * @retval #YACA_ERROR_INTERNAL Internal error
  67  *
  68  * @see #yaca_digest_algorithm_e
  69  * @see yaca_free()
  70  */
  71 int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo,
  72                                  const char *data,
  73                                  size_t data_len,
  74                                  char **digest,
  75                                  size_t *digest_len);
  76
  77 /**
  78  * @brief  Encrypt data using a symmetric cipher.
  79  *
  80  * @since_tizen 3.0
  81  *
  82  * @remarks  The @a ciphertext should be freed using yaca_free()
  83  *
  84  * @param[in]  algo            Encryption algorithm (select #YACA_ENCRYPT_AES if unsure)
  85  * @param[in]  bcm             Chaining mode (select #YACA_BCM_CBC if unsure)
  86  * @param[in]  sym_key         Symmetric encryption key (see key.h for key generation functions)
  87  * @param[in]  iv              Initialization vector
  88  * @param[in]  plaintext       Plaintext to be encrypted
  89  * @param[in]  plaintext_len   Length of the plaintext
  90  * @param[out] ciphertext      Encrypted data, will be allocated by the library
  91  * @param[out] ciphertext_len  Length of the encrypted data (may be larger than decrypted)
  92  *
  93  * @return #YACA_ERROR_NONE on success, negative on error
  94  * @retval #YACA_ERROR_NONE Successful
  95  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
  96  *                                       invalid algo, bcm, sym_key or iv)
  97  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  98  * @retval #YACA_ERROR_INTERNAL Internal error
  99  *
 100  * @see #yaca_encrypt_algorithm_e
 101  * @see #yaca_block_cipher_mode_e
 102  * @see yaca_simple_decrypt()
 103  * @see yaca_free()
 104  */
 105 int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo,
 106                         yaca_block_cipher_mode_e bcm,
 107                         const yaca_key_h sym_key,
 108                         const yaca_key_h iv,
 109                         const char *plaintext,
 110                         size_t plaintext_len,
 111                         char **ciphertext,
 112                         size_t *ciphertext_len);
 113
 114 /**
 115  * @brief  Decrypt data using a symmetric cipher.
 116  *
 117  * @since_tizen 3.0
 118  *
 119  * @remarks  The @a plaintext should be freed using yaca_free()
 120  *
 121  * @param[in]  algo            Decryption algorithm that was used to encrypt the data
 122  * @param[in]  bcm             Chaining mode that was used to encrypt the data
 123  * @param[in]  sym_key         Symmetric encryption key that was used to encrypt the data
 124  * @param[in]  iv              Initialization vector that was used to encrypt the data
 125  * @param[in]  ciphertext      Ciphertext to be decrypted
 126  * @param[in]  ciphertext_len  Length of ciphertext
 127  * @param[out] plaintext       Decrypted data, will be allocated by the library
 128  * @param[out] plaintext_len   Length of the decrypted data
 129  *
 130  * @return #YACA_ERROR_NONE on success, negative on error
 131  * @retval #YACA_ERROR_NONE Successful
 132  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
 133  *                                       invalid algo, bcm, sym_key or iv)
 134  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 135  * @retval #YACA_ERROR_INTERNAL Internal error
 136  *
 137  * @see #yaca_encrypt_algorithm_e
 138  * @see #yaca_block_cipher_mode_e
 139  * @see yaca_simple_encrypt()
 140  * @see yaca_free()
 141  */
 142 int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo,
 143                         yaca_block_cipher_mode_e bcm,
 144                         const yaca_key_h sym_key,
 145                         const yaca_key_h iv,
 146                         const char *ciphertext,
 147                         size_t ciphertext_len,
 148                         char **plaintext,
 149                         size_t *plaintext_len);
 150
 151 /**
 152  * @brief  Create a signature using asymmetric private key.
 153  *
 154  * @since_tizen 3.0
 155  *
 156  * @remarks  The @a signature should be freed using yaca_free()
 157  *
 158  * @param[in]  algo           Digest algorithm that will be used
 159  * @param[in]  key            Private key that will be used, algorithm is
 160  *                            deduced based on key type, supported key types:
 161  *                            - #YACA_KEY_TYPE_RSA_PRIV,
 162  *                            - #YACA_KEY_TYPE_DSA_PRIV,
 163  * @param[in]  data           Data to be signed
 164  * @param[in]  data_len       Length of the data
 165  * @param[out] signature      Message signature, will be allocated by the
 166  * @param[out] signature_len  Length of the signature
 167  *
 168  * @return #YACA_ERROR_NONE on success, negative on error
 169  * @retval #YACA_ERROR_NONE Successful
 170  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
 171  *                                       invalid algo or key)
 172  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 173  * @retval #YACA_ERROR_INTERNAL Internal error
 174  *
 175  * @see #yaca_key_type_e
 176  * @see #yaca_digest_algorithm_e
 177  * @see yaca_simple_verify_signature()
 178  * @see yaca_free()
 179  */
 180 int yaca_simple_calculate_signature(yaca_digest_algorithm_e algo,
 181                                     const yaca_key_h key,
 182                                     const char *data,
 183                                     size_t data_len,
 184                                     char **signature,
 185                                     size_t *signature_len);
 186
 187 /**
 188  * @brief  Verify a signature using asymmetric public key.
 189  *
 190  * @since_tizen 3.0
 191  *
 192  * @param[in]  algo           Digest algorithm that will be used
 193  * @param[in]  key            Public key that will be used, algorithm is
 194  *                            deduced based on key type, supported key types:
 195  *                            - #YACA_KEY_TYPE_RSA_PUB,
 196  *                            - #YACA_KEY_TYPE_DSA_PUB,
 197  * @param[in]  data           Signed data
 198  * @param[in]  data_len       Length of the data
 199  * @param[in]  signature      Message signature
 200  * @param[in]  signature_len  Length of the signature
 201  *
 202  * @return #YACA_ERROR_NONE on success, negative on error
 203  * @retval #YACA_ERROR_NONE Successful
 204  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
 205  *                                       invalid algo or key)
 206  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 207  * @retval #YACA_ERROR_INTERNAL Internal error
 208  * @retval #YACA_ERROR_DATA_MISMATCH The verification failed
 209  *
 210  * @see #yaca_key_type_e
 211  * @see #yaca_digest_algorithm_e
 212  * @see yaca_simple_calculate_signature()
 213  */
 214 int yaca_simple_verify_signature(yaca_digest_algorithm_e algo,
 215                                  const yaca_key_h key,
 216                                  const char *data,
 217                                  size_t data_len,
 218                                  const char *signature,
 219                                  size_t signature_len);
 220
 221 /**
 222  * @brief  Calculate a HMAC of given message using symmetric key.
 223  *
 224  * @since_tizen 3.0
 225  *
 226  * @remarks  For verification, calculate message HMAC and compare with received MAC using
 227  *           yaca_memcmp().
 228  *
 229  * @remarks  The @a mac should be freed using yaca_free()
 230  *
 231  * @param[in]  algo      Digest algorithm that will be used
 232  * @param[in]  key       Key that will be used, supported key types:
 233  *                       - #YACA_KEY_TYPE_SYMMETRIC,
 234  *                       - #YACA_KEY_TYPE_DES
 235  * @param[in]  data      Data to calculate HMAC from
 236  * @param[in]  data_len  Length of the data
 237  * @param[out] mac       MAC, will be allocated by the library
 238  * @param[out] mac_len   Length of the MAC
 239  *
 240  * @return #YACA_ERROR_NONE on success, negative on error
 241  * @retval #YACA_ERROR_NONE Successful
 242  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
 243  *                                       invalid algo or key)
 244  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 245  * @retval #YACA_ERROR_INTERNAL Internal error
 246  *
 247  * @see #yaca_key_type_e
 248  * @see #yaca_digest_algorithm_e
 249  * @see yaca_memcmp()
 250  * @see yaca_free()
 251  */
 252 int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo,
 253                                const yaca_key_h key,
 254                                const char *data,
 255                                size_t data_len,
 256                                char **mac,
 257                                size_t *mac_len);
 258
 259 /**
 260  * @brief  Calculate a CMAC of given message using symmetric key.
 261  *
 262  * @since_tizen 3.0
 263  *
 264  * @remarks  For verification, calculate message CMAC and compare with received MAC using
 265  *           yaca_memcmp().
 266  *
 267  * @remarks  The @a mac should be freed using yaca_free()
 268  *
 269  * @param[in]  algo      Encryption algorithm that will be used
 270  * @param[in]  key       Key that will be used, supported key types:
 271  *                       - #YACA_KEY_TYPE_SYMMETRIC,
 272  *                       - #YACA_KEY_TYPE_DES
 273  * @param[in]  data      Data to calculate CMAC from
 274  * @param[in]  data_len  Length of the data
 275  * @param[out] mac       MAC, will be allocated by the library
 276  * @param[out] mac_len   Length of the MAC
 277  *
 278  * @return #YACA_ERROR_NONE on success, negative on error
 279  * @retval #YACA_ERROR_NONE Successful
 280  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0
 281  *                                       invalid algo or key)
 282  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 283  * @retval #YACA_ERROR_INTERNAL Internal error
 284  *
 285  * @see #yaca_key_type_e
 286  * @see #yaca_encrypt_algorithm_e
 287  * @see yaca_memcmp()
 288  * @see yaca_free()
 289  */
 290 int yaca_simple_calculate_cmac(yaca_encrypt_algorithm_e algo,
 291                                const yaca_key_h key,
 292                                const char *data,
 293                                size_t data_len,
 294                                char **mac,
 295                                size_t *mac_len);
 296
 297 /**@}*/
 298
 299 #ifdef __cplusplus
 300 } /* extern */
 301 #endif
 302
 303 #endif /* YACA_SIMPLE_H */