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-12-06 at 01:17:08 +0000