Functions
Algorithms - SRP

Functions

WOLFSSL_API int wc_SrpInit (Srp *srp, SrpType type, SrpSide side)
 Initializes the Srp struct for usage. More...
 
WOLFSSL_API void wc_SrpTerm (Srp *srp)
 Releases the Srp struct resources after usage. More...
 
WOLFSSL_API int wc_SrpSetUsername (Srp *srp, const byte *username, word32 size)
 Sets the username. This function MUST be called after wc_SrpInit. More...
 
WOLFSSL_API int wc_SrpSetParams (Srp *srp, const byte *N, word32 nSz, const byte *g, word32 gSz, const byte *salt, word32 saltSz)
 Sets the srp parameters based on the username.. Must be called after wc_SrpSetUsername. More...
 
WOLFSSL_API int wc_SrpSetPassword (Srp *srp, const byte *password, word32 size)
 Sets the password. Setting the password does not persists the clear password data in the srp structure. The client calculates x = H(salt + H(user:pswd)) and stores it in the auth field. This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY. More...
 
WOLFSSL_API int wc_SrpSetVerifier (Srp *srp, const byte *verifier, word32 size)
 Sets the verifier. This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY. More...
 
WOLFSSL_API int wc_SrpGetVerifier (Srp *srp, byte *verifier, word32 *size)
 Gets the verifier. The client calculates the verifier with v = g ^ x % N. This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY. More...
 
WOLFSSL_API int wc_SrpSetPrivate (Srp *srp, const byte *priv, word32 size)
 Sets the private ephemeral value. The private ephemeral value is known as: a at the client side. a = random() b at the server side. b = random() This function is handy for unit test cases or if the developer wants to use an external random source to set the ephemeral value. This function MAY be called before wc_SrpGetPublic. More...
 
WOLFSSL_API int wc_SrpGetPublic (Srp *srp, byte *pub, word32 *size)
 Gets the public ephemeral value. The public ephemeral value is known as: A at the client side. A = g ^ a % N B at the server side. B = (k * v + (g ˆ b % N)) % N This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier. The function wc_SrpSetPrivate may be called before wc_SrpGetPublic. More...
 
WOLFSSL_API int wc_SrpComputeKey (Srp *srp, byte *clientPubKey, word32 clientPubKeySz, byte *serverPubKey, word32 serverPubKeySz)
 Computes the session key. The key can be accessed at srp->key after success. More...
 
WOLFSSL_API int wc_SrpGetProof (Srp *srp, byte *proof, word32 *size)
 Gets the proof. This function MUST be called after wc_SrpComputeKey. More...
 
WOLFSSL_API int wc_SrpVerifyPeersProof (Srp *srp, byte *proof, word32 size)
 Verifies the peers proof. This function MUST be called before wc_SrpGetSessionKey. More...
 

Detailed Description

Function Documentation

◆ wc_SrpComputeKey()

WOLFSSL_API int wc_SrpComputeKey ( Srp srp,
byte *  clientPubKey,
word32  clientPubKeySz,
byte *  serverPubKey,
word32  serverPubKeySz 
)

Computes the session key. The key can be accessed at srp->key after success.

Returns
0 Success
BAD_FUNC_ARG Returned if srp, clientPubKey, or serverPubKey or if clientPubKeySz or serverPubKeySz is 0.
SRP_CALL_ORDER_E Returned if wc_SrpComputeKey is called out of order.
<0 Error
Parameters
srpthe Srp structure.
clientPubKeythe client's public ephemeral value.
clientPubKeySzthe client's public ephemeral value size.
serverPubKeythe server's public ephemeral value.
serverPubKeySzthe server's public ephemeral value size.

Example

byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
byte verifier[] = { }; // Contents of some verifier
byte serverPubKey[] = { }; // Contents of server pub key
word32 serverPubKeySize = sizeof(serverPubKey);
byte clientPubKey[64];
word32 clientPubKeySize = 64;
wc_SrpInit(&server, SRP_TYPE_SHA, SRP_SERVER_SIDE);
wc_SrpSetUsername(&server, username, usernameSize);
wc_SrpSetParams(&server, N, sizeof(N), g, sizeof(g), salt, sizeof(salt));
wc_SrpSetVerifier(&server, verifier, sizeof(verifier));
wc_SrpGetPublic(&server, serverPubKey, &serverPubKeySize);
wc_SrpComputeKey(&server, clientPubKey, clientPubKeySz,
serverPubKey, serverPubKeySize)
See also
wc_SrpGetPublic

◆ wc_SrpGetProof()

WOLFSSL_API int wc_SrpGetProof ( Srp srp,
byte *  proof,
word32 *  size 
)

Gets the proof. This function MUST be called after wc_SrpComputeKey.

Returns
0 Success
BAD_FUNC_ARG Returns if srp, proof, or size is null.
BUFFER_E Returns if size is less than the hash size of srp->type.
<0 Error
Parameters
srpthe Srp structure.
proofthe peers proof.
sizethe proof size in bytes.

