doc/HACKING

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