From 09cb4bacf6373f3dd73beb69be9c56289c502f66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dag-Erling=20Sm=C3=B8rgrav?= Date: Sat, 17 Sep 2016 16:48:50 +0200 Subject: [PATCH] Clean up the cryb_sha1(3) man page and add man pages for the SHA-2 functions. --- lib/digest/Makefile.am | 6 +- lib/digest/cryb_sha1.3 | 14 +++-- lib/digest/cryb_sha224.3 | 116 +++++++++++++++++++++++++++++++++++++++ lib/digest/cryb_sha256.3 | 116 +++++++++++++++++++++++++++++++++++++++ lib/digest/cryb_sha384.3 | 116 +++++++++++++++++++++++++++++++++++++++ lib/digest/cryb_sha512.3 | 116 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 479 insertions(+), 5 deletions(-) create mode 100644 lib/digest/cryb_sha224.3 create mode 100644 lib/digest/cryb_sha256.3 create mode 100644 lib/digest/cryb_sha384.3 create mode 100644 lib/digest/cryb_sha512.3 diff --git a/lib/digest/Makefile.am b/lib/digest/Makefile.am index a84e17a..25a8453 100644 --- a/lib/digest/Makefile.am +++ b/lib/digest/Makefile.am @@ -15,4 +15,8 @@ libcryb_digest_la_SOURCES = \ cryb_digest.c dist_man3_MANS = \ - cryb_sha1.3 + cryb_sha1.3 \ + cryb_sha224.3 \ + cryb_sha256.3 \ + cryb_sha384.3 \ + cryb_sha512.3 diff --git a/lib/digest/cryb_sha1.3 b/lib/digest/cryb_sha1.3 index dd439c9..c0ea770 100644 --- a/lib/digest/cryb_sha1.3 +++ b/lib/digest/cryb_sha1.3 @@ -1,5 +1,6 @@ .\"- .\" Copyright (c) 2015 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -26,7 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd February 5, 2015 +.Dd September 17, 2016 .Dt CRYB_SHA1 3 .Os .Sh NAME @@ -36,8 +37,9 @@ .Nm cryb_sha1_complete .Nd Secure Hash Algorithm 1 .Sh LIBRARY -.Lb libcryb +.Lb libcryb-digest .Sh SYNOPSIS +.In stddef.h .In stdint.h .In cryb/sha1.h .Ft void @@ -51,7 +53,7 @@ .Sh DESCRIPTION The .Nm cryb_sha1 -family of functions implements the NIST SHA1 message digest algorithm +family of functions implements the NIST SHA-1 message digest algorithm as described in FIPS 180-4. .Pp The @@ -100,7 +102,11 @@ prefix. The SHA-1 message digest algorithm has been proven to be vulnerable to collision attacks and should not be used for cryptographic purposes. .Sh SEE ALSO -.Xr cryb_hash 3 +.Xr cryb_digest 3 , +.Xr cryb_sha224 3 , +.Xr cryb_sha256 3 , +.Xr cryb_sha384 3 , +.Xr cryb_sha512 3 .Sh REFERENCES .Rs .%Q National Institute of Standards and Technology diff --git a/lib/digest/cryb_sha224.3 b/lib/digest/cryb_sha224.3 new file mode 100644 index 0000000..5601ec9 --- /dev/null +++ b/lib/digest/cryb_sha224.3 @@ -0,0 +1,116 @@ +.\"- +.\" Copyright (c) 2015 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 17, 2016 +.Dt CRYB_SHA224 3 +.Os +.Sh NAME +.Nm cryb_sha224_init , +.Nm cryb_sha224_update , +.Nm cryb_sha224_final , +.Nm cryb_sha224_complete +.Nd Secure Hash Algorithm 2 +.Sh LIBRARY +.Lb libcryb-digest +.Sh SYNOPSIS +.In stddef.h +.In stdint.h +.In cryb/sha224.h +.Ft void +.Fn cryb_sha224_init "cryb_sha224_ctx *context" +.Ft void +.Fn cryb_sha224_update "cryb_sha224_ctx *context" "const void *data" "size_t len" +.Ft void +.Fn cryb_sha224_final "cryb_sha224_ctx *context" "uint8_t *digest" +.Ft void +.Fn cryb_sha224_complete "const void *data" "size_t len" "uint8_t *digest" +.Sh DESCRIPTION +The +.Nm cryb_sha224 +family of functions implements the NIST SHA-224 message digest +algorithm as described in FIPS 180-4. +.Pp +The +.Fn cryb_sha224_init +function initializes the context structure pointed to by +.Va context . +It is the caller's responsibility to allocate this structure. +.Pp +The +.Fn cryb_sha224_update +function hashes the next +.Va len +bytes of data pointed to by the +.Va data +pointer into the given hash context. +.Pp +The +.Fn cryb_sha224_final +function finalizes the computation and writes the resulting message +digest to the caller-provided buffer pointed to by +.Va digest , +which must be at least +.Dv SHA224_DIGEST_LEN +bytes long. +It is the caller's responsibility to dispose of the context structure +after calling +.Fn cryb_sha224_final . +.Pp +The +.Fn cryb_sha224_complete +function is a shortcut to calling +.Fn cryb_sha224_init , +.Fn cryb_sha224_update +and +.Fn cryb_sha224_final +when the entire message is available up front in a single contiguous +buffer. +.Sh IMPLEMENTATION NOTES +The +.In cryb/sha224.h +header provides macros which allows these functions and the context +type to be referred to without their +.Dq Li cryb_ +prefix. +.Sh SEE ALSO +.Xr cryb_digest 3 , +.Xr cryb_sha1 3 , +.Xr cryb_sha256 3 , +.Xr cryb_sha384 3 , +.Xr cryb_sha512 3 +.Sh REFERENCES +.Rs +.%Q National Institute of Standards and Technology +.%R Secure Hash Standard (SHS) (FIPS PUB 180-4) +.%D March 2012 +.Re +.Sh AUTHORS +These functions and this manual page were written for the University +of Oslo by +.An Dag-Erling Sm\(/orgrav Aq Mt d.e.smorgrav@usit.uio.no . diff --git a/lib/digest/cryb_sha256.3 b/lib/digest/cryb_sha256.3 new file mode 100644 index 0000000..3fbf24a --- /dev/null +++ b/lib/digest/cryb_sha256.3 @@ -0,0 +1,116 @@ +.\"- +.\" Copyright (c) 2015 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 17, 2016 +.Dt CRYB_SHA256 3 +.Os +.Sh NAME +.Nm cryb_sha256_init , +.Nm cryb_sha256_update , +.Nm cryb_sha256_final , +.Nm cryb_sha256_complete +.Nd Secure Hash Algorithm 2 +.Sh LIBRARY +.Lb libcryb-digest +.Sh SYNOPSIS +.In stddef.h +.In stdint.h +.In cryb/sha256.h +.Ft void +.Fn cryb_sha256_init "cryb_sha256_ctx *context" +.Ft void +.Fn cryb_sha256_update "cryb_sha256_ctx *context" "const void *data" "size_t len" +.Ft void +.Fn cryb_sha256_final "cryb_sha256_ctx *context" "uint8_t *digest" +.Ft void +.Fn cryb_sha256_complete "const void *data" "size_t len" "uint8_t *digest" +.Sh DESCRIPTION +The +.Nm cryb_sha256 +family of functions implements the NIST SHA-256 message digest +algorithm as described in FIPS 180-4. +.Pp +The +.Fn cryb_sha256_init +function initializes the context structure pointed to by +.Va context . +It is the caller's responsibility to allocate this structure. +.Pp +The +.Fn cryb_sha256_update +function hashes the next +.Va len +bytes of data pointed to by the +.Va data +pointer into the given hash context. +.Pp +The +.Fn cryb_sha256_final +function finalizes the computation and writes the resulting message +digest to the caller-provided buffer pointed to by +.Va digest , +which must be at least +.Dv SHA256_DIGEST_LEN +bytes long. +It is the caller's responsibility to dispose of the context structure +after calling +.Fn cryb_sha256_final . +.Pp +The +.Fn cryb_sha256_complete +function is a shortcut to calling +.Fn cryb_sha256_init , +.Fn cryb_sha256_update +and +.Fn cryb_sha256_final +when the entire message is available up front in a single contiguous +buffer. +.Sh IMPLEMENTATION NOTES +The +.In cryb/sha256.h +header provides macros which allows these functions and the context +type to be referred to without their +.Dq Li cryb_ +prefix. +.Sh SEE ALSO +.Xr cryb_digest 3 , +.Xr cryb_sha1 3 , +.Xr cryb_sha224 3 , +.Xr cryb_sha384 3 , +.Xr cryb_sha512 3 +.Sh REFERENCES +.Rs +.%Q National Institute of Standards and Technology +.%R Secure Hash Standard (SHS) (FIPS PUB 180-4) +.%D March 2012 +.Re +.Sh AUTHORS +These functions and this manual page were written for the University +of Oslo by +.An Dag-Erling Sm\(/orgrav Aq Mt d.e.smorgrav@usit.uio.no . diff --git a/lib/digest/cryb_sha384.3 b/lib/digest/cryb_sha384.3 new file mode 100644 index 0000000..77f73a8 --- /dev/null +++ b/lib/digest/cryb_sha384.3 @@ -0,0 +1,116 @@ +.\"- +.\" Copyright (c) 2015 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 17, 2016 +.Dt CRYB_SHA384 3 +.Os +.Sh NAME +.Nm cryb_sha384_init , +.Nm cryb_sha384_update , +.Nm cryb_sha384_final , +.Nm cryb_sha384_complete +.Nd Secure Hash Algorithm 2 +.Sh LIBRARY +.Lb libcryb-digest +.Sh SYNOPSIS +.In stddef.h +.In stdint.h +.In cryb/sha384.h +.Ft void +.Fn cryb_sha384_init "cryb_sha384_ctx *context" +.Ft void +.Fn cryb_sha384_update "cryb_sha384_ctx *context" "const void *data" "size_t len" +.Ft void +.Fn cryb_sha384_final "cryb_sha384_ctx *context" "uint8_t *digest" +.Ft void +.Fn cryb_sha384_complete "const void *data" "size_t len" "uint8_t *digest" +.Sh DESCRIPTION +The +.Nm cryb_sha384 +family of functions implements the NIST SHA-384 message digest +algorithm as described in FIPS 180-4. +.Pp +The +.Fn cryb_sha384_init +function initializes the context structure pointed to by +.Va context . +It is the caller's responsibility to allocate this structure. +.Pp +The +.Fn cryb_sha384_update +function hashes the next +.Va len +bytes of data pointed to by the +.Va data +pointer into the given hash context. +.Pp +The +.Fn cryb_sha384_final +function finalizes the computation and writes the resulting message +digest to the caller-provided buffer pointed to by +.Va digest , +which must be at least +.Dv SHA384_DIGEST_LEN +bytes long. +It is the caller's responsibility to dispose of the context structure +after calling +.Fn cryb_sha384_final . +.Pp +The +.Fn cryb_sha384_complete +function is a shortcut to calling +.Fn cryb_sha384_init , +.Fn cryb_sha384_update +and +.Fn cryb_sha384_final +when the entire message is available up front in a single contiguous +buffer. +.Sh IMPLEMENTATION NOTES +The +.In cryb/sha384.h +header provides macros which allows these functions and the context +type to be referred to without their +.Dq Li cryb_ +prefix. +.Sh SEE ALSO +.Xr cryb_digest 3 , +.Xr cryb_sha1 3 , +.Xr cryb_sha224 3 , +.Xr cryb_sha256 3 , +.Xr cryb_sha512 3 +.Sh REFERENCES +.Rs +.%Q National Institute of Standards and Technology +.%R Secure Hash Standard (SHS) (FIPS PUB 180-4) +.%D March 2012 +.Re +.Sh AUTHORS +These functions and this manual page were written for the University +of Oslo by +.An Dag-Erling Sm\(/orgrav Aq Mt d.e.smorgrav@usit.uio.no . diff --git a/lib/digest/cryb_sha512.3 b/lib/digest/cryb_sha512.3 new file mode 100644 index 0000000..4599a97 --- /dev/null +++ b/lib/digest/cryb_sha512.3 @@ -0,0 +1,116 @@ +.\"- +.\" Copyright (c) 2015 Universitetet i Oslo +.\" Copyright (c) 2016 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 17, 2016 +.Dt CRYB_SHA512 3 +.Os +.Sh NAME +.Nm cryb_sha512_init , +.Nm cryb_sha512_update , +.Nm cryb_sha512_final , +.Nm cryb_sha512_complete +.Nd Secure Hash Algorithm 2 +.Sh LIBRARY +.Lb libcryb-digest +.Sh SYNOPSIS +.In stddef.h +.In stdint.h +.In cryb/sha512.h +.Ft void +.Fn cryb_sha512_init "cryb_sha512_ctx *context" +.Ft void +.Fn cryb_sha512_update "cryb_sha512_ctx *context" "const void *data" "size_t len" +.Ft void +.Fn cryb_sha512_final "cryb_sha512_ctx *context" "uint8_t *digest" +.Ft void +.Fn cryb_sha512_complete "const void *data" "size_t len" "uint8_t *digest" +.Sh DESCRIPTION +The +.Nm cryb_sha512 +family of functions implements the NIST SHA-512 message digest +algorithm as described in FIPS 180-4. +.Pp +The +.Fn cryb_sha512_init +function initializes the context structure pointed to by +.Va context . +It is the caller's responsibility to allocate this structure. +.Pp +The +.Fn cryb_sha512_update +function hashes the next +.Va len +bytes of data pointed to by the +.Va data +pointer into the given hash context. +.Pp +The +.Fn cryb_sha512_final +function finalizes the computation and writes the resulting message +digest to the caller-provided buffer pointed to by +.Va digest , +which must be at least +.Dv SHA512_DIGEST_LEN +bytes long. +It is the caller's responsibility to dispose of the context structure +after calling +.Fn cryb_sha512_final . +.Pp +The +.Fn cryb_sha512_complete +function is a shortcut to calling +.Fn cryb_sha512_init , +.Fn cryb_sha512_update +and +.Fn cryb_sha512_final +when the entire message is available up front in a single contiguous +buffer. +.Sh IMPLEMENTATION NOTES +The +.In cryb/sha512.h +header provides macros which allows these functions and the context +type to be referred to without their +.Dq Li cryb_ +prefix. +.Sh SEE ALSO +.Xr cryb_digest 3 , +.Xr cryb_sha1 3 , +.Xr cryb_sha224 3 , +.Xr cryb_sha256 3 , +.Xr cryb_sha384 3 +.Sh REFERENCES +.Rs +.%Q National Institute of Standards and Technology +.%R Secure Hash Standard (SHS) (FIPS PUB 180-4) +.%D March 2012 +.Re +.Sh AUTHORS +These functions and this manual page were written for the University +of Oslo by +.An Dag-Erling Sm\(/orgrav Aq Mt d.e.smorgrav@usit.uio.no .