Algorithms - SRP

Functions

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

Functions Documentation

function wc_SrpInit

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

Initializes the Srp struct for usage.

Parameters:

srp the Srp structure to be initialized.
type the hash type to be used.
side the side of the communication.

See:

Return:

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.

Example

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

function wc_SrpTerm

void wc_SrpTerm(
    Srp * srp
)

Releases the Srp struct resources after usage.

Parameters:

srp Pointer to the Srp structure to be terminated.

See: wc_SrpInit

Return: none No returns.

Example

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

function wc_SrpSetUsername

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

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

Parameters:

srp the Srp structure.
username the buffer containing the username.
size the username size in bytes

See:

Return:

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.

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);

function wc_SrpSetParams

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.

Parameters:

srp the Srp structure.
N the Modulus. N = 2q+1, [q, N] are primes.
nSz the N size in bytes.
g the Generator modulo N.
gSz the g size in bytes
salt a small random salt. Specific for each username.
saltSz the salt size in bytes

See:

Return:

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

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);

function wc_SrpSetPassword

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.

Parameters:

srp The Srp structure.
password The buffer containing the password.
size The size of the password in bytes.

See:

Return:

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

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);

function wc_SrpSetVerifier

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.

Parameters:

srp The Srp structure.
verifier The structure containing the verifier.
size The verifier size in bytes.

See:

Return:

0 Success
BAD_FUNC_ARG Returned if srp or verifier is null or srp->side is not SRP_SERVER_SIDE.
<0 Error

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);

function wc_SrpGetVerifier

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.

Parameters:

srp The Srp structure.
verifier The buffer to write the verifier.
size Buffer size in bytes. Updated with the verifier size.

See:

Return:

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

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);

function wc_SrpSetPrivate

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.

Parameters:

srp the Srp structure.
priv the ephemeral value.
size the private size in bytes.

See: wc_SrpGetPublic

Return:

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

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);

function wc_SrpGetPublic

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.

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.

See:

Return:

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

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);

function wc_SrpComputeKey

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.

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.

See: wc_SrpGetPublic

Return:

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

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);

function wc_SrpGetProof

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

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

Parameters:

srp the Srp structure.
proof the peers proof.
size the proof size in bytes.

See: wc_SrpComputeKey

Return:

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

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
}

function wc_SrpVerifyPeersProof

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

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

Parameters:

srp the Srp structure.
proof the peers proof.
size the proof size in bytes.

See:

wc_SrpGetSessionKey
wc_SrpGetProof
wc_SrpTerm

Return:

0 Success
<0 Error

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
}

Updated on 2024-11-22 at 01:12:39 +0000