2 * Secure Remote Password 6a implementation
3 * https://github.com/est31/csrp-gmp
5 * The MIT License (MIT)
7 * Copyright (c) 2010, 2013 Tom Cocagne, 2015 est31 <MTest31@outlook.com>
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:
16 * The above copyright notice and this permission notice shall be included in all
17 * copies or substantial portions of the Software.
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
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
35 * Author: tom.cocagne@gmail.com (Tom Cocagne)
37 * Dependencies: LibGMP
39 * Usage: Refer to test_srp.c for a demonstration
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.
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.
84 /* Sets the memory functions used by srp.
85 * Note: this doesn't set the memory functions used by gmp,
86 * but it is supported to have different functions for srp and gmp.
87 * Don't call this after you have already allocated srp structures.
89 void srp_set_memory_functions(
90 void *(*new_srp_alloc
) (size_t),
91 void *(*new_srp_realloc
) (void *, size_t),
92 void (*new_srp_free
) (void *));
94 /* Out: bytes_v, len_v
96 * The caller is responsible for freeing the memory allocated for bytes_v
98 * The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type.
99 * If provided, they must contain ASCII text of the hexidecimal notation.
101 * If bytes_s == NULL, it is filled with random data.
102 * The caller is responsible for freeing.
104 * Returns SRP_OK on success, and SRP_ERR on error.
105 * bytes_s might be in this case invalid, don't free it.
107 SRP_Result
srp_create_salted_verification_key(SRP_HashAlgorithm alg
,
108 SRP_NGType ng_type
, const char *username_for_verifier
,
109 const unsigned char *password
, size_t len_password
,
110 unsigned char **bytes_s
, size_t *len_s
,
111 unsigned char **bytes_v
, size_t *len_v
,
112 const char *n_hex
, const char *g_hex
);
114 /* Out: bytes_B, len_B.
116 * On failure, bytes_B will be set to NULL and len_B will be set to 0
118 * The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type
120 * If bytes_b == NULL, random data is used for b.
122 * Returns pointer to SRPVerifier on success, and NULL on error.
124 struct SRPVerifier
* srp_verifier_new(SRP_HashAlgorithm alg
, SRP_NGType ng_type
,
125 const char *username
,
126 const unsigned char *bytes_s
, size_t len_s
,
127 const unsigned char *bytes_v
, size_t len_v
,
128 const unsigned char *bytes_A
, size_t len_A
,
129 const unsigned char *bytes_b
, size_t len_b
,
130 unsigned char** bytes_B
, size_t *len_B
,
131 const char* n_hex
, const char* g_hex
);
135 void srp_verifier_delete(struct SRPVerifier
*ver
);
137 // srp_verifier_verify_session must have been called before
138 int srp_verifier_is_authenticated(struct SRPVerifier
*ver
);
140 const char *srp_verifier_get_username(struct SRPVerifier
*ver
);
142 /* key_length may be null */
143 const unsigned char *srp_verifier_get_session_key(
144 struct SRPVerifier
*ver
, size_t *key_length
);
146 size_t srp_verifier_get_session_key_length(struct SRPVerifier
*ver
);
148 /* Verifies session, on success, it writes bytes_HAMK.
149 * user_M must be exactly srp_verifier_get_session_key_length() bytes in size
151 void srp_verifier_verify_session(
152 struct SRPVerifier
*ver
, const unsigned char *user_M
, unsigned char **bytes_HAMK
);
154 /*******************************************************************************/
156 /* The n_hex and g_hex parameters should be 0 unless SRP_NG_CUSTOM is used for ng_type */
157 struct SRPUser
*srp_user_new(SRP_HashAlgorithm alg
, SRP_NGType ng_type
,
158 const char *username
, const char *username_for_verifier
,
159 const unsigned char *bytes_password
, size_t len_password
, const char *n_hex
,
162 void srp_user_delete(struct SRPUser
*usr
);
164 int srp_user_is_authenticated(struct SRPUser
*usr
);
166 const char *srp_user_get_username(struct SRPUser
*usr
);
168 /* key_length may be null */
169 const unsigned char *srp_user_get_session_key(struct SRPUser
*usr
, size_t *key_length
);
171 size_t srp_user_get_session_key_length(struct SRPUser
*usr
);
175 /* Output: username, bytes_A, len_A.
176 * If you don't want it get written, set username to NULL.
177 * If bytes_a == NULL, random data is used for a. */
178 SRP_Result
srp_user_start_authentication(struct SRPUser
* usr
, char **username
,
179 const unsigned char *bytes_a
, size_t len_a
,
180 unsigned char **bytes_A
, size_t* len_A
);
182 /* Output: bytes_M, len_M (len_M may be null and will always be
183 * srp_user_get_session_key_length() bytes in size) */
184 void srp_user_process_challenge(struct SRPUser
*usr
,
185 const unsigned char *bytes_s
, size_t len_s
,
186 const unsigned char *bytes_B
, size_t len_B
,
187 unsigned char **bytes_M
, size_t *len_M
);
190 /* bytes_HAMK must be exactly srp_user_get_session_key_length() bytes in size */
191 void srp_user_verify_session(struct SRPUser
*usr
, const unsigned char *bytes_HAMK
);