From d8199e30941f619906f4d521797914a63a5a9b05 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Tue, 8 Feb 2000 17:12:00 +0000 Subject: Add some libgcrypt dox --- doc/Makefile.am | 32 ++--- doc/gcryptref-cipher.sgml | 23 +++- doc/gcryptref-digest.sgml | 329 ++++++++++++++++++++++++++++++++++++++++++---- doc/gcryptref-misc.sgml | 47 +++++++ doc/gcryptref-pubkey.sgml | 72 ++++++++++ doc/gcryptref.sgml | 41 +----- 6 files changed, 467 insertions(+), 77 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 39fabf9b4..04ad0a4c7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,31 +1,33 @@ ## Process this file with automake to create Makefile.in -##SUBDIRS = gph - EXTRA_DIST = DETAILS gpg.sgml gpg.1 FAQ HACKING OpenPGP man_MANS = gpg.1 +gcryptref.dvi : gcryptref.sgml + +gcryptref.texi : gcryptref.sgml +gcryptref.xml : gcryptref.sgml + + +%.ps: %.dvi + dvips -o $@ $< + + +if MAINTAINER_MODE + %.1 : %.sgml -if HAVE_DOCBOOK_TO_MAN docbook-to-man $< >$@ -else - : Warning: missing docbook-to-man, cannot make $@ - echo ".TH $< 1" >$@ - echo "No man page due to missing docbook-to-man" >>$@ -endif +%.texi : %.xml + docbook2texi $< >$@ -gcryptref.dvi : gcryptref.sgml +%.xml : %.sgml + sgml2xml -x lower $< >$@ -%.dvi: %.sgml - db2dvi $< +endif -%.ps: %.dvi - dvips -o $@ $< -%/%.html: %.sgml - -db2html $< diff --git a/doc/gcryptref-cipher.sgml b/doc/gcryptref-cipher.sgml index 1253b38f3..379de5a7e 100644 --- a/doc/gcryptref-cipher.sgml +++ b/doc/gcryptref-cipher.sgml @@ -18,6 +18,9 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA --> + gcry_cipher_open @@ -48,6 +51,8 @@ cipher functions gcry_cipher_open + + cipher functions gcry_cipher_close gcry_cipher_open creates the context required for @@ -56,6 +61,9 @@ + gcry_cipher_ctl @@ -98,6 +106,9 @@ + gcry_cipher_info @@ -130,6 +141,9 @@ + gcry_cipher_algo_name @@ -161,6 +175,9 @@ + gcry_cipher_map_name @@ -191,7 +208,9 @@ - + gcry_cipher_encrypt @@ -228,6 +247,8 @@ cipher functions gcry_cipher_encrypt + + cipher functions gcry_cipher_decrypt gcry_cipher_encrypt is used to encrypt the data. diff --git a/doc/gcryptref-digest.sgml b/doc/gcryptref-digest.sgml index 63a345a73..f0d5efff4 100644 --- a/doc/gcryptref-digest.sgml +++ b/doc/gcryptref-digest.sgml @@ -18,6 +18,9 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA --> + gcry_md_open @@ -53,7 +56,11 @@ hash functions gcry_md_open + + hash functions gcry_md_enable + + hash functions gcry_md_close gcry_md_open creates the context required for @@ -69,6 +76,9 @@ + gcry_md_copy @@ -99,6 +109,9 @@ + gcry_md_reset @@ -129,8 +142,13 @@ + + gcry_md_ctl + gcry_md_final perform special operations on a digest context @@ -159,33 +177,292 @@ to control the behaviour of all gcry_md functions or one instance of it. + + Currently defined values for cmd are: + GCRYCTL_FINALIZE and the conevnience macro + gcry_md_final(a) + + + + + + + gcry_md_write + gcry_md_putc + calculate the message digest of a buffer + + + + + + #include <gcrypt.h> + + + int gcry_md_write + GCRY_MD_HD h + unsigned char * buffer + size_t buflen + + + int gcry_md_putc + GCRY_MD_HD h + int c + + + + + + Description + + hash functions + gcry_md_write + hash functions + gcry_md_putc + gcry_md_write is used to actually calulate the message + digest of a buffer. This function updates the internal state of the message + digest. + + + gcry_md_putc is a macro which is used to update + the message digest by one byte. this is the preferred way to calculate + a digest if only a few bytes at a time are available. + + + + + + + gcry_md_read + read out the message digest + + + + + + #include <gcrypt.h> + + + unsigned char * gcry_md_read + GCRY_MD_HD h + int algo + + + + + + Description + + hash functions + gcry_md_read + + hash functions + gcry_md_putc + + gcry_md_read returns the message digest after finalizing + the calculation. This function may be used as often as required but it + will alwas return the same value for one handle. The returned message + digest is allocated within the message context and therefore valid until + the conext is released. algo may be given as 0 to return the + only enbaled message digest or it may specify one of the enabled algorithms. + The function will return NULL if the algorithm has not been enabled. + -void gcry_md_write( GCRY_MD_HD hd, const byte *buffer, size_t length); -byte *gcry_md_read( GCRY_MD_HD hd, int algo ); -void gcry_md_hash_buffer( int algo, char *digest, - const char *buffer, size_t length); -int gcry_md_get_algo( GCRY_MD_HD hd ); -unsigned int gcry_md_get_algo_dlen( int algo ); -int gcry_md_info( GCRY_MD_HD h, int what, void *buffer, size_t *nbytes); -int gcry_md_algo_info( int algo, int what, void *buffer, size_t *nbytes); -const char *gcry_md_algo_name( int algo ); -int gcry_md_map_name( const char* name ); - -#define gcry_md_putc(h,c) \ - do { \ - if( (h)->bufpos == (h)->bufsize ) \ - gcry_md_write( (h), NULL, 0 ); \ - (h)->buf[(h)->bufpos++] = (c) & 0xff; \ - } while(0) - -#define gcry_md_final(a) \ - gcry_md_ctl( (a), GCRYCTL_FINALIZE, NULL, 0 ) - -#define gcry_md_is_secure(a) \ - gcry_md_info( (a), GCRYCTL_IS_SECURE, NULL, NULL ) - -#define gcry_md_test_algo(a) \ - gcry_md_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL ) + + + + gcry_md_info + get information about a handle + + + + + + #include <gcrypt.h> + + + int gcry_md_info + GCRY_MD_HD h + int what + void * buffer + size_t buflen + + + + + Description + + hash functions + gcry_md_info + + gcry_md_info returns some information about the + handle or an global parameter. + + + The only defined value for what is + GCRYCTL_IS_SECURE to return whether the handle + has been allocated in secure memory. Buffer and buflen are not needed + in this cases. The convenience macro gcry_md_is_secure(a) + may be also used for this purpose. + + + + + + + + gcry_md_algo_info + gcry_md_test_algo + gcry_md_get_algo_dlen + get information about an algorithm + + + + + + #include <gcrypt.h> + + + int gcry_md_algo_info + int algo + int what + void * buffer + size_t buflen + + + unsigned int gcry_md_get_algo_dlen + int algo + + + + + Description + + hash functions + gcry_md_algo_info + + gcry_md_algo_info returns some information about an + algorithm. On error the value -1 is return and a more detailed error + description is available with gcry_errno. + + + The defined values for what are + GCRYCTL_TEST_ALGO to return whether the algorithm + is supported. Buffer and buflen are not needed + in this cases. The convenience macro gcry_md_test_algo(a) + may be used for this purpose. + + + GCRYCTL_GET_ASNOID to return whether the ASN.1 + object identifier. IF buffer is specified as NULL, only the required + length for the buffer is returned. + + + hash functions + gcry_md_get_algo_dlen + + gcry_md_get_algo_dlen returns the length of the + digest for a given algorithm in bytes. + + + + + + + + gcry_md_algo_name + gcry_md_map_name + map algorithm to string + + + + + + #include <gcrypt.h> + + + const char * gcry_md_algo_name + int algo + + + int gcry_md_map_name + const char*name + + + + + Description + + hash functions + gcry_md_algo_name + + hash functions + gcry_md_map_name + + These both functions are used to map a string with the algorithm name to + the internal algorithm identifier value and vice versa. + + + gcry_md_algo_name never returns NULL even in cases where the + algorithm string is not available. Instead a string consisting of a + single question mark is returned. Do not use this function to test + for the existence of an algorithm. + + + gcry_md_map_name returns 0 if the algorithm is not known + to &libgcrypt;. + + + + + + + + + gcry_md_hash_buffer + fast message calculation + + + + + + #include <gcrypt.h> + + + int gcry_md_hash_buffer + int algo + char * digest + const char * buffer + size_t buflen + + + + + Description + + hash functions + gcry_md_hash_buffer + + gcry_md_hash_buffer is a shortcut function + to calculate a message digest of a buffer. This function does not require + a context and immediatley returns the message digest. + digest must be string large enough to hold the digest + given by algo. This length may be obtained by using the function + gcry_md_get_algo_dlen but in most cases it will be a statically + allocated buffer. + + diff --git a/doc/gcryptref-misc.sgml b/doc/gcryptref-misc.sgml index 881931869..31032d64d 100644 --- a/doc/gcryptref-misc.sgml +++ b/doc/gcryptref-misc.sgml @@ -18,3 +18,50 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA --> + + diff --git a/doc/gcryptref-pubkey.sgml b/doc/gcryptref-pubkey.sgml index 881931869..a1a97dc9c 100644 --- a/doc/gcryptref-pubkey.sgml +++ b/doc/gcryptref-pubkey.sgml @@ -18,3 +18,75 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA --> + + + + + gcry_pk_encrypt + do a public key encryption + + + + + + #include <gcrypt.h> + + + int gcry_pk_encrypt + GCRY_SEXP *result + GCRY_SEXP data + GCRY_SEXP pkey + + + + + + Description + + public key functions + gcry_pk_encrypt + + gcry_pk_encrypt performs public key encryption + operations. The caller has to provide a public key as the &sexp; + pkey and data as a &sexp; + with just one MPI in it. The function returns a &sexp; which may + be passed tp to pk_decrypt. + Later versions of this functions may take more complex input data. + + Returns: 0 or an errorcode. + + + s_data = ( + + + + + diff --git a/doc/gcryptref.sgml b/doc/gcryptref.sgml index 6161e8610..abc3efb20 100644 --- a/doc/gcryptref.sgml +++ b/doc/gcryptref.sgml @@ -20,56 +20,27 @@ + ]> - &libgcrypt; Reference Pages - -Symmetric Cipher Functions + &cipherref; -Hash Functions + &digestref; -Public Key Functions + &pubkeyref; - -Miscellaneous Functions + &miscref; -- cgit v1.2.3