strap v0.1.0 Strap

A module for using SRP (Secure Remote Password) versions 6 and 6a in Elixir.

Link to this section Summary

Functions

Returns known-good primes and generators as defined in RFC5054

Returns the public key for a given client or server

Generates a session key for communication with the remote counterparty

Creates a verifier value that could be sent to the server, e.g. during account creation, without ever sharing the user password

Same as verifier/1, but can be used only with a protocol, not a full client. Could be used, e.g. on the server if the server is supposed to verify characteristics of the user’s password before creating a verifier

Link to this section Types

Link to this type bin_number()
bin_number() :: non_neg_integer() | binary()
Link to this type client()
client() :: {:client, protocol(), non_neg_integer(), non_neg_integer(), non_neg_integer()}
Link to this type hash_fn()
hash_fn() :: (iodata() -> binary())
Link to this type hash_types()
hash_types() :: :sha | :sha256 | atom()
Link to this type protocol()
protocol() :: {srp_version(), binary(), non_neg_integer(), non_neg_integer(), hash_fn()}
Link to this type server()
server() :: {:server, protocol(), non_neg_integer(), non_neg_integer(), non_neg_integer()}
Link to this type srp_version()
srp_version() :: :srp6 | :srp6a

Link to this section Functions

Link to this function client(protocol, username, password, salt, private \\ rand_bytes())
client(protocol(), binary(), binary(), bin_number(), bin_number()) :: client()

Creates a client structure.

Parameters

  • protocol: a protocol structure created by protocol/4.
  • username: a t:String.t or t:binary username.
  • password: a t:String.t or t:binary password.
  • salt: the salt, t:String.t or t:binary, as provided from the server.
  • private: the private key for the client; if not provided, a 256-bit secure random value will be generated.

Returns

A client structure, for use with public_key/1 and session_key/2.

Notes

The username and password are not stored in the resulting structure, but a hash of their values is stored.

Link to this function prime_group(int)
prime_group(pos_integer()) :: {binary(), pos_integer()}

Returns known-good primes and generators as defined in RFC5054.

The following bit-sizes are defined: 1024, 1536, 2048, 3072, 4096, 6144, 8192.

Parameters

  • bit_size: the size in bits of the prime group

Returns

Tuple of the form {<<prime :: binary>>, generator}

Link to this function protocol(version, prime, generator, hash \\ :sha)
protocol(srp_version(), binary(), bin_number(), hash_types()) :: protocol()

Creates a protocol structure.

Parameters

  • srp_version: Either :srp6 or :srp6a
  • prime: A binary string representing the prime N value
  • generator: The generator g integer
  • hash: One of the hash atoms supported by :crypto.hash/2 or a fn/1 that takes an t:iodata value and returns a binary hash of that value.

Returns

A protocol structure, for use in server/3 or client/5.

Link to this function public_value(arg)
public_value(client() | server()) :: binary()

Returns the public key for a given client or server.

Parameters

  • client_server: either a client or server structure, from which the public key will be produced.

Returns

A binary representation of the public key.

Link to this function server(protocol, verifier, private \\ rand_bytes())
server(protocol(), bin_number(), bin_number()) :: server()

Creates a server structure.

Parameters

  • protocol: a protocol structure created by protocol/4.
  • verifier: the verifier value, either t:integer or t:binary.
  • private: the private key for the server; if not provided, a 256-bit secure random value will be generated.

Returns

A server structure, for use with public_key/1 and session_key/2.

Link to this function session_key(arg, client_public)
session_key(client() | server(), bin_number()) ::
  {:error, atom()} |
  {:ok, binary()}

Generates a session key for communication with the remote counterparty.

Parameters

  • client_server: either a client or server structure.
  • counterparty_public: the counterparty’s public value.

Returns

Either:

  • {:ok, session_key}: if the session key creation was successful
  • {:error, reason}: if the session key creation was unsuccesful

Session key creation can be unsuccessful if certain mathematical properties do not hold, compromising the security of unshared secrets or future communication.

Link to this function verifier(arg)
verifier(client()) :: binary()

Creates a verifier value that could be sent to the server, e.g. during account creation, without ever sharing the user password.

Parameters

  • client: a client, created previously.

Returns

A binary string of the verifier.

Link to this function verifier(protocol, username, password, salt)
verifier(protocol(), binary(), binary(), bin_number()) :: binary()

Same as verifier/1, but can be used only with a protocol, not a full client. Could be used, e.g. on the server if the server is supposed to verify characteristics of the user’s password before creating a verifier.

Parameters

  • protocol: a protocol object created with protocol/4.
  • username: the username.
  • password: the password.
  • salt: the salt.

Returns

A binary string of the verifier.