539 lines
21 KiB
Plaintext
539 lines
21 KiB
Plaintext
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sh \" Subsection heading
|
|
.br
|
|
.if t .Sp
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. | will give a
|
|
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
|
|
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
|
|
.\" expand to `' in nroff, nothing in troff, for use with C<>.
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.\"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.hy 0
|
|
.if n .na
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "mhash 3"
|
|
.TH mhash 3 "2000/03/23" "mhash 0.9.2" "mhash library"
|
|
.SH "NAME"
|
|
\&\fBmhash \- Hash Library\fR
|
|
.SH "VERSION"
|
|
.IX Header "VERSION"
|
|
mhash \s-10.9.2\s0
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include "mhash.h"
|
|
.Ve
|
|
.PP
|
|
\&\fB Informative Functions \fR
|
|
.PP
|
|
.Vb 5
|
|
\& size_t mhash_count(void);
|
|
\& size_t mhash_get_block_size(hashid type);
|
|
\& char *mhash_get_hash_name(hashid type);
|
|
\& size_t mhash_get_hash_pblock(hashid type);
|
|
\& hashid mhash_get_mhash_algo( MHASH);
|
|
.Ve
|
|
.PP
|
|
\&\fB Key Generation Functions \fR
|
|
.PP
|
|
.Vb 3
|
|
\& int mhash_keygen_ext(keygenid algorithm, KEYGEN algorithm_data,
|
|
\& void* keyword, int keysize,
|
|
\& unsigned char* password, int passwordlen);
|
|
.Ve
|
|
.PP
|
|
\&\fB Initializing Functions \fR
|
|
.PP
|
|
.Vb 3
|
|
\& MHASH mhash_init(hashid type);
|
|
\& MHASH mhash_hmac_init(const hashid type, void *key, int keysize, int block);
|
|
\& MHASH mhash_cp( MHASH);
|
|
.Ve
|
|
.PP
|
|
\&\fB Update Functions \fR
|
|
.PP
|
|
.Vb 1
|
|
\& int mhash(MHASH thread, const void *plaintext, size_t size);
|
|
.Ve
|
|
.PP
|
|
\&\fB Save/Restore Functions \fR
|
|
.PP
|
|
.Vb 2
|
|
\& int mhash_save_state_mem(MHASH thread, void *mem, int* mem_size );
|
|
\& MHASH mhash_restore_state_mem(void* mem);
|
|
.Ve
|
|
.PP
|
|
\&\fB Finalizing Functions \fR
|
|
.PP
|
|
.Vb 3
|
|
\& void mhash_deinit(MHASH thread, void *result);
|
|
\& void *mhash_end(MHASH thread);
|
|
\& void *mhash_end_m(MHASH thread, void* (*hash_malloc)(size_t));
|
|
.Ve
|
|
.PP
|
|
.Vb 3
|
|
\& void *mhash_hmac_end(MHASH thread);
|
|
\& void *mhash_hmac_end_m(MHASH thread, void* (*hash_malloc)(size_t));
|
|
\& int mhash_hmac_deinit(MHASH thread, void *result);
|
|
.Ve
|
|
.PP
|
|
\&\fB Available Hashes \fR
|
|
.PP
|
|
\&\fI\s-1CRC32\s0\fR:
|
|
The crc32 algorithm is used to compute checksums. The two variants used
|
|
in mhash are: \fB\s-1MHASH_CRC32\s0\fR (like the one used in ethernet) and \fB\s-1MHASH_CRC32B\s0\fR
|
|
(like the one used in \s-1ZIP\s0 programs).
|
|
.PP
|
|
\&\fI\s-1ADLER32\s0\fR:
|
|
The adler32 algorithm is used to compute checksums. It is faster than
|
|
\&\s-1CRC32\s0 and it is considered to be as reliable as \s-1CRC32\s0. This algorithm
|
|
is defined as \fB\s-1MHASH_ADLER32\s0\fR.
|
|
.PP
|
|
\&\fI\s-1MD5\s0\fR: The \s-1MD5\s0 algorithm by Ron Rivest and \s-1RSA\s0. In mhash this algorithm is defined
|
|
as \fB\s-1MHASH_MD5\s0\fR.
|
|
.PP
|
|
\&\fI\s-1MD4\s0\fR: The \s-1MD4\s0 algorithm by Ron Rivest and \s-1RSA\s0. This algorithm is
|
|
considered broken, so don't use it. In mhash this algorithm is defined
|
|
as \fB\s-1MHASH_MD4\s0\fR.
|
|
.PP
|
|
\&\fI\s-1SHA1\s0\fR/\fI\s-1SHA256\s0\fR: The \s-1SHA\s0 algorithm by \s-1US\s0. \s-1NIST/NSA\s0. This algorithm is specified
|
|
for use in the \s-1NIST\s0's Digital Signature Standard. In mhash these algorithm
|
|
are defined as \fB\s-1MHASH_SHA1\s0\fR and \fB\s-1MHASH_SHA256\s0\fR.
|
|
.PP
|
|
\&\fI\s-1HAVAL\s0\fR:
|
|
\&\s-1HAVAL\s0 is a one-way hashing algorithm with variable length of output.
|
|
\&\s-1HAVAL\s0 is a modification of \s-1MD5\s0.
|
|
Defined in mhash as: \fB\s-1MHASH_HAVAL256\s0, \s-1MHASH_HAVAL192\s0, \s-1MHASH_HAVAL160\s0, \s-1MHASH_HAVAL128\s0\fR.
|
|
.PP
|
|
\&\fI\s-1RIPEMD160\s0\fR:
|
|
\&\s-1RIPEMD\-160\s0 is a 160\-bit cryptographic hash function, designed by Hans Dobbertin, Antoon Bosselaers, and Bart Preneel. It is intended to be used as a secure replacement
|
|
for the 128\-bit hash functions \s-1MD4\s0, \s-1MD5\s0, and \s-1RIPEMD\s0. \s-1MD4\s0 and \s-1MD5\s0 were developed by Ron Rivest for \s-1RSA\s0 Data Security, while \s-1RIPEMD\s0 was developed in the
|
|
framework of the \s-1EU\s0 project \s-1RIPE\s0 (\s-1RACE\s0 Integrity Primitives Evaluation, 1988\-1992).
|
|
In mhash this algorithm is defined as \fB\s-1MHASH_RIPEMD160\s0\fR.
|
|
.PP
|
|
\&\fI\s-1TIGER\s0\fR: Tiger is a fast hash function, by Eli Biham and Ross Anderson.
|
|
Tiger was designed to be very fast on modern computers, and in particular on the state-of-the-art 64\-bit computers,
|
|
while it is still not slower than other suggested hash functions on 32\-bit machines.
|
|
In mhash this algorithm is defined as: \fB\s-1MHASH_TIGER\s0, \s-1MHASH_TIGER160\s0, \s-1MHASH_TIGER128\s0\fR.
|
|
.PP
|
|
\&\fI\s-1GOST\s0\fR: \s-1GOST\s0 algorithm is a russian standard and it uses the
|
|
\&\s-1GOST\s0 encryption algorithm to produce a 256 bit hash value. This algorithm
|
|
is specified for use in the Russian Digital Signature Standard.
|
|
In mhash this algorithm is defined as \fB\s-1MHASH_GOST\s0\fR.
|
|
.PP
|
|
\&\fB Available Key Generation algorithms \fR
|
|
.PP
|
|
\&\fI\s-1KEYGEN_MCRYPT\s0\fR: The key generator used in mcrypt.
|
|
.PP
|
|
\&\fI\s-1KEYGEN_ASIS\s0\fR: Just returns the password as binary key.
|
|
.PP
|
|
\&\fI\s-1KEYGEN_HEX\s0\fR: Just converts a hex key into a binary one.
|
|
.PP
|
|
\&\fI\s-1KEYGEN_PKDES\s0\fR: The transformation used in Phil Karn's \s-1DES\s0 encryption program.
|
|
.PP
|
|
\&\fI\s-1KEYGEN_S2K_SIMPLE\s0\fR: The OpenPGP (rfc2440) Simple S2K.
|
|
.PP
|
|
\&\fI\s-1KEYGEN_S2K_SALTED\s0\fR: The OpenPGP Salted S2K.
|
|
.PP
|
|
\&\fI\s-1KEYGEN_S2K_ISALTED\s0\fR: The OpenPGP Iterated Salted S2K.
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
The \fBmhash\fR library provides an easy to use C interface for several \fIhash
|
|
algorithms\fR (also known as \*(L"one\-way\*(R" algorithms). These can be used to
|
|
create checksums, message digests and more. Currently, \s-1MD5\s0, \s-1SHA1\s0, \s-1GOST\s0, \s-1TIGER\s0,
|
|
\&\s-1RIPE\-MD160\s0, \s-1HAVAL\s0 and several other algorithms are supported.
|
|
\&\fBmhash\fR support \fI\s-1HMAC\s0 generation\fR
|
|
(a mechanism for message authentication using cryptographic hash
|
|
functions, and is described in rfc2104). \s-1HMAC\s0 can be used to create
|
|
message digests using a secret key, so that these message digests cannot
|
|
be regenerated (or replaced) by someone else.
|
|
A key generation mechanism was added to \fBmhash\fR since \fIkey generation\fR
|
|
algorithms usually involve hash algorithms.
|
|
.SH "API FUNCTIONS"
|
|
.IX Header "API FUNCTIONS"
|
|
We will describe the \s-1API\s0 of \fBmhash\fR in detail now. The order follows
|
|
the one in the \s-1SYNOPSIS\s0 directly.
|
|
.IP "size_t \fBmhash_count\fR(void);" 4
|
|
.IX Item "size_t mhash_count(void);"
|
|
This returns the \f(CW\*(C`hashid\*(C'\fR of the last available hash. Hashes are numbered from
|
|
0 to \f(CW\*(C`mhash_count()\*(C'\fR.
|
|
.IP "size_t \fBmhash_get_block_size\fR(hashid \fItype\fR);" 4
|
|
.IX Item "size_t mhash_get_block_size(hashid type);"
|
|
If \fItype\fR exists, this returns the used blocksize of the hash \fItype\fR
|
|
in bytes. Otherwise, it returns 0.
|
|
.IP "char *\fBmhash_get_hash_name\fR(hashid \fItype\fR);" 4
|
|
.IX Item "char *mhash_get_hash_name(hashid type);"
|
|
If \fItype\fR exists, this returns the name of the hash \fItype\fR. Otherwise, a
|
|
\&\f(CW\*(C`NULL\*(C'\fR pointer is returned. The string is allocated with \fImalloc\fR\|(3) seperately,
|
|
so do not forget to \fIfree\fR\|(3) it.
|
|
.IP "const char *\fBmhash_get_hash_name_static\fR(hashid \fItype\fR);" 4
|
|
.IX Item "const char *mhash_get_hash_name_static(hashid type);"
|
|
If \fItype\fR exists, this returns the name of the hash \fItype\fR. Otherwise, a
|
|
\&\f(CW\*(C`NULL\*(C'\fR pointer is returned.
|
|
.IP "size_t \fBmhash_get_hash_pblock\fR(hashid \fItype\fR);" 4
|
|
.IX Item "size_t mhash_get_hash_pblock(hashid type);"
|
|
It returns the block size that the algorithm operates. This is used
|
|
in mhash_hmac_init. If the return value is 0 you shouldn't use that
|
|
algorithm in \s-1HMAC\s0.
|
|
.IP "hashid \fBmhash_get_mhash_algo\fR(\s-1MHASH\s0 \fIsrc\fR);" 4
|
|
.IX Item "hashid mhash_get_mhash_algo(MHASH src);"
|
|
Returns the algorithm used in the state of \fIsrc\fR.
|
|
.IP "\s-1MHASH\s0 \fBmhash_init\fR(hashid \fItype\fR);" 4
|
|
.IX Item "MHASH mhash_init(hashid type);"
|
|
This setups a context to begin hashing using the algorithm \fItype\fR. It returns
|
|
a descriptor to that context which will result in leaking memory, if you do not
|
|
call \fImhash_deinit\fR\|(3) later. Returns \f(CW\*(C`MHASH_FAILED\*(C'\fR on failure.
|
|
.IP "\s-1MHASH\s0 \fBmhash_hmac_init\fR(const hashid \fItype\fR, void *\fIkey\fR, int \fIkeysize\fR, int \fIblock\fR);" 4
|
|
.IX Item "MHASH mhash_hmac_init(const hashid type, void *key, int keysize, int block);"
|
|
This setups a context to begin hashing using the algorithm type in \s-1HMAC\s0 mode.
|
|
\&\fIkey\fR should be a pointer to the
|
|
key and \fIkeysize\fR its len. The \fIblock\fR is the block size (in bytes) that the algorithm
|
|
operates. It should be obtained by \fImhash_get_hash_pblock()\fR. If its 0 it defaults to 64.
|
|
After calling it you should use \fImhash()\fR to update the context.
|
|
It returns a descriptor to that context which will result in leaking memory,
|
|
if you do not call \fImhash_hmac_deinit\fR\|(3) later.
|
|
Returns \f(CW\*(C`MHASH_FAILED\*(C'\fR on failure.
|
|
.IP "\s-1MHASH\s0 \fBmhash_cp\fR(\s-1MHASH\s0 \fIsrc\fR);" 4
|
|
.IX Item "MHASH mhash_cp(MHASH src);"
|
|
This setups a new context using the state of \fIsrc\fR.
|
|
.IP "int \fBmhash\fR(\s-1MHASH\s0 \fIthread\fR, const void *\fIplaintext\fR, size_t \fIsize\fR);" 4
|
|
.IX Item "int mhash(MHASH thread, const void *plaintext, size_t size);"
|
|
This updates the context described by \fIthread\fR with \fIplaintext\fR. \fIsize\fR is
|
|
the length of \fIplaintext\fR which may be binary data.
|
|
.IP "int \fBmhash_save_state_mem\fR( \s-1MHASH\s0 \fIthread\fR, void *\fImem\fR, int* \fImem_size\fR);" 4
|
|
.IX Item "int mhash_save_state_mem( MHASH thread, void *mem, int* mem_size);"
|
|
Saves the state of a hashing algorithm such that it can be restored at
|
|
some later point in time using \fBmhash_restore_state_mem\fR(). \fImem_size\fR should
|
|
contain the size of the given \fImem\fR pointer. If it is not enough to hold
|
|
the buffer the required value will be copied there.
|
|
.IP "\s-1MHASH\s0 \fBmhash_restore_state_mem\fR(void* \fImem\fR);" 4
|
|
.IX Item "MHASH mhash_restore_state_mem(void* mem);"
|
|
Restores the state of a hashing algorithm that was saved using
|
|
\&\fBmhash_save_state_mem\fR(). Use like \fBmhash_init\fR().
|
|
.IP "void *\fBmhash_end\fR(\s-1MHASH\s0 \fIthread\fR);" 4
|
|
.IX Item "void *mhash_end(MHASH thread);"
|
|
This frees all resources associated with \fIthread\fR and returns the result of
|
|
the whole hashing operation (the ``\fIdigest\fR'').
|
|
.IP "void \fBmhash_deinit\fR(\s-1MHASH\s0 \fIthread\fR, void* digest);" 4
|
|
.IX Item "void mhash_deinit(MHASH thread, void* digest);"
|
|
This frees all resources associated with \fIthread\fR and stores the result of
|
|
the whole hashing operation in memory pointed by \fIdigest\fR. \fIdigest\fR
|
|
may be null.
|
|
.IP "void *\fBmhash_hmac_end\fR(\s-1MHASH\s0 \fIthread\fR);" 4
|
|
.IX Item "void *mhash_hmac_end(MHASH thread);"
|
|
This frees all resources associated with thread and returns the result of the
|
|
whole hashing operation (the ``\fImac\fR'').
|
|
.IP "int \fBmhash_hmac_deinit\fR(\s-1MHASH\s0 \fIthread\fR, void* digest);" 4
|
|
.IX Item "int mhash_hmac_deinit(MHASH thread, void* digest);"
|
|
This frees all resources associated with \fIthread\fR and stores the result of
|
|
the whole hashing operation in memory pointed by digest. Digest may be
|
|
null. Returns non-zero in case of an error.
|
|
.IP "void *\fBmhash_end_m\fR(\s-1MHASH\s0 \fIthread\fR, void* (*hash_malloc)(size_t));" 4
|
|
.IX Item "void *mhash_end_m(MHASH thread, void* (*hash_malloc)(size_t));"
|
|
This frees all resources associated with \fIthread\fR and returns the result of
|
|
the whole hashing operation (the ``\fIdigest\fR''). The result will be allocated
|
|
by using the \fIhash_malloc()\fR function provided.
|
|
.IP "void *\fBmhash_hmac_end\fR(\s-1MHASH\s0 \fIthread\fR, void* (*hash_malloc)(size_t));" 4
|
|
.IX Item "void *mhash_hmac_end(MHASH thread, void* (*hash_malloc)(size_t));"
|
|
This frees all resources associated with thread and returns the result of the
|
|
whole hashing operation (the ``\fImac\fR''). The result will be allocated
|
|
by using the \fIhash_malloc()\fR function provided.
|
|
.SH "KEYGEN API FUNCTIONS"
|
|
.IX Header "KEYGEN API FUNCTIONS"
|
|
We will now describe the Key Generation \s-1API\s0 of \fBmhash\fR in detail.
|
|
.IP "int \fBmhash_keygen_ext\fR(keygenid \fIalgorithm\fR, \s-1KEYGEN\s0 \fIalgorithm_data\fR, void* \fIkeyword\fR, int \fIkeysize\fR, unsigned char* \fIpassword\fR, int \fIpasswordlen\fR);" 4
|
|
.IX Item "int mhash_keygen_ext(keygenid algorithm, KEYGEN algorithm_data, void* keyword, int keysize, unsigned char* password, int passwordlen);"
|
|
This function, generates a key from a password. The password is read from
|
|
\&\fIpassword\fR and it's len should be in \fIpasswordlen\fR.
|
|
The key generation algorithm is specified in \fIalgorithm\fR, and that algorithm may (internally)
|
|
use the \s-1KEYGEN\s0 structure. The \s-1KEYGEN\s0 structure consists of:
|
|
typedef struct keygen {
|
|
hashid hash_algorithm[2];
|
|
unsigned int count;
|
|
void* salt;
|
|
int salt_size;
|
|
} \s-1KEYGEN\s0;
|
|
.Sp
|
|
The algorithm(s) specified in \fIalgorithm_data.hash_algorithm\fR, should be hash
|
|
algorithms and may be used by the key generation algorithm. Some key generation algorithms
|
|
may use more than one hash algorithms (view also \fImhash_keygen_uses_hash_algorithm()\fR).
|
|
If it is desirable (and supported by the algorithm, eg. \s-1KEYGEN_S2K_SALTED\s0)
|
|
a salt may be specified in \fIalgorithm_data.salt\fR of size \fIalgorithm_data.salt_size\fR
|
|
or may be \s-1NULL\s0.
|
|
.Sp
|
|
The algorithm may use the \fIalgorithm_data.count\fR internally (eg. \s-1KEYGEN_S2K_ISALTED\s0).
|
|
The generated keyword is stored in \fIkeyword\fR, which should be (at least) \fIkeysize\fR bytes long.
|
|
The generated keyword is a binary one. Returns a negative number on failure.
|
|
.IP "int \fBmhash_keygen_uses_salt\fR( keygenid \fIalgorithm\fR);" 4
|
|
.IX Item "int mhash_keygen_uses_salt( keygenid algorithm);"
|
|
This function returns 1 if the specified key generation algorithm needs
|
|
a salt to be specified.
|
|
.IP "int \fBmhash_keygen_uses_count\fR( keygenid \fIalgorithm\fR);" 4
|
|
.IX Item "int mhash_keygen_uses_count( keygenid algorithm);"
|
|
This function returns 1 if the specified key generation algorithm needs
|
|
the algorithm_data.count field in \fImhash_keygen_ext()\fR. The count field tells the algorithm
|
|
to hash repeatedly the password and to stop when \fBcount\fR bytes have
|
|
been processed.
|
|
.IP "int \fBmhash_get_keygen_salt_size\fR( keygenid \fIalgorithm\fR);" 4
|
|
.IX Item "int mhash_get_keygen_salt_size( keygenid algorithm);"
|
|
This function returns the size of the salt size, that the specific
|
|
\&\fIalgorithm\fR will use. If it returns 0, then there is no limitation in
|
|
the size.
|
|
.IP "int \fBmhash_get_keygen_max_key_size\fR( keygenid \fIalgorithm\fR);" 4
|
|
.IX Item "int mhash_get_keygen_max_key_size( keygenid algorithm);"
|
|
This function returns the maximum size of the key, that the key generation
|
|
algorithm may produce.
|
|
If it returns 0, then there is no limitation in the size.
|
|
.IP "int \fBmhash_keygen_uses_hash_algorithm\fR( keygenid \fIalgorithm\fR);" 4
|
|
.IX Item "int mhash_keygen_uses_hash_algorithm( keygenid algorithm);"
|
|
This function returns the number of the hash algorithms the key generation
|
|
algorithm will use. If it is 0 then no hash algorithm is used by the
|
|
key generation algorithm. This is for the \fIalgorithm_data.hash_algorithm\fR field in
|
|
\&\fImhash_keygen_ext()\fR. If
|
|
.IP "size_t \fBmhash_keygen_count\fR(void);" 4
|
|
.IX Item "size_t mhash_keygen_count(void);"
|
|
This returns the \f(CW\*(C`keygenid\*(C'\fR of the last available key generation algorithm.
|
|
Algorithms are numbered from 0 to \f(CW\*(C`mhash_keygen_count()\*(C'\fR.
|
|
.IP "char *\fBmhash_get_keygen_name\fR(keygenid \fItype\fR);" 4
|
|
.IX Item "char *mhash_get_keygen_name(keygenid type);"
|
|
If \fItype\fR exists, this returns the name of the keygen \fItype\fR. Otherwise, a
|
|
\&\f(CW\*(C`NULL\*(C'\fR pointer is returned. The string is allocated with \fImalloc\fR\|(3) seperately,
|
|
so do not forget to \fIfree\fR\|(3) it.
|
|
.IP "const char *\fBmhash_get_keygen_name_static\fR(keygenid \fItype\fR);" 4
|
|
.IX Item "const char *mhash_get_keygen_name_static(keygenid type);"
|
|
If \fItype\fR exists, this returns the name of the keygen \fItype\fR. Otherwise, a
|
|
\&\f(CW\*(C`NULL\*(C'\fR pointer is returned.
|
|
.SH "EXAMPLE"
|
|
.IX Header "EXAMPLE"
|
|
Hashing \s-1STDIN\s0 until \s-1EOF\s0.
|
|
.PP
|
|
.Vb 3
|
|
\& #include <mhash.h>
|
|
\& #include <stdio.h>
|
|
\& #include <stdlib.h>
|
|
.Ve
|
|
.PP
|
|
.Vb 6
|
|
\& int main(void)
|
|
\& {
|
|
\& int i;
|
|
\& MHASH td;
|
|
\& unsigned char buffer;
|
|
\& unsigned char hash[16]; /* enough size for MD5 */
|
|
.Ve
|
|
.PP
|
|
.Vb 1
|
|
\& td = mhash_init(MHASH_MD5);
|
|
.Ve
|
|
.PP
|
|
.Vb 1
|
|
\& if (td == MHASH_FAILED) exit(1);
|
|
.Ve
|
|
.PP
|
|
.Vb 3
|
|
\& while (fread(&buffer, 1, 1, stdin) == 1) {
|
|
\& mhash(td, &buffer, 1);
|
|
\& }
|
|
.Ve
|
|
.PP
|
|
.Vb 1
|
|
\& mhash_deinit(td, hash);
|
|
.Ve
|
|
.PP
|
|
.Vb 5
|
|
\& printf("Hash:");
|
|
\& for (i = 0; i < mhash_get_block_size(MHASH_MD5); i++) {
|
|
\& printf("%.2x", hash[i]);
|
|
\& }
|
|
\& printf("\en");
|
|
.Ve
|
|
.PP
|
|
.Vb 2
|
|
\& exit(0);
|
|
\& }
|
|
.Ve
|
|
.SH "EXAMPLE"
|
|
.IX Header "EXAMPLE"
|
|
An example program using \s-1HMAC:\s0
|
|
.PP
|
|
.Vb 2
|
|
\& #include <mhash.h>
|
|
\& #include <stdio.h>
|
|
.Ve
|
|
.PP
|
|
.Vb 2
|
|
\& int main()
|
|
\& {
|
|
.Ve
|
|
.PP
|
|
.Vb 7
|
|
\& char password[] = "Jefe";
|
|
\& int keylen = 4;
|
|
\& char data[] = "what do ya want for nothing?";
|
|
\& int datalen = 28;
|
|
\& MHASH td;
|
|
\& unsigned char mac[16];
|
|
\& int j;
|
|
.Ve
|
|
.PP
|
|
.Vb 2
|
|
\& td = mhash_hmac_init(MHASH_MD5, password, keylen,
|
|
\& mhash_get_hash_pblock(MHASH_MD5));
|
|
.Ve
|
|
.PP
|
|
.Vb 2
|
|
\& mhash(td, data, datalen);
|
|
\& mhash_hmac_deinit(td, mac);
|
|
.Ve
|
|
.PP
|
|
.Vb 4
|
|
\& /*
|
|
\& * The output should be 0x750c783e6ab0b503eaa86e310a5db738
|
|
\& * according to RFC 2104.
|
|
\& */
|
|
.Ve
|
|
.PP
|
|
.Vb 5
|
|
\& printf("0x");
|
|
\& for (j = 0; j < mhash_get_block_size(MHASH_MD5); j++) {
|
|
\& printf("%.2x", mac[j]);
|
|
\& }
|
|
\& printf("\en");
|
|
.Ve
|
|
.PP
|
|
.Vb 2
|
|
\& exit(0);
|
|
\& }
|
|
.Ve
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
This library was originally written by \fINikos Mavroyanopoulos\fR
|
|
<nmav@hellug.gr> who passed the project over to \fISascha Schumann\fR
|
|
<sascha@schumann.cx> in May 1999. Sascha maintained it until March 2000.
|
|
The library is now maintained by \fINikos Mavroyanopoulos\fR.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
If you find any, please send a bug report (preferrably together with a patch)
|
|
to the maintainer with a detailed description on how to reproduce the bug.
|
|
.SH "AUTHORS"
|
|
.IX Header "AUTHORS"
|
|
Sascha Schumann <sascha@schumann.cx>
|
|
Nikos Mavroyanopoulos <nmav@hellug.gr>
|