doc/HACKING - nest-hello/507800056/libgcrypt - Git at Google


            
            # 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<=====================
	# 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<=====================