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/doc/HMAC.pod | 106 --------------------- src/lib/libcrypto/doc/MD5.pod | 101 -------------------- src/lib/libcrypto/man/HMAC.3 | 206 +++++++++++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/MD5.3 | 184 ++++++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 6 +- 5 files changed, 393 insertions(+), 210 deletions(-) delete mode 100644 src/lib/libcrypto/doc/HMAC.pod delete mode 100644 src/lib/libcrypto/doc/MD5.pod create mode 100644 src/lib/libcrypto/man/HMAC.3 create mode 100644 src/lib/libcrypto/man/MD5.3 (limited to 'src') diff --git a/src/lib/libcrypto/doc/HMAC.pod b/src/lib/libcrypto/doc/HMAC.pod deleted file mode 100644 index d92138d273..0000000000 --- a/src/lib/libcrypto/doc/HMAC.pod +++ /dev/null @@ -1,106 +0,0 @@ -=pod - -=head1 NAME - -HMAC, HMAC_Init, HMAC_Update, HMAC_Final, HMAC_cleanup - HMAC message -authentication code - -=head1 SYNOPSIS - - #include - - unsigned char *HMAC(const EVP_MD *evp_md, const void *key, - int key_len, const unsigned char *d, int n, - unsigned char *md, unsigned int *md_len); - - void HMAC_CTX_init(HMAC_CTX *ctx); - - int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md); - int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md, ENGINE *impl); - int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); - int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); - - void HMAC_CTX_cleanup(HMAC_CTX *ctx); - void HMAC_cleanup(HMAC_CTX *ctx); - -=head1 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. - -HMAC() computes the message authentication code of the B bytes at -B using the hash function B and the key B which is -B bytes long. - -It places the result in B (which must have space for the output of -the hash function, which is no more than B bytes). -If B is NULL, the digest is placed in a static array. The size of -the output is placed in B, unless it is B. - -B can be EVP_sha1(), EVP_ripemd160() etc. - -HMAC_CTX_init() initialises a B before first use. It must be -called. - -HMAC_CTX_cleanup() erases the key and other data from the B -and releases any associated resources. It must be called when an -B is no longer required. - -HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back -compatibility with 0.9.6b, it is deprecated. - -The following functions may be used if the message is not completely -stored in memory: - -HMAC_Init() initializes a B structure to use the hash -function B and the key B which is B bytes -long. It is deprecated and only included for backward compatibility -with OpenSSL 0.9.6b. - -HMAC_Init_ex() initializes or reuses a B structure to use -the function B and key B. Either can be NULL, in which -case the existing one will be reused. HMAC_CTX_init() must have been -called before the first use of an B in this -function. B. - -HMAC_Update() can be called repeatedly with chunks of the message to -be authenticated (B bytes at B). - -HMAC_Final() places the message authentication code in B, which -must have space for the hash function output. - -=head1 RETURN VALUES - -HMAC() returns a pointer to the message authentication code or NULL if -an error occurred. - -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if -an error occurred. - -HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. - -=head1 CONFORMING TO - -RFC 2104 - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() -are available since SSLeay 0.9.0. - -HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available -since OpenSSL 0.9.7. - -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in -versions of OpenSSL before 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/MD5.pod b/src/lib/libcrypto/doc/MD5.pod deleted file mode 100644 index b0edd5416f..0000000000 --- a/src/lib/libcrypto/doc/MD5.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -MD2, MD4, MD5, MD2_Init, MD2_Update, MD2_Final, MD4_Init, MD4_Update, -MD4_Final, MD5_Init, MD5_Update, MD5_Final - MD2, MD4, and MD5 hash functions - -=head1 SYNOPSIS - - #include - - unsigned char *MD2(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD2_Init(MD2_CTX *c); - int MD2_Update(MD2_CTX *c, const unsigned char *data, - unsigned long len); - int MD2_Final(unsigned char *md, MD2_CTX *c); - - - #include - - unsigned char *MD4(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD4_Init(MD4_CTX *c); - int MD4_Update(MD4_CTX *c, const void *data, - unsigned long len); - int MD4_Final(unsigned char *md, MD4_CTX *c); - - - #include - - unsigned char *MD5(const unsigned char *d, unsigned long n, - unsigned char *md); - - int MD5_Init(MD5_CTX *c); - int MD5_Update(MD5_CTX *c, const void *data, - unsigned long len); - int MD5_Final(unsigned char *md, MD5_CTX *c); - -=head1 DESCRIPTION - -MD2, MD4, and MD5 are cryptographic hash functions with a 128 bit output. - -MD2(), MD4(), and MD5() compute the MD2, MD4, and MD5 message digest -of the B bytes at B and place it in B (which must have space -for MD2_DIGEST_LENGTH == MD4_DIGEST_LENGTH == MD5_DIGEST_LENGTH == 16 -bytes of output). If B is NULL, the digest is placed in a static -array. - -The following functions may be used if the message is not completely -stored in memory: - -MD2_Init() initializes a B structure. - -MD2_Update() can be called repeatedly with chunks of the message to -be hashed (B bytes at B). - -MD2_Final() places the message digest in B, which must have space -for MD2_DIGEST_LENGTH == 16 bytes of output, and erases the B. - -MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and -MD5_Final() are analogous using an B and B structure. - -Applications should use the higher level functions -L -etc. instead of calling the hash functions directly. - -=head1 NOTE - -MD2, MD4, and MD5 are recommended only for compatibility with existing -applications. In new applications, SHA-1 or RIPEMD-160 should be -preferred. - -=head1 RETURN VALUES - -MD2(), MD4(), and MD5() return pointers to the hash value. - -MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), -MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for -success, 0 otherwise. - -=head1 CONFORMING TO - -RFC 1319, RFC 1320, RFC 1321 - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), -MD5_Update() and MD5_Final() are available in all versions of SSLeay -and OpenSSL. - -MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and -above. - -=cut 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