.TH LIBSHA1.H 0 2019-02-10 libsha1
.SH NAME
libsha1.h \- SHA-1 and SHA-0 library header
.SH SYNOPSIS
.nf
#include <libsha1.h>

enum libsha1_algorithm {
	LIBSHA1_0, /* SHA-0 */
	LIBSHA1_1  /* SHA-1 */
};

struct libsha1_state {
	/* members omitted */
};

int libsha1_init(struct libsha1_state *restrict \fIstate\fP, enum libsha1_algorithm \fIalgorithm\fP);
size_t libsha1_state_output_size(const struct libsha1_state *restrict \fIstate\fP);
size_t libsha1_algorithm_output_size(enum libsha1_algorithm \fIalgorithm\fP);
void libsha1_update(struct libsha1_state *restrict \fIstate\fP, const void *restrict \fImessage\fP, size_t \fImsglen\fP);
void libsha1_digest(struct libsha1_state *restrict \fIstate\fP, const void *restrict \fImessage\fP, size_t \fImsglen\fP, void *\fIoutput\fP);
int libsha1_sum_fd(int \fIfd\fP, enum libsha1_algorithm \fIalgorithm\fP, void *restrict \fIhashsum\fP);
void libsha1_behex_lower(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP);
void libsha1_behex_upper(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP);
void libsha1_unhex(void *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP);
size_t libsha1_marshal(const struct libsha1_state *restrict \fIstate\fP, void *restrict \fIbuf\fP);
size_t libsha1_unmarshal(struct libsha1_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP);
int libsha1_hmac_init(struct libsha1_hmac_state *restrict \fIstate\fP, enum libsha1_algorithm \fIalgorithm\fP,
                      const void *restrict \fIkey\fP, size_t \fIkeylen\fP);
size_t libsha1_hmac_state_output_size(const struct libsha1_hmac_state *restrict \fIstate\fP);
void libsha1_hmac_update(struct libsha1_hmac_state *restrict \fIstate\fP, const void *restrict \fIdata\fP, size_t \fIn\fP);
void libsha1_hmac_digest(struct libsha1_hmac_state *restrict \fIstate\fP, const void *\fIdata\fP, size_t \fIn\fP, void *\fIoutput\fP);
size_t libsha1_hmac_marshal(const struct libsha1_hmac_state *restrict \fIstate\fP, void *restrict \fIbuf\fP);
size_t libsha1_hmac_unmarshal(struct libsha1_hmac_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP);
.fi
.PP
Link with
.IR \-lsha1 .
.SH DESCRIPTION
The
.B libsha1.h
header, the header for the libsha1 C library defines
.B enum libsha1_algorithm
which has one value per supported algorithm:
.TP
.B LIBSHA1_0
SHA-0
.TP
.B LIBSHA1_1
SHA-1
.PP
Further, the
.B libsha1.h
header defines the opaque, but complete,
.B struct libsha1_state
which stores the selected algorithm and
the state of the hashing. A state can be
securely erased by overriding all bytes
in the structure with zeroes (or any other
byte sequence). The header also
defines the functions:
.TP
.BR libsha1_init (3)
Initialise hashing state.
.TP
.BR libsha1_state_output_size "(3), " libsha1_algorithm_output_size (3)
Get the output size for an algorithm.
.TP
.BR libsha1_update (3)
Feed data into the hashing state.
.TP
.BR libsha1_digest (3)
Get the result of a hashing.
.TP
.BR libsha1_sum_fd (3)
Hash an entire file.
.TP
.BR libsha1_behex_lower "(3), " libsha1_behex_upper (3)
Convert binary output from
.BR libsha1_digest (3)
to hexadecimal.
.TP
.BR libsha1_unhex (3)
Convert a hexadecimal hash to binary.
.TP
.BR libsha1_marshal (3)
Marshal a hashing state.
.TP
.BR libsha1_unmarshal (3)
Unmarshal a hashing state.
.TP
.BR libsha1_hmac_init (3)
Initialise HMAC hashing state.
.TP
.BR libsha1_hmac_update (3)
Feed data into the HMAC hashing state.
.TP
.BR libsha1_hmac_digest (3)
Get the result of an HMAC hashing.
.TP
.BR libsha1_hmac_marshal (3)
Marshal an HMAC hashing state.
.TP
.BR libsha1_hmac_unmarshal (3)
Unmarshal an HMAC hashing state.
.SH EXAMPLES
None.
.SH APPLICATION USAGE
None.
.SH RATIONALE
None.
.SH FUTURE DIRECTIONS
None.
.SH NOTES
None.
.SH BUGS
None.
.SH SEE ALSO
.BR libsha1_algorithm_output_size (3),
.BR libsha1_behex_lower (3),
.BR libsha1_behex_upper (3),
.BR libsha1_digest (3),
.BR libsha1_hmac_digest (3),
.BR libsha1_hmac_init (3),
.BR libsha1_hmac_marshal (3),
.BR libsha1_hmac_unmarshal (3),
.BR libsha1_hmac_update (3),
.BR libsha1_init (3),
.BR libsha1_marshal (3),
.BR libsha1_state_output_size (3),
.BR libsha1_sum_fd (3),
.BR libsha1_unhex (3),
.BR libsha1_unmarshal (3),
.BR libsha1_update (3)