Mailing List Archive

On Friday, 6. September 2002 13:38, you wrote:
> I am developing a webmail application and I am very interested in using
> the libgcrypt functions. So, I have downloaded the libgcrypt from the
> GNU site but I did't got as much information as I needed from the /doc
> files.

I have the same problem. But there doesn't exist a better documentation.

I can send you a wrapper library I wrote (public key alogrithm don't work
correct at the moment). The source of gnupg 1.1.2 is also a good to learn.

Yeah, before trying to use the libgcrypt , I had downloaded the gnupg-1.0.7
from the gnupg.org website and I tried unsuccessfully to isolate the
functions that I would use. There was some global variables that didn't help
either and the documentation on the gnupg website is only about using the
executable gpg ;) When I found the libgcrypt I felt released but the
documentation about using public key functions was none (except for the
title).

Anyway, I just need an explanation on how to use the public key functions,
what are those structures, how can I store the keys, etc. The basics.
Something that I could start with. If anyone can help I would appreciate.

Rüdiger, if you could send me your wrapper library and some example codes I
would be glad.

Thanks,

Rafael P. Laufer

----- Original Message -----
From: "Rüdiger Sonderfeld" <cplusplushelp@gmx.net>
To: <gcrypt-devel@gnupg.org>
Sent: Saturday, September 07, 2002 5:24 AM
Subject: Re: libgcrypt documentation


> On Friday, 6. September 2002 13:38, you wrote:
> > I am developing a webmail application and I am very interested in using
> > the libgcrypt functions. So, I have downloaded the libgcrypt from the
> > GNU site but I did't got as much information as I needed from the /doc
> > files.
>
> I have the same problem. But there doesn't exist a better documentation.
>
> I can send you a wrapper library I wrote (public key alogrithm don't work
> correct at the moment). The source of gnupg 1.1.2 is also a good to learn.
>
> _______________________________________________
> Gcrypt-devel mailing list
> Gcrypt-devel@gnupg.org
> http://lists.gnupg.org/mailman/listinfo/gcrypt-devel
>
>

On Fri, 06 Sep 2002 08:38:26 -0300, Rafael P Laufer said:

> Is there a detailed manual which explaines the use of the functions and
> the structures?? Where can I find some tutorials and code examples ?? If

There is just a reference manual. For example code, see AIDE, GNUTLS
or NEWPG. They all make extensive use of libgcrypt. I'd suggest
ftp://ftp.gnupg.org/alpha/aegypten/newpg-0.9.1.tar.gz


Shalom-Salam,

Werner

> There is just a reference manual. For example code, see AIDE, GNUTLS
> or NEWPG. They all make extensive use of libgcrypt. I'd suggest
> ftp://ftp.gnupg.org/alpha/aegypten/newpg-0.9.1.tar.gz
>

Where is this reference manual ??

Rafael Laufer

On Sun, 08 Sep 2002 11:43:45 -0300, Rafael P Laufer said:

> Where is this reference manual ??

libgcrypt-1.1.9/doc/gcrypt.info

Be warned, a lot of stuff is missing. Do you want to volunteer?


Shalom-Salam,

Werner

I was aware...that's why I am asking for some reference.

For me to be a volunteer I first have to use the library and for that I need
some reference :)

Rafael

----- Original Message -----
From: "Werner Koch" <wk@gnupg.org>
To: "Rafael P. Laufer" <rlaufer@rjnet.com.br>
Cc: <gcrypt-devel@gnupg.org>
Sent: Monday, September 09, 2002 5:04 AM
Subject: Re: libgcrypt documentation


> On Sun, 08 Sep 2002 11:43:45 -0300, Rafael P Laufer said:
>
> > Where is this reference manual ??
>
> libgcrypt-1.1.9/doc/gcrypt.info
>
> Be warned, a lot of stuff is missing. Do you want to volunteer?
>
>
> Shalom-Salam,
>
> Werner
>
>
>

Werner Koch <wk@gnupg.org> writes:

> On Sun, 08 Sep 2002 11:43:45 -0300, Rafael P Laufer said:
>
>> Where is this reference manual ??
>
> libgcrypt-1.1.9/doc/gcrypt.info
>
> Be warned, a lot of stuff is missing. Do you want to volunteer?

