237 lines
6.5 KiB
Groff
237 lines
6.5 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2016 Allan Jude
|
|
.\" 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 21, 2019
|
|
.Dt SKEIN 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm SKEIN256_Init ,
|
|
.Nm SKEIN256_Update ,
|
|
.Nm SKEIN256_Final ,
|
|
.Nm SKEIN256_End ,
|
|
.Nm SKEIN256_File ,
|
|
.Nm SKEIN256_FileChunk ,
|
|
.Nm SKEIN256_Data ,
|
|
.Nm SKEIN512_Init ,
|
|
.Nm SKEIN512_Update ,
|
|
.Nm SKEIN512_Final ,
|
|
.Nm SKEIN512_End ,
|
|
.Nm SKEIN512_File ,
|
|
.Nm SKEIN512_FileChunk ,
|
|
.Nm SKEIN512_Data ,
|
|
.Nm SKEIN1024_Init ,
|
|
.Nm SKEIN1024_Update ,
|
|
.Nm SKEIN1024_Final ,
|
|
.Nm SKEIN1024_End ,
|
|
.Nm SKEIN1024_File ,
|
|
.Nm SKEIN1024_FileChunk ,
|
|
.Nm SKEIN1024_Data
|
|
.Nd calculate the ``SKEIN'' family of message digests
|
|
.Sh LIBRARY
|
|
.Lb libmd
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In skein.h
|
|
.Ft void
|
|
.Fn SKEIN256_Init "SKEIN256_CTX *context"
|
|
.Ft void
|
|
.Fn SKEIN256_Update "SKEIN256_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SKEIN256_Final "unsigned char digest[32]" "SKEIN256_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SKEIN256_End "SKEIN256_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SKEIN256_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SKEIN256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SKEIN256_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.Ft void
|
|
.Fn SKEIN512_Init "SKEIN512_CTX *context"
|
|
.Ft void
|
|
.Fn SKEIN512_Update "SKEIN512_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SKEIN512_Final "unsigned char digest[64]" "SKEIN512_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SKEIN512_End "SKEIN512_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SKEIN512_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SKEIN512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SKEIN512_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.Ft void
|
|
.Fn SKEIN1024_Init "SKEIN1024_CTX *context"
|
|
.Ft void
|
|
.Fn SKEIN1024_Update "SKEIN1024_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SKEIN1024_Final "unsigned char digest[128]" "SKEIN1024_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SKEIN1024_End "SKEIN1024_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SKEIN1024_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SKEIN1024_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SKEIN1024_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.Sh DESCRIPTION
|
|
.Li Skein
|
|
is a new family of cryptographic hash functions based on the
|
|
.Li Threefish
|
|
large-block cipher.
|
|
Its design combines speed, security, simplicity, and a great deal of
|
|
flexibility in a modular package that is easy to analyze.
|
|
.Li Skein
|
|
is defined for three different internal state sizes\(em256 bits, 512 bits, and
|
|
1024 bits\(emand any output size.
|
|
This allows Skein to be a drop-in replacement for the entire SHA family
|
|
of hash functions.
|
|
.Pp
|
|
The
|
|
.Fn SKEIN256_Init ,
|
|
.Fn SKEIN256_Update ,
|
|
and
|
|
.Fn SKEIN256_Final
|
|
functions are the core functions.
|
|
Allocate an
|
|
.Vt SKEIN256_CTX ,
|
|
initialize it with
|
|
.Fn SKEIN256_Init ,
|
|
run over the data with
|
|
.Fn SKEIN256_Update ,
|
|
and finally extract the result using
|
|
.Fn SKEIN256_Final ,
|
|
which will also erase the
|
|
.Vt SKEIN256_CTX .
|
|
.Pp
|
|
.Fn SKEIN256_End
|
|
is a wrapper for
|
|
.Fn SKEIN256_Final
|
|
which converts the return value to a 33-character
|
|
(including the terminating '\e0')
|
|
.Tn ASCII
|
|
string which represents the 256 bits in hexadecimal.
|
|
.Pp
|
|
.Fn SKEIN256_File
|
|
calculates the digest of a file, and uses
|
|
.Fn SKEIN256_End
|
|
to return the result.
|
|
If the file cannot be opened, a null pointer is returned.
|
|
.Fn SKEIN256_FileChunk
|
|
is similar to
|
|
.Fn SKEIN256_File ,
|
|
but it only calculates the digest over a byte-range of the file specified,
|
|
starting at
|
|
.Fa offset
|
|
and spanning
|
|
.Fa length
|
|
bytes.
|
|
If the
|
|
.Fa length
|
|
parameter is specified as 0, or more than the length of the remaining part
|
|
of the file,
|
|
.Fn SKEIN256_FileChunk
|
|
calculates the digest from
|
|
.Fa offset
|
|
to the end of file.
|
|
.Fn SKEIN256_Data
|
|
calculates the digest of a chunk of data in memory, and uses
|
|
.Fn SKEIN256_End
|
|
to return the result.
|
|
.Pp
|
|
When using
|
|
.Fn SKEIN256_End ,
|
|
.Fn SKEIN256_File ,
|
|
or
|
|
.Fn SKEIN256_Data ,
|
|
the
|
|
.Fa buf
|
|
argument can be a null pointer, in which case the returned string
|
|
is allocated with
|
|
.Xr malloc 3
|
|
and subsequently must be explicitly deallocated using
|
|
.Xr free 3
|
|
after use.
|
|
If the
|
|
.Fa buf
|
|
argument is non-null it must point to at least 33 characters of buffer space.
|
|
.Pp
|
|
The
|
|
.Li SKEIN512_
|
|
and
|
|
.Li SKEIN1024_
|
|
functions are similar to the
|
|
.Li SKEIN256_
|
|
functions except they produce a 512-bit, 65 character,
|
|
or 1024-bit, 129 character, output.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn SKEIN256_End
|
|
function called with a null buf argument may fail and return NULL if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ENOMEM
|
|
Insufficient storage space is available.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn SKEIN256_File
|
|
and
|
|
.Fn SKEIN256_FileChunk
|
|
may return NULL when underlying
|
|
.Xr open 2 ,
|
|
.Xr fstat 2 ,
|
|
.Xr lseek 2 ,
|
|
or
|
|
.Xr SKEIN256_End 3
|
|
fail.
|
|
.Sh SEE ALSO
|
|
.Xr md4 3 ,
|
|
.Xr md5 3 ,
|
|
.Xr ripemd 3 ,
|
|
.Xr sha 3 ,
|
|
.Xr sha256 3 ,
|
|
.Xr sha512 3
|
|
.Sh HISTORY
|
|
These functions appeared in
|
|
.Fx 11.0 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The core hash routines were imported from version 1.3 of the optimized
|
|
Skein reference implementation written by
|
|
.An Doug Whiting
|
|
as submitted to the NSA SHA-3 contest.
|
|
The algorithms were developed by
|
|
.An Niels Ferguson ,
|
|
.An Stefan Lucks ,
|
|
.An Bruce Schneier ,
|
|
.An Doug Whiting ,
|
|
.An Mihir Bellare ,
|
|
.An Tadayoshi Kohno ,
|
|
.An Jon Callas,
|
|
and
|
|
.An Jesse Walker .
|