From 65ce7e65531942fe9d55c12496b843d3db3bb2d3 Mon Sep 17 00:00:00 2001 From: Pauli Date: Mon, 2 Sep 2019 14:23:50 +1000 Subject: [PATCH] Update KDF documentation (section 3) Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/9662) --- doc/man3/EVP_KDF.pod | 259 ++++++++++++++++++++++++++++++++++++ doc/man3/EVP_KDF_CTX.pod | 274 --------------------------------------- 2 files changed, 259 insertions(+), 274 deletions(-) create mode 100644 doc/man3/EVP_KDF.pod delete mode 100644 doc/man3/EVP_KDF_CTX.pod diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod new file mode 100644 index 0000000000..fc09d5fad8 --- /dev/null +++ b/doc/man3/EVP_KDF.pod @@ -0,0 +1,259 @@ +=pod + +=head1 NAME + +EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_provider, EVP_KDF_up_ref, +EVP_KDF_name, +EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_kdf, +EVP_KDF_reset, EVP_KDF_size, EVP_KDF_derive, EVP_KDF_CTX_dup, +EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_ex, +EVP_KDF_get_params, EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params, +EVP_KDF_gettable_params - EVP KDF routines + +=head1 SYNOPSIS + + #include + + typedef struct evp_kdf_st EVP_KDF; + typedef struct evp_kdf_ctx_st EVP_KDF_CTX; + + EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf); + const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx); + void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx); + EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src); + void EVP_KDF_reset(EVP_KDF_CTX *ctx); + size_t EVP_KDF_size(EVP_KDF_CTX *ctx); + int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen); + const char *EVP_KDF_name(const EVP_KDF *kdf); + int EVP_KDF_up_ref(EVP_KDF *kdf); + void EVP_KDF_free(EVP_KDF *kdf); + EVP_KDF *EVP_KDF_fetch(OPENSSL_CTX *libctx, const char *algorithm, + const char *properties); + void EVP_KDF_do_all_ex(OPENSSL_CTX *libctx, + void (*fn)(EVP_KDF *kdf, void *arg), + void *arg); + int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]); + int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]); + int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]); + const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf); + const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf); + const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf); + const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf); + +=head1 DESCRIPTION + +The EVP KDF routines are a high level interface to Key Derivation Function +algorithms and should be used instead of algorithm-specific functions. + +After creating a B for the required algorithm using +EVP_KDF_CTX_new(), inputs to the algorithm are supplied +using calls to EVP_KDF_CTX_set_params() before +calling EVP_KDF_derive() to derive the key. + +=head2 Types + +B is a type that holds the implementation of a KDF. + +B is a context type that holds the algorithm inputs. + +=head2 Algorithm implementation fetching + +EVP_KDF_fetch() fetches an implementation of a KDF I, given +a library context I and a set of I. +See L for further information. + +The returned value must eventually be freed with +L. + +EVP_KDF_up_ref() increments the reference count of an already fetched +KDF. + +EVP_KDF_free() frees a fetched algorithm. +NULL is a valid parameter, for which this function is a no-op. + +=head2 Context manipulation functions + +EVP_KDF_CTX_new() creates a new context for the KDF implementation I. + +EVP_KDF_CTX_free() frees up the context C. If I is NULL, nothing +is done. + +EVP_KDF_CTX_kdf() returns the B associated with the context +I. + +=head2 Computing functions + +EVP_KDF_reset() resets the context to the default state as if the context +had just been created. + +EVP_KDF_derive() derives C bytes of key material and places it in the +I buffer. If the algorithm produces a fixed amount of output then an +error will occur unless the C parameter is equal to that output size, +as returned by EVP_KDF_size(). + +EVP_KDF_get_params() retrieves details about the implementation +I. +The set of parameters given with I determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. + +EVP_KDF_CTX_get_params() retrieves chosen parameters, given the +context I and its underlying context. +The set of parameters given with I determine exactly what +parameters should be retrieved. +Note that a parameter that is unknown in the underlying context is +simply ignored. + +EVP_KDF_CTX_set_params() passes chosen parameters to the underlying +context, given a context I. +The set of parameters given with I determine exactly what +parameters are passed down. +Note that a parameter that is unknown in the underlying context is +simply ignored. +Also, what happens when a needed parameter isn't passed down is +defined by the implementation. + +EVP_KDF_gettable_params(), EVP_KDF_CTX_gettable_params() and +EVP_KDF_CTX_settable_params() get a constant B array that +decribes the retrievable and settable parameters, i.e. parameters that +can be used with EVP_KDF_get_params(), EVP_KDF_CTX_get_params() +and EVP_KDF_CTX_set_params(), respectively. +See L for the use of B as parameter descriptor. + +=head2 Information functions + +EVP_KDF_size() returns the output size if the algorithm produces a fixed amount +of output and B otherwise. If an error occurs then 0 is returned. +For some algorithms an error may result if input parameters necessary to +calculate a fixed output size have not yet been supplied. + +EVP_KDF_name() returns the name of the given KDF implementation. + +EVP_KDF_provider() returns the provider that holds the implementation +of the given I. + +EVP_KDF_do_all_ex() traverses all KDF implemented by all activated +providers in the given library context I, and for each of the +implementations, calls the given function I with the implementation method +and the given I as argument. + +=head1 PARAMETER NAMES + +The standard parameter names are: + +=over 4 + +=item B ("pass") + +Some KDF implementations require a password. +For those KDF implementations that support it, this parameter sets the password. + +=item B ("salt") + +Some KDF implementations can take a salt. +For those KDF implementations that support it, this parameter sets the salt. + +The default value, if any, is implementation dependent. + +=item B ("iter") + +Some KDF implementations require an iteration count. +For those KDF implementations that support it, this parameter sets the +iteration count. + +The default value, if any, is implementation dependent. + +=item B ("properties") + +Some KDF implementations use other cryptographic algorithms, this parameter +sets what property query will be used to fetch the implementation. + +=item B ("mac") + +Some KDF implementations use a MAC as an underlying computation +algorithm, this parameter sets what the MAC algorithm should be. + +=item B ("digest") + +For MAC implementations that use a message digest as an underlying computation +algorithm, this parameter sets what the digest algorithm should be. + +=item B ("key") + +Some KDF implementations require a key. +For those KDF implementations that support it, this octet string parameter +sets the key. + +=item B ("maclen") + +Used by implementations that use a MAC with a variable output size (KMAC). +For those KDF implementations that support it, this parameter +sets the MAC output size. + +The default value, if any, is implementation dependent. + +=item B ("macmaxmem_byteslen") + +Memory-hard password-based KDF algorithms, such as scrypt, use an amount of +memory that depends on the load factors provided as input. +For those KDF implementations that support it, this uint64_t parameter sets +an upper limit on the amount of memory that may be consumed while performing +a key derivation. +If this memory usage limit is exceeded because the load factors are chosen +too high, the key derivation will fail. + +The default value is implementation dependent. + +=back + +=head1 RETURN VALUES + +EVP_MAC_fetch() returns a pointer to a newly fetched B, or +NULL if allocation failed. + +EVP_KDF_name() returns the name for the given I, if it has been +added to the object database. + +EVP_KDF_provider() returns a pointer to the provider for the KDF, or +NULL on error. + +EVP_MAC_up_ref() returns 1 on success, 0 on error. + +EVP_KDF_CTX_new() returns either the newly allocated +C structure or C if an error occurred. + +EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value. + +EVP_KDF_size() returns the output size. C is returned to indicate +that the algorithm produces a variable amount of output; 0 to indicate failure. + +The remaining functions return 1 for success and 0 or a negative value for +failure. In particular, a return value of -2 indicates the operation is not +supported by the KDF algorithm. + +=head1 SEE ALSO + +L +L +L +L +L +L +L +L + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man3/EVP_KDF_CTX.pod b/doc/man3/EVP_KDF_CTX.pod deleted file mode 100644 index 4642b20713..0000000000 --- a/doc/man3/EVP_KDF_CTX.pod +++ /dev/null @@ -1,274 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF, EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, -EVP_KDF_CTX_kdf, EVP_KDF_reset, -EVP_KDF_size, EVP_KDF_derive, EVP_KDF_name, -EVP_KDF_CTX_dup, -EVP_KDF_CTX_get_params, -EVP_KDF_CTX_set_params, -EVP_KDF_do_all_ex, - EVP_KDF_fetch, - EVP_KDF_free, -EVP_KDF_get_params, -EVP_KDF_CTX_gettable_params, -EVP_KDF_CTX_settable_params, -EVP_KDF_gettable_params, -EVP_KDF_provider, EVP_KDF_up_ref, -EVP_get_kdfbyname, EVP_get_kdfbynid, EVP_get_kdfbyobj - EVP KDF routines - -=head1 SYNOPSIS - - #include - - typedef struct evp_kdf_st EVP_KDF; - typedef struct evp_kdf_ctx_st EVP_KDF_CTX; - - EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf); - const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx); - void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx); - EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src); - void EVP_KDF_reset(EVP_KDF_CTX *ctx); - size_t EVP_KDF_size(EVP_KDF_CTX *ctx); - int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen); - const char *EVP_KDF_name(const EVP_KDF *kdf); - int EVP_KDF_up_ref(EVP_KDF *kdf); - void EVP_KDF_free(EVP_KDF *kdf); - EVP_KDF *EVP_KDF_fetch(OPENSSL_CTX *libctx, const char *algorithm, - const char *properties); - void EVP_KDF_do_all_ex(OPENSSL_CTX *libctx, - void (*fn)(EVP_KDF *kdf, void *arg), - void *arg); - int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]); - int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]); - int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]); - const OSSL_PARAM *EVP_KDF_gettable_params(const EVP_KDF *kdf); - const OSSL_PARAM *EVP_KDF_CTX_gettable_params(const EVP_KDF *kdf); - const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf); - const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf); - const EVP_KDF *EVP_get_kdfbyname(const char *name); - const EVP_KDF *EVP_get_kdfbynid(int nid); - const EVP_KDF *EVP_get_kdfbyobj(const ASN1_OBJECT *o); - -=head1 DESCRIPTION - -The EVP KDF routines are a high level interface to Key Derivation Function -algorithms and should be used instead of algorithm-specific functions. - -After creating a C for the required algorithm using -EVP_KDF_CTX_new(), inputs to the algorithm are supplied -using calls to EVP_KDF_CTX_set_params() before -calling EVP_KDF_derive() to derive the key. - -=head2 Types - -B is a type that holds the implementation of a KDF. - -B is a context type that holds the algorithm inputs. - -=head2 Context manipulation functions - -EVP_KDF_CTX_new() creates a new context for the KDF type C. - -EVP_KDF_CTX_free() frees up the context C. If C is C, nothing -is done. - -EVP_KDF_CTX_kdf() returns the B associated with the context -C. - -=head2 Computing functions - -EVP_KDF_reset() resets the context to the default state as if the context -had just been created. - -EVP_KDF_CTX_set_params() is used to provide inputs to the KDF algorithm prior to -EVP_KDF_derive() being called. The inputs that may be provided will vary -depending on the KDF algorithm or its implementation. -See L below for a description of standard controls. - -EVP_KDF_derive() derives C bytes of key material and places it in the -C buffer. If the algorithm produces a fixed amount of output then an -error will occur unless the C parameter is equal to that output size, -as returned by EVP_KDF_size(). - -=head2 Information functions - -EVP_KDF_size() returns the output size if the algorithm produces a fixed amount -of output and C otherwise. If an error occurs then 0 is returned. -For some algorithms an error may result if input parameters necessary to -calculate a fixed output size have not yet been supplied. - -EVP_KDF_name() returns the name of the given KDF implementation. - -=head2 Object database functions - -EVP_get_kdfbyname() fetches a KDF implementation from the object -database by name. - -EVP_get_kdfbynid() fetches a KDF implementation from the object -database by numeric identity. - -EVP_get_kdfbyobj() fetches a KDF implementation from the object -database by ASN.1 OBJECT (i.e. an encoded OID). - -=head1 CONTROLS - -The standard controls are: - -=over 4 - -=item B - -This control expects two arguments: C, C - -Some KDF implementations require a password. For those KDF implementations -that support it, this control sets the password. - -=over 4 - -=item "pass" - -The value string is used as is. - -=item "hexpass" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects two arguments: C, C - -Some KDF implementations can take a salt. For those KDF implementations that -support it, this control sets the salt. - -The default value, if any, is implementation dependent. - -=over 4 - -=item "salt" - -The value string is used as is. - -=item "hexsalt" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects one argument: C - -Some KDF implementations require an iteration count. For those KDF implementations that support it, this control sets the iteration count. - -The default value, if any, is implementation dependent. - -=item B - -This control expects one argument: C - -Some KDF implementations use a MAC as an underlying computation -algorithm, this control sets what the MAC algorithm should be. - -=item B - -This control expects one argument: C - -For MAC implementations that use a message digest as an underlying computation -algorithm, this control sets what the digest algorithm should be. - -=item B - -This control expects two arguments: C, C - -Some KDF implementations require a key. For those KDF implementations that -support it, this control sets the key. - -=over 4 - -=item "key" - -The value string is used as is. - -=item "hexkey" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects one argument: C - -Used by implementations that use a MAC with a variable output size (KMAC). For -those KDF implementations that support it, this control sets the MAC output size. - -The default value, if any, is implementation dependent. - -=item B - -This control expects one argument: C - -Memory-hard password-based KDF algorithms, such as scrypt, use an amount of -memory that depends on the load factors provided as input. For those KDF -implementations that support it, this control sets an upper limit on the amount -of memory that may be consumed while performing a key derivation. If this -memory usage limit is exceeded because the load factors are chosen too high, -the key derivation will fail. - -The default value is implementation dependent. - -=back - -=head1 RETURN VALUES - -EVP_KDF_CTX_new() returns either the newly allocated -C structure or C if an error occurred. - -EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value. - -EVP_KDF_size() returns the output size. C is returned to indicate -that the algorithm produces a variable amount of output; 0 to indicate failure. - -EVP_KDF_name() returns the name for the given C, if it has been -added to the object database. - -EVP_get_kdfbyname(), EVP_get_kdfbynid() and EVP_get_kdfbyobj() return -the requested KDF implementation, if it exists in the object database, -otherwise B. - -The remaining functions return 1 for success and 0 or a negative value for -failure. In particular, a return value of -2 indicates the operation is not -supported by the KDF algorithm. - -=head1 SEE ALSO - -L -L -L -L -L -L -L -L - -=head1 HISTORY - -This functionality was added to OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut -- 2.25.1