Not volunteering, but offering a starting point -- at least a possible
starting point, I find writing API documentation using gdoc is nice.
Just C-x 4 h on a function (using gnome-doc.el, from e.g. the
gnome-libs-data Debian package), write documentation, and it is
automatically generated into texinfo which can be included in the main
manual. No need to synch separate manual with the code.

I started moving some documentation from doc/gcrypt.texi into
cipher/cipher.c but soon got bored... I'm not sure how to do the
#define macros too. Ideally they should be converted into @deftypefn
Macro: or something like that. Perhaps someone like to pick up.

If someone has ideas on or pointers to a more robust tools for this
approach, I'd appreciate it. I haven't seen anything like this for
texinfo (I added texinfo support to gdoc for another project).

Index: configure.ac
===================================================================
RCS file: /cvs/gnupg/libgcrypt/configure.ac,v
retrieving revision 1.19
diff -u -p -r1.19 configure.ac
--- configure.ac 23 Aug 2002 20:05:18 -0000 1.19
+++ configure.ac 10 Sep 2002 02:51:57 -0000
@@ -175,6 +175,7 @@ AM_MISSING_PROG(AUTOCONF, autoconf, $mis
AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
dnl AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)
+AM_MISSING_PROG(PERL, perl, $missing_dir)
AC_PROG_CC
AC_PROG_CPP
AM_PROG_AS
Index: cipher/cipher.c
===================================================================
RCS file: /cvs/gnupg/libgcrypt/cipher/cipher.c,v
retrieving revision 1.46
diff -u -p -r1.46 cipher.c
--- cipher/cipher.c 17 Aug 2002 09:15:54 -0000 1.46
+++ cipher/cipher.c 10 Sep 2002 02:51:57 -0000
@@ -490,13 +490,17 @@ cipher_get_blocksize( int algo )
return 0;
}

