cryb.to/cryb-to
1
0
Fork 0
mirror of https://github.com/cryb-to/cryb-to.git synced 2024-11-25 15:15:42 +00:00
Code Issues Projects Releases Packages Wiki Activity

Add man pages for a few functions.

Browse source
This commit is contained in:
Dag-Erling Smørgrav 2016-01-08 17:27:27 +01:00
parent 6fd1a01fd2
commit da40b1fad8
8 changed files with 460 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
lib/core/Makefile.am
View file

@ -12,3 +12,7 @@ libcryb_core_la_SOURCES = \
wstring.c
EXTRA_DIST = _string.c
dist_man3_MANS = \
cryb_strlcat.3 \
cryb_strlcpy.3

82
lib/core/cryb_strlcat.3 Normal file
View file

@ -0,0 +1,82 @@
.\"-
.\" Copyright (c) 2015 Universitetet i Oslo
.\" 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 February 5, 2015
.Dt tsd_strlcat 3
.Os
.Sh NAME
.Nm tsd_strlcat
.Nd safely append a string to a buffer
.Sh LIBRARY
.Lb libtsd
.Sh SYNOPSIS
.In stdint.h
.In tsd/strutil.h
.Ft size_t
.Fn tsd_strlcat "char *dst" "const char *src" "size_t size"
.Sh DESCRIPTION
The
.Nm tsd_strlcat
function appends the NUL-terminated string pointed to by
.Va src
to the NUL-terminated string stored in the buffer pointed to by
.Va dst .
The
.Va size
argument specifies the total size of the buffer including the space
occupied by the existing string and space for the terminating NUL
character.
If the sum of the lengths of both strings exceeds the available space,
the result is truncated.
In all cases, the destination buffer is properly NUL-terminated.
.Sh RETURN VALUES
The
.Fn tsd_strlcat
function returns the sum of the lengths of the original strings.
If this number is equal to or greater than the value of the
.Va size
argument, the string was too long to fit in the buffer.
.Sh IMPLEMENTATION NOTES
If the
.Dv HAVE_STRLCAT
preprocessor macro is defined to 0 or undefined, the
.In tsd/sha1.h
header provides a
.Fn strlcat
macro as an alias to
.Fn tsd_strlcat .
.Sh SEE ALSO
.Xr strlcat 3 ,
.Xr strlcpy 3 ,
.Xr tsd_strlcpy 3
.Sh AUTHORS
The
.Fn tsd_strlcat
function 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 .

81
lib/core/cryb_strlcpy.3 Normal file
View file

@ -0,0 +1,81 @@
.\"-
.\" Copyright (c) 2015 Universitetet i Oslo
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modificpyion, 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 February 5, 2015
.Dt tsd_strlcpy 3
.Os
.Sh NAME
.Nm tsd_strlcpy
.Nd safely copy a string into a buffer
.Sh LIBRARY
.Lb libtsd
.Sh SYNOPSIS
.In stdint.h
.In tsd/strutil.h
.Ft size_t
.Fn tsd_strlcpy "char *dst" "const char *src" "size_t size"
.Sh DESCRIPTION
The
.Nm tsd_strlcpy
function copies the NUL-terminated string pointed to by
.Va src
into the buffer pointed to by
.Va dst .
The
.Va size
argument specifies the total size of the buffer, including the space
required for the terminating NUL character.
If the length of the string exceeds the available space, the result is
truncated.
In all cases, the destination buffer is properly NUL-terminated.
.Sh RETURN VALUES
The
.Fn tsd_strlcpy
function returns the length of the original string.
If this number is equal to or greater than the value of the
.Va size
argument, the string was too long to fit in the buffer.
.Sh IMPLEMENTATION NOTES
If the
.Dv HAVE_STRLCPY
preprocessor macro is defined to 0 or undefined, the
.In tsd/sha1.h
header provides a
.Fn strlcpy
macro as an alias to
.Fn tsd_strlcpy .
.Sh SEE ALSO
.Xr strlcat 3 ,
.Xr strlcpy 3 ,
.Xr tsd_strlcat 3
.Sh AUTHORS
The
.Fn tsd_strlcpy
function 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 .

3
lib/digest/Makefile.am
View file

@ -13,3 +13,6 @@ libcryb_digest_la_SOURCES = \
sha256.c \
sha384.c \
sha512.c
dist_man3_MANS = \
cryb_sha1.3

113
lib/digest/cryb_sha1.3 Normal file
View file

