From 55967afe8085dd63bb004cadc870661003a588e9 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sun, 18 Feb 2018 17:32:13 +0000 Subject: [PATCH] In hmac.c rev. 1.13 2018/02/17 14:53:59, jsing@ provided HMAC_CTX_new(3), HMAC_CTX_free(3), HMAC_CTX_reset(3), and HMAC_CTX_get_md(3). Merge the documentation from OpenSSL, with many tweaks by me. Also include a few earlier improvements from OpenSSL. While here, improve the order of the functions, the description of deprecated functions, and remove a confusing warning about the behaviour of HMAC_Init(3) in historical versions of OpenSSL. --- lib/libcrypto/man/HMAC.3 | 213 +++++++++++++++++++++++++++++---------- 1 file changed, 157 insertions(+), 56 deletions(-) diff --git a/lib/libcrypto/man/HMAC.3 b/lib/libcrypto/man/HMAC.3 index 595d5ed5ceb..cc73d360d9e 100644 --- a/lib/libcrypto/man/HMAC.3 +++ b/lib/libcrypto/man/HMAC.3 @@ -1,9 +1,12 @@ -.\" $OpenBSD: HMAC.3,v 1.7 2017/08/01 14:57:03 schwarze Exp $ -.\" OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" $OpenBSD: HMAC.3,v 1.8 2018/02/18 17:32:13 schwarze Exp $ +.\" full merge up to: OpenSSL crypto/hmac a528d4f0 Oct 27 13:40:11 2015 -0400 +.\" selective merge up to: OpenSSL man3/HMAC b3696a55 Sep 2 09:35:50 2017 -0400 .\" -.\" This file was written by Ulf Moeller . -.\" Copyright (c) 2000-2002, 2006, 2008, 2009, 2013, 2016 The OpenSSL Project. -.\" All rights reserved. +.\" This file was written by Ulf Moeller , +.\" Richard Levitte , and +.\" Matt Caswell . +.\" Copyright (c) 2000-2002, 2006, 2008, 2009, 2013, 2015, 2016 +.\" The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -49,20 +52,24 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 1 2017 $ +.Dd $Mdocdate: February 18 2018 $ .Dt HMAC 3 .Os .Sh NAME .Nm HMAC , +.Nm HMAC_CTX_new , +.Nm HMAC_CTX_reset , +.Nm HMAC_CTX_free , .Nm HMAC_CTX_init , -.Nm HMAC_Init , +.Nm HMAC_CTX_cleanup , +.Nm HMAC_cleanup , .Nm HMAC_Init_ex , +.Nm HMAC_Init , .Nm HMAC_Update , .Nm HMAC_Final , -.Nm HMAC_CTX_cleanup , -.Nm HMAC_cleanup , .Nm HMAC_CTX_copy , .Nm HMAC_CTX_set_flags , +.Nm HMAC_CTX_get_md , .Nm HMAC_size .Nd HMAC message authentication code .Sh SYNOPSIS @@ -77,24 +84,42 @@ .Fa "unsigned char *md" .Fa "unsigned int *md_len" .Fc +.Ft HMAC_CTX * +.Fn HMAC_CTX_new void +.Ft int +.Fo HMAC_CTX_reset +.Fa "HMAC_CTX *ctx" +.Fc +.Ft void +.Fo HMAC_CTX_free +.Fa "HMAC_CTX *ctx" +.Fc .Ft void .Fo HMAC_CTX_init .Fa "HMAC_CTX *ctx" .Fc +.Ft void +.Fo HMAC_CTX_cleanup +.Fa "HMAC_CTX *ctx" +.Fc +.Ft void +.Fo HMAC_cleanup +.Fa "HMAC_CTX *ctx" +.Fc .Ft int -.Fo HMAC_Init +.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_Init_ex +.Fo HMAC_Init .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 @@ -108,14 +133,6 @@ .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 .Ft int .Fo HMAC_CTX_copy .Fa "HMAC_CTX *dctx" @@ -126,6 +143,10 @@ .Fa "HMAC_CTX *ctx" .Fa "unsigned long flags" .Fc +.Ft const EVP_MD * +.Fo HMAC_CTX_get_md +.Fa "const HMAC_CTX *ctx" +.Fc .Ft size_t .Fo HMAC_size .Fa "const HMAC_CTX *e" @@ -158,7 +179,7 @@ If .Fa md is .Dv NULL , -the digest is placed in a static array. +the digest is placed in a static array, which is not thread safe. The size of the output is placed in .Fa md_len , unless it is @@ -170,19 +191,48 @@ can be .Xr EVP_ripemd160 3 , etc. .Pp +.Fn HMAC_CTX_new +allocates and initializes a new +.Vt HMAC_CTX +object. +.Pp +.Fn HMAC_CTX_reset +zeroes and re-initializes +.Fa ctx +and associated resources, making it suitable for new computations +as if it was deleted with +.Fn HMAC_CTX_free +and newly created with +.Fn HMAC_CTX_new . +.Pp +.Fn HMAC_CTX_free +erases the key and other data from +.Fa ctx , +releases any associated resources, and finally frees +.Fa ctx +itself. +.Pp .Fn HMAC_CTX_init -initialises a +is a deprecated function to initialize an empty .Vt HMAC_CTX -before first use. -It must be called. +object, similar to +.Fn CTX_new +but without the allocation. +Calling it is required for static objects and objects on the stack +before using them. .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. +is a deprecated function to erase the key and other data from +.Fa ctx +and release any associated resources, similar to +.Fn HMAC_CTX_free +but without freeing +.Fa ctx +itself. +Calling it is required for static objects and objects on the stack +that were initialized with +.Fn HMAC_CTX_init +and are no longer needed. .Pp .Fn HMAC_cleanup is an alias for @@ -193,39 +243,66 @@ It is deprecated and implemented as a macro. 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 +sets up or reuses +.Fa ctx +to use the hash function .Fa evp_md -and key +and the key .Fa key . Either can be .Dv NULL , -in which case the existing one will be reused. +in which case the existing one is reused. +The +.Fa ctx +must have been created with +.Fn HMAC_CTX_new +or initialized with .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 +before the first use in this function. +If .Fn HMAC_Init_ex -in programs that expect it will cause them to stop working. +is called with a +.Dv NULL +.Fa key +but +.Fa evp_md +is neither +.Dv NULL +nor the same as the previous digest used by +.Fa ctx , +then an error is returned because reuse of an existing key with a +different digest is not supported. +.Pp +.Fn HMAC_Init +is a deprecated wrapper around +.Fn HMAC_Init_ex . +If called with both +.Fa key +and +.Fa md , +it calls +.Fn HMAC_CTX_init +first, which only makes sense for an empty, uninitialized +.Fa ctx , +but not for one already initialized with +.Fn HMAC_CTX_new +or +.Fn HMAC_CTX_init . +If +.Fa key +or +.Fa md +is +.Dv NULL , +it does not call +.Fn HMAC_CTX_init ; +so in this case, +.Fa ctx +already needs to be initialized with +.Fn HMAC_CTX_new +or +.Fn HMAC_CTX_init . .Pp .Fn HMAC_Update can be called repeatedly with chunks of the message to be authenticated @@ -260,6 +337,14 @@ returns a pointer to the message authentication code or .Dv NULL if an error occurred. .Pp +.Fn HMAC_CTX_new +returns a pointer to the new +.Vt HMAC_CTX +object or +.Dv NULL +if an error occurred. +.Pp +.Fn HMAC_CTX_reset , .Fn HMAC_Init_ex , .Fn HMAC_Update , .Fn HMAC_Final , @@ -267,6 +352,15 @@ and .Fn HMAC_CTX_copy return 1 for success or 0 if an error occurred. .Pp +.Fn HMAC_CTX_get_md +returns the message digest that was previously set for +.Fa ctx +with +.Fn HMAC_Init_ex , +or +.Dv NULL +if none was set. +.Pp .Fn HMAC_size returns the length in bytes of the underlying hash function output or 0 on error. @@ -289,6 +383,13 @@ and .Fn HMAC_CTX_cleanup are available since OpenSSL 0.9.7. .Pp +.Fn HMAC_CTX_new , +.Fn HMAC_CTX_reset , +.Fn HMAC_CTX_free , +and +.Fn HMAC_CTX_get_md +first appeared in OpenSSL 1.1.0. +.Pp .Fn HMAC_Init_ex , .Fn HMAC_Update , and -- 2.20.1