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