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