Algorithms - SRP

Functions
WOLFSSL_API int	wc_SrpInit (Srp *srp, SrpType type, SrpSide side)
	Initializes the Srp struct for usage.
WOLFSSL_API void	wc_SrpTerm (Srp *srp)
	Releases the Srp struct resources after usage.
WOLFSSL_API int	wc_SrpSetUsername (Srp *srp, const byte *username, word32 size)
	Sets the username. This function MUST be called after wc_SrpInit.
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.
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.
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.
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.
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.
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.
WOLFSSL_API int	wc_SrpGetProof (Srp *srp, byte *proof, word32 *size)
	Gets the proof. This function MUST be called after wc_SrpComputeKey.
WOLFSSL_API int	wc_SrpVerifyPeersProof (Srp *srp, byte *proof, word32 size)
	Verifies the peers proof. This function MUST be called before wc_SrpGetSessionKey.

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

srp	the Srp structure.
clientPubKey	the client's public ephemeral value.
clientPubKeySz	the client's public ephemeral value size.
serverPubKey	the server's public ephemeral value.
serverPubKeySz	the server's public ephemeral value size.

Example

Srp server;
 
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)
wc_SrpTerm(&server);

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

srp	the Srp structure.
proof	the peers proof.
size	the 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

srp	the Srp structure.
pub	the buffer to write the public ephemeral value.
size	the 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

srp	The Srp structure.
verifier	The buffer to write the verifier.
size	Buffer 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

srp	the Srp structure to be initialized.
type	the hash type to be used.
side	the 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_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

srp	The Srp structure.
password	The buffer containing the password.
size	The 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

srp	the Srp structure.
priv	the ephemeral value.
size	the 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

srp	the Srp structure.
username	the buffer containing the username.
size	the 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

srp	The Srp structure.
verifier	The structure containing the verifier.
size	The 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

srp	Pointer to the Srp structure to be terminated.

Example

Srp srp;
wc_SrpInit(&srp, SRP_TYPE_SHA, SRP_CLIENT_SIDE);
// Use srp
wc_SrpTerm(&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

srp	the Srp structure.
proof	the peers proof.
size	the 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