.TH LIBSHA2.H 0 2019-02-10 libsha2
.SH NAME
libsha2.h \- SHA-2 library header
.SH SYNOPSIS
.nf
#include <libsha2.h>

enum libsha2_algorithm {
	LIBSHA2_224,     /* SHA-224     */
	LIBSHA2_256,     /* SHA-256     */
	LIBSHA2_384,     /* SHA-384     */
	LIBSHA2_512,     /* SHA-512     */
	LIBSHA2_512_224, /* SHA-512/224 */
	LIBSHA2_512_256  /* SHA-512/256 */
};

struct libsha2_state {
	/* members omitted */
};

int libsha2_init(struct libsha2_state *restrict \fIstate\fP, enum libsha2_algorithm \fIalgorithm\fP);
size_t libsha2_state_output_size(const struct libsha2_state *restrict \fIstate\fP);
size_t libsha2_algorithm_output_size(enum libsha2_algorithm \fIalgorithm\fP);
void libsha2_update(struct libsha2_state *restrict \fIstate\fP, const void *restrict \fImessage\fP, size_t \fImsglen\fP);
void libsha2_digest(struct libsha2_state *restrict \fIstate\fP, const void *restrict \fImessage\fP, size_t \fImsglen\fP, void *\fIoutput\fP);
int libsha2_sum_fd(int \fIfd\fP, enum libsha2_algorithm \fIalgorithm\fP, void *restrict \fIhashsum\fP);
void libsha2_behex_lower(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP);
void libsha2_behex_upper(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP);
void libsha2_unhex(void *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP);
size_t libsha2_marshal(const struct libsha2_state *restrict \fIstate\fP, void *restrict \fIbuf\fP);
size_t libsha2_unmarshal(struct libsha2_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP);
int libsha2_hmac_init(struct libsha2_hmac_state *restrict \fIstate\fP, enum libsha2_algorithm \fIalgorithm\fP,
                      const void *restrict \fIkey\fP, size_t \fIkeylen\fP);
size_t libsha2_hmac_state_output_size(const struct libsha2_hmac_state *restrict \fIstate\fP);
void libsha2_hmac_update(struct libsha2_hmac_state *restrict \fIstate\fP, const void *restrict \fIdata\fP, size_t \fIn\fP);
void libsha2_hmac_digest(struct libsha2_hmac_state *restrict \fIstate\fP, const void *\fIdata\fP, size_t \fIn\fP, void *\fIoutput\fP);
size_t libsha2_hmac_marshal(const struct libsha2_hmac_state *restrict \fIstate\fP, void *restrict \fIbuf\fP);
size_t libsha2_hmac_unmarshal(struct libsha2_hmac_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP);
.fi
.PP
Link with
.IR \-lsha2 .
.SH DESCRIPTION
The
.B libsha2.h
header, the header for the libsha2 C library defines
.B enum libsha2_algorithm
which has one value per supported algorithm:
.TP
.B LIBSHA2_224
SHA-224
.TP
.B LIBSHA2_256
SHA-256
.TP
.B LIBSHA2_384
SHA-384
.TP
.B LIBSHA2_512
SHA-512
.TP
.B LIBSHA2_512_224
SHA-512/224
.TP
.B LIBSHA2_512_256
SHA-512/256
.PP
Further, the
.B libsha2.h
header defines the opaque, but complete,
.B struct libsha2_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 libsha2_init (3)
Initialise hashing state.
.TP
.BR libsha2_state_output_size "(3), " libsha2_algorithm_output_size (3)
Get the output size for an algorithm.
.TP
.BR libsha2_update (3)
Feed data into the hashing state.
.TP
.BR libsha2_digest (3)
Get the result of a hashing.
.TP
.BR libsha2_sum_fd (3)
Hash an entire file.
.TP
.BR libsha2_behex_lower "(3), " libsha2_behex_upper (3)
Convert binary output from
.BR libsha2_digest (3)
to hexadecimal.
.TP
.BR libsha2_unhex (3)
Convert a hexadecimal hash to binary.
.TP
.BR libsha2_marshal (3)
Marshal a hashing state.
.TP
.BR libsha2_unmarshal (3)
Unmarshal a hashing state.
.TP
.BR libsha2_hmac_init (3)
Initialise HMAC hashing state.
.TP
.BR libsha2_hmac_update (3)
Feed data into the HMAC hashing state.
.TP
.BR libsha2_hmac_digest (3)
Get the result of an HMAC hashing.
.TP
.BR libsha2_hmac_marshal (3)
Marshal an HMAC hashing state.
.TP
.BR libsha2_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 libsha2_algorithm_output_size (3),
.BR libsha2_behex_lower (3),
.BR libsha2_behex_upper (3),
.BR libsha2_digest (3),
.BR libsha2_hmac_digest (3),
.BR libsha2_hmac_init (3),
.BR libsha2_hmac_marshal (3),
.BR libsha2_hmac_unmarshal (3),
.BR libsha2_hmac_update (3),
.BR libsha2_init (3),
.BR libsha2_marshal (3),
.BR libsha2_state_output_size (3),
.BR libsha2_sum_fd (3),
.BR libsha2_unhex (3),
.BR libsha2_unmarshal (3),
.BR libsha2_update (3)