api/yaca/yaca_sign.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_sign.h
  21  * @brief  Advanced API for the integrity handling - HMAC, CMAC and digital signature.
  22  */
  23
  24 #ifndef YACA_SIGN_H
  25 #define YACA_SIGN_H
  26
  27 #include <stddef.h>
  28 #include <yaca_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @addtogroup CAPI_YACA_INTEGRITY_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief  Initializes a signature context for asymmetric signatures.
  41  *
  42  * @since_tizen 3.0
  43  *
  44  * @remarks  For verification use yaca_verify_initialize(), yaca_verify_update() and
  45  *           yaca_verify_finalize() functions with matching public key.
  46  *
  47  * @remarks  For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be
  48  *           changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING.
  49  *
  50  * @remarks  The @a ctx should be released using yaca_context_destroy()
  51  *
  52  * @param[out] ctx      Newly created context
  53  * @param[in]  algo     Digest algorithm that will be used
  54  * @param[in]  prv_key  Private key that will be used, algorithm is deduced based
  55  *                      on key type, supported key types:
  56  *                      - #YACA_KEY_TYPE_RSA_PRIV,
  57  *                      - #YACA_KEY_TYPE_DSA_PRIV,
  58  *                      - #YACA_KEY_TYPE_EC_PRIV
  59  *
  60  * @return #YACA_ERROR_NONE on success, negative on error
  61  * @retval #YACA_ERROR_NONE Successful
  62  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
  63  *                                       invalid algo or key)
  64  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  65  * @retval #YACA_ERROR_INTERNAL Internal error
  66  *
  67  * @see #yaca_key_type_e
  68  * @see #yaca_digest_algorithm_e
  69  * @see #yaca_padding_e
  70  * @see yaca_context_set_property()
  71  * @see yaca_sign_update()
  72  * @see yaca_sign_finalize()
  73  * @see yaca_verify_initialize()
  74  * @see yaca_verify_update()
  75  * @see yaca_verify_finalize()
  76  * @see yaca_context_destroy()
  77  */
  78 int yaca_sign_initialize(yaca_context_h *ctx,
  79                          yaca_digest_algorithm_e algo,
  80                          const yaca_key_h prv_key);
  81
  82 /**
  83  * @brief  Initializes a signature context for HMAC.
  84  *
  85  * @since_tizen 3.0
  86  *
  87  * @remarks  For verification, calculate message HMAC and compare with received MAC using
  88  *           yaca_memcmp().
  89  *
  90  * @remarks  The @a ctx should be released using yaca_context_destroy()
  91  *
  92  * @param[out] ctx      Newly created context
  93  * @param[in]  algo     Digest algorithm that will be used
  94  * @param[in]  sym_key  Symmetric key that will be used, supported key types:
  95  *                      - #YACA_KEY_TYPE_SYMMETRIC,
  96  *                      - #YACA_KEY_TYPE_DES
  97  *
  98  * @return #YACA_ERROR_NONE on success, negative on error
  99  * @retval #YACA_ERROR_NONE Successful
 100  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 101  *                                       invalid algo or key)
 102  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 103  * @retval #YACA_ERROR_INTERNAL Internal error
 104  *
 105  * @see #yaca_key_type_e
 106  * @see #yaca_digest_algorithm_e
 107  * @see yaca_sign_update()
 108  * @see yaca_sign_finalize()
 109  * @see yaca_memcmp()
 110  * @see yaca_context_destroy()
 111  */
 112 int yaca_sign_initialize_hmac(yaca_context_h *ctx,
 113                               yaca_digest_algorithm_e algo,
 114                               const yaca_key_h sym_key);
 115
 116 /**
 117  * @brief  Initializes a signature context for CMAC.
 118  *
 119  * @since_tizen 3.0
 120  *
 121  * @remarks  For verification, calculate message CMAC and compare with received MAC using
 122  *           yaca_memcmp().
 123  *
 124  * @remarks  The @a ctx should be released using yaca_context_destroy()
 125  *
 126  * @param[out] ctx      Newly created context
 127  * @param[in]  algo     Encryption algorithm that will be used
 128  * @param[in]  sym_key  Symmetric key that will be used, supported key types:
 129  *                      - #YACA_KEY_TYPE_SYMMETRIC,
 130  *                      - #YACA_KEY_TYPE_DES
 131  *
 132  * @return #YACA_ERROR_NONE on success, negative on error
 133  * @retval #YACA_ERROR_NONE Successful
 134  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 135  *                                       invalid algo or key)
 136  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 137  * @retval #YACA_ERROR_INTERNAL Internal error
 138  *
 139  * @see #yaca_key_type_e
 140  * @see #yaca_encrypt_algorithm_e
 141  * @see yaca_sign_update()
 142  * @see yaca_sign_finalize()
 143  * @see yaca_memcmp()
 144  * @see yaca_context_destroy()
 145  */
 146 int yaca_sign_initialize_cmac(yaca_context_h *ctx,
 147                               yaca_encrypt_algorithm_e algo,
 148                               const yaca_key_h sym_key);
 149
 150 /**
 151  * @brief  Feeds the message into the digital signature or MAC algorithm.
 152  *
 153  * @since_tizen 3.0
 154  *
 155  * @param[in,out] ctx          Context created by yaca_sign_initialize(),
 156  *                             yaca_sign_initialize_hmac() or yaca_sign_initialize_cmac()
 157  * @param[in]     message      Message to be signed
 158  * @param[in]     message_len  Length of the message
 159  *
 160  * @return #YACA_ERROR_NONE on success, negative on error
 161  * @retval #YACA_ERROR_NONE Successful
 162  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 163  *                                       invalid context)
 164  * @retval #YACA_ERROR_INTERNAL Internal error
 165  *
 166  * @see yaca_sign_initialize()
 167  * @see yaca_sign_finalize()
 168  * @see yaca_sign_initialize_hmac()
 169  * @see yaca_sign_initialize_cmac()
 170  */
 171 int yaca_sign_update(yaca_context_h ctx,
 172                      const char *message,
 173                      size_t message_len);
 174
 175 /**
 176  * @brief  Calculates the final signature or MAC.
 177  *
 178  * @since_tizen 3.0
 179  *
 180  * @remarks  Skipping yaca_sign_update() and calling only yaca_sign_finalize() will produce a
 181  *           signature or MAC of an empty message.
 182  *
 183  * @param[in,out] ctx              A valid sign context
 184  * @param[out]    signature        Buffer for the MAC or the message signature
 185  *                                 (must be allocated by client, see yaca_context_get_output_length())
 186  * @param[out]    signature_len    Length of the MAC or the signature,
 187  *                                 actual number of bytes written will be returned here
 188  *
 189  * @return #YACA_ERROR_NONE on success, negative on error
 190  * @retval #YACA_ERROR_NONE Successful
 191  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 192  *                                       invalid context)
 193  * @retval #YACA_ERROR_INTERNAL Internal error
 194  *
 195  * @see yaca_sign_initialize()
 196  * @see yaca_sign_update()
 197  * @see yaca_sign_initialize_hmac()
 198  * @see yaca_sign_initialize_cmac()
 199  * @see yaca_context_get_output_length()
 200  */
 201 int yaca_sign_finalize(yaca_context_h ctx,
 202                        char *signature,
 203                        size_t *signature_len);
 204
 205 /**
 206  * @brief  Initializes a signature verification context for asymmetric signatures
 207  *
 208  * @since_tizen 3.0
 209  *
 210  * @remarks  For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be
 211  *           changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING.
 212  *           For verify to succeed it has to be set to the same value it was signed with.
 213  *
 214  * @remarks  The @a ctx should be released using yaca_context_destroy()
 215  *
 216  * @param[out] ctx      Newly created context
 217  * @param[in]  algo     Digest algorithm that will be used
 218  * @param[in]  pub_key  Public key that will be used, algorithm is deduced based on
 219  *                      key type, supported key types:
 220  *                      - #YACA_KEY_TYPE_RSA_PUB,
 221  *                      - #YACA_KEY_TYPE_DSA_PUB,
 222  *                      - #YACA_KEY_TYPE_EC_PUB
 223  *
 224  * @return #YACA_ERROR_NONE on success, negative on error
 225  * @retval #YACA_ERROR_NONE Successful
 226  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 227  *                                       invalid algo or key)
 228  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 229  * @retval #YACA_ERROR_INTERNAL Internal error
 230  *
 231  * @see #yaca_key_type_e
 232  * @see #yaca_digest_algorithm_e
 233  * @see #yaca_padding_e
 234  * @see yaca_context_set_property()
 235  * @see yaca_verify_update()
 236  * @see yaca_verify_finalize()
 237  * @see yaca_context_destroy()
 238  */
 239 int yaca_verify_initialize(yaca_context_h *ctx,
 240                            yaca_digest_algorithm_e algo,
 241                            const yaca_key_h pub_key);
 242
 243 /**
 244  * @brief  Feeds the message into the digital signature verification algorithm.
 245  *
 246  * @since_tizen 3.0
 247  *
 248  * @param[in,out] ctx          Context created by yaca_verify_initialize()
 249  * @param[in]     message      Message
 250  * @param[in]     message_len  Length of the message
 251  *
 252  * @return #YACA_ERROR_NONE on success, negative on error
 253  * @retval #YACA_ERROR_NONE Successful
 254  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 255  *                                       invalid context)
 256  * @retval #YACA_ERROR_INTERNAL Internal error
 257  *
 258  * @see yaca_verify_initialize()
 259  * @see yaca_verify_finalize()
 260  */
 261 int yaca_verify_update(yaca_context_h ctx,
 262                        const char *message,
 263                        size_t message_len);
 264
 265 /**
 266  * @brief  Performs the verification.
 267  *
 268  * @since_tizen 3.0
 269  *
 270  * @remarks  Skipping yaca_verify_update() and calling only yaca_verify_finalize() will verify
 271  *           the signature of an empty message.
 272  *
 273  * @param[in,out] ctx            A valid verify context
 274  * @param[in]     signature      Message signature to be verified
 275  * @param[in]     signature_len  Length of the signature
 276  *
 277  * @return #YACA_ERROR_NONE on success, negative on error
 278  * @retval #YACA_ERROR_NONE Successful
 279  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 280  *                                       invalid context)
 281  * @retval #YACA_ERROR_INTERNAL Internal error
 282  * @retval #YACA_ERROR_DATA_MISMATCH The verification failed
 283  *
 284  * @see yaca_verify_initialize()
 285  * @see yaca_verify_update()
 286  * @see yaca_sign_finalize()
 287  */
 288 int yaca_verify_finalize(yaca_context_h ctx,
 289                          const char *signature,
 290                          size_t signature_len);
 291
 292 /**
 293   * @}
 294   */
 295
 296 #ifdef __cplusplus
 297 } /* extern */
 298 #endif
 299
 300 #endif /* YACA_SIGN_H */