api/yaca/yaca_crypto.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_crypto.h
  21  * @brief
  22  */
  23
  24 #ifndef YACA_CRYPTO_H
  25 #define YACA_CRYPTO_H
  26
  27 #include <stddef.h>
  28 #include <yaca_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @defgroup  Non-Crypto  Yet Another Crypto API - non crypto related functions.
  36  *
  37  *
  38  * @{
  39  */
  40
  41 /**
  42  * @brief  NULL value for the crypto context.
  43  *
  44  * @since_tizen 3.0
  45  */
  46 #define YACA_CONTEXT_NULL ((yaca_context_h) NULL)
  47
  48 /**
  49  * @brief  Initializes the library. Must be called before any other crypto
  50  *         function. Should be called once in each thread that uses yaca.
  51  *
  52  * @since_tizen 3.0
  53  *
  54  * @return #YACA_ERROR_NONE on success, negative on error
  55  * @retval #YACA_ERROR_NONE Successful
  56  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  57  * @retval #YACA_ERROR_INTERNAL Internal error
  58  *
  59  * @see yaca_cleanup()
  60  */
  61 int yaca_initialize(void);
  62
  63 /**
  64  * @brief  Cleans up the library. Must be called before exiting the thread that
  65  *         called yaca_initialize().
  66  *
  67  * @since_tizen 3.0
  68  *
  69  * @return #YACA_ERROR_NONE on success
  70  * @retval #YACA_ERROR_NONE Successful
  71  *
  72  * @see yaca_initialize()
  73  */
  74 int yaca_cleanup(void);
  75
  76 /**
  77  * @brief  Allocates the memory.
  78  *
  79  * @since_tizen 3.0
  80  *
  81  * @remarks  The @a memory should be freed using yaca_free()
  82  *
  83  * @param[in]  size   Size of the allocation (bytes)
  84  * @param[out] memory Allocated memory
  85  *
  86  * @return #YACA_ERROR_NONE on success, negative on error
  87  * @retval #YACA_ERROR_NONE Successful
  88  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0)
  89  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
  90  *
  91  * @see yaca_zalloc()
  92  * @see yaca_realloc()
  93  * @see yaca_free()
  94  */
  95 int yaca_malloc(size_t size, void **memory);
  96
  97 /**
  98  * @brief  Allocates the zeroed memory.
  99  *
 100  * @since_tizen 3.0
 101  *
 102  * @remarks  The @a memory should be freed using yaca_free()
 103  *
 104  * @param[in]  size    Size of the allocation (bytes)
 105  * @param[out] memory  Allocated memory
 106  *
 107  * @return #YACA_ERROR_NONE on success, negative on error
 108  * @retval #YACA_ERROR_NONE Successful
 109  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0)
 110  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 111  *
 112  * @see yaca_malloc()
 113  * @see yaca_realloc()
 114  * @see yaca_free()
 115  */
 116 int yaca_zalloc(size_t size, void **memory);
 117
 118 /**
 119  * @brief  Re-allocates the memory.
 120  *
 121  * @since_tizen 3.0
 122  *
 123  * @remarks  In case of failure the function doesn't free the memory pointed by @a memory.
 124  *
 125  * @remarks  If @a *memory is NULL then the call is equivalent to yaca_malloc().
 126  *
 127  * @remarks  If the function fails the contents of @a memory will be left unchanged.
 128  *
 129  * @remarks  The @a memory should be freed using yaca_free()
 130  *
 131  * @param[in]     size    Size of the new allocation (bytes)
 132  * @param[in,out] memory  Memory to be reallocated
 133  *
 134  * @return #YACA_ERROR_NONE on success, negative on error
 135  * @retval #YACA_ERROR_NONE Successful
 136  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0)
 137  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 138  *
 139  * @see yaca_malloc()
 140  * @see yaca_zalloc()
 141  * @see yaca_free()
 142  */
 143 int yaca_realloc(size_t size, void **memory);
 144
 145 /**
 146  * @brief  Frees the memory allocated by yaca_malloc(), yaca_zalloc(),
 147  *         yaca_realloc() or one of the cryptographic operations.
 148  *
 149  * @since_tizen 3.0
 150  *
 151  * @param[in] memory  Pointer to the memory to be freed
 152  *
 153  * @return #YACA_ERROR_NONE on success
 154  * @retval #YACA_ERROR_NONE Successful
 155  *
 156  * @see yaca_malloc()
 157  * @see yaca_zalloc()
 158  * @see yaca_realloc()
 159  */
 160 int yaca_free(void *memory);
 161
 162 /**
 163  * @brief  Safely compares first @a len bytes of two buffers.
 164  *
 165  * @since_tizen 3.0
 166  *
 167  * @param[in]  first  Pointer to the first buffer
 168  * @param[in]  second Pointer to the second buffer
 169  * @param[in]  len    Length to compare
 170  *
 171  * @return #YACA_ERROR_NONE when buffers are equal otherwise #YACA_ERROR_DATA_MISMATCH
 172  * @retval #YACA_ERROR_NONE Successful
 173  * @retval #YACA_ERROR_DATA_MISMATCH Buffers are different
 174  */
 175 int yaca_memcmp(const void *first, const void *second, size_t len);
 176
 177 /**
 178  * @brief  Generates random data.
 179  *
 180  * @since_tizen 3.0
 181  *
 182  * @param[in,out] data      Pointer to the memory to be randomized
 183  * @param[in]     data_len  Length of the memory to be randomized
 184  *
 185  * @return #YACA_ERROR_NONE on success, negative on error
 186  * @retval #YACA_ERROR_NONE Successful
 187  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0)
 188  * @retval #YACA_ERROR_INTERNAL Internal error
 189  */
 190 int yaca_randomize_bytes(char *data, size_t data_len);
 191
 192 /**
 193  * @brief  Sets the non-standard context properties. Can only be called on an
 194  *         initialized context.
 195  *
 196  * @since_tizen 3.0
 197  *
 198  * @param[in,out] ctx        Previously initialized crypto context
 199  * @param[in]     property   Property to be set
 200  * @param[in]     value      Property value
 201  * @param[in]     value_len  Length of the property value
 202  *
 203  * @return #YACA_ERROR_NONE on success, negative on error
 204  * @retval #YACA_ERROR_NONE Successful
 205  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 206  *                                       invalid ctx or property)
 207  * @retval #YACA_ERROR_INTERNAL Internal error
 208  *
 209  * @see #yaca_property_e
 210  * @see yaca_context_get_property()
 211  */
 212 int yaca_context_set_property(yaca_context_h ctx,
 213                               yaca_property_e property,
 214                               const void *value,
 215                               size_t value_len);
 216
 217 /**
 218  * @brief  Returns the non-standard context properties. Can only be called on an
 219  *         initialized context.
 220  *
 221  * @since_tizen 3.0
 222  *
 223  * @remarks  The @a value should be freed using yaca_free()
 224  *
 225  * @param[in]  ctx        Previously initialized crypto context
 226  * @param[in]  property   Property to be read
 227  * @param[out] value      Copy of the property value
 228  * @param[out] value_len  Length of the property value will be returned here
 229  *
 230  * @return #YACA_ERROR_NONE on success, negative on error
 231  * @retval #YACA_ERROR_NONE Successful
 232  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 233  *                                       invalid ctx or property)
 234  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 235  * @retval #YACA_ERROR_INTERNAL Internal error
 236  *
 237  * @see #yaca_property_e
 238  * @see yaca_context_set_property()
 239  * @see yaca_free()
 240  */
 241 int yaca_context_get_property(const yaca_context_h ctx,
 242                               yaca_property_e property,
 243                               void **value,
 244                               size_t *value_len);
 245
 246 /**
 247  * @brief  Destroys the crypto context. Must be called on all contexts that are
 248  *         no longer used. Passing #YACA_CONTEXT_NULL is allowed.
 249  *
 250  * @since_tizen 3.0
 251  *
 252  * @param[in,out] ctx  Crypto context
 253  *
 254  * @return #YACA_ERROR_NONE on success
 255  * @retval #YACA_ERROR_NONE Successful
 256  *
 257  * @see #yaca_context_h
 258  *
 259  */
 260 int yaca_context_destroy(yaca_context_h ctx);
 261
 262 /**
 263  * @brief  Returns the output length for a given algorithm. Can only be called
 264  *         on an initialized context.
 265  *
 266  * @since_tizen 3.0
 267  *
 268  * @remarks  This function can be used to learn the required size of the output buffer
 269  *           for a single operation (eg. *_update or *_finalize). In case the operation
 270  *           has no input (eg. *_finalize), the value of @a input_len has to be set to 0.
 271  *
 272  * @param[in]  ctx         Previously initialized crypto context
 273  * @param[in]  input_len   Length of the input data to be processed
 274  * @param[out] output_len  Required length of the output
 275  *
 276  * @return #YACA_ERROR_NONE on success, negative on error
 277  * @retval #YACA_ERROR_NONE Successful
 278  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 279  *                                       invalid context or too big input_len)
 280  * @retval #YACA_ERROR_INTERNAL Internal error
 281  */
 282 int yaca_context_get_output_length(const yaca_context_h ctx,
 283                                    size_t input_len,
 284                                    size_t *output_len);
 285
 286 /**@}*/
 287
 288 #ifdef __cplusplus
 289 } /* extern */
 290 #endif
 291
 292 #endif /* YACA_CRYPTO_H */