Generate the ChangeLog from commit logs.
[libgcrypt.git] / doc / HACKING
1                         Various hacking notes                  -*- text -*-
2                        =======================
3
4 No more ChangeLog files
5 -----------------------
6
7 Do not modify any of the ChangeLog files in Libgcrypt.  Starting on
8 December 1st, 2011 we put change information only in the GIT commit
9 log, and generate a top-level ChangeLog file from logs at "make dist"
10 time.  As such, there are strict requirements on the form of the
11 commit log messages.  The old ChangeLog files have all be renamed to
12 ChangeLog-2011
13
14
15 Commit log requirements
16 -----------------------
17
18 Your commit log should always start with a one-line summary, the second
19 line should be blank, and the remaining lines are usually ChangeLog-style
20 entries for all affected files.  However, it's fine -- even recommended --
21 to write a few lines of prose describing the change, when the summary
22 and ChangeLog entries don't give enough of the big picture.  Omit the
23 leading TABs that you're used to seeing in a "real" ChangeLog file, but
24 keep the maximum line length at 72 or smaller, so that the generated
25 ChangeLog lines, each with its leading TAB, will not exceed 80 columns.
26
27
28
29 Taking optimized MPI code out of GMP:
30 -------------------------------------
31
32   I generated the pentium4/* files by glueing the existing assembler
33   prologues to the GMP 4.2.1 assembler files generated with the m4
34   tool in GMP's build process, for example:
35
36     $ m4 -DHAVE_CONFIG_H -D__GMP_WITHIN_GMP -DOPERATION_rshift -DPIC \
37       rshift.asm >tmp-rshift.s
38
39   Then tmp-rshift will contain the assembler instructions for the
40   configured platform.  Unfortunately, this way the comments are lost.
41   For most files I re-inserted some of the comments, but this is
42   tedious work.
43
44
45 Debugging math stuff:
46 ---------------------
47
48   While debugging the ECC code in libgcrypt, I was in need for some
49   computer algebra system which would allow me to verify the numbers
50   in the debugging easily.  I found that PARI (pari-gp package in
51   Debian) has support for elliptic curves.  The below commands shows
52   how they are set up and used with an example.
53
54   ===8<========
55   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
56
57   p = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF")
58   a = hextodec("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC")
59   b = hextodec("51953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF109E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B503F00")
60
61   /* Set up y^2 = x^3 + ax + b mod (p).  */
62   e = ellinit(Mod(1,p)*[0,0,0,a,b]);
63
64   gx = hextodec ("00C6858E06B70404E9CD9E3ECB662395B4429C648139053FB521F828AF606B4D3DBAA14B5E77EFE75928FE1DC127A2FFA8DE3348B3C1856A429BF97E7E31C2E5BD66")
65   gy = hextodec ("011839296A789A3BC0045C8A5FB42C7D1BD998F54449579B446817AFBD17273E662C97EE72995EF42640C550B9013FAD0761353C7086A272C24088BE94769FD16650")
66   g = Mod(1,p)*[gx,gy]
67
68   n = hextodec ("01FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA51868783BF2F966B7FCC0148F709A5D03BB5C9B8899C47AEBB6FB71E91386409")
69
70   /* Verify that G is on the curve, and that n is the order.  */
71   ellisoncurve (e,g)
72   isprime (n)
73   ellpow (e,g,n)
74
75   d = hextodec ("018F9573F25059571BDF614529953DE2540497CEDABD04F3AF78813BED7BB163A2FD919EECF822848FCA39EF55E500F8CE861C7D53D371857F7774B79428E887F81B")
76
77   qx = hextodec ("00316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B3B")
78   /* Note: WRONG! (It is apparent that this is the same as X shifted by
79      8 bit).  */
80   qy = hextodec ("0000316AAAD3E905875938F588BD9E8A4785EF9BDB76D62A83A5340F82CB8E800B25619F5C3EA02B7A4FA43D7497C7702F7DFBEAC8E8F92C3CAABD9F84182FDA391B")
81   q = Mod(1,p)*[qx,qy]
82
83   /* Calculate what Q should be given d.  */
84   ellpow (e,g,d)
85
86   /* This is not 0 and thus shows that libgcrypt gave Q and d that do
87   not match.  */
88   ellpow (e,g,d) - q
89   ====8<=====================