-
-/****************
- * Open a cipher handle for use with algorithm ALGO, in mode MODE
- * and return the handle. Return NULL and set the internal error variable
- * if something goes wrong.
- */
-
+/**
+ * gcry_cipher_open:
+ * @algo: Algorithm number, e.g. %GCRY_CIPHER_AES.
+ * @mode: Mode of operation, e.g. %GCRY_CIPHER_MODE_CBC.
+ * @flags: Flags, including %GCRY_CIPHER_SECURE and %GCRY_CIPHER_ENABLE_SYNC.
+ *
+ * This function creates the context required for most of the othercipher
+ * functions.
+ *
+ * Return value: In case of an error @code{NULL} is returned.
+ **/
GCRY_CIPHER_HD
gcry_cipher_open( int algo, int mode, unsigned int flags )
{
@@ -580,6 +584,12 @@ gcry_cipher_open( int algo, int mode, un
}


+/**
+ * gcry_cipher_close:
+ * @h: Handle from gcry_cipher_open().
+ *
+ * This function releases the context created by @code{gcry_cipher_open}.
+ **/
void
gcry_cipher_close( GCRY_CIPHER_HD h )
{
@@ -953,6 +963,13 @@ cipher_sync( GCRY_CIPHER_HD c )
}


+/**
+ * gcry_cipher_ctl:
+ *
+ * gcry_cipher_ctl() controls various aspects of the cipher module and
+ * specific cipher contexts. Usually some more specialzed functions are
+ * used for this purpose.
+ **/
int
gcry_cipher_ctl( GCRY_CIPHER_HD h, int cmd, void *buffer, size_t buflen)
{
Index: doc/Makefile.am
===================================================================
RCS file: /cvs/gnupg/libgcrypt/doc/Makefile.am,v
retrieving revision 1.21
diff -u -p -r1.21 Makefile.am
--- doc/Makefile.am 14 May 2002 13:11:06 -0000 1.21
+++ doc/Makefile.am 10 Sep 2002 02:51:57 -0000
@@ -22,3 +22,7 @@ DISTCLEANFILES = gcrypt.cps
info_TEXINFOS = gcrypt.texi
gcrypt_TEXINFOS = lgpl.texi gpl.texi fdl.texi

+gcrypt.info: gcrypt.texi cipher-ref.texi
+
+cipher-ref.texi: $(top_srcdir)/cipher/cipher.c
+ $(PERL) gdoc -texinfo $(top_srcdir)/cipher/cipher.c > $@
Index: doc/gcrypt.texi
===================================================================
RCS file: /cvs/gnupg/libgcrypt/doc/gcrypt.texi,v
retrieving revision 1.3
diff -u -p -r1.3 gcrypt.texi
--- doc/gcrypt.texi 14 Aug 2002 19:07:55 -0000 1.3
+++ doc/gcrypt.texi 10 Sep 2002 02:51:57 -0000
@@ -272,29 +272,10 @@ gcc -o foo foo.c `libgcrypt-config --cfl
@c **********************************************************
@c ******************* Ciphers ****************************
@c **********************************************************
-@c @include cipher-ref.texi
@node Cipher Functions
@chapter Cipher Functions

-
-@deftypefun GCRY_CIPHER_HD gcry_cipher_open (int @var{algo}, int @var{mode}, unsigned int @var{flags})
-
-This function creates the context required for most of the othercipher
-functions. In case of an error @code{NULL} is returned.
-@end deftypefun
-
-@deftypefun void gcry_cipher_close (GCRY_CIPHER_HD @var{h})
-
-This function releases the context created by @code{gcry_cipher_open}.
-@end deftypefun
-
-
-@deftypefun int gcry_cipher_ctl (GCRY_CIPHER_HD @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
-
-@code{gcry_cipher_ctl} controls various aspects of the cipher module and
-specific cipher contexts. Usually some more specialzed functions are
-used for this purpose.
-@end deftypefun
+@include cipher-ref.texi

@deftypefun int gcry_cipher_setkey (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})

On Tue, 10 Sep 2002 05:01:27 +0200, Simon Josefsson said:

> starting point, I find writing API documentation using gdoc is nice.
> Just C-x 4 h on a function (using gnome-doc.el, from e.g. the
> gnome-libs-data Debian package), write documentation, and it is
> automatically generated into texinfo which can be included in the main

I did this in the past for a few libraries but meanwhile I changed it
back to regular manual writing. The problem with doc strings is that
there are often out of contect and for a real manual one has to write
more than just the description of functions and types. Given that an
API should not change, I don't think it is a hard task to keep it all
in sync. The experience with GPGME has shown that writing the manual
(well, okay it is also more a reference manual than a user manual)
along with the code isn't too hard.

The style coding is usually done doesn't fit best with writing a good
manual. For example the Gnus manual is very readbale and I don't
think that it would be possible to generate it from the Lisp comment
strings. Literate Programming might be a way out, though.

Werner Koch <wk@gnupg.org> writes:

> On Tue, 10 Sep 2002 05:01:27 +0200, Simon Josefsson said:
>
>> starting point, I find writing API documentation using gdoc is nice.
>> Just C-x 4 h on a function (using gnome-doc.el, from e.g. the
>> gnome-libs-data Debian package), write documentation, and it is
>> automatically generated into texinfo which can be included in the main
>
> I did this in the past for a few libraries but meanwhile I changed it
> back to regular manual writing. The problem with doc strings is that
> there are often out of contect and for a real manual one has to write
> more than just the description of functions and types. Given that an
> API should not change, I don't think it is a hard task to keep it all
> in sync. The experience with GPGME has shown that writing the manual
> (well, okay it is also more a reference manual than a user manual)
> along with the code isn't too hard.
>
> The style coding is usually done doesn't fit best with writing a good
> manual. For example the Gnus manual is very readbale and I don't
> think that it would be possible to generate it from the Lisp comment
> strings. Literate Programming might be a way out, though.

Yes, gnome-doc and its like are mostly for reference manuals. But it
seems like it is that part of the manual which is mostly missing
though.

Btw, CVS fails make check on some platforms, it crashes somewhere
inside the hash code invoked from the new DES selftest (call to
md_open). I don't have a debugger on the system so I don't have a
backtrace.