@ -0,0 +1,113 @@
.\"-
.\" Copyright (c) 2015 Universitetet i Oslo
.\" 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 February 5, 2015
.Dt CRYB_SHA1 3
.Os
.Sh NAME
.Nm cryb_sha1_init ,
.Nm cryb_sha1_update ,
.Nm cryb_sha1_final ,
.Nm cryb_sha1_complete
.Nd Secure Hash Algorithm 1
.Sh LIBRARY
.Lb libcryb
.Sh SYNOPSIS
.In stdint.h
.In cryb/sha1.h
.Ft void
.Fn cryb_sha1_init "cryb_sha1_ctx *context"
.Ft void
.Fn cryb_sha1_update "cryb_sha1_ctx *context" "const void *data" "size_t len"
.Ft void
.Fn cryb_sha1_final "cryb_sha1_ctx *context" "uint8_t *digest"
.Ft void
.Fn cryb_sha1_complete "const void *data" "size_t len" "uint8_t *digest"
.Sh DESCRIPTION
The
.Nm cryb_sha1
family of functions implements the NIST SHA1 message digest algorithm
as described in FIPS 180-4.
.Pp
The
.Fn cryb_sha1_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_sha1_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_sha1_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 SHA1_DIGEST_LEN
bytes long.
It is the caller's responsibility to dispose of the context structure
after calling
.Fn cryb_sha1_final .
.Pp
The
.Fn cryb_sha1_complete
function is a shortcut to calling
.Fn cryb_sha1_init ,
.Fn cryb_sha1_update
and
.Fn cryb_sha1_final
when the entire message is available up front in a single contiguous
buffer.
.Sh IMPLEMENTATION NOTES
The
.In cryb/sha1.h
header provides macros which allows these functions and the context
type to be referred to without their
.Dq Li cryb_
prefix.
.Pp
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
.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 .

4
lib/hash/Makefile.am
View file

@ -9,3 +9,7 @@ libcryb_hash_la_SOURCES = \
fletcher64.c \
murmur3_32.c \
pearson.c
dist_man3_MANS = \
cryb_fletcher.3 \
cryb_hash.3

93
lib/hash/cryb_fletcher.3 Normal file
View file

@ -0,0 +1,93 @@
.\"-
.\" 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 January 8, 2016
.Dt CRYB_FLETCHER 3
.Os
.Sh NAME
.Nm cryb_fletcher16_hash ,
.Nm cryb_fletcher32_hash ,
.Nm cryb_fletcher64_hash
.Nd hash functions
.Sh LIBRARY
.Lb libcryb-hash
.Sh SYNOPSIS
.In stdint.h
.In cryb/hash.h
.Ft uint16_t
.Fn fletcher16_hash "const void *data" "size_t len"
.Ft uint32_t
.Fn fletcher32_hash "const void *data" "size_t len"
.Ft uint64_t
.Fn fletcher64_hash "const void *data" "size_t len"
.Sh DESCRIPTION
The
.Fn cryb_fletcher16_hash ,
.Fn cryb_fletcher32_hash
and
.Fn cryb_fletcher64_hash
function return a 16-bit, 32-bit or 64-bit checksum of the
.Va len
first bytes of the object pointed to by
.Va data .
.Pp
Unlike the Pearson hash implemented by
.Fn cryb_hash
or cryptographic message digests such as the SHA family, these
checksums are suitable for error detection.
.Sh IMPLEMENTATION NOTES
Fletcher's paper assumes that the length of the input is a multiple of
the algorithm's word size (half the output size), and does not specify
or suggest how to handle odd-length input.
This implementation zero-pads the input up to the nearest multiple of
the word size.
If strict compatibility with other implementations is required, the
caller should take care to either pad the input or truncate the
.Va len
argument before calling the checksum function.
.Sh SEE ALSO
.Xr cryb_hash 3
.\".Sh REFERENCES
.Rs
.%A "Fletcher, John G."
.%D "January 1982"
.%T "An Arithmetic Checksum for Serial Transmissions"
.%J "IEEE Transactions on Communications"
.%V "30"
.%N "1"
.%P "247-252"
.%O "doi:10.1109/tcom.1982.1095369"
.Re
.Sh AUTHORS
The
.Fn cryb_fletcher16 ,
.Fn cryb_fletcher32
and
.Fn cryb_fletcher64
functions and this manual page were written by
.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .

80
lib/hash/cryb_hash.3 Normal file
View file

@ -0,0 +1,80 @@
.\"-
.\" Copyright (c) 2015-2016 Universitetet i Oslo
.\" 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 January 8, 2016
.Dt CRYB_HASH 3
.Os
.Sh NAME
.Nm cryb_hash ,
.Nm cryb_strhash
.Nd hash functions
.Sh LIBRARY
.Lb libcryb-hash
.Sh SYNOPSIS
.In stdint.h
.In cryb/hash.h
.Ft uint8_t
.Fn cryb_hash "const void *data" "size_t len"
.Ft uint8_t
.Fn cryb_strhash "const char *str"
.Sh DESCRIPTION
The
.Fn cryb_hash
function returns an 8-bit hash of the
.Va len
first bytes of the object pointed to by
.Va data .
.Pp
The
.Fn cryb_strhash
function returns an 8-bit hash of the NUL-terminated string pointed to
by
.Va str ,
not including the terminating NUL.
It is equivalent to calling
.Li cryb_hash(str, strlen(str)) .
.Sh SEE ALSO
.Xr cryb_sha1 3
.Sh REFERENCES
.Rs
.%A "Pearson, Peter K."
.%D "June 1990"
.%T "Fast Hashing of Variable-Length Text Strings"
.%J "Communications of the ACM"
.%V "33"
.%N "6"
.%P "677"
.%O "doi:10.1145/78973.78978"
.Re
.Sh AUTHORS
The
.Fn cryb_hash
and
.Fn cryb_strhash
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 .