srp.h

00001 /* srp.h
00002  *
00003  * Copyright (C) 2006-2016 wolfSSL Inc.
00004  *
00005  * This file is part of wolfSSL.
00006  *
00007  * wolfSSL is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 2 of the License, or
00010  * (at your option) any later version.
00011  *
00012  * wolfSSL is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with this program; if not, write to the Free Software
00019  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
00020  */
00021 
00022 
00023 #ifdef WOLFCRYPT_HAVE_SRP
00024 
00025 #ifndef WOLFCRYPT_SRP_H
00026 #define WOLFCRYPT_SRP_H
00027 
00028 #include <wolfssl/wolfcrypt/types.h>
00029 #include <wolfssl/wolfcrypt/sha.h>
00030 #include <wolfssl/wolfcrypt/sha256.h>
00031 #include <wolfssl/wolfcrypt/sha512.h>
00032 #include <wolfssl/wolfcrypt/integer.h>
00033 
00034 #ifdef __cplusplus
00035     extern "C" {
00036 #endif
00037 
00038 /* Select the largest available hash for the buffer size. */
00039 #if defined(WOLFSSL_SHA512)
00040     #define SRP_MAX_DIGEST_SIZE SHA512_DIGEST_SIZE
00041 #elif defined(WOLFSSL_SHA384)
00042     #define SRP_MAX_DIGEST_SIZE SHA384_DIGEST_SIZE
00043 #elif !defined(NO_SHA256)
00044     #define SRP_MAX_DIGEST_SIZE SHA256_DIGEST_SIZE
00045 #elif !defined(NO_SHA)
00046     #define SRP_MAX_DIGEST_SIZE SHA_DIGEST_SIZE
00047 #else
00048     #error "You have to have some kind of SHA hash if you want to use SRP."
00049 #endif
00050 
00051 /* Set the minimum number of bits acceptable in an SRP modulus */
00052 #define SRP_DEFAULT_MIN_BITS 512
00053 
00054 /**
00055  * SRP side, client or server.
00056  */
00057 typedef enum {
00058     SRP_CLIENT_SIDE  = 0,
00059     SRP_SERVER_SIDE  = 1,
00060 } SrpSide;
00061 
00062 /**
00063  * SRP hash type, SHA[1|256|384|512].
00064  */
00065 typedef enum {
00066         SRP_TYPE_SHA    = 1,
00067         SRP_TYPE_SHA256 = 2,
00068         SRP_TYPE_SHA384 = 3,
00069         SRP_TYPE_SHA512 = 4,
00070 } SrpType;
00071 
00072 /**
00073  * SRP hash struct.
00074  */
00075 typedef struct {
00076     byte type;
00077     union {
00078         #ifndef NO_SHA
00079             Sha sha;
00080         #endif
00081         #ifndef NO_SHA256
00082             Sha256 sha256;
00083         #endif
00084         #ifdef WOLFSSL_SHA384
00085             Sha384 sha384;
00086         #endif
00087         #ifdef WOLFSSL_SHA512
00088             Sha512 sha512;
00089         #endif
00090     } data;
00091 } SrpHash;
00092 
00093 typedef struct Srp {
00094     SrpSide side;                   /**< Client or Server, @see SrpSide.      */
00095     SrpType type;                   /**< Hash type, @see SrpType.             */
00096     byte*   user;                   /**< Username, login.                     */
00097     word32  userSz;                 /**< Username length.                     */
00098     byte*   salt;                   /**< Small salt.                          */
00099     word32  saltSz;                 /**< Salt length.                         */
00100     mp_int  N;                      /**< Modulus. N = 2q+1, [q, N] are primes.*/
00101     mp_int  g;                      /**< Generator. A generator modulo N.     */
00102     byte    k[SRP_MAX_DIGEST_SIZE]; /**< Multiplier parameter. k = H(N, g)   */
00103     mp_int  auth;                   /**< Client: x = H(salt + H(user:pswd))   */
00104                                     /**< Server: v = g ^ x % N                */
00105     mp_int  priv;                   /**< Private ephemeral value.             */
00106     SrpHash client_proof;           /**< Client proof. Sent to the Server.    */
00107     SrpHash server_proof;           /**< Server proof. Sent to the Client.    */
00108     byte*   key;                    /**< Session key.                         */
00109     word32  keySz;                  /**< Session key length.                  */
00110     int (*keyGenFunc_cb) (struct Srp* srp, byte* secret, word32 size);
00111         /**< Function responsible for generating the session key.             */
00112         /**< It MUST use XMALLOC with type DYNAMIC_TYPE_SRP to allocate the   */
00113         /**< key buffer for this structure and set keySz to the buffer size.  */
00114         /**< The default function used by this implementation is a modified   */
00115         /**< version of t_mgf1 that uses the proper hash function according   */
00116         /**< to srp->type.                                                    */
00117 } Srp;
00118 
00119 /**
00120  * Initializes the Srp struct for usage.
00121  *
00122  * @param[out] srp   the Srp structure to be initialized.
00123  * @param[in]  type  the hash type to be used.
00124  * @param[in]  side  the side of the communication.
00125  *
00126  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00127  */
00128 WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side);
00129 
00130 /**
00131  * Releases the Srp struct resources after usage.
00132  *
00133  * @param[in,out] srp    the Srp structure to be terminated.
00134  */
00135 WOLFSSL_API void wc_SrpTerm(Srp* srp);
00136 
00137 /**
00138  * Sets the username.
00139  *
00140  * This function MUST be called after wc_SrpInit.
00141  *
00142  * @param[in,out] srp       the Srp structure.
00143  * @param[in]     username  the buffer containing the username.
00144  * @param[in]     size      the username size in bytes
00145  *
00146  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00147  */
00148 WOLFSSL_API int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size);
00149 
00150 
00151 /**
00152  * Sets the srp parameters based on the username.
00153  *
00154  * This function MUST be called after wc_SrpSetUsername.
00155  *
00156  * @param[in,out] srp       the Srp structure.
00157  * @param[in]     N         the Modulus. N = 2q+1, [q, N] are primes.
00158  * @param[in]     nSz       the N size in bytes.
00159  * @param[in]     g         the Generator modulo N.
00160  * @param[in]     gSz       the g size in bytes
00161  * @param[in]     salt      a small random salt. Specific for each username.
00162  * @param[in]     saltSz    the salt size in bytes
00163  *
00164  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00165  */
00166 WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N,    word32 nSz,
00167                                           const byte* g,    word32 gSz,
00168                                           const byte* salt, word32 saltSz);
00169 
00170 /**
00171  * Sets the password.
00172  *
00173  * Setting the password does not persists the clear password data in the
00174  * srp structure. The client calculates x = H(salt + H(user:pswd)) and stores
00175  * it in the auth field.
00176  *
00177  * This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY.
00178  *
00179  * @param[in,out] srp       the Srp structure.
00180  * @param[in]     password  the buffer containing the password.
00181  * @param[in]     size      the password size in bytes.
00182  *
00183  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00184  */
00185 WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size);
00186 
00187 /**
00188  * Sets the verifier.
00189  *
00190  * This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY.
00191  *
00192  * @param[in,out] srp       the Srp structure.
00193  * @param[in]     verifier  the buffer containing the verifier.
00194  * @param[in]     size      the verifier size in bytes.
00195  *
00196  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00197  */
00198 WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size);
00199 
00200 /**
00201  * Gets the verifier.
00202  *
00203  * The client calculates the verifier with v = g ^ x % N.
00204  * This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY.
00205  *
00206  * @param[in,out] srp       the Srp structure.
00207  * @param[out]    verifier  the buffer to write the verifier.
00208  * @param[in,out] size      the buffer size in bytes. Will be updated with the
00209  *                          verifier size.
00210  *
00211  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00212  */
00213 WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size);
00214 
00215 /**
00216  * Sets the private ephemeral value.
00217  *
00218  * The private ephemeral value is known as:
00219  *   a at the client side. a = random()
00220  *   b at the server side. b = random()
00221  * This function is handy for unit test cases or if the developer wants to use
00222  * an external random source to set the ephemeral value.
00223  * This function MAY be called before wc_SrpGetPublic.
00224  *
00225  * @param[in,out] srp       the Srp structure.
00226  * @param[in]     priv      the ephemeral value.
00227  * @param[in]     size      the private size in bytes.
00228  *
00229  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00230  */
00231 WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size);
00232 
00233 /**
00234  * Gets the public ephemeral value.
00235  *
00236  * The public ephemeral value is known as:
00237  *   A at the client side. A = g ^ a % N
00238  *   B at the server side. B = (k * v + (g ˆ b % N)) % N
00239  * This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier.
00240  *
00241  * @param[in,out] srp       the Srp structure.
00242  * @param[out]    pub       the buffer to write the public ephemeral value.
00243  * @param[in,out] size      the the buffer size in bytes. Will be updated with
00244  *                          the ephemeral value size.
00245  *
00246  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00247  */
00248 WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size);
00249 
00250 
00251 /**
00252  * Computes the session key.
00253  *
00254  * The key can be accessed at srp->key after success.
00255  *
00256  * @param[in,out] srp               the Srp structure.
00257  * @param[in]     clientPubKey      the client's public ephemeral value.
00258  * @param[in]     clientPubKeySz    the client's public ephemeral value size.
00259  * @param[in]     serverPubKey      the server's public ephemeral value.
00260  * @param[in]     serverPubKeySz    the server's public ephemeral value size.
00261  *
00262  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00263  */
00264 WOLFSSL_API int wc_SrpComputeKey(Srp* srp,
00265                                  byte* clientPubKey, word32 clientPubKeySz,
00266                                  byte* serverPubKey, word32 serverPubKeySz);
00267 
00268 /**
00269  * Gets the proof.
00270  *
00271  * This function MUST be called after wc_SrpComputeKey.
00272  *
00273  * @param[in,out] srp   the Srp structure.
00274  * @param[out]    proof the buffer to write the proof.
00275  * @param[in,out] size  the buffer size in bytes. Will be updated with the
00276  *                          proof size.
00277  *
00278  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00279  */
00280 WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size);
00281 
00282 /**
00283  * Verifies the peers proof.
00284  *
00285  * This function MUST be called before wc_SrpGetSessionKey.
00286  *
00287  * @param[in,out] srp   the Srp structure.
00288  * @param[in]     proof the peers proof.
00289  * @param[in]     size  the proof size in bytes.
00290  *
00291  * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
00292  */
00293 WOLFSSL_API int wc_SrpVerifyPeersProof(Srp* srp, byte* proof, word32 size);
00294 
00295 #ifdef __cplusplus
00296    } /* extern "C" */
00297 #endif
00298 
00299 #endif /* WOLFCRYPT_SRP_H */
00300 #endif /* WOLFCRYPT_HAVE_SRP */
00301