SRP - Secure Remote Password APIs

Type declarations and APIs for the SRP key agreement protocol. More...

Macros
#define	ocrypto_srp_SALT_BYTES   (16)
#define	ocrypto_srp_VERIFIER_BYTES   (384)
#define	ocrypto_srp_SECRET_KEY_BYTES   (32)
#define	ocrypto_srp_PUBLIC_KEY_BYTES   (384)
#define	ocrypto_srp_SCRAMBLING_PARAMETER_BYTES   (64)
#define	ocrypto_srp_PREMASTER_SECRET_BYTES   (384)
#define	ocrypto_srp_SESSION_KEY_BYTES   (64)
#define	ocrypto_srp_PROOF_BYTES   (64)

Functions
void	ocrypto_srp_server_public_key (uint8_t pub_b[(384)], const uint8_t priv_b[(32)], const uint8_t k[(384)], const uint8_t v[(384)])
void	ocrypto_srp_client_public_key (unsigned char pub_a[(384)], const unsigned char *priv_a, size_t a_len)

SRP-6 password verifier generation.
A password verifier is generated from a user name and a password. The password pass may be discarded, as only the verifier is used during later computations.
void	ocrypto_srp_verifier (uint8_t v[(384)], const uint8_t salt[(16)], const uint8_t *user, size_t user_len, const uint8_t *pass, size_t pass_len)

SRP-6 public key generation.
An ephemeral keypair can be generated based on the password verifier to be used when opening a new session.
void	ocrypto_srp_public_key (uint8_t pub_b[(384)], const uint8_t priv_b[(32)], const uint8_t v[(384)])

SRP-6 session key generation.
A premaster secret can be derived from both the client's and server's public keys, the server's private key and the password verifier. A shared session key can be generated from this premaster secret.
void	ocrypto_srp_scrambling_parameter (uint8_t u[(64)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)])
int	ocrypto_srp_premaster_secret (uint8_t s[(384)], const uint8_t pub_a[(384)], const uint8_t priv_b[(32)], const uint8_t u[(64)], const uint8_t v[(384)])
int	ocrypto_srp_server_premaster_secret (uint8_t s[(384)], const uint8_t pub_a[(384)], const uint8_t priv_b[(32)], const uint8_t *u, size_t u_len, const uint8_t v[(384)])
int	ocrypto_srp_client_premaster_secret (uint8_t s[(384)], const uint8_t priv_a[(32)], const uint8_t pub_b[(384)], const uint8_t k[(384)], const uint8_t *u, const uint8_t *h, size_t h_len)
void	ocrypto_srp_session_key (uint8_t k[(64)], const uint8_t s[(384)])

SRP-6 proof exchange.
Proofs are exchanged from client to server and vice versa to ensure that both parties computed the same shared session key. The proofs only match if the correct password is used by the client.
void	ocrypto_srp_proof_m1 (uint8_t m1[(64)], const uint8_t *user, size_t user_len, const uint8_t salt[(16)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)], const uint8_t k[(64)])
void	ocrypto_srp_proof_m2 (uint8_t m2[(64)], const uint8_t pub_a[(384)], const uint8_t m1[(64)], const uint8_t k[(64)])

SRP-6 password verifier generation with context.
A password verifier is generated from a user name and a password. The password pass may be discarded, as only the verifier is used in subsequent computations.
void	ocrypto_srp_verifier_ctx (ocrypto_srp_ctx *ctx, uint8_t v[(384)], const uint8_t salt[(16)], const uint8_t *user, size_t user_len, const uint8_t *pass, size_t pass_len)

SRP-6 public key generation with context.
An ephemeral keypair can be generated based on the password verifier to be used when opening a new session.
void	ocrypto_srp_public_key_ctx (ocrypto_srp_ctx *ctx, uint8_t pub_b[(384)], const uint8_t priv_b[(32)], const uint8_t v[(384)])

SRP-6 session key generation with context.
A premaster secret can be derived from both the client's and server's public keys, the server's private key and the password verifier. A shared session key can be generated from this premaster secret.
void	ocrypto_srp_scrambling_parameter_ctx (ocrypto_srp_ctx *ctx, uint8_t u[(64)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)])
int	ocrypto_srp_premaster_secret_ctx (ocrypto_srp_ctx *ctx, uint8_t s[(384)], const uint8_t pub_a[(384)], const uint8_t priv_b[(32)], const uint8_t u[(64)], const uint8_t v[(384)])
void	ocrypto_srp_session_key_ctx (ocrypto_srp_ctx *ctx, uint8_t k[(64)], const uint8_t s[(384)])

SRP-6 proof exchange with context.
Proofs are exchanged from client to server and vice versa to ensure that both parties computed the same shared session key. The proofs only match if the correct password is used by the client.
void	ocrypto_srp_proof_m1_ctx (ocrypto_srp_ctx *ctx, uint8_t m1[(64)], const uint8_t *user, size_t user_len, const uint8_t salt[(16)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)], const uint8_t k[(64)])
void	ocrypto_srp_proof_m2_ctx (ocrypto_srp_ctx *ctx, uint8_t m2[(64)], const uint8_t pub_a[(384)], const uint8_t m1[(64)], const uint8_t k[(64)])

Detailed Description

Type declarations and APIs for the SRP key agreement protocol.

SRP is an augmented password-authenticated key agreement protocol, specifically designed to work around existing patents. SRP allows the use of user names and passwords over unencrypted channels and supplies a shared secret at the end of the authentication sequence that can be used to generate encryption keys.

An eavesdropper or man in the middle cannot obtain enough information to be able to brute force guess a password without further interactions with the parties for each guess.

The server does not store password-equivalent data. This means that an attacker who steals the server data cannot masquerade as the client unless they first perform a brute force search for the password.

The specific variant implemented here is SRP-6 3072 bit SHA-512.

See also

RFC 5054 - Using the Secure Remote Password (SRP) Protocol for TLS Authentication

The Stanford SRP Homepage

Basic protocol overview

Setup

1. Server generates a username / password combination together with a salt.
2. Server derives a password verifier (see ocrypto_srp_verifier).
3. The username, salt and verifier are stored and required to open sessions. The original password is no longer needed.

Session opening

1. Client sends a username and the public key of an ephemeral key pair to the server.
2. Server sends the salt and the public key of another ephemeral key pair to the client (see ocrypto_srp_public_key).
3. Client and Server both compute the session key from this information (see ocrypto_srp_scrambling_parameter, ocrypto_srp_premaster_secret, ocrypto_srp_session_key).
4. Client sends proof of the session key to the server.
5. Server validates proof (see ocrypto_srp_proof_m1), then sends proof of the session key to the client (see ocrypto_srp_proof_m2).
6. Client validates proof. Both parties know that they share the same private session key.