View Source Eddy (Eddy v1.0.0)
Meet Eddy! A steady little Ed25519 library for Elixir. Ed25519 is an
elliptic curve that can be used in signature schemes and ECDH shared secrets.
highlights
Highlights
- Pure Elixir implementation of
Ed25519(no external dependencies) - Secure generation of EdDSA key pairs
- Ed25519 signature schemes
- X25519 (ECDH) shared secrets
- Build your own crypto - customisable hash algo
instalation
Instalation
The package can be installed by adding eddy to your list of dependencies in
mix.exs.
def deps do
[
{:eddy, "~> 1.0.0"}
]
end
quick-start
Quick start
1-key-generation
1. Key generation
Generate new EdDSA keypairs.
iex> privkey = Eddy.generate_key()
%Eddy.PrivKey{}
iex> pubkey = Eddy.get_pubkey(privkey)
%Eddy.PubKey{}
2-sign-messages
2. Sign messages
Sign messages with a private key.
iex> sig = Eddy.sign("test", privkey)
%Eddy.Sig{}
3-verify-messages
3. Verify messages
Verify a signature against the message and a public key.
iex> Eddy.verify(sig, "test", pubkey)
true
iex> Eddy.verify(sig, "test", wrong_pubkey)
false
4-x25519-shared-secrets
4. X25519 shared secrets
ECDH shared secrets are computed by multiplying a public key with a private key. The operation yields the same result in both directions.
iex> s1 = Eddy.get_shared_secret(priv_a, pubkey_b)
iex> s2 = Eddy.get_shared_secret(priv_b, pubkey_a)
iex> s1 == s2
true
custom-hash-function
Custom hash function
As per the rfc8032 spec,
by default Eddy uses the sha512 hash function internally. Optionally,
a custom hash function can be configured in your application's
config/config.exs.
The custom hash function must return 64 bytes.
import Config
# The hash function will be invoked as `:crypto.hash(:sha3_512, payload)`
config :eddy, hash_fn: {:crypto, :hash, [:sha3_512], []}
# The hash function will be invoked as `B3.hash(payload, length: 64)`
config :eddy, hash_fn: {B3, :hash, [], [[length: 64]]}Link to this section Summary
Functions
Generates a new random private key.
Takes a private key and returns the corresponding public key.
Computes an ECDH shared secret from the given private and public keys.
Returns the Ed25519 elliptic curve parameters.
Signs the message with the given private key.
Verifies the signature against the given message and public key. Returns a boolean or error tuple.
Link to this section Types
@type encoding() :: :raw | :base16 | :base64 | :hex
Binary encoding format.
Eddy can encoding keys and signatures in raw, base16 or base64 encodings. Hex is as base16, but with lower case letters.
@type privkey() :: Eddy.PrivKey.t() | binary()
Private Key.
Are represented as PrivKey structs or 32 byte binaries.
@type pubkey() :: Eddy.PubKey.t() | binary()
Public Key.
Are represented as PubKey structs or 32 byte binaries.
@type sig() :: Eddy.Sig.t() | binary()
Signature.
Are represented as Sig structs or 64 byte binaries.
Link to this section Functions
Generates a new random private key.
The private key can optionally be returned as a raw or encoded binary.
options
Options
:encoding- Optionally encode with a binaryencoding/0.
examples
Examples
iex> privkey = Eddy.generate_key()
%Eddy.PrivKey{}
iex> privkey = Eddy.generate_key(encoding: :raw)
<<182, 7, 194, 105, 23, 114, 238, 195, 188, 101, 41, 99, 155, 2, 174, 52, 187,
235, 72, 4, 221, 189, 111, 49, 33, 240, 224, 53, 161, 77, 253, 50>>
iex> privkey = Eddy.generate_key(encoding: :hex)
"3056ade0bc0215aa21db1dfddd3ea6786a4127b28efddb7e9b6af9845b8ef57a"Takes a private key and returns the corresponding public key.
Acceps a private key struct or raw binary. The public key can optionally be returned as a raw or encoded binary.
options
Options
:encoding- Optionally encode with a binaryencoding/0.
examples
Examples
iex> pubkey = Eddy.get_pubkey(privkey)
%Eddy.PubKey{}
iex> pubkey = Eddy.get_pubkey(privkey, encoding: :hex)
"9dcfaa3dca4a02da72c500885dd6824a7c9abb76b88f9e3f10378f33c56d2465"@spec params() :: map()
Returns the Ed25519 elliptic curve parameters.
Signs the message with the given private key.
Acceps a private key struct or raw binary. The signature can optionally be returned as a raw or encoded binary.
options
Options
:encoding- Optionally encode with a binaryencoding/0.
examples
Examples
iex> sig = Eddy.sign("test", privkey)
%Eddy.Sig{}
iex> sig = Eddy.sign("test", privkey, encoding: :base64)
"uS5X1ek6+aHAYGMEMWLF5+O9W8rxK6HDHHI2QOoBOReVaAsf5sFSI3Dqvms4LUtecW/ILAOaWS1L737ye6dkBg=="Verifies the signature against the given message and public key. Returns a boolean or error tuple.
Acceps a public key struct or raw binary. The signature can optionally be decoded from a raw or encoded binary.
options
Options
:encoding- Optionally decode from a binaryencoding/0.
examples
Examples
iex> Eddy.verify(sig, "test", pubkey)
true
iex> sig = "uS5X1ek6+aHAYGMEMWLF5+O9W8rxK6HDHHI2QOoBOReVaAsf5sFSI3Dqvms4LUtecW/ILAOaWS1L737ye6dkBg=="
iex> Eddy.verify(sig, "test", pubkey, encoding: :base64)
true