idnits 2.17.1 draft-irtf-cfrg-eddsa-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1079: '...same private key MUST NOT be used for ...' RFC 2119 keyword, line 1087: '...it, the receiver MUST buffer the entir...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 9, 2015) is 3060 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '0' on line 1348 -- Looks like a reference, but probably isn't: '31' on line 398 -- Looks like a reference, but probably isn't: '1' on line 1349 -- Looks like a reference, but probably isn't: '32' on line 503 -- Looks like a reference, but probably isn't: '63' on line 503 -- Looks like a reference, but probably isn't: '8' on line 533 == Missing Reference: 'S' is mentioned on line 694, but not defined -- Looks like a reference, but probably isn't: '56' on line 569 -- Looks like a reference, but probably isn't: '57' on line 664 -- Looks like a reference, but probably isn't: '113' on line 664 -- Looks like a reference, but probably isn't: '4' on line 694 -- Looks like a reference, but probably isn't: '3' on line 1351 -- Looks like a reference, but probably isn't: '2' on line 1350 ** Obsolete normative reference: RFC 4634 (Obsoleted by RFC 6234) == Outdated reference: A later version (-11) exists of draft-irtf-cfrg-curves-10 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 14 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Josefsson 3 Internet-Draft SJD AB 4 Intended status: Informational I. Liusvaara 5 Expires: June 11, 2016 Independent 6 December 9, 2015 8 Edwards-curve Digital Signature Algorithm (EdDSA) 9 draft-irtf-cfrg-eddsa-01 11 Abstract 13 The elliptic curve signature scheme Edwards-curve Digital Signature 14 Algorithm (EdDSA) is described. The algorithm is instantiated with 15 recommended parameters for the Curve25519 and Curve448 curves. An 16 example implementation and test vectors are provided. 18 NOTE: Anything not about Ed25519 in this document is premature and 19 there is at least one FIXME that makes some things unimplementable. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on June 11, 2016. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Notation and Conventions . . . . . . . . . . . . . . . . . . 4 57 3. EdDSA Algorithm . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3.2. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3.3. Sign . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 3.4. Verify . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4. PureEdDSA, HashEdDSA and Naming . . . . . . . . . . . . . . . 7 63 5. EdDSA Instances . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.1. Ed25519ph and Ed25519 . . . . . . . . . . . . . . . . . . 8 65 5.1.1. Modular arithmetic . . . . . . . . . . . . . . . . . 8 66 5.1.2. Encoding . . . . . . . . . . . . . . . . . . . . . . 9 67 5.1.3. Decoding . . . . . . . . . . . . . . . . . . . . . . 9 68 5.1.4. Point addition . . . . . . . . . . . . . . . . . . . 10 69 5.1.5. Key Generation . . . . . . . . . . . . . . . . . . . 10 70 5.1.6. Sign . . . . . . . . . . . . . . . . . . . . . . . . 11 71 5.1.7. Verify . . . . . . . . . . . . . . . . . . . . . . . 12 72 5.2. Ed448ph and Ed448 . . . . . . . . . . . . . . . . . . . . 12 73 5.2.1. Modular arithmetic . . . . . . . . . . . . . . . . . 12 74 5.2.2. Encoding . . . . . . . . . . . . . . . . . . . . . . 12 75 5.2.3. Decoding . . . . . . . . . . . . . . . . . . . . . . 13 76 5.2.4. Point addition . . . . . . . . . . . . . . . . . . . 13 77 5.2.5. Key Generation . . . . . . . . . . . . . . . . . . . 14 78 5.2.6. Sign . . . . . . . . . . . . . . . . . . . . . . . . 14 79 5.2.7. Verify . . . . . . . . . . . . . . . . . . . . . . . 15 80 6. Ed25519 Python illustration . . . . . . . . . . . . . . . . . 15 81 7. Test Vectors . . . . . . . . . . . . . . . . . . . . . . . . 20 82 7.1. Test Vectors for Ed25519 . . . . . . . . . . . . . . . . 20 83 7.2. Test Vectors for Ed25519ph . . . . . . . . . . . . . . . 23 84 7.3. Test Vectors for Ed448 . . . . . . . . . . . . . . . . . 23 85 7.4. Test Vectors for Ed448ph . . . . . . . . . . . . . . . . 23 86 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 88 10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 89 10.1. Side-channel leaks . . . . . . . . . . . . . . . . . . . 23 90 10.2. Mixing different prehashes . . . . . . . . . . . . . . . 24 91 10.3. Signing large amounts of data at once . . . . . . . . . 24 92 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 93 11.1. Normative References . . . . . . . . . . . . . . . . . . 25 94 11.2. Informative References . . . . . . . . . . . . . . . . . 25 95 Appendix A. Ed25519 Python Library . . . . . . . . . . . . . . . 26 96 Appendix B. Library driver . . . . . . . . . . . . . . . . . . . 29 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 99 1. Introduction 101 The Edwards-curve Digital Signature Algorithm (EdDSA) is a variant of 102 Schnorr's signature system with (possibly Twisted) Edwards curves. 103 EdDSA needs to be instantiated with certain parameters and this 104 document describe some recommended variants. 106 To facilitate adoption in the Internet community of EdDSA, this 107 document describe the signature scheme in an implementation-oriented 108 way, and provide sample code and test vectors. 110 The advantages with EdDSA include: 112 1. High-performance on a variety of platforms. 114 2. Does not require the use of a unique random number for each 115 signature. 117 3. More resilient to side-channel attacks. 119 4. Small public keys (32 or 57 bytes) and signatures (64 or 114 120 bytes). 122 5. The formulas are "strongly unified", i.e., they are valid for all 123 points on the curve, with no exceptions. This obviates the need 124 for EdDSA to perform expensive point validation on untrusted 125 public values. 127 6. Collision resilience, meaning that hash-function collisions do 128 not break this system. (Only holds for PureEdDSA.) 130 The original EdDSA paper [EDDSA] and the generalized version 131 described in "EdDSA for more curves" [EDDSA2] provide further 132 background. The [I-D.irtf-cfrg-curves] document discuss specific 133 curves, including Curve25519 [CURVE25519] and Ed448-Goldilocks 134 [ED448]. 136 Ed25519 is intended to operate at around the 128-bit security level, 137 and Ed448 at around the 224-bit security level. A large quantum 138 computer would be able to break both. Reasonable projections of the 139 abilities of classical computers conclude that Ed25519 is perfectly 140 safe. Ed448 is provided for those applications with relaxed 141 performance requirements and where there is a desire to hedge against 142 analytical attacks on elliptic curves. 144 2. Notation and Conventions 146 FIXME: make sure this is aligned with irtf-cfrg-curves 148 The following notation is used throughout the document: 150 GF(p) --- finite field with p elements 152 x^y --- x multiplied by itself y times 154 B --- generator of the group or subgroup of interest 156 [n]B --- B added to itself n times. 158 h_i --- the i'th bit of h 160 a || b --- (bit-)string a concatenated with (bit-)string b 162 a <= b --- a is less than or equal to b 164 i+j --- sum of i and j 166 i*j --- multiplication of i and j 168 i x j --- cartesian product of i and j 170 Use of parenthesis (i.e., '(' and ')') are used to group expressions, 171 in order to avoid having the description depend on a binding order 172 between operators. 174 Bit strings are converted to octet strings by taking bits from left 175 to right and packing those from least significant bit of each octet 176 to most siginficant bit, and moving to the next octet when each octet 177 fills up. The conversion from octet string to bit string is the 178 reverse of this process. E.g. the 16-bit bit string: 180 b0 b1 b2 b3 b4 b5 b6 b7 b8 b9 b10 b11 b12 b13 b14 b15 182 Is converted into two octets x0 and x1 (in this order) as: 184 x0 = b7*128+b6*64+b5*32+b4*16+b3*8+b2*4+b1*2+b0 185 x1 = b15*128+b14*64+b13*32+b12*16+b11*8+b10*4+b9*2+b8 187 Little-endian encoding into bits places bits from left to right from 188 least significant to most significant. If combined with bit string 189 to octet string conversion defined above, this results in little- 190 endian encoding into octets (if length is not multiple of 8, the most 191 significant bits of last octet remain unused). 193 3. EdDSA Algorithm 195 EdDSA is a digital signature system with eleven parameters. 197 The generic EdDSA digital signature system with its eleven input 198 parameters is not intended to be implemented directly. Chosing 199 parameters is critical for secure and efficient operation. Instead, 200 you would implement a particular parameter choice for EdDSA (such as 201 Ed25519 or Ed448), sometimes slightly generalized to achieve code re- 202 use to cover Ed25519 and Ed448. 204 Therefore, a precise explanation of the generic EdDSA is thus not 205 particularly useful for implementers. For background and 206 completeness, a succinct description of the generic EdDSA algorithm 207 is given here. 209 The definition of some parameters, such as n and c, may help to 210 explain some non-intuitive steps of the algorithm. 212 This description closely follows [EDDSA2]. 214 EdDSA has eleven parameters: 216 1. An odd prime power p. EdDSA uses an elliptic curve over the 217 finite field GF(p). 219 2. An integer b with 2^(b-1) > p. EdDSA public keys have exactly b 220 bits, and EdDSA signatures have exactly 2*b bits. b is 221 recommended to be multiple of 8, so public key and signature 222 lengths are integral number of octets. 224 3. A (b-1)-bit encoding of elements of the finite field GF(p). 226 4. A cryptographic hash function H producing 2*b-bit output. 227 Conservative hash functions are recommended and do not have much 228 impact on the total cost of EdDSA. 230 5. An integer c that is 2 or 3. Secret EdDSA scalars are multiples 231 of 2^c. The integer c is the base-2 logarithm of the so called 232 cofactor. 234 6. An integer n with c <= n < b. Secret EdDSA scalars have exactly 235 n + 1 bits, with the top bit (the 2^n position) always set and 236 the bottom c bits always cleared. 238 7. A nonzero square element a of GF(p). The usual recommendation 239 for best performance is a = -1 if p mod 4 = 1, and a = 1 if p 240 mod 4 = 3. 242 8. An element B != (0,1) of the set E = { (x,y) is a member of 243 GF(p) x GF(p) such that a * x^2 + y^2 = 1 + d * x^2 * y^2 }. 245 9. An odd prime l such that [l]B = 0 and 2^c * l = #E. The number 246 #E (the number of points on the curve) is part of the standard 247 data provided for an elliptic curve E. 249 10. A "prehash" function PH. PureEdDSA means EdDSA where PH is the 250 identity function, i.e., PH(M) = M. HashEdDSA means EdDSA where 251 PH generates a short output, no matter how long the message is; 252 for example, PH(M) = SHA-512(M). 254 Points on the curve form a group under addition, (x3, y3) = (x1, y1) 255 + (x2, y2), with the formulas 257 x1 * y2 + x2 * y1 y1 * y2 - a * x1 * x2 258 x3 = --------------------------, y3 = --------------------------- 259 1 + d * x1 * x2 * y1 * y2 1 - d * x1 * x2 * y1 * y2 261 The neutral element in the group is (0, 1). 263 Unlike many other curves used for cryptographic applications, these 264 formulas are "strongly unified": they are valid for all points on the 265 curve, with no exceptions. In particular, the denominators are non- 266 zero for all input points. 268 There are more efficient formulas, which are still strongly unified, 269 which use homogeneous coordinates to avoid the expensive modulo p 270 inversions. See [Faster-ECC] and [Edwards-revisited]. 272 3.1. Encoding 274 An integer 0 < S < l - 1 is encoded in little-endian form as a b-bit 275 string ENC(S). 277 An element (x,y) of E is encoded as a b-bit string called ENC(x,y) 278 which is the (b-1)-bit encoding of y concatenated with one bit that 279 is 1 if x is negative and 0 if x is not negative. 281 The encoding of GF(p) is used to define "negative" elements of GF(p): 282 specifically, x is negative if the (b-1)-bit encoding of x is 283 lexicographically larger than the (b-1)-bit encoding of -x. 285 3.2. Keys 287 An EdDSA secret key is a b-bit string k. Let the hash H(k) = (h_0, 288 h_1, ..., h_(2b-1)) determine an integer s which is 2^n plus the sum 289 of m = 2^i * h_i for all integer i, c <= i <= n. Let s determine the 290 multiple A = [s]B. The EdDSA public key is ENC(A). The bits h_b, 291 ..., h_(2b-1) is used below during signing. 293 3.3. Sign 295 The EdDSA signature of a message M under a secret key k is defined as 296 the PureEdDSA signature of PH(M). In other words, EdDSA simply uses 297 PureEdDSA to sign PH(M). 299 The PureEdDSA signature of a message M under a secret key k is the 300 2*b-bit string ENC(R) || ENC(S). R and S are derived as follows. 301 First define r = H(h_b, ... h_(2b-1), M) interpreting 2*b-bit strings 302 in little-endian form as integers in {0, 1, ..., 2^(2*b) - 1}. Let R 303 = [r]B and S = (r + H(ENC(R) || ENC(A) || P(M)) s) mod l. The s used 304 here is from the previous section. 306 3.4. Verify 308 To verify a PureEdDSA signature ENC(R) || ENC(S) on a message M under 309 a public key ENC(A), proceed as follows. Parse the inputs so that A 310 and R is an element of E, and S is a member of the set {0, 1, ..., 311 l-1 }. Compute h = H(ENC(R) || ENC(A) || M) and check the group 312 equation [2^c * S] B = 2^c * R + [2^c * h] A in E. Verification is 313 rejected if parsing fails or the group equation does not hold. 315 EdDSA verification for a message M is defined as PureEdDSA 316 verification for PH(M). 318 4. PureEdDSA, HashEdDSA and Naming 320 One of the parameters of the EdDSA algorithm is the "prehash" 321 function. This may be the identity function, resulting in an 322 algorithm called PureEdDSA, or a collision-resistant hash function 323 such as SHA-512, resulting in an algorithm called HashEdDSA. 325 Chosing which variant to use depends on which property is deemed to 326 be more important between 1) collision resilience, and 2) a single- 327 pass interface for creating signatures. The collision resilience 328 property means EdDSA is secure even if it is feasible to compute 329 collisions for the hash function. The single-pass interface property 330 means that only one pass over the input message is required to create 331 a signature. PureEdDSA requires two passes over the input. Many 332 existing APIs, protocols and environments assume digital signature 333 algorithms only need one pass over the input, and may have API or 334 bandwidth concerns supporting anything else. 336 Note that single-pass verification is not possible with most uses of 337 signatures, no matter which signature algorithm is chosen. This is 338 because most of the time one can't process the message until 339 signature is validated, which needs a pass on the entire message. 341 This document specify parameters resulting in the HashEdDSA variants 342 Ed25519ph and Ed448ph, and the PureEdDSA variants Ed25519 and Ed448. 344 5. EdDSA Instances 346 This section instantiate the general EdDSA algorithm for the 347 Curve25519 and Ed448 curves, each for the PureEdDSA and HashEdDSA 348 variants. Thus four different parameter sets are described. 350 5.1. Ed25519ph and Ed25519 352 Ed25519 is PureEdDSA instantiated with: p as the prime 2^255-19, 353 b=256, the 255-bit encoding of GF(p) being the little-endian encoding 354 of {0, 1, ..., p-1}, H being SHA-512 [RFC4634], c being 3, n being 355 254, a being -1, d = -121665/121666 which is a member of GF(p), and B 356 is the unique point (x, 4/5) in E for which x is "positive", which 357 with the encoding used simply means that the least significant bit of 358 x is 0, l is the prime 2^252 + 359 27742317777372353535851937790883648493. 361 Ed25519ph is the same but with PH being SHA-512 instead, i.e., the 362 input is hashed using SHA-512 before signing with Ed25519. 364 Written out explicitly, B is the point (15112221349535400772501151409 365 588531511454012693041857206046113283949847762202, 4631683569492647816 366 9428394003475163141307993866256225615783033603165251855960). 368 The values for p, a, d, B and l follows from the "edwards25519" 369 values in [I-D.irtf-cfrg-curves]. 371 The curve used is equivalent to Curve25519 [CURVE25519], under a 372 change of coordinates, which means that the difficulty of the 373 discrete logarithm problem is the same as for Curve25519. 375 5.1.1. Modular arithmetic 377 For advise on how to implement arithmetic modulo p = 2^255 - 19 378 efficiently and securely, see Curve25519 [CURVE25519]. For inversion 379 modulo p, it is recommended to use the identity x^-1 = x^(p-2) (mod 380 p). 382 For point decoding or "decompression", square roots modulo p are 383 needed. They can be computed using the Tonelli-Shanks algorithm, or 384 the special case for p = 5 (mod 8). To find a square root of a, 385 first compute the candidate root x = a^((p+3)/8) (mod p). Then there 386 are three cases: 388 x^2 = a (mod p). Then x is a square root. 390 x^2 = -a (mod p). Then 2^((p-1)/4) x is a square root. 392 a is not a square modulo p. 394 5.1.2. Encoding 396 All values are coded as octet strings, and integers are coded using 397 little endian convention. I.e., a 32-octet string h h[0],...h[31] 398 represents the integer h[0] + 2^8 h[1] + ... + 2^248 h[31]. 400 A curve point (x,y), with coordinates in the range 0 <= x,y < p, is 401 coded as follows. First encode the y-coordinate as a little-endian 402 string of 32 octets. The most significant bit of the final octet is 403 always zero. To form the encoding of the point, copy the least 404 significant bit of the x-coordinate to the most significant bit of 405 the final octet. 407 5.1.3. Decoding 409 Decoding a point, given as a 32-octet string, is a little more 410 complicated. 412 1. First interpret the string as an integer in little-endian 413 representation. Bit 255 of this number is the least significant 414 bit of the x-coordinate, and denote this value x_0. The 415 y-coordinate is recovered simply by clearing this bit. If the 416 resulting value is >= p, decoding fails. 418 2. To recover the x coordinate, the curve equation implies x^2 = 419 (y^2 - 1) / (d y^2 + 1) (mod p). The denominator is always 420 nonzero mod p. Let u = y^2 - 1 and v = d y^2 + 1. To compute 421 the square root of (u/v), the first step is to compute the 422 candidate root x = (u/v)^((p+3)/8). This can be done using the 423 following trick, to use a single modular powering for both the 424 inversion of v and the square root: 426 (p+3)/8 3 (p-5)/8 427 x = (u/v) = u v (u v^7) (mod p) 429 3. Again, there are three cases: 431 1. If v x^2 = u (mod p), x is a square root. 433 2. If v x^2 = -u (mod p), set x <-- x 2^((p-1)/4), which is a 434 square root. 436 3. Otherwise, no square root exists modulo p, and decoding 437 fails. 439 4. Finally, use the x_0 bit to select the right square root. If x = 440 0, and x_0 = 1, decoding fails. Otherwise, if x_0 != x mod 2, 441 set x <-- p - x. Return the decoded point (x,y). 443 5.1.4. Point addition 445 For point addition, the following method is recommended. A point 446 (x,y) is represented in extended homogeneous coordinates (X, Y, Z, 447 T), with x = X/Z, y = Y/Z, x y = T/Z. 449 The following formulas for adding two points, (x3,y3) = 450 (x1,y1)+(x2,y2) are described in [Edwards-revisited], section 3.1. 451 They are strongly unified, i.e., they work for any pair of valid 452 input points. 454 A = (Y1-X1)*(Y2-X2) 455 B = (Y1+X1)*(Y2+X2) 456 C = T1*2*d*T2 457 D = Z1*2*Z2 458 E = B-A 459 F = D-C 460 G = D+C 461 H = B+A 462 X3 = E*F 463 Y3 = G*H 464 T3 = E*H 465 Z3 = F*G 467 5.1.5. Key Generation 469 The secret is 32 octets (256 bits, corresponding to b) of 470 cryptographically-secure random data. See [RFC4086] for a discussion 471 about randomness. 473 The 32-byte public key is generated by the following steps. 475 1. Hash the 32-byte secret using SHA-512, storing the digest in a 476 64-octet large buffer, denoted h. Only the lower 32 bytes are 477 used for generating the public key. 479 2. Prune the buffer: The lowest 3 bits of the first octet are 480 cleared, the highest bit of the last octet is cleared, and second 481 highest bit of the last octet is set. 483 3. Interpret the buffer as the little-endian integer, forming a 484 secret scalar a. Perform a fixed-base scalar multiplication 485 [a]B. 487 4. The public key A is the encoding of the point [a]B. First encode 488 the y coordinate (in the range 0 <= y < p) as a little-endian 489 string of 32 octets. The most significant bit of the final octet 490 is always zero. To form the encoding of the point [a]B, copy the 491 least significant bit of the x coordinate to the most significant 492 bit of the final octet. The result is the public key. 494 5.1.6. Sign 496 The inputs to the signing procedure is the secret key, a 32-octet 497 string, and a message M of arbitrary size. 499 1. Hash the secret key, 32-octets, using SHA-512. Let h denote the 500 resulting digest. Construct the secret scalar a from the first 501 half of the digest, and the corresponding public key A, as 502 described in the previous section. Let prefix denote the second 503 half of the hash digest, h[32],...,h[63]. 505 2. Compute SHA-512(prefix || M), where M is the message to be 506 signed. Interpret the 64-octet digest as a little-endian integer 507 r. 509 3. Compute the point [r]B. For efficiency, do this by first 510 reducing r modulo l, the group order of B. Let the string R be 511 the encoding of this point. 513 4. Compute SHA512(R || A || M), and interpret the 64-octet digest as 514 a little-endian integer k. 516 5. Compute S = (r + k * a) mod l. For efficiency, again reduce k 517 modulo l first. 519 6. Form the signature of the concatenation of R (32 octets) and the 520 little-endian encoding of S (32 octets, three most significant 521 bits of the final octet are always zero). 523 5.1.7. Verify 525 1. To verify a signature on a message M, first split the signature 526 into two 32-octet halves. Decode the first half as a point R, 527 and the second half as an integer S, in the range 0 <= s < l. If 528 the decoding fails, the signature is invalid. 530 2. Compute SHA512(R || A || M), and interpret the 64-octet digest as 531 a little-endian integer k. 533 3. Check the group equation [8][S]B = [8]R + [8][k]A. It's 534 sufficient, but not required, to instead check [S]B = R + [k]A. 536 5.2. Ed448ph and Ed448 538 Ed448 is PureEdDSA instantiated with p as the prime 2^448 - 2^224 - 539 1, b=456, the 455-bit encoding of GF(2^448-2^224-1) is the usual 540 little-endian encoding of {0, 1, ..., 2^448 - 2^224 - 2}, H is 541 [FIXME: needs 912-bit hash], c being 2, n being 448, a being 1, d 542 being - 39081, B is (X(P), Y(P)), and l is the prime 2^446 - 543 13818066809895115352007386748515426880336692474882178609894547503885. 545 Ed448ph is the same but with P being SHA-512 instead, i.e., the input 546 is hashed using SHA-512 before signing with Ed448. 548 The values of p, a, d, X(p), Y(p), and l are taken from curve named 549 "edwards448" in [I-D.irtf-cfrg-curves]. 551 The curve is equivalent to Ed448-Goldilocks under change of 552 basepoint, which preserves difficulty of the discrete logarithm. 554 5.2.1. Modular arithmetic 556 For advise on how to implement arithmetic modulo p = 2^448 - 2^224 - 557 1 efficiently and securely, see [ED448]. For inversion modulo p, it 558 is recommended to use the identity x^-1 = x^(p-2) (mod p). 560 For point decoding or "decompression", square roots modulo p are 561 needed. They can be computed by first computing candidate root x = a 562 ^ (p+1)/4 (mod p) and then checking if x^2 = a. If it is, then x is 563 square root of a. 565 5.2.2. Encoding 567 All values are coded as octet strings, and integers are coded using 568 little endian convention. I.e., a 57-octet string h h[0],...h[56] 569 represents the integer h[0] + 2^8 h[1] + ... + 2^448 h[56]. 571 A curve point (x,y), with coordinates in the range 0 <= x,y < p, is 572 coded as follows. First encode the y-coordinate as a little-endian 573 string of 57 octets. The final octet is always zero. To form the 574 encoding of the point, copy the least significant bit of the 575 x-coordinate to the most significant bit of the final octet. 577 5.2.3. Decoding 579 Decoding a point, given as a 57-octet string, is a little more 580 complicated. 582 1. First interpret the string as an integer in little-endian 583 representation. Bit 455 of this number is the least significant 584 bit of the x-coordinate, and denote this value x_0. The 585 y-coordinate is recovered simply by clearing this bit. If the 586 resulting value is >= p, decoding fails. 588 2. To recover the x coordinate, the curve equation implies x^2 = 589 (y^2 - 1) / (d y^2 - 1) (mod p). The denominator is always 590 nonzero mod p. Let u = y^2 - 1 and v = d y^2 - 1. To compute 591 the square root of (u/v), the first step is to compute the 592 candidate root x = (u/v)^((p+1)/4). This can be done using the 593 following trick, to use a single modular powering for both the 594 inversion of v and the square root: 596 (p+1)/4 3 (p-3)/4 597 x = (u/v) = u v (u^5 v^3) (mod p) 599 3. If v * x^2 = u, the recovered x coordinate is x. Otherwise no 600 square root exists, and the decoding fails. 602 4. Finally, use the x_0 bit to select the right square root. If x = 603 0, and x_0 = 1, decoding fails. Otherwise, if x_0 != x mod 2, 604 set x <-- p - x. Return the decoded point (x,y). 606 5.2.4. Point addition 608 For point addition, the following method is recommended. A point 609 (x,y) is represented in projective coordinates (X, Y, Z), with x = X/ 610 Z, y = Y/Z. 612 The following formulas for adding two points, (x3,y3) = 613 (x1,y1)+(x2,y2) are described in [FIXME: Add reference]. They are 614 strongly unified, i.e., they work for any pair of valid input points. 616 A = Z1*Z2 617 B = A^2 618 C = X1*X2 619 D = Y1*Y2 620 E = d*C*D 621 F = B-E 622 G = B+E 623 H = (X1+X2)*(Y1+Y2) 624 X3 = A*G*(H-C-D) 625 Y3 = A*G*(D-C) 626 Z3 = F*G 628 5.2.5. Key Generation 630 The secret is 57 octets (456 bits, corresponding to b) of 631 cryptographically-secure random data. See [RFC4086] for a discussion 632 about randomness. 634 The 57-byte public key is generated by the following steps. 636 1. Hash the 57-byte secret using FIXME-HASH, storing the digest in a 637 114-octet large buffer, denoted h. Only the lower 57 bytes are 638 used for generating the public key. 640 2. Prune the buffer: The two least significant bits of the first 641 octet are cleared, all 8 bits the last octet are cleared, and the 642 highest bit of the second to last octet is set. 644 3. Interpret the buffer as the little-endian integer, forming a 645 secret scalar a. Perform a known-base-point scalar 646 multiplication [a]B. 648 4. The public key A is the encoding of the point [a]B. First encode 649 the y coordinate (in the range 0 <= y < p) as a little-endian 650 string of 57 octets. The most significant bit of the final octet 651 is always zero. To form the encoding of the point [a]B, copy the 652 least significant bit of the x coordinate to the most significant 653 bit of the final octet. The result is the public key. 655 5.2.6. Sign 657 The inputs to the signing procedure is the secret key, a 32-octet 658 string, and a message M of arbitrary size. 660 1. Hash the secret key, 57-octets, using FIXME-HASH. Let h denote 661 the resulting digest. Construct the secret scalar a from the 662 first half of the digest, and the corresponding public key A, as 663 described in the previous section. Let prefix denote the second 664 half of the hash digest, h[57],...,h[113]. 666 2. Compute FIXME-HASH(prefix || M), where M is the message to be 667 signed. Interpret the 114-octet digest as a little- endian 668 integer r. 670 3. Compute the point [r]B. For efficiency, do this by first 671 reducing r modulo l, the group order of B. Let the string R be 672 the encoding of this point. 674 4. Compute FIXME-HASH(R || A || M), and interpret the 114- octet 675 digest as a little-endian integer k. 677 5. Compute S = (r + k * a) mod l. For efficiency, again reduce k 678 modulo l first. 680 6. Form the signature of the concatenation of R (57 octets) and the 681 little-endian encoding of S (57 octets, ten most significant bits 682 of the final octets always zero). 684 5.2.7. Verify 686 1. To verify a signature on a message M, first split the signature 687 into two 57-octet halves. Decode the first half as a point R, 688 and the second half as an integer S, in the range 0 <= s < l. If 689 the decoding fails, the signature is invalid. 691 2. Compute FIXME-HASH(R || A || M), and interpret the 114-octet 692 digest as a little-endian integer k. 694 3. Check the group equation [4][S]B = [4]R + [4][k]A. It's 695 sufficient, but not required, to instead check [S]B = R + [k]A. 697 6. Ed25519 Python illustration 699 The rest of this section describes how Ed25519 can be implemented in 700 Python (version 3.2 or later) for illustration. See appendix A for 701 the complete implementation and appendix B for a test-driver to run 702 it through some test vectors. 704 Note that this code is not intended for production as it is not 705 proven to be correct for all inputs, nor does it protect against 706 side-channel attacks. The purpose is to illustrate the algorithm to 707 help implementers with their own implementation. 709 First some preliminaries that will be needed. 711 import hashlib 713 def sha512(s): 714 return hashlib.sha512(s).digest() 716 # Base field Z_p 717 p = 2**255 - 19 719 def modp_inv(x): 720 return pow(x, p-2, p) 722 # Curve constant 723 d = -121665 * modp_inv(121666) % p 725 # Group order 726 q = 2**252 + 27742317777372353535851937790883648493 728 def sha512_modq(s): 729 return int.from_bytes(sha512(s), "little") % q 731 Then follows functions to perform point operations. 733 # Points are represented as tuples (X, Y, Z, T) of extended coordinates, 734 # with x = X/Z, y = Y/Z, x*y = T/Z 736 def point_add(P, Q): 737 A = (P[1]-P[0])*(Q[1]-Q[0]) % p 738 B = (P[1]+P[0])*(Q[1]+Q[0]) % p 739 C = 2 * P[3] * Q[3] * d % p 740 D = 2 * P[2] * Q[2] % p 741 E = B-A 742 F = D-C 743 G = D+C 744 H = B+A 745 return (E*F, G*H, F*G, E*H) 747 # Computes Q = s * Q 748 def point_mul(s, P): 749 Q = (0, 1, 1, 0) # Neutral element 750 while s > 0: 751 # Is there any bit-set predicate? 752 if s & 1: 753 Q = point_add(Q, P) 754 P = point_add(P, P) 755 s >>= 1 756 return Q 758 def point_equal(P, Q): 759 # x1 / z1 == x2 / z2 <==> x1 * z2 == x2 * z1 760 if (P[0] * Q[2] - Q[0] * P[2]) % p != 0: 761 return False 762 if (P[1] * Q[2] - Q[1] * P[2]) % p != 0: 763 return False 764 return True 766 Now follows functions for point compression. 768 # Square root of -1 769 modp_sqrt_m1 = pow(2, (p-1) // 4, p) 771 # Compute corresponding x coordinate, with low bit corresponding to sign, 772 # or return None on failure 773 def recover_x(y, sign): 774 x2 = (y*y-1) * modp_inv(d*y*y+1) 775 if x2 == 0: 776 if sign: 777 return None 778 else: 779 return 0 781 # Compute square root of x2 782 x = pow(x2, (p+3) // 8, p) 783 if (x*x - x2) % p != 0: 784 x = x * modp_sqrt_m1 % p 785 if (x*x - x2) % p != 0: 786 return None 788 if (x & 1) != sign: 789 x = p - x 790 return x 792 # Base point 793 g_y = 4 * modp_inv(5) % p 794 g_x = recover_x(g_y, 0) 795 G = (g_x, g_y, 1, g_x * g_y % p) 797 def point_compress(P): 798 zinv = modp_inv(P[2]) 799 x = P[0] * zinv % p 800 y = P[1] * zinv % p 801 return int.to_bytes(y | ((x & 1) << 255), 32, "little") 803 def point_decompress(s): 804 if len(s) != 32: 805 raise Exception("Invalid input length for decompression") 806 y = int.from_bytes(s, "little") 807 sign = y >> 255 808 y &= (1 << 255) - 1 810 x = recover_x(y, sign) 811 if x is None: 812 return None 813 else: 814 return (x, y, 1, x*y % p) 816 These are functions for manipulating the secret. 818 def secret_expand(secret): 819 if len(secret) != 32: 820 raise Exception("Bad size of private key") 821 h = sha512(secret) 822 a = int.from_bytes(h[:32], "little") 823 a &= (1 << 254) - 8 824 a |= (1 << 254) 825 return (a, h[32:]) 827 def secret_to_public(secret): 828 (a, dummy) = secret_expand(secret) 829 return point_compress(point_mul(a, G)) 831 The signature function works as below. 833 def sign(secret, msg): 834 a, prefix = secret_expand(secret) 835 A = point_compress(point_mul(a, G)) 836 r = sha512_modq(prefix + msg) 837 R = point_mul(r, G) 838 Rs = point_compress(R) 839 h = sha512_modq(Rs + A + msg) 840 s = (r + h * a) % q 841 return Rs + int.to_bytes(s, 32, "little") 843 And finally the verification function. 845 def verify(public, msg, signature): 846 if len(public) != 32: 847 raise Exception("Bad public-key length") 848 if len(signature) != 64: 849 Exception("Bad signature length") 850 A = point_decompress(public) 851 if not A: 852 return False 853 Rs = signature[:32] 854 R = point_decompress(Rs) 855 if not R: 856 return False 857 s = int.from_bytes(signature[32:], "little") 858 h = sha512_modq(Rs + public + msg) 859 sB = point_mul(s, G) 860 hA = point_mul(h, A) 861 return point_equal(sB, point_add(R, hA)) 863 7. Test Vectors 865 This section contains test vectors for Ed25519ph, Ed448ph, Ed25519 866 and Ed448. 868 Each section contains sequence of test vectors. The octets are hex 869 encoded and whitespace is inserted for readability Ed25519 and 870 Ed25519ph private and public keys 32 octets, signatures are 64 871 octets. Ed448 and Ed448ph private and public keys are 57 octets, 872 signatures are 114 octets. Messages are of arbitrary length. 874 7.1. Test Vectors for Ed25519 876 These test vectors are taken from [ED25519-TEST-VECTORS] (but we 877 removed the public key as a suffix of the secret key, and removed the 878 message from the signature) and [ED25519-LIBGCRYPT-TEST-VECTORS]. 880 -----TEST 1 881 SECRET KEY: 882 9d61b19deffd5a60ba844af492ec2cc4 883 4449c5697b326919703bac031cae7f60 885 PUBLIC KEY: 886 d75a980182b10ab7d54bfed3c964073a 887 0ee172f3daa62325af021a68f707511a 889 MESSAGE (length 0 bytes): 891 SIGNATURE: 892 e5564300c360ac729086e2cc806e828a 893 84877f1eb8e5d974d873e06522490155 894 5fb8821590a33bacc61e39701cf9b46b 895 d25bf5f0595bbe24655141438e7a100b 897 -----TEST 2 898 SECRET KEY: 899 4ccd089b28ff96da9db6c346ec114e0f 900 5b8a319f35aba624da8cf6ed4fb8a6fb 902 PUBLIC KEY: 903 3d4017c3e843895a92b70aa74d1b7ebc 904 9c982ccf2ec4968cc0cd55f12af4660c 906 MESSAGE (length 1 byte): 907 72 909 SIGNATURE: 910 92a009a9f0d4cab8720e820b5f642540 911 a2b27b5416503f8fb3762223ebdb69da 912 085ac1e43e15996e458f3613d0f11d8c 913 387b2eaeb4302aeeb00d291612bb0c00 915 -----TEST 3 916 SECRET KEY: 917 c5aa8df43f9f837bedb7442f31dcb7b1 918 66d38535076f094b85ce3a2e0b4458f7 920 PUBLIC KEY: 921 fc51cd8e6218a1a38da47ed00230f058 922 0816ed13ba3303ac5deb911548908025 924 MESSAGE (length 2 bytes): 925 af82 927 SIGNATURE: 928 6291d657deec24024827e69c3abe01a3 929 0ce548a284743a445e3680d7db5ac3ac 930 18ff9b538d16f290ae67f760984dc659 931 4a7c15e9716ed28dc027beceea1ec40a 933 -----TEST 1024 934 SECRET KEY: 935 f5e5767cf153319517630f226876b86c 936 8160cc583bc013744c6bf255f5cc0ee5 938 PUBLIC KEY: 939 278117fc144c72340f67d0f2316e8386 940 ceffbf2b2428c9c51fef7c597f1d426e 942 MESSAGE (length 1023 bytes): 943 08b8b2b733424243760fe426a4b54908 944 632110a66c2f6591eabd3345e3e4eb98 945 fa6e264bf09efe12ee50f8f54e9f77b1 946 e355f6c50544e23fb1433ddf73be84d8 947 79de7c0046dc4996d9e773f4bc9efe57 948 38829adb26c81b37c93a1b270b20329d 949 658675fc6ea534e0810a4432826bf58c 950 941efb65d57a338bbd2e26640f89ffbc 951 1a858efcb8550ee3a5e1998bd177e93a 952 7363c344fe6b199ee5d02e82d522c4fe 953 ba15452f80288a821a579116ec6dad2b 954 3b310da903401aa62100ab5d1a36553e 955 06203b33890cc9b832f79ef80560ccb9 956 a39ce767967ed628c6ad573cb116dbef 957 efd75499da96bd68a8a97b928a8bbc10 958 3b6621fcde2beca1231d206be6cd9ec7 959 aff6f6c94fcd7204ed3455c68c83f4a4 960 1da4af2b74ef5c53f1d8ac70bdcb7ed1 961 85ce81bd84359d44254d95629e9855a9 962 4a7c1958d1f8ada5d0532ed8a5aa3fb2 963 d17ba70eb6248e594e1a2297acbbb39d 964 502f1a8c6eb6f1ce22b3de1a1f40cc24 965 554119a831a9aad6079cad88425de6bd 966 e1a9187ebb6092cf67bf2b13fd65f270 967 88d78b7e883c8759d2c4f5c65adb7553 968 878ad575f9fad878e80a0c9ba63bcbcc 969 2732e69485bbc9c90bfbd62481d9089b 970 eccf80cfe2df16a2cf65bd92dd597b07 971 07e0917af48bbb75fed413d238f5555a 972 7a569d80c3414a8d0859dc65a46128ba 973 b27af87a71314f318c782b23ebfe808b 974 82b0ce26401d2e22f04d83d1255dc51a 975 ddd3b75a2b1ae0784504df543af8969b 976 e3ea7082ff7fc9888c144da2af58429e 977 c96031dbcad3dad9af0dcbaaaf268cb8 978 fcffead94f3c7ca495e056a9b47acdb7 979 51fb73e666c6c655ade8297297d07ad1 980 ba5e43f1bca32301651339e22904cc8c 981 42f58c30c04aafdb038dda0847dd988d 982 cda6f3bfd15c4b4c4525004aa06eeff8 983 ca61783aacec57fb3d1f92b0fe2fd1a8 984 5f6724517b65e614ad6808d6f6ee34df 985 f7310fdc82aebfd904b01e1dc54b2927 986 094b2db68d6f903b68401adebf5a7e08 987 d78ff4ef5d63653a65040cf9bfd4aca7 988 984a74d37145986780fc0b16ac451649 989 de6188a7dbdf191f64b5fc5e2ab47b57 990 f7f7276cd419c17a3ca8e1b939ae49e4 991 88acba6b965610b5480109c8b17b80e1 992 b7b750dfc7598d5d5011fd2dcc5600a3 993 2ef5b52a1ecc820e308aa342721aac09 994 43bf6686b64b2579376504ccc493d97e 995 6aed3fb0f9cd71a43dd497f01f17c0e2 996 cb3797aa2a2f256656168e6c496afc5f 997 b93246f6b1116398a346f1a641f3b041 998 e989f7914f90cc2c7fff357876e506b5 999 0d334ba77c225bc307ba537152f3f161 1000 0e4eafe595f6d9d90d11faa933a15ef1 1001 369546868a7f3a45a96768d40fd9d034 1002 12c091c6315cf4fde7cb68606937380d 1003 b2eaaa707b4c4185c32eddcdd306705e 1004 4dc1ffc872eeee475a64dfac86aba41c 1005 0618983f8741c5ef68d3a101e8a3b8ca 1006 c60c905c15fc910840b94c00a0b9d0 1007 SIGNATURE: 1008 0aab4c900501b3e24d7cdf4663326a3a 1009 87df5e4843b2cbdb67cbf6e460fec350 1010 aa5371b1508f9f4528ecea23c436d94b 1011 5e8fcd4f681e30a6ac00a9704a188a03 1012 ----- 1014 7.2. Test Vectors for Ed25519ph 1016 TODO 1018 7.3. Test Vectors for Ed448 1020 TODO 1022 7.4. Test Vectors for Ed448ph 1024 TODO 1026 8. Acknowledgements 1028 EdDSA and Ed25519 was initially described in a paper due to Daniel J. 1029 Bernstein, Niels Duif, Tanja Lange, Peter Schwabe and Bo-Yin Yang. 1030 The Ed448 curves is due to Mike Hamburg. 1032 This draft is based on an earlier draft co-authored by Niels Moeller. 1034 Feedback on this document was received from Werner Koch, Damien 1035 Miller, Bob Bradley, Franck Rondepierre, Alexey Melnikov, Kenny 1036 Paterson, and Robert Edmonds. 1038 The Ed25519 test vectors were double checked by Bob Bradley using 3 1039 separate implementations (one based on TweetNaCl and 2 different 1040 implementations based on code from SUPERCOP). 1042 9. IANA Considerations 1044 None. 1046 10. Security Considerations 1048 10.1. Side-channel leaks 1050 For implementations performing signatures, secrecy of the key is 1051 fundamental. It is possible to protect against some side-channel 1052 attacks by ensuring that the implementation executes exactly the same 1053 sequence of instructions and performs exactly the same memory 1054 accesses, for any value of the secret key. 1056 To make an implementation side-channel silent in this way, the modulo 1057 p arithmetic must not use any data-dependent branches, e.g., related 1058 to carry propagation. Side channel-silent point addition is 1059 straight-forward, thanks to the unified formulas. 1061 Scalar multiplication, multiplying a point by an integer, needs some 1062 additional effort to implement in a side-channel silent manner. One 1063 simple approach is to implement a side-channel silent conditional 1064 assignment, and use together with the binary algorithm to examine one 1065 bit of the integer at a time. 1067 Note that the example implementations in this document do not attempt 1068 to be side-channel silent. 1070 10.2. Mixing different prehashes 1072 Using the same key with different prehashes is a bad idea. The most 1073 obvious problem is that identity transform can produce message values 1074 colliding with hashes of interesting messages (or vice versa). 1075 Additionally, even if it is infeasible to find collisions in two hash 1076 functions, there is nothing guaranteeing that finding collisions 1077 between hashes is infeasible. 1079 For these reasons, the same private key MUST NOT be used for multiple 1080 algorithms (including prehashes) without protocol preventing messages 1081 output by different prehash algorithms from colliding. 1083 10.3. Signing large amounts of data at once 1085 Avoid signing large amounts of data at once (where "large" depends on 1086 expected verifier). In practicular, unless the underlying protocol 1087 does not require it, the receiver MUST buffer the entire message (or 1088 enough information to reconstruct it, e.g. compressed or encrypted 1089 version) to be verified. 1091 This is needed becuse most of the time, it is unsafe to process 1092 unverified data, and verifying the signature makes a pass through 1093 whole message, causing ultimately at least two passes through. 1095 As API consideration, this means that any IUF verification interface 1096 is prone to misuse. 1098 11. References 1099 11.1. Normative References 1101 [RFC4634] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms 1102 (SHA and HMAC-SHA)", RFC 4634, July 2006. 1104 [I-D.irtf-cfrg-curves] 1105 Langley, A. and M. Hamburg, "Elliptic Curves for 1106 Security", draft-irtf-cfrg-curves-10 (work in progress), 1107 October 2015. 1109 11.2. Informative References 1111 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1112 Requirements for Security", BCP 106, RFC 4086, June 2005. 1114 [EDDSA] Bernstein, D., Duif, N., Lange, T., Schwabe, P., and B. 1115 Yang, "High-speed high-security signatures", WWW 1116 http://ed25519.cr.yp.to/ed25519-20110926.pdf, September 1117 2011. 1119 [EDDSA2] Bernstein, D., Josefsson, S., Lange, T., Schwabe, P., and 1120 B. Yang, "EdDSA for more curves", WWW 1121 http://ed25519.cr.yp.to/eddsa-20150704.pdf, July 2015. 1123 [Faster-ECC] 1124 Bernstein, D. and T. Lange, "Faster addition and doubling 1125 on elliptic curves", WWW http://eprint.iacr.org/2007/286, 1126 July 2007. 1128 [Edwards-revisited] 1129 Hisil, H., Wong, K., Carter, G., and E. Dawson, "Twisted 1130 Edwards Curves Revisited", WWW 1131 http://eprint.iacr.org/2008/522, December 2008. 1133 [CURVE25519] 1134 Bernstein, D., "Curve25519: new Diffie-Hellman speed 1135 records", WWW http://cr.yp.to/ecdh.html, February 2006. 1137 [ED448] Hamburg, M., "Ed448-Goldilocks, a new elliptic curve", WWW 1138 http://eprint.iacr.org/2015/625, June 2015. 1140 [ED25519-TEST-VECTORS] 1141 Bernstein, D., Duif, N., Lange, T., Schwabe, P., and B. 1142 Yang, "Ed25519 test vectors", WWW 1143 http://ed25519.cr.yp.to/python/sign.input, July 2011. 1145 [ED25519-LIBGCRYPT-TEST-VECTORS] 1146 Koch, W., "Ed25519 Libgcrypt test vectors", WWW 1147 http://git.gnupg.org/cgi- 1148 bin/gitweb.cgi?p=libgcrypt.git;a=blob;f=tests/t-ed25519.in 1149 p;h=e13566f826321eece65e02c593bc7d885b3dbe23;hb=refs/ 1150 heads/master, July 2014. 1152 Appendix A. Ed25519 Python Library 1154 Below is an example implementation of Ed25519 written in Python, 1155 version 3.2 or higher is required. 1157 # Loosely based on the public domain code at 1158 # http://ed25519.cr.yp.to/software.html 1159 # 1160 # Needs python-3.2 1162 import hashlib 1164 def sha512(s): 1165 return hashlib.sha512(s).digest() 1167 # Base field Z_p 1168 p = 2**255 - 19 1170 def modp_inv(x): 1171 return pow(x, p-2, p) 1173 # Curve constant 1174 d = -121665 * modp_inv(121666) % p 1176 # Group order 1177 q = 2**252 + 27742317777372353535851937790883648493 1179 def sha512_modq(s): 1180 return int.from_bytes(sha512(s), "little") % q 1182 # Points are represented as tuples (X, Y, Z, T) of extended coordinates, 1183 # with x = X/Z, y = Y/Z, x*y = T/Z 1185 def point_add(P, Q): 1186 A = (P[1]-P[0])*(Q[1]-Q[0]) % p 1187 B = (P[1]+P[0])*(Q[1]+Q[0]) % p 1188 C = 2 * P[3] * Q[3] * d % p 1189 D = 2 * P[2] * Q[2] % p 1190 E = B-A 1191 F = D-C 1192 G = D+C 1193 H = B+A 1194 return (E*F, G*H, F*G, E*H) 1196 # Computes Q = s * Q 1197 def point_mul(s, P): 1198 Q = (0, 1, 1, 0) # Neutral element 1199 while s > 0: 1200 # Is there any bit-set predicate? 1201 if s & 1: 1202 Q = point_add(Q, P) 1203 P = point_add(P, P) 1204 s >>= 1 1205 return Q 1207 def point_equal(P, Q): 1208 # x1 / z1 == x2 / z2 <==> x1 * z2 == x2 * z1 1209 if (P[0] * Q[2] - Q[0] * P[2]) % p != 0: 1210 return False 1211 if (P[1] * Q[2] - Q[1] * P[2]) % p != 0: 1212 return False 1213 return True 1215 # Square root of -1 1216 modp_sqrt_m1 = pow(2, (p-1) // 4, p) 1218 # Compute corresponding x coordinate, with low bit corresponding to sign, 1219 # or return None on failure 1220 def recover_x(y, sign): 1221 x2 = (y*y-1) * modp_inv(d*y*y+1) 1222 if x2 == 0: 1223 if sign: 1224 return None 1225 else: 1226 return 0 1228 # Compute square root of x2 1229 x = pow(x2, (p+3) // 8, p) 1230 if (x*x - x2) % p != 0: 1231 x = x * modp_sqrt_m1 % p 1232 if (x*x - x2) % p != 0: 1233 return None 1235 if (x & 1) != sign: 1236 x = p - x 1237 return x 1239 # Base point 1240 g_y = 4 * modp_inv(5) % p 1241 g_x = recover_x(g_y, 0) 1242 G = (g_x, g_y, 1, g_x * g_y % p) 1244 def point_compress(P): 1245 zinv = modp_inv(P[2]) 1246 x = P[0] * zinv % p 1247 y = P[1] * zinv % p 1248 return int.to_bytes(y | ((x & 1) << 255), 32, "little") 1250 def point_decompress(s): 1251 if len(s) != 32: 1252 raise Exception("Invalid input length for decompression") 1253 y = int.from_bytes(s, "little") 1254 sign = y >> 255 1255 y &= (1 << 255) - 1 1257 x = recover_x(y, sign) 1258 if x is None: 1259 return None 1260 else: 1261 return (x, y, 1, x*y % p) 1263 def secret_expand(secret): 1264 if len(secret) != 32: 1265 raise Exception("Bad size of private key") 1266 h = sha512(secret) 1267 a = int.from_bytes(h[:32], "little") 1268 a &= (1 << 254) - 8 1269 a |= (1 << 254) 1270 return (a, h[32:]) 1272 def secret_to_public(secret): 1273 (a, dummy) = secret_expand(secret) 1274 return point_compress(point_mul(a, G)) 1276 def sign(secret, msg): 1277 a, prefix = secret_expand(secret) 1278 A = point_compress(point_mul(a, G)) 1279 r = sha512_modq(prefix + msg) 1280 R = point_mul(r, G) 1281 Rs = point_compress(R) 1282 h = sha512_modq(Rs + A + msg) 1283 s = (r + h * a) % q 1284 return Rs + int.to_bytes(s, 32, "little") 1286 def verify(public, msg, signature): 1287 if len(public) != 32: 1288 raise Exception("Bad public-key length") 1289 if len(signature) != 64: 1290 Exception("Bad signature length") 1291 A = point_decompress(public) 1292 if not A: 1293 return False 1294 Rs = signature[:32] 1295 R = point_decompress(Rs) 1296 if not R: 1297 return False 1298 s = int.from_bytes(signature[32:], "little") 1299 h = sha512_modq(Rs + public + msg) 1300 sB = point_mul(s, G) 1301 hA = point_mul(h, A) 1302 return point_equal(sB, point_add(R, hA)) 1304 Appendix B. Library driver 1306 Below is a command-line tool that uses the library above to perform 1307 computations, for interactive use or for self-checking. 1309 import sys 1310 import binascii 1312 from ed25519 import * 1314 def point_valid(P): 1315 zinv = modp_inv(P[2]) 1316 x = P[0] * zinv % p 1317 y = P[1] * zinv % p 1318 assert (x*y - P[3]*zinv) % p == 0 1319 return (-x*x + y*y - 1 - d*x*x*y*y) % p == 0 1321 assert point_valid(G) 1322 Z = (0, 1, 1, 0) 1323 assert point_valid(Z) 1324 assert point_equal(Z, point_add(Z, Z)) 1325 assert point_equal(G, point_add(Z, G)) 1326 assert point_equal(Z, point_mul(0, G)) 1327 assert point_equal(G, point_mul(1, G)) 1328 assert point_equal(point_add(G, G), point_mul(2, G)) 1329 for i in range(0, 100): 1330 assert point_valid(point_mul(i, G)) 1331 assert point_equal(Z, point_mul(q, G)) 1333 def munge_string(s, pos, change): 1334 return (s[:pos] + 1335 int.to_bytes(s[pos] ^ change, 1, "little") + 1336 s[pos+1:]) 1338 # Read a file in the format of 1339 # http://ed25519.cr.yp.to/python/sign.input 1340 lineno = 0 1341 while True: 1342 line = sys.stdin.readline() 1343 if not line: 1344 break 1345 lineno = lineno + 1 1346 print(lineno) 1347 fields = line.split(":") 1348 secret = (binascii.unhexlify(fields[0]))[:32] 1349 public = binascii.unhexlify(fields[1]) 1350 msg = binascii.unhexlify(fields[2]) 1351 signature = binascii.unhexlify(fields[3])[:64] 1353 assert public == secret_to_public(secret) 1354 assert signature == sign(secret, msg) 1355 assert verify(public, msg, signature) 1356 if len(msg) == 0: 1357 bad_msg = b"x" 1358 else: 1359 bad_msg = munge_string(msg, len(msg) // 3, 4) 1360 assert not verify(public, bad_msg, signature) 1361 bad_signature = munge_string(signature, 20, 8) 1362 assert not verify(public, msg, bad_signature) 1363 bad_signature = munge_string(signature, 40, 16) 1364 assert not verify(public, msg, bad_signature) 1366 Authors' Addresses 1367 Simon Josefsson 1368 SJD AB 1370 Email: simon@josefsson.org 1371 URI: http://josefsson.org/ 1373 Ilari Liusvaara 1374 Independent 1376 Email: ilariliusvaara@welho.com