From 05264184755e9ad926b368969ae307f8b4784f6e Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 3 Nov 2016 10:02:57 +0000 Subject: convert HMAC and MD5 manuals from pod to mdoc --- src/lib/libcrypto/man/HMAC.3 | 206 +++++++++++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/MD5.3 | 184 ++++++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 6 +- 3 files changed, 393 insertions(+), 3 deletions(-) create mode 100644 src/lib/libcrypto/man/HMAC.3 create mode 100644 src/lib/libcrypto/man/MD5.3 (limited to 'src/lib/libcrypto/man') diff --git a/src/lib/libcrypto/man/HMAC.3 b/src/lib/libcrypto/man/HMAC.3 new file mode 100644 index 0000000000..577070afb0 --- /dev/null +++ b/src/lib/libcrypto/man/HMAC.3 @@ -0,0 +1,206 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt HMAC 3 +.Os +.Sh NAME +.Nm HMAC , +.Nm HMAC_Init , +.Nm HMAC_Update , +.Nm HMAC_Final , +.Nm HMAC_cleanup +.Nd HMAC message authentication code +.Sh SYNOPSIS +.In openssl/hmac.h +.Ft unsigned char * +.Fo HMAC +.Fa "const EVP_MD *evp_md" +.Fa "const void *key" +.Fa "int key_len" +.Fa "const unsigned char *d" +.Fa "int n" +.Fa "unsigned char *md" +.Fa "unsigned int *md_len" +.Fc +.Ft void +.Fo HMAC_CTX_init +.Fa "HMAC_CTX *ctx" +.Fc +.Ft int +.Fo HMAC_Init +.Fa "HMAC_CTX *ctx" +.Fa "const void *key" +.Fa "int key_len" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo HMAC_Init_ex +.Fa "HMAC_CTX *ctx" +.Fa "const void *key" +.Fa "int key_len" +.Fa "const EVP_MD *md" +.Fa "ENGINE *impl" +.Fc +.Ft int +.Fo HMAC_Update +.Fa "HMAC_CTX *ctx" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo HMAC_Final +.Fa "HMAC_CTX *ctx" +.Fa "unsigned char *md" +.Fa "unsigned int *len" +.Fc +.Ft void +.Fo HMAC_CTX_cleanup +.Fa "HMAC_CTX *ctx" +.Fc +.Ft void +.Fo HMAC_cleanup +.Fa "HMAC_CTX *ctx" +.Fc +.Sh DESCRIPTION +HMAC is a MAC (message authentication code), i.e. a keyed hash +function used for message authentication, which is based on a hash +function. +.Pp +.Fn HMAC +computes the message authentication code of the +.Fa n +bytes at +.Fa d +using the hash function +.Fa evp_md +and the key +.Fa key +which is +.Fa key_len +bytes long. +.Pp +It places the result in +.Fa md , +which must have space for the output of the hash function, which is no +more than +.Dv EVP_MAX_MD_SIZE +bytes. +If +.Fa md +is +.Dv NULL , +the digest is placed in a static array. +The size of the output is placed in +.Fa md_len , +unless it is +.Dv NULL . +.Pp +.Fa evp_md +can be +.Xr EVP_sha1 3 , +.Xr EVP_ripemd160 3 , +etc. +.Pp +.Fn HMAC_CTX_init +initialises a +.Vt HMAC_CTX +before first use. +It must be called. +.Pp +.Fn HMAC_CTX_cleanup +erases the key and other data from the +.Vt HMAC_CTX +and releases any associated resources. +It must be called when an +.Vt HMAC_CTX +is no longer required. +.Pp +.Fn HMAC_cleanup +is an alias for +.Fn HMAC_CTX_cleanup +included for backward compatibility with 0.9.6b. +It is deprecated. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn HMAC_Init +initializes a +.Vt HMAC_CTX +structure to use the hash function +.Fa evp_md +and the key +.Fa key +which is +.Fa key_len +bytes long. +It is deprecated and only included for backward compatibility with +OpenSSL 0.9.6b. +.Pp +.Fn HMAC_Init_ex +initializes or reuses a +.Vt HMAC_CTX +structure to use the function +.Fa evp_md +and key +.Fa key . +Either can be +.Dv NULL , +in which case the existing one will be reused. +.Fn HMAC_CTX_init +must have been called before the first use of an +.Vt HMAC_CTX +in this function. +.Sy N.B. +.Fn HMAC_Init +had this undocumented behaviour in previous versions of OpenSSL - +failure to switch to +.Fn HMAC_Init_ex +in programs that expect it will cause them to stop working. +.Pp +.Fn HMAC_Update +can be called repeatedly with chunks of the message to be authenticated +.Pq Fa len No bytes at Fa data . +.Pp +.Fn HMAC_Final +places the message authentication code in +.Fa md , +which must have space for the hash function output. +.Sh RETURN VALUES +.Fn HMAC +returns a pointer to the message authentication code or +.Dv NULL +if an error occurred. +.Pp +.Fn HMAC_Init_ex , +.Fn HMAC_Update , +and +.Fn HMAC_Final +return 1 for success or 0 if an error occurred. +.Pp +.Fn HMAC_CTX_init +and +.Fn HMAC_CTX_cleanup +do not return values. +.Sh SEE ALSO +.Xr evp 3 +.Sh STANDARDS +RFC 2104 +.Sh HISTORY +.Fn HMAC , +.Fn HMAC_Init , +.Fn HMAC_Update , +.Fn HMAC_Final , +and +.Fn HMAC_cleanup +are available since SSLeay 0.9.0. +.Pp +.Fn HMAC_CTX_init , +.Fn HMAC_Init_ex , +and +.Fn HMAC_CTX_cleanup +are available since OpenSSL 0.9.7. +.Pp +.Fn HMAC_Init_ex , +.Fn HMAC_Update , +and +.Fn HMAC_Final +did not return values in versions of OpenSSL before 1.0.0. diff --git a/src/lib/libcrypto/man/MD5.3 b/src/lib/libcrypto/man/MD5.3 new file mode 100644 index 0000000000..b0053c1acd --- /dev/null +++ b/src/lib/libcrypto/man/MD5.3 @@ -0,0 +1,184 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt MD5 3 +.Os +.Sh NAME +.Nm MD2 , +.Nm MD4 , +.Nm MD5 , +.Nm MD2_Init , +.Nm MD2_Update , +.Nm MD2_Final , +.Nm MD4_Init , +.Nm MD4_Update , +.Nm MD4_Final , +.Nm MD5_Init , +.Nm MD5_Update , +.Nm MD5_Final +.Nd MD2, MD4, and MD5 hash functions +.Sh SYNOPSIS +.In openssl/md2.h +.Ft unsigned char * +.Fo MD2 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo MD2_Init +.Fa "MD2_CTX *c" +.Fc +.Ft int +.Fo MD2_Update +.Fa "MD2_CTX *c" +.Fa "const unsigned char *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo MD2_Final +.Fa "unsigned char *md" +.Fa "MD2_CTX *c" +.Fc +.In openssl/md4.h +.Ft unsigned char * +.Fo MD4 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo MD4_Init +.Fa "MD4_CTX *c" +.Fc +.Ft int +.Fo MD4_Update +.Fa "MD4_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo MD4_Final +.Fa "unsigned char *md" +.Fa "MD4_CTX *c" +.Fc +.In openssl/md5.h +.Ft unsigned char * +.Fo MD5 +.Fa "const unsigned char *d" +.Fa "unsigned long n" +.Fa "unsigned char *md" +.Fc +.Ft int +.Fo MD5_Init +.Fa "MD5_CTX *c" +.Fc +.Ft int +.Fo MD5_Update +.Fa "MD5_CTX *c" +.Fa "const void *data" +.Fa "unsigned long len" +.Fc +.Ft int +.Fo MD5_Final +.Fa "unsigned char *md" +.Fa "MD5_CTX *c" +.Fc +.Sh DESCRIPTION +MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit +output. +.Pp +.Fn MD2 , +.Fn MD4 , +and +.Fn MD5 +compute the MD2, MD4, and MD5 message digest of the +.Fa n +bytes at +.Fa d +and place it in +.Fa md , +which must have space for +.Dv MD2_DIGEST_LENGTH No == +.Dv MD4_DIGEST_LENGTH No == +.Dv MD5_DIGEST_LENGTH No == 16 +bytes of output. +If +.Fa md +is +.Dv NULL , +the digest is placed in a static array. +.Pp +The following functions may be used if the message is not completely +stored in memory: +.Pp +.Fn MD2_Init +initializes a +.Vt MD2_CTX +structure. +.Pp +.Fn MD2_Update +can be called repeatedly with chunks of the message to be hashed +.Pq Fa len No bytes at Fa data . +.Pp +.Fn MD2_Final +places the message digest in +.Fa md , +which must have space for +.Dv MD2_DIGEST_LENGTH No == 16 +bytes of output, and erases the +.Vt MD2_CTX . +.Pp +.Fn MD4_Init , +.Fn MD4_Update , +.Fn MD4_Final , +.Fn MD5_Init , +.Fn MD5_Update , +and +.Fn MD5_Final +are analogous using an +.Vt MD4_CTX +and +.Vt MD5_CTX +structure. +.Pp +Applications should use the higher level functions +.Xr EVP_DigestInit 3 +etc. instead of calling these hash functions directly. +.Sh RETURN VALUES +.Fn MD2 , +.Fn MD4 , +and +.Fn MD5 +return pointers to the hash value. +.Pp +.Fn MD2_Init , +.Fn MD2_Update , +.Fn MD2_Final , +.Fn MD4_Init , +.Fn MD4_Update , +.Fn MD4_Final , +.Fn MD5_Init , +.Fn MD5_Update , +and +.Fn MD5_Final +return 1 for success or 0 otherwise. +.Sh SEE ALSO +.Xr EVP_DigestInit 3 +.Sh STANDARDS +RFC 1319, RFC 1320, RFC 1321 +.Sh HISTORY +.Fn MD2 , +.Fn MD2_Init , +.Fn MD2_Update , +.Fn MD2_Final , +.Fn MD5 , +.Fn MD5_Init , +.Fn MD5_Update , +and +.Fn MD5_Final +are available in all versions of SSLeay and OpenSSL. +.Pp +.Fn MD4 , +.Fn MD4_Init , +and +.Fn MD4_Update +are available in OpenSSL 0.9.6 and above. diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index f4fd152ff7..1989a25092 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.38 2016/11/03 09:35:34 schwarze Exp $ +# $OpenBSD: Makefile,v 1.39 2016/11/03 10:02:57 schwarze Exp $ .include # for NOMAN @@ -115,6 +115,8 @@ MAN= \ EVP_SealInit.3 \ EVP_SignInit.3 \ EVP_VerifyInit.3 \ + HMAC.3 \ + MD5.3 \ UI_new.3 \ bn_dump.3 \ crypto.3 \ @@ -124,8 +126,6 @@ MAN= \ lh_new.3 \ GENMAN= \ - HMAC.3 \ - MD5.3 \ OBJ_nid2obj.3 \ OPENSSL_VERSION_NUMBER.3 \ OPENSSL_config.3 \ -- cgit v1.2.3-55-g6feb