wolf SSL / wolfSSL

wolfSSL SSL/TLS library, support up to TLS1.3

Dependents:   CyaSSL-Twitter-OAuth4Tw Example-client-tls-cert TwitterReader TweetTest ... more

wolfssl/wolfcrypt/srp.h@13:f67a6c6013ca, 2017-08-22 (annotated)

Committer:
wolfSSL
Date:
Tue Aug 22 10:48:22 2017 +0000
Revision:
13:f67a6c6013ca
Parent:
11:cee25a834751 
wolfSSL3.12.0 with TLS1.3

Who changed what in which revision?

UserRevisionLine numberNew contents of line
wolfSSL 11:cee25a834751 1 /* srp.h
wolfSSL 11:cee25a834751 2 *
wolfSSL 11:cee25a834751 3 * Copyright (C) 2006-2016 wolfSSL Inc.
wolfSSL 11:cee25a834751 4 *
wolfSSL 11:cee25a834751 5 * This file is part of wolfSSL.
wolfSSL 11:cee25a834751 6 *
wolfSSL 11:cee25a834751 7 * wolfSSL is free software; you can redistribute it and/or modify
wolfSSL 11:cee25a834751 8 * it under the terms of the GNU General Public License as published by
wolfSSL 11:cee25a834751 9 * the Free Software Foundation; either version 2 of the License, or
wolfSSL 11:cee25a834751 10 * (at your option) any later version.
wolfSSL 11:cee25a834751 11 *
wolfSSL 11:cee25a834751 12 * wolfSSL is distributed in the hope that it will be useful,
wolfSSL 11:cee25a834751 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
wolfSSL 11:cee25a834751 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
wolfSSL 11:cee25a834751 15 * GNU General Public License for more details.
wolfSSL 11:cee25a834751 16 *
wolfSSL 11:cee25a834751 17 * You should have received a copy of the GNU General Public License
wolfSSL 11:cee25a834751 18 * along with this program; if not, write to the Free Software
wolfSSL 11:cee25a834751 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
wolfSSL 11:cee25a834751 20 */
wolfSSL 11:cee25a834751 21
wolfSSL 11:cee25a834751 22
wolfSSL 11:cee25a834751 23 #ifdef WOLFCRYPT_HAVE_SRP
wolfSSL 11:cee25a834751 24
wolfSSL 11:cee25a834751 25 #ifndef WOLFCRYPT_SRP_H
wolfSSL 11:cee25a834751 26 #define WOLFCRYPT_SRP_H
wolfSSL 11:cee25a834751 27
wolfSSL 11:cee25a834751 28 #include <wolfssl/wolfcrypt/types.h>
wolfSSL 11:cee25a834751 29 #include <wolfssl/wolfcrypt/sha.h>
wolfSSL 11:cee25a834751 30 #include <wolfssl/wolfcrypt/sha256.h>
wolfSSL 11:cee25a834751 31 #include <wolfssl/wolfcrypt/sha512.h>
wolfSSL 11:cee25a834751 32 #include <wolfssl/wolfcrypt/integer.h>
wolfSSL 11:cee25a834751 33
wolfSSL 11:cee25a834751 34 #ifdef __cplusplus
wolfSSL 11:cee25a834751 35 extern "C" {
wolfSSL 11:cee25a834751 36 #endif
wolfSSL 11:cee25a834751 37
wolfSSL 11:cee25a834751 38 /* Select the largest available hash for the buffer size. */
wolfSSL 11:cee25a834751 39 #if defined(WOLFSSL_SHA512)
wolfSSL 11:cee25a834751 40 #define SRP_MAX_DIGEST_SIZE SHA512_DIGEST_SIZE
wolfSSL 11:cee25a834751 41 #elif defined(WOLFSSL_SHA384)
wolfSSL 11:cee25a834751 42 #define SRP_MAX_DIGEST_SIZE SHA384_DIGEST_SIZE
wolfSSL 11:cee25a834751 43 #elif !defined(NO_SHA256)
wolfSSL 11:cee25a834751 44 #define SRP_MAX_DIGEST_SIZE SHA256_DIGEST_SIZE
wolfSSL 11:cee25a834751 45 #elif !defined(NO_SHA)
wolfSSL 11:cee25a834751 46 #define SRP_MAX_DIGEST_SIZE SHA_DIGEST_SIZE
wolfSSL 11:cee25a834751 47 #else
wolfSSL 11:cee25a834751 48 #error "You have to have some kind of SHA hash if you want to use SRP."
wolfSSL 11:cee25a834751 49 #endif
wolfSSL 11:cee25a834751 50
wolfSSL 11:cee25a834751 51 /* Set the minimum number of bits acceptable in an SRP modulus */
wolfSSL 11:cee25a834751 52 #define SRP_MODULUS_MIN_BITS 512
wolfSSL 11:cee25a834751 53
wolfSSL 11:cee25a834751 54 /* Set the minimum number of bits acceptable for private keys (RFC 5054) */
wolfSSL 11:cee25a834751 55 #define SRP_PRIVATE_KEY_MIN_BITS 256
wolfSSL 11:cee25a834751 56
wolfSSL 11:cee25a834751 57 /**
wolfSSL 11:cee25a834751 58 * SRP side, client or server.
wolfSSL 11:cee25a834751 59 */
wolfSSL 11:cee25a834751 60 typedef enum {
wolfSSL 11:cee25a834751 61 SRP_CLIENT_SIDE = 0,
wolfSSL 11:cee25a834751 62 SRP_SERVER_SIDE = 1,
wolfSSL 11:cee25a834751 63 } SrpSide;
wolfSSL 11:cee25a834751 64
wolfSSL 11:cee25a834751 65 /**
wolfSSL 11:cee25a834751 66 * SRP hash type, SHA[1|256|384|512].
wolfSSL 11:cee25a834751 67 */
wolfSSL 11:cee25a834751 68 typedef enum {
wolfSSL 11:cee25a834751 69 SRP_TYPE_SHA = 1,
wolfSSL 11:cee25a834751 70 SRP_TYPE_SHA256 = 2,
wolfSSL 11:cee25a834751 71 SRP_TYPE_SHA384 = 3,
wolfSSL 11:cee25a834751 72 SRP_TYPE_SHA512 = 4,
wolfSSL 11:cee25a834751 73 } SrpType;
wolfSSL 11:cee25a834751 74
wolfSSL 11:cee25a834751 75 /**
wolfSSL 11:cee25a834751 76 * SRP hash struct.
wolfSSL 11:cee25a834751 77 */
wolfSSL 11:cee25a834751 78 typedef struct {
wolfSSL 11:cee25a834751 79 byte type;
wolfSSL 11:cee25a834751 80 union {
wolfSSL 11:cee25a834751 81 #ifndef NO_SHA
wolfSSL 11:cee25a834751 82 Sha sha;
wolfSSL 11:cee25a834751 83 #endif
wolfSSL 11:cee25a834751 84 #ifndef NO_SHA256
wolfSSL 11:cee25a834751 85 Sha256 sha256;
wolfSSL 11:cee25a834751 86 #endif
wolfSSL 11:cee25a834751 87 #ifdef WOLFSSL_SHA384
wolfSSL 11:cee25a834751 88 Sha384 sha384;
wolfSSL 11:cee25a834751 89 #endif
wolfSSL 11:cee25a834751 90 #ifdef WOLFSSL_SHA512
wolfSSL 11:cee25a834751 91 Sha512 sha512;
wolfSSL 11:cee25a834751 92 #endif
wolfSSL 11:cee25a834751 93 } data;
wolfSSL 11:cee25a834751 94 } SrpHash;
wolfSSL 11:cee25a834751 95
wolfSSL 11:cee25a834751 96 typedef struct Srp {
wolfSSL 11:cee25a834751 97 SrpSide side; /**< Client or Server, @see SrpSide. */
wolfSSL 11:cee25a834751 98 SrpType type; /**< Hash type, @see SrpType. */
wolfSSL 11:cee25a834751 99 byte* user; /**< Username, login. */
wolfSSL 11:cee25a834751 100 word32 userSz; /**< Username length. */
wolfSSL 11:cee25a834751 101 byte* salt; /**< Small salt. */
wolfSSL 11:cee25a834751 102 word32 saltSz; /**< Salt length. */
wolfSSL 11:cee25a834751 103 mp_int N; /**< Modulus. N = 2q+1, [q, N] are primes.*/
wolfSSL 11:cee25a834751 104 mp_int g; /**< Generator. A generator modulo N. */
wolfSSL 11:cee25a834751 105 byte k[SRP_MAX_DIGEST_SIZE]; /**< Multiplier parameter. k = H(N, g) */
wolfSSL 11:cee25a834751 106 mp_int auth; /**< Client: x = H(salt + H(user:pswd)) */
wolfSSL 11:cee25a834751 107 /**< Server: v = g ^ x % N */
wolfSSL 11:cee25a834751 108 mp_int priv; /**< Private ephemeral value. */
wolfSSL 11:cee25a834751 109 SrpHash client_proof; /**< Client proof. Sent to the Server. */
wolfSSL 11:cee25a834751 110 SrpHash server_proof; /**< Server proof. Sent to the Client. */
wolfSSL 11:cee25a834751 111 byte* key; /**< Session key. */
wolfSSL 11:cee25a834751 112 word32 keySz; /**< Session key length. */
wolfSSL 11:cee25a834751 113 int (*keyGenFunc_cb) (struct Srp* srp, byte* secret, word32 size);
wolfSSL 11:cee25a834751 114 /**< Function responsible for generating the session key. */
wolfSSL 11:cee25a834751 115 /**< It MUST use XMALLOC with type DYNAMIC_TYPE_SRP to allocate the */
wolfSSL 11:cee25a834751 116 /**< key buffer for this structure and set keySz to the buffer size. */
wolfSSL 11:cee25a834751 117 /**< The default function used by this implementation is a modified */
wolfSSL 11:cee25a834751 118 /**< version of t_mgf1 that uses the proper hash function according */
wolfSSL 11:cee25a834751 119 /**< to srp->type. */
wolfSSL 11:cee25a834751 120 void* heap; /**< heap hint pointer */
wolfSSL 11:cee25a834751 121 } Srp;
wolfSSL 11:cee25a834751 122
wolfSSL 11:cee25a834751 123 /**
wolfSSL 11:cee25a834751 124 * Initializes the Srp struct for usage.
wolfSSL 11:cee25a834751 125 *
wolfSSL 11:cee25a834751 126 * @param[out] srp the Srp structure to be initialized.
wolfSSL 11:cee25a834751 127 * @param[in] type the hash type to be used.
wolfSSL 11:cee25a834751 128 * @param[in] side the side of the communication.
wolfSSL 11:cee25a834751 129 *
wolfSSL 11:cee25a834751 130 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 131 */
wolfSSL 11:cee25a834751 132 WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side);
wolfSSL 11:cee25a834751 133
wolfSSL 11:cee25a834751 134 /**
wolfSSL 11:cee25a834751 135 * Releases the Srp struct resources after usage.
wolfSSL 11:cee25a834751 136 *
wolfSSL 11:cee25a834751 137 * @param[in,out] srp the Srp structure to be terminated.
wolfSSL 11:cee25a834751 138 */
wolfSSL 11:cee25a834751 139 WOLFSSL_API void wc_SrpTerm(Srp* srp);
wolfSSL 11:cee25a834751 140
wolfSSL 11:cee25a834751 141 /**
wolfSSL 11:cee25a834751 142 * Sets the username.
wolfSSL 11:cee25a834751 143 *
wolfSSL 11:cee25a834751 144 * This function MUST be called after wc_SrpInit.
wolfSSL 11:cee25a834751 145 *
wolfSSL 11:cee25a834751 146 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 147 * @param[in] username the buffer containing the username.
wolfSSL 11:cee25a834751 148 * @param[in] size the username size in bytes
wolfSSL 11:cee25a834751 149 *
wolfSSL 11:cee25a834751 150 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 151 */
wolfSSL 11:cee25a834751 152 WOLFSSL_API int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size);
wolfSSL 11:cee25a834751 153
wolfSSL 11:cee25a834751 154
wolfSSL 11:cee25a834751 155 /**
wolfSSL 11:cee25a834751 156 * Sets the srp parameters based on the username.
wolfSSL 11:cee25a834751 157 *
wolfSSL 11:cee25a834751 158 * This function MUST be called after wc_SrpSetUsername.
wolfSSL 11:cee25a834751 159 *
wolfSSL 11:cee25a834751 160 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 161 * @param[in] N the Modulus. N = 2q+1, [q, N] are primes.
wolfSSL 11:cee25a834751 162 * @param[in] nSz the N size in bytes.
wolfSSL 11:cee25a834751 163 * @param[in] g the Generator modulo N.
wolfSSL 11:cee25a834751 164 * @param[in] gSz the g size in bytes
wolfSSL 11:cee25a834751 165 * @param[in] salt a small random salt. Specific for each username.
wolfSSL 11:cee25a834751 166 * @param[in] saltSz the salt size in bytes
wolfSSL 11:cee25a834751 167 *
wolfSSL 11:cee25a834751 168 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 169 */
wolfSSL 11:cee25a834751 170 WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz,
wolfSSL 11:cee25a834751 171 const byte* g, word32 gSz,
wolfSSL 11:cee25a834751 172 const byte* salt, word32 saltSz);
wolfSSL 11:cee25a834751 173
wolfSSL 11:cee25a834751 174 /**
wolfSSL 11:cee25a834751 175 * Sets the password.
wolfSSL 11:cee25a834751 176 *
wolfSSL 11:cee25a834751 177 * Setting the password does not persists the clear password data in the
wolfSSL 11:cee25a834751 178 * srp structure. The client calculates x = H(salt + H(user:pswd)) and stores
wolfSSL 11:cee25a834751 179 * it in the auth field.
wolfSSL 11:cee25a834751 180 *
wolfSSL 11:cee25a834751 181 * This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY.
wolfSSL 11:cee25a834751 182 *
wolfSSL 11:cee25a834751 183 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 184 * @param[in] password the buffer containing the password.
wolfSSL 11:cee25a834751 185 * @param[in] size the password size in bytes.
wolfSSL 11:cee25a834751 186 *
wolfSSL 11:cee25a834751 187 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 188 */
wolfSSL 11:cee25a834751 189 WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size);
wolfSSL 11:cee25a834751 190
wolfSSL 11:cee25a834751 191 /**
wolfSSL 11:cee25a834751 192 * Sets the verifier.
wolfSSL 11:cee25a834751 193 *
wolfSSL 11:cee25a834751 194 * This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY.
wolfSSL 11:cee25a834751 195 *
wolfSSL 11:cee25a834751 196 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 197 * @param[in] verifier the buffer containing the verifier.
wolfSSL 11:cee25a834751 198 * @param[in] size the verifier size in bytes.
wolfSSL 11:cee25a834751 199 *
wolfSSL 11:cee25a834751 200 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 201 */
wolfSSL 11:cee25a834751 202 WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size);
wolfSSL 11:cee25a834751 203
wolfSSL 11:cee25a834751 204 /**
wolfSSL 11:cee25a834751 205 * Gets the verifier.
wolfSSL 11:cee25a834751 206 *
wolfSSL 11:cee25a834751 207 * The client calculates the verifier with v = g ^ x % N.
wolfSSL 11:cee25a834751 208 * This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY.
wolfSSL 11:cee25a834751 209 *
wolfSSL 11:cee25a834751 210 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 211 * @param[out] verifier the buffer to write the verifier.
wolfSSL 11:cee25a834751 212 * @param[in,out] size the buffer size in bytes. Will be updated with the
wolfSSL 11:cee25a834751 213 * verifier size.
wolfSSL 11:cee25a834751 214 *
wolfSSL 11:cee25a834751 215 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 216 */
wolfSSL 11:cee25a834751 217 WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size);
wolfSSL 11:cee25a834751 218
wolfSSL 11:cee25a834751 219 /**
wolfSSL 11:cee25a834751 220 * Sets the private ephemeral value.
wolfSSL 11:cee25a834751 221 *
wolfSSL 11:cee25a834751 222 * The private ephemeral value is known as:
wolfSSL 11:cee25a834751 223 * a at the client side. a = random()
wolfSSL 11:cee25a834751 224 * b at the server side. b = random()
wolfSSL 11:cee25a834751 225 * This function is handy for unit test cases or if the developer wants to use
wolfSSL 11:cee25a834751 226 * an external random source to set the ephemeral value.
wolfSSL 11:cee25a834751 227 * This function MAY be called before wc_SrpGetPublic.
wolfSSL 11:cee25a834751 228 *
wolfSSL 11:cee25a834751 229 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 230 * @param[in] priv the ephemeral value.
wolfSSL 11:cee25a834751 231 * @param[in] size the private size in bytes.
wolfSSL 11:cee25a834751 232 *
wolfSSL 11:cee25a834751 233 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 234 */
wolfSSL 11:cee25a834751 235 WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size);
wolfSSL 11:cee25a834751 236
wolfSSL 11:cee25a834751 237 /**
wolfSSL 11:cee25a834751 238 * Gets the public ephemeral value.
wolfSSL 11:cee25a834751 239 *
wolfSSL 11:cee25a834751 240 * The public ephemeral value is known as:
wolfSSL 11:cee25a834751 241 * A at the client side. A = g ^ a % N
wolfSSL 11:cee25a834751 242 * B at the server side. B = (k * v + (g ˆ b % N)) % N
wolfSSL 11:cee25a834751 243 * This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier.
wolfSSL 11:cee25a834751 244 *
wolfSSL 11:cee25a834751 245 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 246 * @param[out] pub the buffer to write the public ephemeral value.
wolfSSL 11:cee25a834751 247 * @param[in,out] size the the buffer size in bytes. Will be updated with
wolfSSL 11:cee25a834751 248 * the ephemeral value size.
wolfSSL 11:cee25a834751 249 *
wolfSSL 11:cee25a834751 250 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 251 */
wolfSSL 11:cee25a834751 252 WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size);
wolfSSL 11:cee25a834751 253
wolfSSL 11:cee25a834751 254
wolfSSL 11:cee25a834751 255 /**
wolfSSL 11:cee25a834751 256 * Computes the session key.
wolfSSL 11:cee25a834751 257 *
wolfSSL 11:cee25a834751 258 * The key can be accessed at srp->key after success.
wolfSSL 11:cee25a834751 259 *
wolfSSL 11:cee25a834751 260 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 261 * @param[in] clientPubKey the client's public ephemeral value.
wolfSSL 11:cee25a834751 262 * @param[in] clientPubKeySz the client's public ephemeral value size.
wolfSSL 11:cee25a834751 263 * @param[in] serverPubKey the server's public ephemeral value.
wolfSSL 11:cee25a834751 264 * @param[in] serverPubKeySz the server's public ephemeral value size.
wolfSSL 11:cee25a834751 265 *
wolfSSL 11:cee25a834751 266 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 267 */
wolfSSL 11:cee25a834751 268 WOLFSSL_API int wc_SrpComputeKey(Srp* srp,
wolfSSL 11:cee25a834751 269 byte* clientPubKey, word32 clientPubKeySz,
wolfSSL 11:cee25a834751 270 byte* serverPubKey, word32 serverPubKeySz);
wolfSSL 11:cee25a834751 271
wolfSSL 11:cee25a834751 272 /**
wolfSSL 11:cee25a834751 273 * Gets the proof.
wolfSSL 11:cee25a834751 274 *
wolfSSL 11:cee25a834751 275 * This function MUST be called after wc_SrpComputeKey.
wolfSSL 11:cee25a834751 276 *
wolfSSL 11:cee25a834751 277 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 278 * @param[out] proof the buffer to write the proof.
wolfSSL 11:cee25a834751 279 * @param[in,out] size the buffer size in bytes. Will be updated with the
wolfSSL 11:cee25a834751 280 * proof size.
wolfSSL 11:cee25a834751 281 *
wolfSSL 11:cee25a834751 282 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 283 */
wolfSSL 11:cee25a834751 284 WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size);
wolfSSL 11:cee25a834751 285
wolfSSL 11:cee25a834751 286 /**
wolfSSL 11:cee25a834751 287 * Verifies the peers proof.
wolfSSL 11:cee25a834751 288 *
wolfSSL 11:cee25a834751 289 * This function MUST be called before wc_SrpGetSessionKey.
wolfSSL 11:cee25a834751 290 *
wolfSSL 11:cee25a834751 291 * @param[in,out] srp the Srp structure.
wolfSSL 11:cee25a834751 292 * @param[in] proof the peers proof.
wolfSSL 11:cee25a834751 293 * @param[in] size the proof size in bytes.
wolfSSL 11:cee25a834751 294 *
wolfSSL 11:cee25a834751 295 * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
wolfSSL 11:cee25a834751 296 */
wolfSSL 11:cee25a834751 297 WOLFSSL_API int wc_SrpVerifyPeersProof(Srp* srp, byte* proof, word32 size);
wolfSSL 11:cee25a834751 298
wolfSSL 11:cee25a834751 299 #ifdef __cplusplus
wolfSSL 11:cee25a834751 300 } /* extern "C" */
wolfSSL 11:cee25a834751 301 #endif
wolfSSL 11:cee25a834751 302
wolfSSL 11:cee25a834751 303 #endif /* WOLFCRYPT_SRP_H */
wolfSSL 11:cee25a834751 304 #endif /* WOLFCRYPT_HAVE_SRP */
wolfSSL 11:cee25a834751 305