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