Minor changes, add man pages, rename libsha2_state_initialise to libsha2_init

Signed-off-by: Mattias Andrée <maandree@kth.se>

16 files changed, 614 insertions, 6 deletions

diff --git a/Makefile b/Makefile
index 566907e..893704a 100644
--- a/Makefile
+++ b/Makefile
@@ -21,12 +21,26 @@ OBJ =\
 	behex_lower.o\
 	behex_upper.o\
 	digest.o\
-	state_initialise.o\
+	init.o\
 	state_output_size.o\
 	sum_fd.o\
 	unhex.o\
 	update.o\
 
+MAN0 =\
+	libsha2.h.0
+
+MAN3 =\
+	libsha2_algorithm_output_size.3\
+	libsha2_behex_lower.3\
+	libsha2_behex_upper.3\
+	libsha2_digest.3\
+	libsha2_init.3\
+	libsha2_state_output_size.3\
+	libsha2_sum_fd.3\
+	libsha2_unhex.3\
+	libsha2_update.3
+
 
 all: libsha2.a libsha2.$(LIBEXT)
 $(OBJ): $(@:.o=.c) $(HDR)
diff --git a/TODO b/TODO
index 0087301..7adeb9b 100644
--- a/TODO
+++ b/TODO
@@ -1 +1,3 @@
 Add HMAC support
