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  * @see yaca_malloc()
 154  * @see yaca_zalloc()
 155  * @see yaca_realloc()
 156  */
 157 void yaca_free(void *memory);
 158
 159 /**
 160  * @brief  Safely compares first @a len bytes of two buffers.
 161  *
 162  * @since_tizen 3.0
 163  *
 164  * @param[in]  first  Pointer to the first buffer
 165  * @param[in]  second Pointer to the second buffer
 166  * @param[in]  len    Length to compare
 167  *
 168  * @return #YACA_ERROR_NONE when buffers are equal otherwise #YACA_ERROR_DATA_MISMATCH
 169  * @retval #YACA_ERROR_NONE Successful
 170  * @retval #YACA_ERROR_DATA_MISMATCH Buffers are different
 171  */
 172 int yaca_memcmp(const void *first, const void *second, size_t len);
 173
 174 /**
 175  * @brief  Generates random data.
 176  *
 177  * @since_tizen 3.0
 178  *
 179  * @param[in,out] data      Pointer to the memory to be randomized
 180  * @param[in]     data_len  Length of the memory to be randomized
 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, 0)
 185  * @retval #YACA_ERROR_INTERNAL Internal error
 186  */
 187 int yaca_randomize_bytes(char *data, size_t data_len);
 188
 189 /**
 190  * @brief  Sets the non-standard context properties. Can only be called on an
 191  *         initialized context.
 192  *
 193  * @remarks  The @a value has to be of type appropriate for given property. See #yaca_property_e
 194  *           for details on corresponding types.
 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  * @remarks  The @a value has to be of type appropriate for given property. See #yaca_property_e
 226  *           for details on corresponding types.
 227  *
 228  * @remarks  @a value_len can be NULL if returned @a value is a single object (i.e. not an array/buffer)
 229  *
 230  * @param[in]  ctx        Previously initialized crypto context
 231  * @param[in]  property   Property to be read
 232  * @param[out] value      Copy of the property value
 233  * @param[out] value_len  Length of the property value will be returned here
 234  *
 235  * @return #YACA_ERROR_NONE on success, negative on error
 236  * @retval #YACA_ERROR_NONE Successful
 237  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 238  *                                       invalid ctx or property)
 239  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 240  * @retval #YACA_ERROR_INTERNAL Internal error
 241  *
 242  * @see #yaca_property_e
 243  * @see yaca_context_set_property()
 244  * @see yaca_free()
 245  */
 246 int yaca_context_get_property(const yaca_context_h ctx,
 247                               yaca_property_e property,
 248                               void **value,
 249                               size_t *value_len);
 250
 251 /**
 252  * @brief  Destroys the crypto context. Must be called on all contexts that are
 253  *         no longer used. Passing #YACA_CONTEXT_NULL is allowed.
 254  *
 255  * @since_tizen 3.0
 256  *
 257  * @param[in,out] ctx  Crypto context
 258  *
 259  * @see #yaca_context_h
 260  *
 261  */
 262 void yaca_context_destroy(yaca_context_h ctx);
 263
 264 /**
 265  * @brief  Returns the output length for a given algorithm. Can only be called
 266  *         on an initialized context.
 267  *
 268  * @since_tizen 3.0
 269  *
 270  * @remarks  This function can be used to learn the required size of the output buffer
 271  *           for a single operation (eg. *_update or *_finalize). In case the operation
 272  *           has no input (eg. *_finalize), the value of @a input_len has to be set to 0.
 273  *
 274  * @param[in]  ctx         Previously initialized crypto context
 275  * @param[in]  input_len   Length of the input data to be processed
 276  * @param[out] output_len  Required length of the output
 277  *
 278  * @return #YACA_ERROR_NONE on success, negative on error
 279  * @retval #YACA_ERROR_NONE Successful
 280  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
 281  *                                       invalid context or too big input_len)
 282  * @retval #YACA_ERROR_INTERNAL Internal error
 283  */
 284 int yaca_context_get_output_length(const yaca_context_h ctx,
 285                                    size_t input_len,
 286                                    size_t *output_len);
 287
 288 /**@}*/
 289
 290 #ifdef __cplusplus
 291 } /* extern */
 292 #endif
 293
 294 #endif /* YACA_CRYPTO_H */