tor

The Tor anonymity network
git clone https://git.dasho.dev/tor.git
Log | Files | Refs | README | LICENSE

equix.h (4618B)

      1 /* Copyright (c) 2020 tevador <tevador@gmail.com> */
      2 /* See LICENSE for licensing information */
      3 
      4 #ifndef EQUIX_H
      5 #define EQUIX_H
      6 
      7 #include <stdint.h>
      8 #include <stddef.h>
      9 
     10 /*
     11 * The solver will return at most this many solutions.
     12 */
     13 #define EQUIX_MAX_SOLS 8
     14 
     15 /*
     16 * The number of indices.
     17 */
     18 #define EQUIX_NUM_IDX 8
     19 
     20 /*
     21 * 16-bit index.
     22 */
     23 typedef uint16_t equix_idx;
     24 
     25 /*
     26 *  The solution.
     27 */
     28 typedef struct equix_solution {
     29    equix_idx idx[EQUIX_NUM_IDX];
     30 } equix_solution;
     31 
     32 /*
     33 * Extra informational flags returned by the solver
     34 */
     35 typedef enum equix_solution_flags {
     36    EQUIX_SOLVER_DID_USE_COMPILER = (1 << 0),
     37 } equix_solution_flags;
     38 
     39 /*
     40 * Fixed size buffer containing up to EQUIX_MAX_SOLS solutions.
     41 */
     42 typedef struct equix_solutions_buffer {
     43    unsigned count;
     44    equix_solution_flags flags;
     45    equix_solution sols[EQUIX_MAX_SOLS];
     46 } equix_solutions_buffer;
     47 
     48 /*
     49 * Result type for solve and verify operations
     50 */
     51 typedef enum equix_result {
     52    EQUIX_OK,               /* Solution is valid */
     53    EQUIX_FAIL_CHALLENGE,   /* The challenge is invalid (the internal hash
     54                               function doesn't pass validation). */
     55    EQUIX_FAIL_ORDER,       /* Indices are not in the correct order. */
     56    EQUIX_FAIL_PARTIAL_SUM, /* The partial sums of the hash values don't
     57                               have the required number of trailing zeroes. */
     58    EQUIX_FAIL_FINAL_SUM,   /* The hash values don't sum to zero. */
     59    EQUIX_FAIL_COMPILE,     /* Can't compile, and no fallback is enabled */
     60    EQUIX_FAIL_NO_SOLVER,   /* Solve requested on a context with no solver */
     61    EQUIX_FAIL_INTERNAL,    /* Internal error (bug) */
     62 } equix_result;
     63 
     64 /*
     65 * Opaque struct that holds the Equi-X context
     66 */
     67 typedef struct equix_ctx equix_ctx;
     68 
     69 /*
     70 * Flags for context creation
     71 */
     72 typedef enum equix_ctx_flags {
     73    EQUIX_CTX_VERIFY = 0,       /* Context for verification */
     74    EQUIX_CTX_SOLVE = 1,        /* Context for solving */
     75    EQUIX_CTX_MUST_COMPILE = 2, /* Must compile internal hash function */
     76    EQUIX_CTX_TRY_COMPILE = 4,  /* Compile if possible */
     77    EQUIX_CTX_HUGEPAGES = 8,    /* Allocate solver memory using HugePages */
     78 } equix_ctx_flags;
     79 
     80 #if defined(_WIN32) || defined(__CYGWIN__)
     81 #define EQUIX_WIN
     82 #endif
     83 
     84 /* Shared/static library definitions */
     85 #ifdef EQUIX_WIN
     86    #ifdef EQUIX_SHARED
     87        #define EQUIX_API __declspec(dllexport)
     88    #elif !defined(EQUIX_STATIC)
     89        #define EQUIX_API __declspec(dllimport)
     90    #else
     91        #define EQUIX_API
     92    #endif
     93    #define EQUIX_PRIVATE
     94 #else
     95    #ifdef EQUIX_SHARED
     96        #define EQUIX_API __attribute__ ((visibility ("default")))
     97    #else
     98        #define EQUIX_API __attribute__ ((visibility ("hidden")))
     99    #endif
    100    #define EQUIX_PRIVATE __attribute__ ((visibility ("hidden")))
    101 #endif
    102 
    103 #ifdef __cplusplus
    104 extern "C" {
    105 #endif
    106 
    107 /*
    108 * Allocate an Equi-X context.
    109 *
    110 * @param flags is the type of context to be created
    111 *
    112 * @return pointer to a newly created context. Returns NULL on memory
    113 *         allocation failure.
    114 */
    115 EQUIX_API equix_ctx* equix_alloc(equix_ctx_flags flags);
    116 
    117 /*
    118 * Free an Equi-X a context.
    119 *
    120 * @param ctx is a pointer to the context
    121 */
    122 EQUIX_API void equix_free(equix_ctx* ctx);
    123 
    124 /*
    125 * Find Equi-X solutions for the given challenge.
    126 *
    127 * @param ctx             pointer to an Equi-X context
    128 * @param challenge       pointer to the challenge data
    129 * @param challenge_size  size of the challenge
    130 * @param output          pointer to the output array where solutions will be
    131 *                        stored
    132 *
    133 * @return On success, returns EQUIX_OK and sets output->count to the number
    134 *         of solutions found, with the solutions themselves written to the
    135 *         output buffer. If the challenge is unusable, returns
    136 *         EQUIX_FAIL_CHALLENGE. If the EQUIX_CTX_MUST_COMPILE flag is in use
    137 *         and the compiler fails, this can return EQUIX_FAIL_COMPILE.
    138 */
    139 EQUIX_API equix_result equix_solve(
    140    equix_ctx* ctx,
    141    const void* challenge,
    142    size_t challenge_size,
    143    equix_solutions_buffer *output);
    144 
    145 /*
    146 * Verify an Equi-X solution.
    147 *
    148 * @param ctx             pointer to an Equi-X context
    149 * @param challenge       pointer to the challenge data
    150 * @param challenge_size  size of the challenge
    151 * @param solution        pointer to the solution to be verified
    152 *
    153 * @return Verification result. This can return EQUIX_OK or any of the
    154 *         EQUIX_FAIL_* error codes.
    155 */
    156 EQUIX_API equix_result equix_verify(
    157    equix_ctx* ctx,
    158    const void* challenge,
    159    size_t challenge_size,
    160    const equix_solution* solution);
    161 
    162 #ifdef __cplusplus
    163 }
    164 #endif
    165 
    166 #endif