diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/HMAC.3')
-rw-r--r-- | secure/lib/libcrypto/man/man3/HMAC.3 | 98 |
1 files changed, 62 insertions, 36 deletions
diff --git a/secure/lib/libcrypto/man/man3/HMAC.3 b/secure/lib/libcrypto/man/man3/HMAC.3 index dd574605d0e9..15ab6c68203e 100644 --- a/secure/lib/libcrypto/man/man3/HMAC.3 +++ b/secure/lib/libcrypto/man/man3/HMAC.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,23 +130,41 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "HMAC 3" -.TH HMAC 3 "2022-06-21" "1.1.1p" "OpenSSL" +.IX Title "HMAC 3ossl" +.TH HMAC 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -HMAC, HMAC_CTX_new, HMAC_CTX_reset, HMAC_CTX_free, HMAC_Init, HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_copy, HMAC_CTX_set_flags, HMAC_CTX_get_md, HMAC_size \&\- HMAC message authentication code +HMAC, +HMAC_CTX_new, +HMAC_CTX_reset, +HMAC_CTX_free, +HMAC_Init, +HMAC_Init_ex, +HMAC_Update, +HMAC_Final, +HMAC_CTX_copy, +HMAC_CTX_set_flags, +HMAC_CTX_get_md, +HMAC_size +\&\- HMAC message authentication code .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/hmac.h> \& -\& unsigned char *HMAC(const EVP_MD *evp_md, const void *key, -\& int key_len, const unsigned char *d, size_t n, +\& unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len, +\& const unsigned char *data, size_t data_len, \& unsigned char *md, unsigned int *md_len); -\& +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 \& HMAC_CTX *HMAC_CTX_new(void); \& int HMAC_CTX_reset(HMAC_CTX *ctx); \& @@ -166,13 +182,13 @@ HMAC, HMAC_CTX_new, HMAC_CTX_reset, HMAC_CTX_free, HMAC_Init, HMAC_Init_ex, HMAC \& size_t HMAC_size(const HMAC_CTX *e); .Ve .PP -Deprecated: +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): .PP -.Vb 4 -\& #if OPENSSL_API_COMPAT < 0x10100000L +.Vb 2 \& int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, \& const EVP_MD *md); -\& #endif .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" @@ -180,23 +196,31 @@ Deprecated: function used for message authentication, which is based on a hash function. .PP -\&\s-1\fBHMAC\s0()\fR computes the message authentication code of the \fBn\fR bytes at -\&\fBd\fR using the hash function \fBevp_md\fR and the key \fBkey\fR which is -\&\fBkey_len\fR bytes long. +\&\s-1\fBHMAC\s0()\fR computes the message authentication code of the \fIdata_len\fR bytes at +\&\fIdata\fR using the hash function \fIevp_md\fR and the key \fIkey\fR which is +\&\fIkey_len\fR bytes long. The \fIkey\fR may also be \s-1NULL\s0 with \fIkey_len\fR being 0. .PP -It places the result in \fBmd\fR (which must have space for the output of +It places the result in \fImd\fR (which must have space for the output of the hash function, which is no more than \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes). -If \fBmd\fR is \s-1NULL,\s0 the digest is placed in a static array. The size of -the output is placed in \fBmd_len\fR, unless it is \fB\s-1NULL\s0\fR. Note: passing a \s-1NULL\s0 -value for \fBmd\fR to use the static array is not thread safe. +If \fImd\fR is \s-1NULL,\s0 the digest is placed in a static array. The size of +the output is placed in \fImd_len\fR, unless it is \s-1NULL.\s0 Note: passing a \s-1NULL\s0 +value for \fImd\fR to use the static array is not thread safe. .PP -\&\fBevp_md\fR is a message digest such as \fBEVP_sha1()\fR, \fBEVP_ripemd160()\fR etc. \s-1HMAC\s0 does -not support variable output length digests such as \fBEVP_shake128()\fR and +\&\fIevp_md\fR is a message digest such as \fBEVP_sha1()\fR, \fBEVP_ripemd160()\fR etc. +\&\s-1HMAC\s0 does not support variable output length digests such as \fBEVP_shake128()\fR and \&\fBEVP_shake256()\fR. .PP +\&\s-1\fBHMAC\s0()\fR uses the default \fB\s-1OSSL_LIB_CTX\s0\fR. +Use \fBEVP_Q_mac\fR\|(3) instead if a library context is required. +.PP +All of the functions described below are deprecated. +Applications should instead use \fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3), +\&\fBEVP_MAC_init\fR\|(3), \fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3) +or the 'quick' single-shot \s-1MAC\s0 function \fBEVP_Q_mac\fR\|(3). +.PP \&\fBHMAC_CTX_new()\fR creates a new \s-1HMAC_CTX\s0 in heap memory. .PP -\&\fBHMAC_CTX_reset()\fR zeros an existing \fB\s-1HMAC_CTX\s0\fR and associated +\&\fBHMAC_CTX_reset()\fR clears an existing \fB\s-1HMAC_CTX\s0\fR and associated resources, making it suitable for new computations as if it was newly created with \fBHMAC_CTX_new()\fR. .PP @@ -208,27 +232,27 @@ The following functions may be used if the message is not completely stored in memory: .PP \&\fBHMAC_Init_ex()\fR initializes or reuses a \fB\s-1HMAC_CTX\s0\fR structure to use the hash -function \fBevp_md\fR and key \fBkey\fR. If both are \s-1NULL,\s0 or if \fBkey\fR is \s-1NULL\s0 -and \fBevp_md\fR is the same as the previous call, then the +function \fIevp_md\fR and key \fIkey\fR. If both are \s-1NULL,\s0 or if \fIkey\fR is \s-1NULL\s0 +and \fIevp_md\fR is the same as the previous call, then the existing key is -reused. \fBctx\fR must have been created with \fBHMAC_CTX_new()\fR before the first use +reused. \fIctx\fR must have been created with \fBHMAC_CTX_new()\fR before the first use of an \fB\s-1HMAC_CTX\s0\fR in this function. .PP -If \fBHMAC_Init_ex()\fR is called with \fBkey\fR \s-1NULL\s0 and \fBevp_md\fR is not the -same as the previous digest used by \fBctx\fR then an error is returned +If \fBHMAC_Init_ex()\fR is called with \fIkey\fR \s-1NULL\s0 and \fIevp_md\fR is not the +same as the previous digest used by \fIctx\fR then an error is returned because reuse of an existing key with a different digest is not supported. .PP \&\fBHMAC_Init()\fR initializes a \fB\s-1HMAC_CTX\s0\fR structure to use the hash -function \fBevp_md\fR and the key \fBkey\fR which is \fBkey_len\fR bytes +function \fIevp_md\fR and the key \fIkey\fR which is \fIkey_len\fR bytes long. .PP \&\fBHMAC_Update()\fR can be called repeatedly with chunks of the message to -be authenticated (\fBlen\fR bytes at \fBdata\fR). +be authenticated (\fIlen\fR bytes at \fIdata\fR). .PP -\&\fBHMAC_Final()\fR places the message authentication code in \fBmd\fR, which +\&\fBHMAC_Final()\fR places the message authentication code in \fImd\fR, which must have space for the hash function output. .PP -\&\fBHMAC_CTX_copy()\fR copies all of the internal state from \fBsctx\fR into \fBdctx\fR. +\&\fBHMAC_CTX_copy()\fR copies all of the internal state from \fIsctx\fR into \fIdctx\fR. .PP \&\fBHMAC_CTX_set_flags()\fR applies the specified flags to the internal EVP_MD_CTXs. These flags have the same meaning as for \fBEVP_MD_CTX_set_flags\fR\|(3). @@ -243,7 +267,7 @@ supplied \s-1HMAC_CTX.\s0 an error occurred. .PP \&\fBHMAC_CTX_new()\fR returns a pointer to a new \fB\s-1HMAC_CTX\s0\fR on success or -\&\fB\s-1NULL\s0\fR if an error occurred. +\&\s-1NULL\s0 if an error occurred. .PP \&\fBHMAC_CTX_reset()\fR, \fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR and \&\fBHMAC_CTX_copy()\fR return 1 for success or 0 if an error occurred. @@ -258,9 +282,11 @@ or zero on error. \&\s-1RFC 2104\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\s-1\fBSHA1\s0\fR\|(3), \fBevp\fR\|(7) +\&\s-1\fBSHA1\s0\fR\|(3), \fBEVP_Q_mac\fR\|(3), \fBevp\fR\|(7) .SH "HISTORY" .IX Header "HISTORY" +All functions except for \s-1\fBHMAC\s0()\fR were deprecated in OpenSSL 3.0. +.PP \&\fBHMAC_CTX_init()\fR was replaced with \fBHMAC_CTX_reset()\fR in OpenSSL 1.1.0. .PP \&\fBHMAC_CTX_cleanup()\fR existed in OpenSSL before version 1.1.0. @@ -271,9 +297,9 @@ or zero on error. OpenSSL before version 1.0.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |