1# HACKING -*- org -*- 2#+TITLE: Hacking notes for Libgcrypt 3#+STARTUP: showall 4 5* How to contribute 6 7 The following stuff explains some basic procedures you need to 8 follow if you want to contribute code or documentation. 9 10 *WARNING:* This file might be out of date. You better follow the 11 instructions from doc/HACKING as found in the master branch of the 12 git repository at git://git.gnupg.org/libgcrypt.git . 13 14 15** No more ChangeLog files 16 17 Do not modify any of the ChangeLog files in Libgcrypt. Starting on 18 December 1st, 2011 we put change information only in the GIT commit 19 log, and generate a top-level ChangeLog file from logs at "make 20 dist" time. As such, there are strict requirements on the form of 21 the commit log messages. The old ChangeLog files have all be 22 renamed to ChangeLog-2011 23 24** Commit log requirements 25 26 Your commit log should always start with a one-line summary, the 27 second line should be blank, and the remaining lines are usually 28 ChangeLog-style entries for all affected files. However, it's fine 29 -- even recommended -- to write a few lines of prose describing the 30 change, when the summary and ChangeLog entries don't give enough of 31 the big picture. Omit the leading TABs that you're used to seeing 32 in a "real" ChangeLog file, but keep the maximum line length at 72 33 or smaller, so that the generated ChangeLog lines, each with its 34 leading TAB, will not exceed 80 columns. 35 36** License policy 37 38 Libgcrypt is currently licensed under the LGPLv2+ with tools and the 39 manual being under the GPLv2+. We may eventually update to a newer 40 version of the licenses or a combination of them. It is thus 41 important, that all contributed code allows for an update of the 42 license; for example we can't accept code under the LGPLv2(only). 43 44 Libgcrypt used to have a strict policy of requiring copyright 45 assignments to the FSF. To avoid this major organizational overhead 46 and to allow inclusion of code, not copyrighted by the FSF, this 47 policy has been relaxed. It is now also possible to contribute code 48 by asserting that the contribution is in accordance to the 49 "Libgcrypt Developer's Certificate of Origin" as found in the file 50 "DCO". (Except for a slight wording change, this DCO is identical 51 to the one used by the Linux kernel.) 52 53 If your want to contribute code or documentation to Libgcrypt and 54 you didn't signed a copyright assignment with the FSF in the past, 55 you need to take these simple steps: 56 57 - Decide which mail address you want to use. Please have your real 58 name in the address and not a pseudonym. Anonymous contributions 59 can only be done if you find a proxy who certifies for you. 60 61 - If your employer or school might claim ownership of code written 62 by you; you need to talk to them to make sure that you have the 63 right to contribute under the DCO. 64 65 - Send an OpenPGP signed mail to the gcrypt-devel@gnupg.org mailing 66 list from your mail address. Include a copy of the DCO as found 67 in the official master branch. Insert your name and email address 68 into the DCO in the same way you want to use it later. Example: 69 70 Signed-off-by: Joe R. Hacker <joe@example.org> 71 72 (If you really need it, you may perform simple transformations of 73 the mail address: Replacing "@" by " at " or "." by " dot ".) 74 75 - That's it. From now on you only need to add a "Signed-off-by:" 76 line with your name and mail address to the commit message. It is 77 recommended to send the patches using a PGP/MIME signed mail. 78 79** Coding standards 80 81 Please follow the GNU coding standards. If you are in doubt consult 82 the existing code as an example. Do no re-indent code without a 83 need. If you really need to do it, use a separate commit for such a 84 change. 85 86 87* Porting hints 88** Taking optimized MPI code out of GMP: 89 90 I generated the pentium4/* files by glueing the existing assembler 91 prologues to the GMP 4.2.1 assembler files generated with the m4 92 tool in GMP's build process, for example: 93 94 $ m4 -DHAVE_CONFIG_H -D__GMP_WITHIN_GMP -DOPERATION_rshift -DPIC \ 95 rshift.asm >tmp-rshift.s 96 97 Then tmp-rshift will contain the assembler instructions for the 98 configured platform. Unfortunately, this way the comments are lost. 99 For most files I re-inserted some of the comments, but this is 100 tedious work. 101 102 103* Debug hints 104 105** Debugging math stuff: 106 107 While debugging the ECC code in libgcrypt, I was in need for some 108 computer algebra system which would allow me to verify the numbers 109 in the debugging easily. I found that PARI (pari-gp package in 110 Debian) has support for elliptic curves. The below commands shows 111 how they are set up and used with an example. 112 113 ===8<======== 114 hextodec(s)=local(v=Vec(s),a=10,b=11,c=12,d=13,e=14,f=15,A=10,B=11,C=12,D=13,E=14,F=15,h);if(#setunion(Set(v),Vec("0123456789ABCDEFabcdef"))>22,error);for(i=1,#v,h=shift(h,4)+eval(v[i]));h 115 116 p = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF") 117 a = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC") 118 b = hextodec("51953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF109E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B503F00") 119 120 /* Set up y^2 = x^3 + ax + b mod (p). */ 121 e = ellinit(Mod(1,p)*[0,0,0,a,b]); 122 123 gx = hextodec ("00C6858E06B70404E9CD9E3ECB662395B4429C648139053FB521F828AF606B4D3DBAA14B5E77EFE75928FE1DC127A2FFA8DE3348B3C1856A429BF97E7E31C2E5BD66") 124 gy = hextodec ("011839296A789A3BC0045C8A5FB42C7D1BD998F54449579B446817AFBD17273E662C97EE72995EF42640C550B9013FAD0761353C7086A272C24088BE94769FD16650") 125 g = Mod(1,p)*[gx,gy] 126 127 n = hextodec ("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409") 128 129 /* Verify that G is on the curve, and that n is the order. */ 130 ellisoncurve (e,g) 131 isprime (n) 132 ellpow (e,g,n) 133 134 d = hextodec ("018F9573F25059571BDF614529953DE2540497CEDABD04F3AF78813BED7BB163A2FD919EECF822848FCA39EF55E500F8CE861C7D53D371857F7774B79428E887F81B") 135 136 qx = hextodec ("00316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B3B") 137 /* Note: WRONG! (It is apparent that this is the same as X shifted by 138 8 bit). */ 139 qy = hextodec ("0000316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B") 140 q = Mod(1,p)*[qx,qy] 141 142 /* Calculate what Q should be given d. */ 143 ellpow (e,g,d) 144 145 /* This is not 0 and thus shows that libgcrypt gave Q and d that do 146 not match. */ 147 ellpow (e,g,d) - q 148 ====8<===================== 149