Example

Srp cli;
byte clientProof[SRP_MAX_DIGEST_SIZE];
word32 clientProofSz = SRP_MAX_DIGEST_SIZE;
// Initialize Srp following steps from previous examples
if (wc_SrpGetProof(&cli, clientProof, &clientProofSz) != 0)
{
// Error getting proof
}
See also
wc_SrpComputeKey

◆ wc_SrpGetPublic()

WOLFSSL_API int wc_SrpGetPublic ( Srp srp,
byte *  pub,
word32 *  size 
)

Gets the public ephemeral value. The public ephemeral value is known as: A at the client side. A = g ^ a % N B at the server side. B = (k * v + (g ˆ b % N)) % N This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier. The function wc_SrpSetPrivate may be called before wc_SrpGetPublic.

Returns
0 Success
BAD_FUNC_ARG Returned if srp, pub, or size is null.
SRP_CALL_ORDER_E Returned if wc_SrpGetPublic is called out of order.
BUFFER_E Returned if size < srp.N.
<0 Error
Parameters
srpthe Srp structure.
pubthe buffer to write the public ephemeral value.
sizethe the buffer size in bytes. Will be updated with the ephemeral value size.

Example

Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt));
wc_SrpSetPassword(&srp, password, passwordSize)
byte public[64];
word32 publicSz = 0;
if( wc_SrpGetPublic(&srp, public, &publicSz) != 0)
{
// Error getting public ephemeral
}
wc_SrpTerm(&srp);
See also
wc_SrpSetPrivate
wc_SrpSetPassword
wc_SrpSetVerifier

◆ wc_SrpGetVerifier()

WOLFSSL_API int wc_SrpGetVerifier ( Srp srp,
byte *  verifier,
word32 *  size 
)

Gets the verifier. The client calculates the verifier with v = g ^ x % N. This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY.

Returns
0 Success
BAD_FUNC_ARG Returned if srp, verifier or size is null or if srp->side is not SRP_CLIENT_SIDE.
SRP_CALL_ORDER_E Returned if wc_SrpGetVerifier is called out of order.
<0 Error
Parameters
srpThe Srp structure.
verifierThe buffer to write the verifier.
sizeBuffer size in bytes. Updated with the verifier size.

Example

Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
byte v[64];
word32 vSz = 0;
vSz = sizeof(v);
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt))
wc_SrpSetPassword(&srp, password, passwordSize)
if( wc_SrpGetVerifier(&srp, v, &vSz ) != 0)
{
// Error getting verifier
}
wc_SrpTerm(&srp);
See also
wc_SrpSetVerifier
wc_SrpSetPassword

◆ wc_SrpInit()

WOLFSSL_API int wc_SrpInit ( Srp srp,
SrpType  type,
SrpSide  side 
)

Initializes the Srp struct for usage.

Returns
0 on success.
BAD_FUNC_ARG Returns when there's an issue with the arguments such as srp being null or SrpSide not being SRP_CLIENT_SIDE or SRP_SERVER_SIDE.
NOT_COMPILED_IN Returns when a type is passed as an argument but hasn't been configured in the wolfCrypt build.
<0 on error.
Parameters
srpthe Srp structure to be initialized.
typethe hash type to be used.
sidethe side of the communication.

Example

Srp srp;
if (wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE) != 0)
{
// Initialization error
}
else
{
wc_SrpTerm(&srp);
}
See also
wc_SrpTerm
wc_SrpSetUsername

◆ wc_SrpSetParams()

WOLFSSL_API int wc_SrpSetParams ( Srp srp,
const byte *  N,
word32  nSz,
const byte *  g,
word32  gSz,
const byte *  salt,
word32  saltSz 
)

Sets the srp parameters based on the username.. Must be called after wc_SrpSetUsername.

Returns
0 Success
BAD_FUNC_ARG Returns if srp, N, g, or salt is null or if nSz < gSz.
SRP_CALL_ORDER_E Returns if wc_SrpSetParams is called before wc_SrpSetUsername.
<0 Error
Parameters
srpthe Srp structure.
Nthe Modulus. N = 2q+1, [q, N] are primes.
nSzthe N size in bytes.
gthe Generator modulo N.
gSzthe g size in bytes
salta small random salt. Specific for each username.
saltSzthe salt size in bytes
_Example_
Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
if(wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt,
sizeof(salt)) != 0)
{
// Error setting params
}
wc_SrpTerm(&srp);
See also
wc_SrpInit
wc_SrpSetUsername
wc_SrpTerm

◆ wc_SrpSetPassword()

WOLFSSL_API int wc_SrpSetPassword ( Srp srp,
const byte *  password,
word32  size 
)

Sets the password. Setting the password does not persists the clear password data in the srp structure. The client calculates x = H(salt + H(user:pswd)) and stores it in the auth field. This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY.

