ed25519/readme.txt

   1 Ed25519
   2 =======
   3
   4 Retrived from from 'https://github.com/orlp/ed25519.git' commit
   5 e65e7f944d03dda8564f9f901e2a9999bbdf71c8. Might used git submodule, but meantime
   6 this is sufficient. Build with 'make'.
   7  -- Brod
   8
   9 This is a portable implementation of [Ed25519](http://ed25519.cr.yp.to/) based
  10 on the SUPERCOP "ref10" implementation. Additionally there is key exchanging
  11 and scalar addition included to further aid building a PKI using Ed25519. All
  12 code is licensed under the permissive zlib license.
  13
  14 All code is pure ANSI C without any dependencies, except for the random seed
  15 generation which uses standard OS cryptography APIs (`CryptGenRandom` on
  16 Windows, `/dev/urandom` on nix). If you wish to be entirely portable define
  17 `ED25519_NO_SEED`. This disables the `ed25519_create_seed` function, so if your
  18 application requires key generation you must supply your own seeding function
  19 (which is simply a 256 bit (32 byte) cryptographic random number generator).
  20
  21
  22 Performance
  23 -----------
  24
  25 On a Windows machine with an Intel Pentium B970 @ 2.3GHz I got the following
  26 speeds (running on only one a single core):
  27
  28     Seed generation: 64us (15625 per second)
  29     Key generation: 88us (11364 per second)
  30     Message signing (short message): 87us (11494 per second)
  31     Message verifying (short message): 228us (4386 per second)
  32     Scalar addition: 100us (10000 per second)
  33     Key exchange: 220us (4545 per second)
  34
  35 The speeds on other machines may vary. Sign/verify times will be higher with
  36 longer messages. The implementation significantly benefits from 64 bit
  37 architectures, if possible compile as 64 bit.
  38
  39
  40 Usage
  41 -----
  42
  43 Simply add all .c and .h files in the `src/` folder to your project and include
  44 `ed25519.h` in any file you want to use the API. If you prefer to use a shared
  45 library, only copy `ed25519.h` and define `ED25519_DLL` before importing. A
  46 windows DLL is pre-built.
  47
  48 There are no defined types for seeds, private keys, public keys, shared secrets
  49 or signatures. Instead simple `unsigned char` buffers are used with the
  50 following sizes:
  51
  52 ```c
  53 unsigned char seed[32];
  54 unsigned char signature[64];
  55 unsigned char public_key[32];
  56 unsigned char private_key[64];
  57 unsigned char scalar[32];
  58 unsigned char shared_secret[32];
  59 ```
  60
  61 API
  62 ---
  63
  64 ```c
  65 int ed25519_create_seed(unsigned char *seed);
  66 ```
  67
  68 Creates a 32 byte random seed in `seed` for key generation. `seed` must be a
  69 writable 32 byte buffer. Returns 0 on success, and nonzero on failure.
  70
  71 ```c
  72 void ed25519_create_keypair(unsigned char *public_key, unsigned char *private_key,
  73                             const unsigned char *seed);
  74 ```
  75
  76 Creates a new key pair from the given seed. `public_key` must be a writable 32
  77 byte buffer, `private_key` must be a writable 64 byte buffer and `seed` must be
  78 a 32 byte buffer.
  79
  80 ```c
  81 void ed25519_sign(unsigned char *signature,
  82                   const unsigned char *message, size_t message_len,
  83                   const unsigned char *public_key, const unsigned char *private_key);
  84 ```
  85
  86 Creates a signature of the given message with the given key pair. `signature`
  87 must be a writable 64 byte buffer. `message` must have at least `message_len`
  88 bytes to be read.
  89
  90 ```c
  91 int ed25519_verify(const unsigned char *signature,
  92                    const unsigned char *message, size_t message_len,
  93                    const unsigned char *public_key);
  94 ```
  95
  96 Verifies the signature on the given message using `public_key`. `signature`
  97 must be a readable 64 byte buffer. `message` must have at least `message_len`
  98 bytes to be read. Returns 1 if the signature matches, 0 otherwise.
  99
 100 ```c
 101 void ed25519_add_scalar(unsigned char *public_key, unsigned char *private_key,
 102                         const unsigned char *scalar);
 103 ```
 104
 105 Adds `scalar` to the given key pair where scalar is a 32 byte buffer (possibly
 106 generated with `ed25519_create_seed`), generating a new key pair. You can
 107 calculate the public key sum without knowing the private key and vice versa by
 108 passing in `NULL` for the key you don't know. This is useful for enforcing
 109 randomness on a key pair by a third party while only knowing the public key,
 110 among other things.  Warning: the last bit of the scalar is ignored - if
 111 comparing scalars make sure to clear it with `scalar[31] &= 127`.
 112
 113
 114 ```c
 115 void ed25519_key_exchange(unsigned char *shared_secret,
 116                           const unsigned char *public_key, const unsigned char *private_key);
 117 ```
 118
 119 Performs a key exchange on the given public key and private key, producing a
 120 shared secret. It is recommended to hash the shared secret before using it.
 121 `shared_secret` must be a 32 byte writable buffer where the shared secret will
 122 be stored.
 123
 124 Example
 125 -------
 126
 127 ```c
 128 unsigned char seed[32], public_key[32], private_key[64], signature[64];
 129 unsigned char other_public_key[32], other_private_key[64], shared_secret[32];
 130 const unsigned char message[] = "TEST MESSAGE";
 131
 132 /* create a random seed, and a key pair out of that seed */
 133 if (ed25519_create_seed(seed)) {
 134     printf("error while generating seed\n");
 135     exit(1);
 136 }
 137
 138 ed25519_create_keypair(public_key, private_key, seed);
 139
 140 /* create signature on the message with the key pair */
 141 ed25519_sign(signature, message, strlen(message), public_key, private_key);
 142
 143 /* verify the signature */
 144 if (ed25519_verify(signature, message, strlen(message), public_key)) {
 145     printf("valid signature\n");
 146 } else {
 147     printf("invalid signature\n");
 148 }
 149
 150 /* create a dummy keypair to use for a key exchange, normally you'd only have
 151 the public key and receive it through some communication channel */
 152 if (ed25519_create_seed(seed)) {
 153     printf("error while generating seed\n");
 154     exit(1);
 155 }
 156
 157 ed25519_create_keypair(other_public_key, other_private_key, seed);
 158
 159 /* do a key exchange with other_public_key */
 160 ed25519_key_exchange(shared_secret, other_public_key, private_key);
 161
 162 /*
 163     the magic here is that ed25519_key_exchange(shared_secret, public_key,
 164     other_private_key); would result in the same shared_secret
 165 */
 166
 167 ```
 168
 169 License
 170 -------
 171 All code is released under the zlib license. See license.txt for details.