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