Returns
0 Success
BAD_FUNC_ARG Returns if srp or password is null or if srp->side is not set to SRP_CLIENT_SIDE.
SRP_CALL_ORDER_E Returns when wc_SrpSetPassword is called out of order.
<0 Error
Parameters
srpThe Srp structure.
passwordThe buffer containing the password.
sizeThe size of the password in bytes.

Example

Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte password[] = "password";
word32 passwordSize = 8;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt));
if(wc_SrpSetPassword(&srp, password, passwordSize) != 0)
{
// Error setting password
}
wc_SrpTerm(&srp);
See also
wc_SrpInit
wc_SrpSetUsername
wc_SrpSetParams

◆ wc_SrpSetPrivate()

WOLFSSL_API int wc_SrpSetPrivate ( Srp srp,
const byte *  priv,
word32  size 
)

Sets the private ephemeral value. The private ephemeral value is known as: a at the client side. a = random() b at the server side. b = random() This function is handy for unit test cases or if the developer wants to use an external random source to set the ephemeral value. This function MAY be called before wc_SrpGetPublic.

Returns
0 Success
BAD_FUNC_ARG Returned if srp, private, or size is null.
SRP_CALL_ORDER_E Returned if wc_SrpSetPrivate is called out of order.
<0 Error
Parameters
srpthe Srp structure.
privthe ephemeral value.
sizethe private size in bytes.

Example

Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
byte verifier = { }; // Contents of some verifier
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_SERVER_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt))
wc_SrpSetVerifier(&srp, verifier, sizeof(verifier))
byte b[] = { }; // Some ephemeral value
if( wc_SrpSetPrivate(&srp, b, sizeof(b)) != 0)
{
// Error setting private ephemeral
}
wc_SrpTerm(&srp);
See also
wc_SrpGetPublic

◆ wc_SrpSetUsername()

WOLFSSL_API int wc_SrpSetUsername ( Srp srp,
const byte *  username,
word32  size 
)

Sets the username. This function MUST be called after wc_SrpInit.

Returns
0 Username set successfully.
BAD_FUNC_ARG: Return if srp or username is null.
MEMORY_E: Returns if there is an issue allocating memory for srp->user
< 0: Error.
Parameters
srpthe Srp structure.
usernamethe buffer containing the username.
sizethe username size in bytes

Example

Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
if(wc_SrpSetUsername(&srp, username, usernameSize) != 0)
{
// Error occurred setting username.
}
wc_SrpTerm(&srp);
See also
wc_SrpInit
wc_SrpSetParams
wc_SrpTerm

◆ wc_SrpSetVerifier()

WOLFSSL_API int wc_SrpSetVerifier ( Srp srp,
const byte *  verifier,
word32  size 
)

Sets the verifier. This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY.

Returns
0 Success
BAD_FUNC_ARG Returned if srp or verifier is null or srp->side is not SRP_SERVER_SIDE.
<0 Error
Parameters
srpThe Srp structure.
verifierThe structure containing the verifier.
sizeThe verifier size in bytes.

Example

Srp srp;
byte username[] = "user";
word32 usernameSize = 4;
byte N[] = { }; // Contents of byte array N
byte g[] = { }; // Contents of byte array g
byte salt[] = { }; // Contents of byte array salt
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_SERVER_SIDE);
wc_SrpSetUsername(&srp, username, usernameSize);
wc_SrpSetParams(&srp, N, sizeof(N), g, sizeof(g), salt, sizeof(salt))
byte verifier[] = { }; // Contents of some verifier
if(wc_SrpSetVerifier(&srp, verifier, sizeof(verifier)) != 0)
{
// Error setting verifier
}
wc_SrpTerm(&srp);
See also
wc_SrpInit
wc_SrpSetParams
wc_SrpGetVerifier

◆ wc_SrpTerm()

WOLFSSL_API void wc_SrpTerm ( Srp srp)

Releases the Srp struct resources after usage.

Returns
none No returns.
Parameters
srpPointer to the Srp structure to be terminated.

Example

Srp srp;
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
// Use srp
See also
wc_SrpInit

◆ wc_SrpVerifyPeersProof()

WOLFSSL_API int wc_SrpVerifyPeersProof ( Srp srp,
byte *  proof,
word32  size 
)

Verifies the peers proof. This function MUST be called before wc_SrpGetSessionKey.

Returns
0 Success
<0 Error
Parameters
srpthe Srp structure.
proofthe peers proof.
sizethe proof size in bytes.

Example

Srp cli;
Srp srv;
byte clientProof[SRP_MAX_DIGEST_SIZE];
word32 clientProofSz = SRP_MAX_DIGEST_SIZE;
// Initialize Srp following steps from previous examples
// First get the proof
wc_SrpGetProof(&cli, clientProof, &clientProofSz)
if (wc_SrpVerifyPeersProof(&srv, clientProof, clientProofSz) != 0)
{
// Error verifying proof
}
See also
wc_SrpGetSessionKey
wc_SrpGetProof
wc_SrpTerm