idnits 2.17.1 draft-irtf-cfrg-eddsa-00.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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 7, 2015) is 3124 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 1182 -- Looks like a reference, but probably isn't: '31' on line 445 -- Looks like a reference, but probably isn't: '1' on line 1183 -- Looks like a reference, but probably isn't: '32' on line 467 -- Looks like a reference, but probably isn't: '63' on line 467 -- Looks like a reference, but probably isn't: '55' on line 523 -- Looks like a reference, but probably isn't: '56' on line 524 -- Looks like a reference, but probably isn't: '3' on line 1185 -- Looks like a reference, but probably isn't: '2' on line 1184 ** Obsolete normative reference: RFC 4634 (Obsoleted by RFC 6234) == Outdated reference: A later version (-11) exists of draft-irtf-cfrg-curves-01 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 11 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: April 9, 2016 Independent 6 October 7, 2015 8 Edwards-curve Digital Signature Algorithm (EdDSA) 9 draft-irtf-cfrg-eddsa-00 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 extremely 19 premature and there is at least one FIXME that makes some things 20 unimplementable. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on April 9, 2016. 39 Copyright Notice 41 Copyright (c) 2015 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. EdDSA Algorithm . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3.2. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 3.3. Sign . . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.4. Verify . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 4. PureEdDSA, HashEdDSA and Naming . . . . . . . . . . . . . . . 6 64 5. EdDSA Instances . . . . . . . . . . . . . . . . . . . . . . . 7 65 5.1. Ed25519ph and Ed25519 . . . . . . . . . . . . . . . . . . 7 66 5.1.1. Modular arithmetic . . . . . . . . . . . . . . . . . 8 67 5.1.2. Encoding . . . . . . . . . . . . . . . . . . . . . . 8 68 5.1.3. Decoding . . . . . . . . . . . . . . . . . . . . . . 8 69 5.1.4. Point addition . . . . . . . . . . . . . . . . . . . 9 70 5.1.5. Key Generation . . . . . . . . . . . . . . . . . . . 10 71 5.1.6. Sign . . . . . . . . . . . . . . . . . . . . . . . . 10 72 5.1.7. Verify . . . . . . . . . . . . . . . . . . . . . . . 11 73 5.2. Ed448ph and Ed448 . . . . . . . . . . . . . . . . . . . . 11 74 6. Ed25519 Python illustration . . . . . . . . . . . . . . . . . 12 75 7. Test Vectors . . . . . . . . . . . . . . . . . . . . . . . . 16 76 7.1. Test Vectors for Ed25519ph . . . . . . . . . . . . . . . 16 77 7.2. Test Vectors for Ed448ph . . . . . . . . . . . . . . . . 16 78 7.3. Test Vectors for Ed25519 . . . . . . . . . . . . . . . . 16 79 7.4. Test Vectors for Ed448 . . . . . . . . . . . . . . . . . 20 80 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 81 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 82 10. Security Considerations . . . . . . . . . . . . . . . . . . . 20 83 10.1. Side-channel leaks . . . . . . . . . . . . . . . . . . . 20 84 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 85 11.1. Normative References . . . . . . . . . . . . . . . . . . 21 86 11.2. Informative References . . . . . . . . . . . . . . . . . 21 87 Appendix A. Ed25519 Python Library . . . . . . . . . . . . . . . 22 88 Appendix B. Library driver . . . . . . . . . . . . . . . . . . . 25 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 91 1. Introduction 93 The Edwards-curve Digital Signature Algorithm (EdDSA) is a variant of 94 Schnorr's signature system with (possibly Twisted) Edwards curves. 95 EdDSA needs to be instantiated with certain parameters and this 96 document describe some recommended variants. 98 To facilitate adoption in the Internet community of EdDSA, this 99 document describe the signature scheme in an implementation-oriented 100 way, and provide sample code and test vectors. 102 The advantages with EdDSA include: 104 1. High-performance on a variety of platforms. 106 2. Does not require the use of a unique random number for each 107 signature. 109 3. More resilient to side-channel attacks. 111 4. Small public keys (32 or 57 bytes) and signatures (64 or 114 112 bytes). 114 5. The formulas are "strongly unified", i.e., they are valid for all 115 points on the curve, with no exceptions. This obviates the need 116 for EdDSA to perform expensive point validation on untrusted 117 public values. 119 6. Collision resilience, meaning that hash-function collisions do 120 not break this system. (Only holds for PureEdDSA.) 122 For further background, see the original EdDSA paper [EDDSA] and the 123 generalized version described in EdDSA for more curves [EDDSA2]. The 124 [I-D.irtf-cfrg-curves] document discuss specific curves, including 125 Curve25519 [CURVE25519] and Ed448-Goldilocks [ED448]. 127 2. Notation 129 FIXME: make sure this is aligned with irtf-cfrg-curves 131 The following notation is used throughout the document: 133 GF(p) --- finite field with p elements 135 x^y --- x multiplied by itself y times 137 B --- generator of the group or subgroup of interest 139 n B --- B added to itself n times. 141 h_i --- the i'th bit of h 143 a || b --- (bit-)string a concatenated with (bit-)string b 145 a <= b --- a is less than or equal to b 146 A + B --- sum of A and B 148 A x B --- cartesian product of A and B 150 3. EdDSA Algorithm 152 EdDSA is a digital signature system with eleven parameters. 154 The generic EdDSA digital signature system with its eleven input 155 parameters is not intended to be implemented directly. Chosing 156 parameters is critical for secure and efficient operation. Instead, 157 you would implement a particular parameter choice for EdDSA (such as 158 Ed25519 or Ed448), sometimes slightly generalized to achieve code re- 159 use to cover Ed25519 and Ed448. 161 Therefor, a precise explanation of the generic EdDSA is thus not 162 particularly useful for implementers. For background and 163 completeness, a succinct description of the generic EdDSA algorithm 164 is given here. 166 The definition of some parameters, such as n and c, may help to 167 explain some non-intuitive steps of the algorithm. 169 This description closely follows [EDDSA2]. 171 EdDSA has elevent parameters: 173 1. An odd prime power p. EdDSA uses an elliptic curve over the 174 finite field GF(p). 176 2. An integer b with 2^(b-1) > p. EdDSA public keys have exactly b 177 bits, and EdDSA signatures have exactly 2b bits. 179 3. A (b-1)-bit encoding of elements of the finite field GF(p). 181 4. A cryptographic hash function H producing 2b-bit output. 182 Conservative hash functions are recommended and do not have much 183 impact on the total cost of EdDSA. 185 5. An integer c that is 2 or 3. Secret EdDSA scalars are multiples 186 of 2^c. 188 6. An integer n with c <= n <= b. Secret EdDSA scalars have 189 exactly n + 1 bits, with the top bit (the 2^n position) always 190 set and the bottom c bits always cleared. 192 7. A nonzero square element a of GF(p). The usual recommendation 193 for best performance is a = -1 if p mod 4 = 1, and a = 1 if p 194 mod 4 = 3. 196 8. An element B != (0,1) of the set E = { (x,y) is a member of 197 GF(p) x GF(p) such that a x^2 + y^2 = 1 + d x^2 y^2 }. 199 9. An odd prime l such that l B = 0 and 2^c l = #E. The number #E 200 is part of the standard data provided for an elliptic curve E. 202 10. A "prehash" function PH. PureEdDSA means EdDSA where PH is the 203 identity function, i.e., PH(M) = M. HashEdDSA means EdDSA where 204 PH generates a short output, no matter how long the message is; 205 for example, PH(M) = SHA-512(M). 207 Points on the curve form a group under addition, (x3, y3) = (x1, y1) 208 + (x2, y2), with the formulas 210 x1 y2 + x2 y1 y1 y2 - a x1 x2 211 x3 = -------------------, y3 = ------------------- 212 1 + d x1 x2 y1 y2 1 - d x1 x2 y1 y2 214 The neutral element in the group is (0, 1). 216 For Ed25519, the curve used is equivalent to Curve25519 [CURVE25519], 217 under a change of coordinates, which means that the difficulty of the 218 discrete logarithm problem is the same as for Curve25519. 220 For Ed448, the curve is equivalent to Ed448-Goldilocks under change 221 of basepoint, which also preserves difficulty of the discrete 222 logarithm. 224 Unlike many other curves used for cryptographic applications, these 225 formulas are "strongly unified": they are valid for all points on the 226 curve, with no exceptions. In particular, the denominators are non- 227 zero for all input points. 229 There are more efficient formulas, which are still strongly unified, 230 which use homogeneous coordinates to avoid the expensive modulo p 231 inversions. See [Faster-ECC] and [Edwards-revisited]. 233 3.1. Encoding 235 An integer 0 < S < l - 1 is encoded in little-endian form as a b-bit 236 string ENC(S). 238 An element (x,y) of E is encoded as a b-bit string called ENC(x,y) 239 which is the (b-1)-bit encoding of y concatenated with one bit that 240 is 1 if x is negative and 0 if x is not negative. 242 The encoding of GF(p) is used to define "negative" elements of GF(p): 243 specifically, x is negative if the (b-1)-bit encoding of x is 244 lexicographically larger than the (b-1)-bit encoding of -x. 246 3.2. Keys 248 An EdDSA secret key is a b-bit string k. Let the hash H(k) = (h_0, 249 h_1, ..., h_(2b-1)) determine an integer s which is 2^n plus the sum 250 of m = 2^i * h_i for all i equal or larger than c and equal to or 251 less than n. Let s determine the multiple A = s B. The EdDSA public 252 key is ENC(A). The bits h_b, ..., h_(2b-1) is used below during 253 signing. 255 3.3. Sign 257 The EdDSA signature of a message M under a secret key k is defined as 258 the PureEdDSA signature of PH(M). In other words, EdDSA simply uses 259 PureEdDSA to sign PH(M). 261 The PureEdDSA signature of a message M under a secret key k is the 262 2b-bit string ENC(R) || ENC(S). R and S are derived as follows. 263 First define r = H(h_b, ... h_(2b-1), M) interpreting 2b-bit strings 264 in little-endian form as integers in {0, 1, ..., 2^(2b) - 1}. Let R 265 = r B and S = (r + H(ENC(R) || ENC(A) || P(M)) s) mod l. The s used 266 here is from the previous section. 268 3.4. Verify 270 To verify a signature ENC(R) || ENC(S) on a message M under a public 271 key ENC(A), proceed as follows. Parse the inputs so that A and R is 272 an element of E, and S is a member of the set {0, 1, ..., l-1 }. 273 Compute h = H(ENC(R) || ENC(A) || M) and check the group equation 2^c 274 S B = 2^c R + 2^c h A in E. Verification is rejected if parsing 275 fails or the group equation does not hold. 277 EdDSA verification for a message M is defined as PureEdDSA 278 verification for PH(M). 280 4. PureEdDSA, HashEdDSA and Naming 282 One of the parameters of the EdDSA algorithm is the "prehash" 283 function. This may be the identity function, resulting in an 284 algorithm called PureEdDSA, or a collision-resistant hash function 285 such as SHA-512, resulting in an algorithm called HashEdDSA. 287 Chosing which variant to use depends on which property is deemed to 288 be more important between 1) collision resilience, and 2) a single- 289 pass interface. The collision reilience property means EdDSA is 290 secure even if it is feasible to compute collisions for the hash 291 function. The single-pass interface property means that only one 292 pass over the input message is required, whereas PureEdDSA requires 293 two passes over the input. Many existing APIs, protocols and 294 environments assume digital signature algorithms only need one pass 295 over the input, and may have API or bandwidth concerns supporting 296 anything else. 298 This document specify parameters resulting in the HashEdDSA variants 299 Ed25519ph and Ed448ph, and the PureEdDSA variants Ed25519 and Ed448. 301 5. EdDSA Instances 303 This section instantiate the general EdDSA algorithm for the 304 Curve25519 and Ed448 curves, each for the PureEdDSA and HashEdDSA 305 variants. Thus four different parameter sets are described. 307 5.1. Ed25519ph and Ed25519 309 Ed25519 is PureEdDSA instantiated with p as the prime 2^255-19, 310 b=256, the 255-bit encoding of GF(p) being the little-endian encoding 311 of {0, 1, ..., p-1}, H being SHA-512 [RFC4634], c being 3, n being 312 254, a being -1, d = -121665/121666 which is a member of GF(p), and B 313 is the unique point (x, 4/5) in E for which x is "positive", which 314 with the encoding used simply means that the least significant bit of 315 x is 0, l is the prime 2^252 + 316 27742317777372353535851937790883648493. 318 Ed25519ph is the same but with PH being SHA-512 instead, i.e., the 319 input is hashed using SHA-512 before signing with Ed25519. 321 Written out explicitly, B is the point (15112221349535400772501151409 322 588531511454012693041857206046113283949847762202, 4631683569492647816 323 9428394003475163141307993866256225615783033603165251855960). 325 The values for p, a, d, B and l follows from the "edwards25519" 326 values in [I-D.irtf-cfrg-curves]. 328 FIXME: Ilari: Do we want to refer more to "Edwards25519" from CFRG- 329 CURVES to get rid of those long-looking constants from above? Simon: 330 I think we do with the previous paragraph -- do you want to remove 331 them from this document? The cfrg-curves draft uses the same 332 variable name for many different values, so repeating the values here 333 may help. Maybe we can split this up into "specified here" and 334 "specified in cfrg-curves" for easier double checking. 336 5.1.1. Modular arithmetic 338 For advise on how to implement arithmetic modulo p = 2^255 - 19 339 efficiently and securely, see Curve25519 [CURVE25519]. For inversion 340 modulo p, it is recommended to use the identity x^-1 = x^(p-2) (mod 341 p). 343 For point decoding or "decompression", square roots modulo p are 344 needed. They can be computed using the Tonelli-Shanks algorithm, or 345 the special case for p = 5 (mod 8). To find a square root of a, 346 first compute the candidate root x = a^((p+3)/8) (mod p). Then there 347 are three cases: 349 x^2 = a (mod p). Then x is a square root. 351 x^2 = -a (mod p). Then 2^((p-1)/4) x is a square root. 353 a is not a square modulo p. 355 5.1.2. Encoding 357 All values are coded as octet strings, and integers are coded using 358 little endian convention. I.e., a 32-octet string h h[0],...h[31] 359 represents the integer h[0] + 2^8 h[1] + ... + 2^248 h[31]. 361 A curve point (x,y), with coordinates in the range 0 <= x,y < p, is 362 coded as follows. First encode the y-coordinate as a little-endian 363 string of 32 octets. The most significant bit of the final octet is 364 always zero. To form the encoding of the point, copy the least 365 significant bit of the x-coordinate to the most significant bit of 366 the final octet. 368 5.1.3. Decoding 370 Decoding a point, given as a 32-octet string, is a little more 371 complicated. 373 1. First interpret the string as an integer in little-endian 374 representation. Bit 255 of this number is the least significant 375 bit of the x-coordinate, and denote this value x_0. The 376 y-coordinate is recovered simply by clearing this bit. If the 377 resulting value is >= p, decoding fails. 379 2. To recover the x coordinate, the curve equation implies x^2 = 380 (y^2 - 1) / (d y^2 + 1) (mod p). Since d is a non-square and -1 381 is a square, the numerator, (d y^2 + 1), is always invertible 382 modulo p. Let u = y^2 - 1 and v = d y^2 + 1. To compute the 383 square root of (u/v), the first step is to compute the candidate 384 root x = (u/v)^((p+3)/8). This can be done using the following 385 trick, to use a single modular powering for both the inversion of 386 v and the square root: 388 (p+3)/8 3 (p-5)/8 389 x = (u/v) = u v (u v^7) (mod p) 391 3. Again, there are three cases: 393 1. If v x^2 = u (mod p), x is a square root. 395 2. If v x^2 = -u (mod p), set x <-- x 2^((p-1)/4), which is a 396 square root. 398 3. Otherwise, no square root exists modulo p, and decoding 399 fails. 401 4. Finally, use the x_0 bit to select the right square root. If x = 402 0, and x_0 = 1, decoding fails. Otherwise, if x_0 != x mod 2, 403 set x <-- p - x. Return the decoded point (x,y). 405 5.1.4. Point addition 407 For point addition, the following method is recommended. A point 408 (x,y) is represented in extended homogeneous coordinates (X, Y, Z, 409 T), with x = X/Z, y = Y/Z, x y = T/Z. 411 The following formulas for adding two points, (x3,y3) = 412 (x1,y1)+(x2,y2) are described in [Edwards-revisited], section 3.1. 413 They are strongly unified, i.e., they work for any pair of valid 414 input points. 416 A = (Y1-X1)*(Y2-X2) 417 B = (Y1+X1)*(Y2+X2) 418 C = T1*2*d*T2 419 D = Z1*2*Z2 420 E = B-A 421 F = D-C 422 G = D+C 423 H = B+A 424 X3 = E*F 425 Y3 = G*H 426 T3 = E*H 427 Z3 = F*G 429 5.1.5. Key Generation 431 The secret is 32 octets (256 bits, corresponding to b) of 432 cryptographically-secure random data. See [RFC4086] for a discussion 433 about randomness. 435 The 32-byte public key is generated by the following steps. 437 1. Hash the 32-byte secret using SHA-512, storing the digest in a 438 64-octet large buffer, denoted h. Only the lower 32 bytes are 439 used for generating the public key. 441 2. Prune the buffer. In C terminology: 443 h[0] &= ~0x07; 444 h[31] &= 0x7F; 445 h[31] |= 0x40; 447 3. Interpret the buffer as the little-endian integer, forming a 448 secret scalar a. Perform a known-base-point scalar 449 multiplication a B. 451 4. The public key A is the encoding of the point aB. First encode 452 the y coordinate (in the range 0 <= y < p) as a little-endian 453 string of 32 octets. The most significant bit of the final octet 454 is always zero. To form the encoding of the point aB, copy the 455 least significant bit of the x coordinate to the most significant 456 bit of the final octet. The result is the public key. 458 5.1.6. Sign 460 The inputs to the signing procedure is the secret key, a 32-octet 461 string, and a message M of arbitrary size. 463 1. Hash the secret key, 32-octets, using SHA-512. Let h denote the 464 resulting digest. Construct the secret scalar a from the first 465 half of the digest, and the corresponding public key A, as 466 described in the previous section. Let prefix denote the second 467 half of the hash digest, h[32],...,h[63]. 469 2. Compute SHA-512(prefix || M), where M is the message to be 470 signed. Interpret the 64-octet digest as a little-endian integer 471 r. 473 3. Compute the point rB. For efficiency, do this by first reducing 474 r modulo q, the group order of B. Let the string R be the 475 encoding of this point. 477 4. Compute SHA512(R || A || M), and interpret the 64-octet digest as 478 a little-endian integer k. 480 5. Compute s = (r + k a) mod q. For efficiency, again reduce k 481 modulo q first. 483 6. Form the signature of the concatenation of R (32 octets) and the 484 little-endian encoding of s (32 octets, three most significant 485 bits of the final octets always zero). 487 5.1.7. Verify 489 1. To verify a signature on a message M, first split the signature 490 into two 32-octet halves. Decode the first half as a point R, 491 and the second half as an integer s, in the range 0 <= s < q. If 492 the decoding fails, the signature is invalid. 494 2. Compute SHA512(R || A || M), and interpret the 64-octet digest as 495 a little-endian integer k. 497 3. Check the group equation 8s B = 8 R + 8k A. It's sufficient, but 498 not required, to instead check s B = R + k A. 500 5.2. Ed448ph and Ed448 502 Ed448 is PureEdDSA instantiated with p as the prime 2^448 - 2^224 - 503 1, b=456, the 455-bit encoding of GF(2^448-2^224-1) is the usual 504 little-endian encoding of {0, 1, ..., 2^448 - 2^224 - 2}, H is 505 [FIXME: needs 912-bit hash], c being 2, n being 448, a being 1, d 506 being - 39081, B is (X(P), Y(P)), and l is the prime 2^446 - 507 13818066809895115352007386748515426880336692474882178609894547503885. 509 Ed448ph is the same but with P being SHA-512 instead, i.e., the input 510 is hashed using SHA-512 before signing with Ed448. 512 The values of p, a, d, X(p), Y(p), and l are taken from curve named 513 "edwards448" in [I-D.irtf-cfrg-curves]. 515 FIXME: Everything except the hash is straightforward generalization 516 from Ed25519 case (but duplicating all the text does not seem very 517 sensible), except now the curve is untwisted, so point formulas are 518 bit different, keys are 57 bytes, signatures 114, and the pruning 519 formula becomes: 521 h[0] &= ~0x03; 522 h[55] &= 0xFF; 523 h[55] |= 0x80; 524 h[56] = 0; 526 6. Ed25519 Python illustration 528 The rest of this section describes how Ed25519 can be implemented in 529 Python (version 3.2 or later) for illustration. See appendix A for 530 the complete implementation and appendix B for a test-driver to run 531 it through some test vectors. 533 Note that this code is not intended for production as it is not 534 proven to be correct for all inputs, nor does it protect against 535 side-channel attacks. The purpose is to illustrate the algorithm to 536 help implementers with their own implementation. 538 First some preliminaries that will be needed. 540 import hashlib 542 def sha512(s): 543 return hashlib.sha512(s).digest() 545 # Base field Z_p 546 p = 2**255 - 19 548 def modp_inv(x): 549 return pow(x, p-2, p) 551 # Curve constant 552 d = -121665 * modp_inv(121666) % p 554 # Group order 555 q = 2**252 + 27742317777372353535851937790883648493 557 def sha512_modq(s): 558 return int.from_bytes(sha512(s), "little") % q 560 Then follows functions to perform point operations. 562 # Points are represented as tuples (X, Y, Z, T) of extended coordinates, 563 # with x = X/Z, y = Y/Z, x*y = T/Z 565 def point_add(P, Q): 566 A = (P[1]-P[0])*(Q[1]-Q[0]) % p 567 B = (P[1]+P[0])*(Q[1]+Q[0]) % p 568 C = 2 * P[3] * Q[3] * d % p 569 D = 2 * P[2] * Q[2] % p 570 E = B-A 571 F = D-C 572 G = D+C 573 H = B+A 574 return (E*F, G*H, F*G, E*H) 576 # Computes Q = s * Q 577 def point_mul(s, P): 578 Q = (0, 1, 1, 0) # Neutral element 579 while s > 0: 580 # Is there any bit-set predicate? 581 if s & 1: 582 Q = point_add(Q, P) 583 P = point_add(P, P) 584 s >>= 1 585 return Q 587 def point_equal(P, Q): 588 # x1 / z1 == x2 / z2 <==> x1 * z2 == x2 * z1 589 if (P[0] * Q[2] - Q[0] * P[2]) % p != 0: 590 return False 591 if (P[1] * Q[2] - Q[1] * P[2]) % p != 0: 592 return False 593 return True 595 Now follows functions for point compression. 597 # Square root of -1 598 modp_sqrt_m1 = pow(2, (p-1) // 4, p) 600 # Compute corresponding x coordinate, with low bit corresponding to sign, 601 # or return None on failure 602 def recover_x(y, sign): 603 x2 = (y*y-1) * modp_inv(d*y*y+1) 604 if x2 == 0: 605 if sign: 606 return None 607 else: 608 return 0 610 # Compute square root of x2 611 x = pow(x2, (p+3) // 8, p) 612 if (x*x - x2) % p != 0: 613 x = x * modp_sqrt_m1 % p 614 if (x*x - x2) % p != 0: 615 return None 617 if (x & 1) != sign: 618 x = p - x 619 return x 621 # Base point 622 g_y = 4 * modp_inv(5) % p 623 g_x = recover_x(g_y, 0) 624 G = (g_x, g_y, 1, g_x * g_y % p) 626 def point_compress(P): 627 zinv = modp_inv(P[2]) 628 x = P[0] * zinv % p 629 y = P[1] * zinv % p 630 return int.to_bytes(y | ((x & 1) << 255), 32, "little") 632 def point_decompress(s): 633 if len(s) != 32: 634 raise Exception("Invalid input length for decompression") 635 y = int.from_bytes(s, "little") 636 sign = y >> 255 637 y &= (1 << 255) - 1 639 x = recover_x(y, sign) 640 if x is None: 641 return None 642 else: 643 return (x, y, 1, x*y % p) 645 These are functions for manipulating the secret. 647 def secret_expand(secret): 648 if len(secret) != 32: 649 raise Exception("Bad size of private key") 650 h = sha512(secret) 651 a = int.from_bytes(h[:32], "little") 652 a &= (1 << 254) - 8 653 a |= (1 << 254) 654 return (a, h[32:]) 656 def secret_to_public(secret): 657 (a, dummy) = secret_expand(secret) 658 return point_compress(point_mul(a, G)) 660 The signature function works as below. 662 def sign(secret, msg): 663 a, prefix = secret_expand(secret) 664 A = point_compress(point_mul(a, G)) 665 r = sha512_modq(prefix + msg) 666 R = point_mul(r, G) 667 Rs = point_compress(R) 668 h = sha512_modq(Rs + A + msg) 669 s = (r + h * a) % q 670 return Rs + int.to_bytes(s, 32, "little") 672 And finally the verification function. 674 def verify(public, msg, signature): 675 if len(public) != 32: 676 raise Exception("Bad public-key length") 677 if len(signature) != 64: 678 Exception("Bad signature length") 679 A = point_decompress(public) 680 if not A: 681 return False 682 Rs = signature[:32] 683 R = point_decompress(Rs) 684 if not R: 685 return False 686 s = int.from_bytes(signature[32:], "little") 687 h = sha512_modq(Rs + public + msg) 688 sB = point_mul(s, G) 689 hA = point_mul(h, A) 690 return point_equal(sB, point_add(R, hA)) 692 7. Test Vectors 694 This section contains test vectors for Ed25519ph, Ed448ph, Ed25519 695 and Ed448. 697 7.1. Test Vectors for Ed25519ph 699 TODO 701 7.2. Test Vectors for Ed448ph 703 TODO 705 7.3. Test Vectors for Ed25519 707 Below is a sequence of octets with test vectors for the the Ed25519 708 signature algorithm. The octets are hex encoded and whitespace is 709 inserted for readability. Private keys are 64 bytes, public keys 32 710 bytes, message of arbitrary length, and signatures are 64 bytes. The 711 test vectors are taken from [ED25519-TEST-VECTORS] (but we removed 712 the public key as a suffix of the secret key, and removed the message 713 from the signature) and [ED25519-LIBGCRYPT-TEST-VECTORS]. 715 -----TEST 1 716 SECRET KEY: 717 9d61b19deffd5a60ba844af492ec2cc4 718 4449c5697b326919703bac031cae7f60 720 PUBLIC KEY: 721 d75a980182b10ab7d54bfed3c964073a 722 0ee172f3daa62325af021a68f707511a 724 MESSAGE (length 0 bytes): 726 SIGNATURE: 727 e5564300c360ac729086e2cc806e828a 728 84877f1eb8e5d974d873e06522490155 729 5fb8821590a33bacc61e39701cf9b46b 730 d25bf5f0595bbe24655141438e7a100b 732 -----TEST 2 733 SECRET KEY: 734 4ccd089b28ff96da9db6c346ec114e0f 735 5b8a319f35aba624da8cf6ed4fb8a6fb 737 PUBLIC KEY: 738 3d4017c3e843895a92b70aa74d1b7ebc 739 9c982ccf2ec4968cc0cd55f12af4660c 740 MESSAGE (length 1 byte): 741 72 743 SIGNATURE: 744 92a009a9f0d4cab8720e820b5f642540 745 a2b27b5416503f8fb3762223ebdb69da 746 085ac1e43e15996e458f3613d0f11d8c 747 387b2eaeb4302aeeb00d291612bb0c00 749 -----TEST 3 750 SECRET KEY: 751 c5aa8df43f9f837bedb7442f31dcb7b1 752 66d38535076f094b85ce3a2e0b4458f7 754 PUBLIC KEY: 755 fc51cd8e6218a1a38da47ed00230f058 756 0816ed13ba3303ac5deb911548908025 758 MESSAGE (length 2 bytes): 759 af82 761 SIGNATURE: 762 6291d657deec24024827e69c3abe01a3 763 0ce548a284743a445e3680d7db5ac3ac 764 18ff9b538d16f290ae67f760984dc659 765 4a7c15e9716ed28dc027beceea1ec40a 767 -----TEST 1024 768 SECRET KEY: 769 f5e5767cf153319517630f226876b86c 770 8160cc583bc013744c6bf255f5cc0ee5 772 PUBLIC KEY: 773 278117fc144c72340f67d0f2316e8386 774 ceffbf2b2428c9c51fef7c597f1d426e 776 MESSAGE (length 1023 bytes): 777 08b8b2b733424243760fe426a4b54908 778 632110a66c2f6591eabd3345e3e4eb98 779 fa6e264bf09efe12ee50f8f54e9f77b1 780 e355f6c50544e23fb1433ddf73be84d8 781 79de7c0046dc4996d9e773f4bc9efe57 782 38829adb26c81b37c93a1b270b20329d 783 658675fc6ea534e0810a4432826bf58c 784 941efb65d57a338bbd2e26640f89ffbc 785 1a858efcb8550ee3a5e1998bd177e93a 786 7363c344fe6b199ee5d02e82d522c4fe 787 ba15452f80288a821a579116ec6dad2b 788 3b310da903401aa62100ab5d1a36553e 789 06203b33890cc9b832f79ef80560ccb9 790 a39ce767967ed628c6ad573cb116dbef 791 efd75499da96bd68a8a97b928a8bbc10 792 3b6621fcde2beca1231d206be6cd9ec7 793 aff6f6c94fcd7204ed3455c68c83f4a4 794 1da4af2b74ef5c53f1d8ac70bdcb7ed1 795 85ce81bd84359d44254d95629e9855a9 796 4a7c1958d1f8ada5d0532ed8a5aa3fb2 797 d17ba70eb6248e594e1a2297acbbb39d 798 502f1a8c6eb6f1ce22b3de1a1f40cc24 799 554119a831a9aad6079cad88425de6bd 800 e1a9187ebb6092cf67bf2b13fd65f270 801 88d78b7e883c8759d2c4f5c65adb7553 802 878ad575f9fad878e80a0c9ba63bcbcc 803 2732e69485bbc9c90bfbd62481d9089b 804 eccf80cfe2df16a2cf65bd92dd597b07 805 07e0917af48bbb75fed413d238f5555a 806 7a569d80c3414a8d0859dc65a46128ba 807 b27af87a71314f318c782b23ebfe808b 808 82b0ce26401d2e22f04d83d1255dc51a 809 ddd3b75a2b1ae0784504df543af8969b 810 e3ea7082ff7fc9888c144da2af58429e 811 c96031dbcad3dad9af0dcbaaaf268cb8 812 fcffead94f3c7ca495e056a9b47acdb7 813 51fb73e666c6c655ade8297297d07ad1 814 ba5e43f1bca32301651339e22904cc8c 815 42f58c30c04aafdb038dda0847dd988d 816 cda6f3bfd15c4b4c4525004aa06eeff8 817 ca61783aacec57fb3d1f92b0fe2fd1a8 818 5f6724517b65e614ad6808d6f6ee34df 819 f7310fdc82aebfd904b01e1dc54b2927 820 094b2db68d6f903b68401adebf5a7e08 821 d78ff4ef5d63653a65040cf9bfd4aca7 822 984a74d37145986780fc0b16ac451649 823 de6188a7dbdf191f64b5fc5e2ab47b57 824 f7f7276cd419c17a3ca8e1b939ae49e4 825 88acba6b965610b5480109c8b17b80e1 826 b7b750dfc7598d5d5011fd2dcc5600a3 827 2ef5b52a1ecc820e308aa342721aac09 828 43bf6686b64b2579376504ccc493d97e 829 6aed3fb0f9cd71a43dd497f01f17c0e2 830 cb3797aa2a2f256656168e6c496afc5f 831 b93246f6b1116398a346f1a641f3b041 832 e989f7914f90cc2c7fff357876e506b5 833 0d334ba77c225bc307ba537152f3f161 834 0e4eafe595f6d9d90d11faa933a15ef1 835 369546868a7f3a45a96768d40fd9d034 836 12c091c6315cf4fde7cb68606937380d 837 b2eaaa707b4c4185c32eddcdd306705e 838 4dc1ffc872eeee475a64dfac86aba41c 839 0618983f8741c5ef68d3a101e8a3b8ca 840 c60c905c15fc910840b94c00a0b9d0 842 SIGNATURE: 843 0aab4c900501b3e24d7cdf4663326a3a 844 87df5e4843b2cbdb67cbf6e460fec350 845 aa5371b1508f9f4528ecea23c436d94b 846 5e8fcd4f681e30a6ac00a9704a188a03 848 -----TEST 1A 849 -----An additional test with the data from test 1 but using an 850 -----uncompressed public key. 851 SECRET KEY: 852 9d61b19deffd5a60ba844af492ec2cc4 853 4449c5697b326919703bac031cae7f60 855 PUBLIC KEY: 856 0455d0e09a2b9d34292297e08d60d0f6 857 20c513d47253187c24b12786bd777645 858 ce1a5107f7681a02af2523a6daf372e1 859 0e3a0764c9d3fe4bd5b70ab18201985a 860 d7 862 MSG (length 0 bytes): 864 SIGNATURE: 865 e5564300c360ac729086e2cc806e828a 866 84877f1eb8e5d974d873e06522490155 867 5fb8821590a33bacc61e39701cf9b46b 868 d25bf5f0595bbe24655141438e7a100b 870 -----TEST 1B 871 -----An additional test with the data from test 1 but using an 872 -----compressed prefix. 873 SECRET KEY: 874 9d61b19deffd5a60ba844af492ec2cc4 875 4449c5697b326919703bac031cae7f60 877 PUBLIC KEY: 878 40d75a980182b10ab7d54bfed3c96407 879 3a0ee172f3daa62325af021a68f70751 880 1a 882 MESSAGE (length 0 bytes): 884 SIGNATURE: 885 e5564300c360ac729086e2cc806e828a 886 84877f1eb8e5d974d873e06522490155 887 5fb8821590a33bacc61e39701cf9b46b 888 d25bf5f0595bbe24655141438e7a100b 889 ----- 891 7.4. Test Vectors for Ed448 893 TODO 895 8. Acknowledgements 897 Feedback on this document was received from Werner Koch, Damien 898 Miller, Bob Bradley, and Franck Rondepierre. The Ed25519 test 899 vectors were double checked by Bob Bradley using 3 separate 900 implementations (one based on TweetNaCl and 2 different 901 implementations based on code from SUPERCOP). 903 9. IANA Considerations 905 None. 907 10. Security Considerations 909 10.1. Side-channel leaks 911 For implementations performing signatures, secrecy of the key is 912 fundamental. It is possible to protect against some side-channel 913 attacks by ensuring that the implementation executes exactly the same 914 sequence of instructions and performs exactly the same memory 915 accesses, for any value of the secret key. 917 To make an implementation side-channel silent in this way, the modulo 918 p arithmetic must not use any data-dependent branches, e.g., related 919 to carry propagation. Side channel-silent point addition is 920 straight-forward, thanks to the unified formulas. 922 Scalar multiplication, multiplying a point by an integer, needs some 923 additional effort to implement in a side-channel silent manner. One 924 simple approach is to implement a side-channel silent conditional 925 assignment, and use together with the binary algorithm to examine one 926 bit of the integer at a time. 928 Note that the example implementation in this document does not 929 attempt to be side-channel silent. 931 11. References 933 11.1. Normative References 935 [RFC4634] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms 936 (SHA and HMAC-SHA)", RFC 4634, July 2006. 938 [I-D.irtf-cfrg-curves] 939 Langley, A., Salz, R., and S. Turner, "Elliptic Curves for 940 Security", draft-irtf-cfrg-curves-01 (work in progress), 941 January 2015. 943 11.2. Informative References 945 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 946 Requirements for Security", BCP 106, RFC 4086, June 2005. 948 [EDDSA] Bernstein, D., Duif, N., Lange, T., Schwabe, P., and B. 949 Yang, "High-speed high-security signatures", WWW 950 http://ed25519.cr.yp.to/ed25519-20110926.pdf, September 951 2011. 953 [EDDSA2] Bernstein, D., Josefsson, S., Lange, T., Schwabe, P., and 954 B. Yang, "EdDSA for more curves", WWW 955 http://ed25519.cr.yp.to/eddsa-20150704.pdf, July 2015. 957 [Faster-ECC] 958 Bernstein, D. and T. Lange, "Faster addition and doubling 959 on elliptic curves", WWW http://eprint.iacr.org/2007/286, 960 July 2007. 962 [Edwards-revisited] 963 Hisil, H., Wong, K., Carter, G., and E. Dawson, "Twisted 964 Edwards Curves Revisited", WWW 965 http://eprint.iacr.org/2008/522, December 2008. 967 [CURVE25519] 968 Bernstein, D., "Curve25519: new Diffie-Hellman speed 969 records", WWW http://cr.yp.to/ecdh.html, February 2006. 971 [ED448] Hamburg, M., "Ed448-Goldilocks, a new elliptic curve", WWW 972 http://eprint.iacr.org/2015/625, June 2015. 974 [ED25519-TEST-VECTORS] 975 Bernstein, D., Duif, N., Lange, T., Schwabe, P., and B. 976 Yang, "Ed25519 test vectors", WWW 977 http://ed25519.cr.yp.to/python/sign.input, July 2011. 979 [ED25519-LIBGCRYPT-TEST-VECTORS] 980 Koch, W., "Ed25519 Libgcrypt test vectors", WWW 981 http://git.gnupg.org/cgi- 982 bin/gitweb.cgi?p=libgcrypt.git;a=blob;f=tests/t-ed25519.in 983 p;h=e13566f826321eece65e02c593bc7d885b3dbe23;hb=refs/ 984 heads/master, July 2014. 986 Appendix A. Ed25519 Python Library 988 Below is an example implementation of Ed25519 written in Python, 989 version 3.2 or higher is required. 991 # Loosely based on the public domain code at 992 # http://ed25519.cr.yp.to/software.html 993 # 994 # Needs python-3.2 996 import hashlib 998 def sha512(s): 999 return hashlib.sha512(s).digest() 1001 # Base field Z_p 1002 p = 2**255 - 19 1004 def modp_inv(x): 1005 return pow(x, p-2, p) 1007 # Curve constant 1008 d = -121665 * modp_inv(121666) % p 1010 # Group order 1011 q = 2**252 + 27742317777372353535851937790883648493 1013 def sha512_modq(s): 1014 return int.from_bytes(sha512(s), "little") % q 1016 # Points are represented as tuples (X, Y, Z, T) of extended coordinates, 1017 # with x = X/Z, y = Y/Z, x*y = T/Z 1019 def point_add(P, Q): 1020 A = (P[1]-P[0])*(Q[1]-Q[0]) % p 1021 B = (P[1]+P[0])*(Q[1]+Q[0]) % p 1022 C = 2 * P[3] * Q[3] * d % p 1023 D = 2 * P[2] * Q[2] % p 1024 E = B-A 1025 F = D-C 1026 G = D+C 1027 H = B+A 1028 return (E*F, G*H, F*G, E*H) 1030 # Computes Q = s * Q 1031 def point_mul(s, P): 1032 Q = (0, 1, 1, 0) # Neutral element 1033 while s > 0: 1034 # Is there any bit-set predicate? 1035 if s & 1: 1036 Q = point_add(Q, P) 1037 P = point_add(P, P) 1038 s >>= 1 1039 return Q 1041 def point_equal(P, Q): 1042 # x1 / z1 == x2 / z2 <==> x1 * z2 == x2 * z1 1043 if (P[0] * Q[2] - Q[0] * P[2]) % p != 0: 1044 return False 1045 if (P[1] * Q[2] - Q[1] * P[2]) % p != 0: 1046 return False 1047 return True 1049 # Square root of -1 1050 modp_sqrt_m1 = pow(2, (p-1) // 4, p) 1052 # Compute corresponding x coordinate, with low bit corresponding to sign, 1053 # or return None on failure 1054 def recover_x(y, sign): 1055 x2 = (y*y-1) * modp_inv(d*y*y+1) 1056 if x2 == 0: 1057 if sign: 1058 return None 1059 else: 1060 return 0 1062 # Compute square root of x2 1063 x = pow(x2, (p+3) // 8, p) 1064 if (x*x - x2) % p != 0: 1065 x = x * modp_sqrt_m1 % p 1066 if (x*x - x2) % p != 0: 1067 return None 1069 if (x & 1) != sign: 1070 x = p - x 1071 return x 1073 # Base point 1074 g_y = 4 * modp_inv(5) % p 1075 g_x = recover_x(g_y, 0) 1076 G = (g_x, g_y, 1, g_x * g_y % p) 1078 def point_compress(P): 1079 zinv = modp_inv(P[2]) 1080 x = P[0] * zinv % p 1081 y = P[1] * zinv % p 1082 return int.to_bytes(y | ((x & 1) << 255), 32, "little") 1084 def point_decompress(s): 1085 if len(s) != 32: 1086 raise Exception("Invalid input length for decompression") 1087 y = int.from_bytes(s, "little") 1088 sign = y >> 255 1089 y &= (1 << 255) - 1 1091 x = recover_x(y, sign) 1092 if x is None: 1093 return None 1094 else: 1095 return (x, y, 1, x*y % p) 1097 def secret_expand(secret): 1098 if len(secret) != 32: 1099 raise Exception("Bad size of private key") 1100 h = sha512(secret) 1101 a = int.from_bytes(h[:32], "little") 1102 a &= (1 << 254) - 8 1103 a |= (1 << 254) 1104 return (a, h[32:]) 1106 def secret_to_public(secret): 1107 (a, dummy) = secret_expand(secret) 1108 return point_compress(point_mul(a, G)) 1110 def sign(secret, msg): 1111 a, prefix = secret_expand(secret) 1112 A = point_compress(point_mul(a, G)) 1113 r = sha512_modq(prefix + msg) 1114 R = point_mul(r, G) 1115 Rs = point_compress(R) 1116 h = sha512_modq(Rs + A + msg) 1117 s = (r + h * a) % q 1118 return Rs + int.to_bytes(s, 32, "little") 1120 def verify(public, msg, signature): 1121 if len(public) != 32: 1122 raise Exception("Bad public-key length") 1123 if len(signature) != 64: 1124 Exception("Bad signature length") 1125 A = point_decompress(public) 1126 if not A: 1127 return False 1128 Rs = signature[:32] 1129 R = point_decompress(Rs) 1130 if not R: 1131 return False 1132 s = int.from_bytes(signature[32:], "little") 1133 h = sha512_modq(Rs + public + msg) 1134 sB = point_mul(s, G) 1135 hA = point_mul(h, A) 1136 return point_equal(sB, point_add(R, hA)) 1138 Appendix B. Library driver 1140 Below is a command-line tool that uses the library above to perform 1141 computations, for interactive use or for self-checking. 1143 import sys 1144 import binascii 1146 from ed25519 import * 1148 def point_valid(P): 1149 zinv = modp_inv(P[2]) 1150 x = P[0] * zinv % p 1151 y = P[1] * zinv % p 1152 assert (x*y - P[3]*zinv) % p == 0 1153 return (-x*x + y*y - 1 - d*x*x*y*y) % p == 0 1155 assert point_valid(G) 1156 Z = (0, 1, 1, 0) 1157 assert point_valid(Z) 1158 assert point_equal(Z, point_add(Z, Z)) 1159 assert point_equal(G, point_add(Z, G)) 1160 assert point_equal(Z, point_mul(0, G)) 1161 assert point_equal(G, point_mul(1, G)) 1162 assert point_equal(point_add(G, G), point_mul(2, G)) 1163 for i in range(0, 100): 1164 assert point_valid(point_mul(i, G)) 1165 assert point_equal(Z, point_mul(q, G)) 1167 def munge_string(s, pos, change): 1168 return (s[:pos] + 1169 int.to_bytes(s[pos] ^ change, 1, "little") + 1170 s[pos+1:]) 1172 # Read a file in the format of 1173 # http://ed25519.cr.yp.to/python/sign.input 1174 lineno = 0 1175 while True: 1176 line = sys.stdin.readline() 1177 if not line: 1178 break 1179 lineno = lineno + 1 1180 print(lineno) 1181 fields = line.split(":") 1182 secret = (binascii.unhexlify(fields[0]))[:32] 1183 public = binascii.unhexlify(fields[1]) 1184 msg = binascii.unhexlify(fields[2]) 1185 signature = binascii.unhexlify(fields[3])[:64] 1187 assert public == secret_to_public(secret) 1188 assert signature == sign(secret, msg) 1189 assert verify(public, msg, signature) 1190 if len(msg) == 0: 1191 bad_msg = b"x" 1192 else: 1193 bad_msg = munge_string(msg, len(msg) // 3, 4) 1194 assert not verify(public, bad_msg, signature) 1195 bad_signature = munge_string(signature, 20, 8) 1196 assert not verify(public, msg, bad_signature) 1197 bad_signature = munge_string(signature, 40, 16) 1198 assert not verify(public, msg, bad_signature) 1200 Authors' Addresses 1201 Simon Josefsson 1202 SJD AB 1204 Email: simon@josefsson.org 1205 URI: http://josefsson.org/ 1207 Ilari Liusvaara 1208 Independent 1210 Email: ilariliusvaara@welho.com