+Add marshal support
+Add bit support
diff --git a/state_initialise.c b/init.c
index ba6fee0..a7ffa73 100644
--- a/state_initialise.c
+++ b/init.c
@@ -86,7 +86,7 @@ static const uint64_t H_512_256[] = {
  * @return             Zero on success, -1 on error
  */
 int
-libsha2_state_initialise(struct libsha2_state *restrict state, enum libsha2_algorithm algorithm)
+libsha2_init(struct libsha2_state *restrict state, enum libsha2_algorithm algorithm)
 {
 	size_t i;
 
diff --git a/libsha2.h b/libsha2.h
index 5b37130..02a386b 100644
--- a/libsha2.h
+++ b/libsha2.h
@@ -164,7 +164,7 @@ struct libsha2_state {
 #if defined(__GNUC__)
 __attribute__((__leaf__, __nothrow__, __nonnull__))
 #endif
-int libsha2_state_initialise(struct libsha2_state *restrict, enum libsha2_algorithm);
+int libsha2_init(struct libsha2_state *restrict, enum libsha2_algorithm);
 
 /**
  * Get the output size of the algorithm specified for a state
diff --git a/libsha2.h.0 b/libsha2.h.0
new file mode 100644
index 0000000..5e79f73
--- /dev/null
+++ b/libsha2.h.0
@@ -0,0 +1,110 @@
+.TH LIBSHA2.H 0 2019-02-09 libjson
+.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 char *restrict \fImessage\fP, size_t \fImsglen\fP);
+void libsha2_digest(struct libsha2_state *restrict \fIstate\fP, const char *restrict \fImessage\fP, size_t \fImsglen\fP, char *\fIoutput\fP);
+int libsha2_sum_fd(int \fIfd\fP, enum libsha2_algorithm \fIalgorithm\fP, char *restrict \fIhashsum\fP);
+void libsha2_behex_lower(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP, size_t \fIn\fP);
+void libsha2_behex_upper(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP, size_t \fIn\fP);
+void libsha2_unhex(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\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. 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.
+.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_init (3),
+.BR libsha2_state_output_size (3),
+.BR libsha2_sum_fd (3),
+.BR libsha2_unhex (3),
+.BR libsha2_update (3)
diff --git a/libsha2_algorithm_output_size.3 b/libsha2_algorithm_output_size.3
new file mode 100644
index 0000000..49fd598
--- /dev/null
+++ b/libsha2_algorithm_output_size.3
@@ -0,0 +1,51 @@
+.TH LIBSHA2_ALGORITHM_OUTPUT_SIZE 3 2019-02-09 libjson
+.SH NAME
+libsha2_algorithm_output_size \- Get the size of the output for a SHA 2 algorithm
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+size_t libsha2_algorithm_output_size(enum libsha2_algorithm \fIalgorithm\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_algorithm_output_size ()
+function get the output size for the
+binary output of the hash algorithm
+selected for the selected
+.IR algorithm .
+.SH RETURN VALUE
+The
+.BR libsha2_algorithm_output_size ()
+function returns the output size in bytes,
+a positive number upon successful completion,
+otherwise 0 is returned and
+.I errno
+is set appropriately.
+.SH ERRORS
+The
+.BR libsha2_algorithm_output_size ()
+function will fail if:
+.TP
+.B EINVAL
+.I algorithm
+is not a valid
+.B enum libsha2_algorithm
+value.
+.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_state_output_size (3)
diff --git a/libsha2_behex_lower.3 b/libsha2_behex_lower.3
new file mode 100644
index 0000000..7882aa7
--- /dev/null
+++ b/libsha2_behex_lower.3
@@ -0,0 +1,49 @@
+.TH LIBSHA2_BEHEX_LOWER 3 2019-02-09 libjson
+.SH NAME
+libsha2_behex_lower \- Convert binary to lower case hexadecimal
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+void libsha2_behex_lower(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP, size_t \fIn\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_behex_lower ()
+function converts the
+.I n
+first bytes of
+.I hashsum
+to lower case hexadecimal, as exactly
+.I 2*n
+characters, and stores the result, with
+NUL byte termination, to
+.IR output .
+.PP
+The user must make sure that
+.I output
+is at least
+.I 2*n+1
+bytes large.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.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_behex_upper (3),
+.BR libsha2_unhex (3)
diff --git a/libsha2_behex_upper.3 b/libsha2_behex_upper.3
new file mode 100644
index 0000000..6faaae2
--- /dev/null
+++ b/libsha2_behex_upper.3
@@ -0,0 +1,49 @@
+.TH LIBSHA2_BEHEX_UPPER 3 2019-02-09 libjson
+.SH NAME
+libsha2_behex_upper \- Convert binary to upper case hexadecimal
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+void libsha2_behex_upper(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP, size_t \fIn\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_behex_upper ()
+function converts the
+.I n
+first bytes of
+.I hashsum
+to upper case hexadecimal, as exactly
+.I 2*n
+characters, and stores the result, with
+NUL byte termination, to
+.IR output .
+.PP
+The user must make sure that
+.I output
+is at least
+.I 2*n+1
+bytes large.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.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_behex_lower (3),
+.BR libsha2_unhex (3)
diff --git a/libsha2_digest.3 b/libsha2_digest.3
new file mode 100644
index 0000000..2e7d31e
--- /dev/null
+++ b/libsha2_digest.3
@@ -0,0 +1,61 @@
+.TH LIBSHA2_DIGEST 3 2019-02-09 libjson
+.SH NAME
+libsha2_digest \- Get the result of a SHA 2 hashing
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+void libsha2_digest(struct libsha2_state *restrict \fIstate\fP, const char *restrict \fImessage\fP, size_t \fImsglen\fP, char *\fIoutput\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_digest ()
+function feeds the first
+.I msglen
+bytes of
+.I message
+into the hashing state of the
+.I state
+parameter, and finalises the hashing.
+The resulting hash is stored in binary
+format in
+.I output .
+The user must make sure that
+.I output
+is sufficiently large, which means at
+least the return value of the
+.BR libsha2_state_output_size (3)
+function.
+.PP
+The
+.BR libsha2_behex_lower (3)
+and
+.BR libsha2_behex_upper (3)
+functions can be used to convert the
+result to hexadecimal format.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.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_behex_lower (3),
+.BR libsha2_behex_upper (3),
+.BR libsha2_init (3),
+.BR libsha2_state_output_size (3),
+.BR libsha2_sum_fd (3),
+.BR libsha2_update (3)
diff --git a/libsha2_init.3 b/libsha2_init.3
new file mode 100644
index 0000000..2a11f89
--- /dev/null
+++ b/libsha2_init.3
@@ -0,0 +1,64 @@
+.TH LIBSHA2_INIT 3 2019-02-09 libjson
+.SH NAME
+libsha2_init \- Initialises hashing with a SHA 2 algorithm
+.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 */
+};
+
+int libsha2_init(struct libsha2_state *restrict \fIstate\fP, enum libsha2_algorithm \fIalgorithm\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_init ()
+function stores the selected
+.I algorithm
+in
+.I state
+and initialises
+.I state
+accordingly with the initial hashing state.
+.SH RETURN VALUE
+The
+.BR libsha2_init ()
+function returns 0 upon successful completion,
+otherwise -1 is returned and
+.I errno
+is set appropriately.
+.SH ERRORS
+The
+.BR libsha2_init ()
+function will fail if:
+.TP
+.B EINVAL
+.I algorithm
+is not a valid
+.B enum libsha2_algorithm
+value.
+.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_digest (3),
+.BR libsha2_sum_fd (3),
+.BR libsha2_update (3)
diff --git a/libsha2_state_output_size.3 b/libsha2_state_output_size.3
new file mode 100644
index 0000000..34b4156
--- /dev/null
+++ b/libsha2_state_output_size.3
@@ -0,0 +1,40 @@
+.TH LIBSHA2_STATE_OUTPUT_SIZE 3 2019-02-09 libjson
+.SH NAME
+libsha2_state_output_size \- Get the size of the output for a SHA 2 algorithm
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+size_t libsha2_state_output_size(const struct libsha2_state *restrict \fIstate\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_state_output_size ()
+function get the output size for the
+binary output of the hash algorithm
+selected for
+.IR state .
+.SH RETURN VALUE
+The
+.BR libsha2_state_output_size ()
+function returns the output size in bytes,
+a positive number.
+.SH ERRORS
+None.
+.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)
diff --git a/libsha2_sum_fd.3 b/libsha2_sum_fd.3
new file mode 100644
index 0000000..18e9291
--- /dev/null
+++ b/libsha2_sum_fd.3
@@ -0,0 +1,77 @@
+.TH LIBSHA2_SUM_FD 3 2019-02-09 libjson
+.SH NAME
+libsha2_sum_fd \- Hash a file with a SHA 2 algorithm
+.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 */
+};
+
+int libsha2_sum_fd(int \fIfd\fP, enum libsha2_algorithm \fIalgorithm\fP, char *restrict \fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_sum_fd ()
+function hashes the file with the
+file descriptor
+.I fd
+with the selected
+.IR algorithm .
+The resulting hash is stored in binary
+format in
+.I hashsum .
+The user must make sure that
+.I hashsum
+is sufficiently large, which means at
+least the return value of the
+.BR libsha2_algorithm_output_size (3)
+function.
+.PP
+The
+.BR libsha2_behex_lower (3)
+and
+.BR libsha2_behex_upper (3)
+functions can be used to convert the
+result to hexadecimal format.
+.SH RETURN VALUE
+The
+.BR libsha2_sum_fd ()
+function returns 0 upon successful completion,
+otherwise -1 is returned and
+.I errno
+is set appropriately.
+.SH ERRORS
+The
+.BR libsha2_sum_fd ()
+function may fail for any reason specified for the
+.BR read (3)
+and
+.BR libsha2_init (3)
+functions.
+.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_init (3)
diff --git a/libsha2_unhex.3 b/libsha2_unhex.3
new file mode 100644
index 0000000..c1f7865
--- /dev/null
+++ b/libsha2_unhex.3
@@ -0,0 +1,48 @@
+.TH LIBSHA2_UNHEX 3 2019-02-09 libjson
+.SH NAME
+libsha2_unhex \- Covert hexadecimal to binary
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+void libsha2_unhex(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_unhex ()
+function converts the content of the string
+.I hashsum
+to binary and stores the result in
+.IR output .
+.PP
+The user must make sure that
+.I hashsum
+is a NUL terminated string with an even number of characters
+and each character is a hexadecimal digit (both lower case
+and upper case, including mixing, is allowed). The output will
+be half the length of this string, and the user must make sure
+that
+.I output
+is at least this size.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.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_behex_lower (3),
+.BR libsha2_behex_upper (3)
diff --git a/libsha2_update.3 b/libsha2_update.3
new file mode 100644
index 0000000..c504b76
--- /dev/null
+++ b/libsha2_update.3
@@ -0,0 +1,42 @@
+.TH LIBSHA2_UPDATE 3 2019-02-09 libjson
+.SH NAME
+libsha2_update \- Feed data into a SHA 2 algorithm
+.SH SYNOPSIS
+.nf
+#include <libsha2.h>
+
+void libsha2_update(struct libsha2_state *restrict \fIstate\fP, const char *restrict \fImessage\fP, size_t \fImsglen\fP);
+.fi
+.PP
+Link with
+.IR \-lsha2 .
+.SH DESCRIPTION
+The
+.BR libsha2_update ()
+function feeds the first
+.I msglen
+bytes of
+.I message
+into the hashing state of the
+.I state
+parameter.
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.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_digest (3),
+.BR libsha2_init (3),
+.BR libsha2_sum_fd (3)
diff --git a/sum_fd.c b/sum_fd.c
index 381a634..35d4121 100644
--- a/sum_fd.c
+++ b/sum_fd.c
@@ -20,7 +20,7 @@ libsha2_sum_fd(int fd, enum libsha2_algorithm algorithm, char *restrict hashsum)
 	size_t blksize = 4096;
 	char *restrict chunk;
 
-	if (libsha2_state_initialise(&state, algorithm) < 0)
+	if (libsha2_init(&state, algorithm) < 0)
 		return -1;
 
 	if (fstat(fd, &attr) == 0 && attr.st_blksize > 0)
diff --git a/unhex.c b/unhex.c
index 0dc231d..a84ac19 100644
--- a/unhex.c
+++ b/unhex.c
@@ -14,9 +14,10 @@ void
 libsha2_unhex(char *restrict output, const char *restrict hashsum)
 {
 	size_t n = strlen(hashsum) / 2;
+	char a, b;
 	while (n--) {
-		char a = hashsum[2 * n + 0];
-		char b = hashsum[2 * n + 1];
+		a = hashsum[2 * n + 0];
+		b = hashsum[2 * n + 1];
 
 		a = (char)((a & 15) + (a > '9' ? 9 : 0));
 		b = (char)((b & 15) + (b > '9' ? 9 : 0));