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