diff options
Diffstat (limited to 'comm/third_party/libgcrypt/doc/HACKING')
| -rw-r--r-- | comm/third_party/libgcrypt/doc/HACKING | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/comm/third_party/libgcrypt/doc/HACKING b/comm/third_party/libgcrypt/doc/HACKING new file mode 100644 index 0000000000..0cb8d56098 --- /dev/null +++ b/comm/third_party/libgcrypt/doc/HACKING @@ -0,0 +1,143 @@ +# HACKING -*- org -*- +#+TITLE: Hacking notes for Libgcrypt +#+STARTUP: showall + +* How to contribute + + The following stuff explains some basic procedures you need to + follow if you want to contribute code or documentation. + +** No more ChangeLog files + + Do not modify any of the ChangeLog files in Libgcrypt. Starting on + December 1st, 2011 we put change information only in the GIT commit + log, and generate a top-level ChangeLog file from logs at "make + dist" time. As such, there are strict requirements on the form of + the commit log messages. The old ChangeLog files have all be + renamed to ChangeLog-2011 + +** Commit log requirements + + Your commit log should always start with a one-line summary, the + second line should be blank, and the remaining lines are usually + ChangeLog-style entries for all affected files. However, it's fine + -- even recommended -- to write a few lines of prose describing the + change, when the summary and ChangeLog entries don't give enough of + the big picture. Omit the leading TABs that you're used to seeing + in a "real" ChangeLog file, but keep the maximum line length at 72 + or smaller, so that the generated ChangeLog lines, each with its + leading TAB, will not exceed 80 columns. + +** License policy + + Libgcrypt is currently licensed under the LGPLv2+ with tools and the + manual being under the GPLv2+. We may eventually update to a newer + version of the licenses or a combination of them. It is thus + important, that all contributed code allows for an update of the + license; for example we can't accept code under the LGPLv2(only). + + Libgcrypt used to have a strict policy of requiring copyright + assignments to the FSF. To avoid this major organizational overhead + and to allow inclusion of code, not copyrighted by the FSF, this + policy has been relaxed. It is now also possible to contribute code + by asserting that the contribution is in accordance to the + "Libgcrypt Developer's Certificate of Origin" as found in the file + "DCO". (Except for a slight wording change, this DCO is identical + to the one used by the Linux kernel.) + + If your want to contribute code or documentation to Libgcrypt and + you didn't signed a copyright assignment with the FSF in the past, + you need to take these simple steps: + + - Decide which mail address you want to use. Please have your real + name in the address and not a pseudonym. Anonymous contributions + can only be done if you find a proxy who certifies for you. + + - If your employer or school might claim ownership of code written + by you; you need to talk to them to make sure that you have the + right to contribute under the DCO. + + - Send an OpenPGP signed mail to the gcrypt-devel@gnupg.org mailing + list from your mail address. Include a copy of the DCO as found + in the official master branch. Insert your name and email address + into the DCO in the same way you want to use it later. Example: + + Signed-off-by: Joe R. Hacker <joe@example.org> + + (If you really need it, you may perform simple transformations of + the mail address: Replacing "@" by " at " or "." by " dot ".) + + - That's it. From now on you only need to add a "Signed-off-by:" + line with your name and mail address to the commit message. It is + recommended to send the patches using a PGP/MIME signed mail. + +** Coding standards + + Please follow the GNU coding standards. If you are in doubt consult + the existing code as an example. Do no re-indent code without a + need. If you really need to do it, use a separate commit for such a + change. + + +* Porting hints +** Taking optimized MPI code out of GMP: + + I generated the pentium4/* files by glueing the existing assembler + prologues to the GMP 4.2.1 assembler files generated with the m4 + tool in GMP's build process, for example: + + $ m4 -DHAVE_CONFIG_H -D__GMP_WITHIN_GMP -DOPERATION_rshift -DPIC \ + rshift.asm >tmp-rshift.s + + Then tmp-rshift will contain the assembler instructions for the + configured platform. Unfortunately, this way the comments are lost. + For most files I re-inserted some of the comments, but this is + tedious work. + + +* Debug hints + +** Debugging math stuff: + + While debugging the ECC code in libgcrypt, I was in need for some + computer algebra system which would allow me to verify the numbers + in the debugging easily. I found that PARI (pari-gp package in + Debian) has support for elliptic curves. The below commands shows + how they are set up and used with an example. + + ===8<======== + 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 + + p = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF") + a = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC") + b = hextodec("51953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF109E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B503F00") + + /* Set up y^2 = x^3 + ax + b mod (p). */ + e = ellinit(Mod(1,p)*[0,0,0,a,b]); + + gx = hextodec ("00C6858E06B70404E9CD9E3ECB662395B4429C648139053FB521F828AF606B4D3DBAA14B5E77EFE75928FE1DC127A2FFA8DE3348B3C1856A429BF97E7E31C2E5BD66") + gy = hextodec ("011839296A789A3BC0045C8A5FB42C7D1BD998F54449579B446817AFBD17273E662C97EE72995EF42640C550B9013FAD0761353C7086A272C24088BE94769FD16650") + g = Mod(1,p)*[gx,gy] + + n = hextodec ("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409") + + /* Verify that G is on the curve, and that n is the order. */ + ellisoncurve (e,g) + isprime (n) + ellpow (e,g,n) + + d = hextodec ("018F9573F25059571BDF614529953DE2540497CEDABD04F3AF78813BED7BB163A2FD919EECF822848FCA39EF55E500F8CE861C7D53D371857F7774B79428E887F81B") + + qx = hextodec ("00316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B3B") + /* Note: WRONG! (It is apparent that this is the same as X shifted by + 8 bit). */ + qy = hextodec ("0000316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B") + q = Mod(1,p)*[qx,qy] + + /* Calculate what Q should be given d. */ + ellpow (e,g,d) + + /* This is not 0 and thus shows that libgcrypt gave Q and d that do + not match. */ + ellpow (e,g,d) - q + ====8<===================== |