gitweb.dragonflybsd.org Git - dragonfly.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\"
	2	.\" ----------------------------------------------------------------------------
	3	.\" "THE BEER-WARE LICENSE" (Revision 42):
	4	.\" <phk@FreeBSD.org> wrote this file. As long as you retain this notice you
	5	.\" can do whatever you want with this stuff. If we meet some day, and you think
	6	.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
	7	.\" ----------------------------------------------------------------------------
	8	.\"
	9	.\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
	10	.\" $FreeBSD: src/lib/libmd/sha256.3,v 1.4 2005/11/17 13:00:00 ru Exp $
	11	.\" $DragonFly: src/lib/libmd/sha256.3,v 1.2 2008/09/11 20:25:34 swildner Exp $
	12	.\"
	13	.Dd April 29, 2006
	14	.Dt SHA256 3
	15	.Os
	16	.Sh NAME
	17	.Nm SHA256_Init ,
	18	.Nm SHA256_Update ,
	19	.Nm SHA256_Final ,
	20	.Nm SHA256_End ,
	21	.Nm SHA256_File ,
	22	.Nm SHA256_FileChunk ,
	23	.Nm SHA256_Data
	24	.Nd calculate the FIPS 180-2 ``SHA-256'' message digest
	25	.Sh LIBRARY
	26	.Lb libmd
	27	.Sh SYNOPSIS
	28	.In sys/types.h
	29	.In sha256.h
	30	.Ft void
	31	.Fn SHA256_Init "SHA256_CTX *context"
	32	.Ft void
	33	.Fn SHA256_Update "SHA256_CTX context" "const unsigned char data" "size_t len"
	34	.Ft void
	35	.Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context"
	36	.Ft "char *"
	37	.Fn SHA256_End "SHA256_CTX context" "char buf"
	38	.Ft "char *"
	39	.Fn SHA256_File "const char filename" "char buf"
	40	.Ft "char *"
	41	.Fn SHA256_FileChunk "const char filename" "char buf" "off_t offset" "off_t length"
	42	.Ft "char *"
	43	.Fn SHA256_Data "const unsigned char data" "unsigned int len" "char buf"
	44	.Sh DESCRIPTION
	45	The
	46	.Li SHA256_
	47	functions calculate a 256-bit cryptographic checksum (digest)
	48	for any number of input bytes.
	49	A cryptographic checksum is a one-way
	50	hash function; that is, it is computationally impractical to find
	51	the input corresponding to a particular output.
	52	This net result is
	53	a
	54	.Dq fingerprint
	55	of the input-data, which does not disclose the actual input.
	56	.Pp
	57	The
	58	.Fn SHA256_Init ,
	59	.Fn SHA256_Update ,
	60	and
	61	.Fn SHA256_Final
	62	functions are the core functions.
	63	Allocate an
	64	.Vt SHA256_CTX ,
	65	initialize it with
	66	.Fn SHA256_Init ,
	67	run over the data with
	68	.Fn SHA256_Update ,
	69	and finally extract the result using
	70	.Fn SHA256_Final .
	71	.Pp
	72	.Fn SHA256_End
	73	is a wrapper for
	74	.Fn SHA256_Final
	75	which converts the return value to a 65-character
	76	(including the terminating '\e0')
	77	.Tn ASCII
	78	string which represents the 256 bits in hexadecimal.
	79	.Pp
	80	.Fn SHA256_File
	81	calculates the digest of a file, and uses
	82	.Fn SHA256_End
	83	to return the result.
	84	If the file cannot be opened, a null pointer is returned.
	85	.Fn SHA256_FileChunk
	86	is similar to
	87	.Fn SHA256_File ,
	88	but it only calculates the digest over a byte-range of the file specified,
	89	starting at
	90	.Fa offset
	91	and spanning
	92	.Fa length
	93	bytes.
	94	If the
	95	.Fa length
	96	parameter is specified as 0, or more than the length of the remaining part
	97	of the file,
	98	.Fn SHA256_FileChunk
	99	calculates the digest from
	100	.Fa offset
	101	to the end of file.
	102	.Fn SHA256_Data
	103	calculates the digest of a chunk of data in memory, and uses
	104	.Fn SHA256_End
	105	to return the result.
	106	.Pp
	107	When using
	108	.Fn SHA256_End ,
	109	.Fn SHA256_File ,
	110	or
	111	.Fn SHA256_Data ,
	112	the
	113	.Fa buf
	114	argument can be a null pointer, in which case the returned string
	115	is allocated with
	116	.Xr malloc 3
	117	and subsequently must be explicitly deallocated using
	118	.Xr free 3
	119	after use.
	120	If the
	121	.Fa buf
	122	argument is non-null it must point to at least 65 characters of buffer space.
	123	.Sh SEE ALSO
	124	.Xr md2 3 ,
	125	.Xr md4 3 ,
	126	.Xr md5 3 ,
	127	.Xr ripemd 3 ,
	128	.Xr sha 3
	129	.Sh HISTORY
	130	These functions appeared in
	131	.Fx 4.0 .
	132	.Sh AUTHORS
	133	The core hash routines were implemented by Colin Percival based on
	134	the published
	135	.Tn FIPS 180-2
	136	standard.
	137	.Sh BUGS
	138	No method is known to exist which finds two files having the same hash value,
	139	nor to find a file with a specific hash value.
	140	There is on the other hand no guarantee that such a method does not exist.