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