src/util/srp.h

   1 /*
   2  * Secure Remote Password 6a implementation
   3  * https://github.com/est31/csrp-gmp
   4  *
   5  * The MIT License (MIT)
   6  *
   7  * Copyright (c) 2010, 2013 Tom Cocagne, 2015 est31 <MTest31@outlook.com>
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a copy of
  10  * this software and associated documentation files (the "Software"), to deal in
  11  * the Software without restriction, including without limitation the rights to
  12  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
  13  * of the Software, and to permit persons to whom the Software is furnished to do
  14  * so, subject to the following conditions:
  15  *
  16  * The above copyright notice and this permission notice shall be included in all
  17  * copies or substantial portions of the Software.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  22  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  23  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  24  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25  * SOFTWARE.
  26  *
  27  */
  28
  29 /*
  30  *
  31  * Purpose:       This is a direct implementation of the Secure Remote Password
  32  *                Protocol version 6a as described by
  33  *                http://srp.stanford.edu/design.html
  34  *
  35  * Author:        tom.cocagne@gmail.com (Tom Cocagne)
  36  *
  37  * Dependencies:  LibGMP
  38  *
  39  * Usage:         Refer to test_srp.c for a demonstration
  40  *
  41  * Notes:
  42  *    This library allows multiple combinations of hashing algorithms and
  43  *    prime number constants. For authentication to succeed, the hash and
  44  *    prime number constants must match between
  45  *    srp_create_salted_verification_key(), srp_user_new(),
  46  *    and srp_verifier_new(). A recommended approach is to determine the
  47  *    desired level of security for an application and globally define the
  48  *    hash and prime number constants to the predetermined values.
  49  *
  50  *    As one might suspect, more bits means more security. As one might also
  51  *    suspect, more bits also means more processing time. The test_srp.c
  52  *    program can be easily modified to profile various combinations of
  53  *    hash & prime number pairings.
  54  */
  55
  56 #ifndef SRP_H
  57 #define SRP_H
  58
  59 struct SRPVerifier;
  60 struct SRPUser;
  61
  62 typedef enum {
  63         SRP_NG_1024,
  64         SRP_NG_2048,
  65         SRP_NG_4096,
  66         SRP_NG_8192,
  67         SRP_NG_CUSTOM
  68 } SRP_NGType;
  69
  70 typedef enum {
  71         /*SRP_SHA1,*/
  72         /*SRP_SHA224,*/
  73         SRP_SHA256,
  74         /*SRP_SHA384,
  75         SRP_SHA512*/
  76 } SRP_HashAlgorithm;
  77
  78 typedef enum {
  79         SRP_ERR,
  80         SRP_OK,
  81 } SRP_Result;
  82
  83 // clang-format off
  84
  85 /* Sets the memory functions used by srp.
  86  * Note: this doesn't set the memory functions used by gmp,
  87  * but it is supported to have different functions for srp and gmp.
  88  * Don't call this after you have already allocated srp structures.
  89  */
  90 void srp_set_memory_functions(
  91         void *(*new_srp_alloc) (size_t),
  92         void *(*new_srp_realloc) (void *, size_t),
  93         void (*new_srp_free) (void *));
  94
  95 /* Out: bytes_v, len_v
  96  *
  97  * The caller is responsible for freeing the memory allocated for bytes_v
  98  *
  99  * The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type.
 100  * If provided, they must contain ASCII text of the hexidecimal notation.
 101  *
 102  * If bytes_s == NULL, it is filled with random data.
 103  * The caller is responsible for freeing.
 104  *
 105  * Returns SRP_OK on success, and SRP_ERR on error.
 106  * bytes_s might be in this case invalid, don't free it.
 107  */
 108 SRP_Result srp_create_salted_verification_key(SRP_HashAlgorithm alg,
 109         SRP_NGType ng_type, const char *username_for_verifier,
 110         const unsigned char *password, size_t len_password,
 111         unsigned char **bytes_s,  size_t *len_s,
 112         unsigned char **bytes_v, size_t *len_v,
 113         const char *n_hex, const char *g_hex);
 114
 115 /* Out: bytes_B, len_B.
 116  *
 117  * On failure, bytes_B will be set to NULL and len_B will be set to 0
 118  *
 119  * The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type
 120  *
 121  * If bytes_b == NULL, random data is used for b.
 122  *
 123  * Returns pointer to SRPVerifier on success, and NULL on error.
 124  */
 125 struct SRPVerifier* srp_verifier_new(SRP_HashAlgorithm alg, SRP_NGType ng_type,
 126         const char *username,
 127         const unsigned char *bytes_s, size_t len_s,
 128         const unsigned char *bytes_v, size_t len_v,
 129         const unsigned char *bytes_A, size_t len_A,
 130         const unsigned char *bytes_b, size_t len_b,
 131         unsigned char** bytes_B, size_t *len_B,
 132         const char* n_hex, const char* g_hex);
 133
 134 // clang-format on
 135
 136 void srp_verifier_delete(struct SRPVerifier *ver);
 137
 138 // srp_verifier_verify_session must have been called before
 139 int srp_verifier_is_authenticated(struct SRPVerifier *ver);
 140
 141 const char *srp_verifier_get_username(struct SRPVerifier *ver);
 142
 143 /* key_length may be null */
 144 const unsigned char *srp_verifier_get_session_key(
 145         struct SRPVerifier *ver, size_t *key_length);
 146
 147 size_t srp_verifier_get_session_key_length(struct SRPVerifier *ver);
 148
 149 /* Verifies session, on success, it writes bytes_HAMK.
 150  * user_M must be exactly srp_verifier_get_session_key_length() bytes in size
 151  */
 152 void srp_verifier_verify_session(
 153         struct SRPVerifier *ver, const unsigned char *user_M, unsigned char **bytes_HAMK);
 154
 155 /*******************************************************************************/
 156
 157 /* The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type */
 158 struct SRPUser *srp_user_new(SRP_HashAlgorithm alg, SRP_NGType ng_type,
 159         const char *username, const char *username_for_verifier,
 160         const unsigned char *bytes_password, size_t len_password, const char *n_hex,
 161         const char *g_hex);
 162
 163 void srp_user_delete(struct SRPUser *usr);
 164
 165 int srp_user_is_authenticated(struct SRPUser *usr);
 166
 167 const char *srp_user_get_username(struct SRPUser *usr);
 168
 169 /* key_length may be null */
 170 const unsigned char *srp_user_get_session_key(struct SRPUser *usr, size_t *key_length);
 171
 172 size_t srp_user_get_session_key_length(struct SRPUser *usr);
 173
 174 // clang-format off
 175
 176 /* Output: username, bytes_A, len_A.
 177  * If you don't want it get written, set username to NULL.
 178  * If bytes_a == NULL, random data is used for a. */
 179 SRP_Result srp_user_start_authentication(struct SRPUser* usr, char **username,
 180         const unsigned char *bytes_a, size_t len_a,
 181         unsigned char **bytes_A, size_t* len_A);
 182
 183 /* Output: bytes_M, len_M  (len_M may be null and will always be
 184  *                          srp_user_get_session_key_length() bytes in size) */
 185 void srp_user_process_challenge(struct SRPUser *usr,
 186         const unsigned char *bytes_s, size_t len_s,
 187         const unsigned char *bytes_B, size_t len_B,
 188         unsigned char **bytes_M, size_t *len_M);
 189 // clang-format on
 190
 191 /* bytes_HAMK must be exactly srp_user_get_session_key_length() bytes in size */
 192 void srp_user_verify_session(struct SRPUser *usr, const unsigned char *bytes_HAMK);
 193
 194 #endif /* Include Guard */