diff options
author | Pauli <paul.dale@oracle.com> | 2019-09-02 14:23:50 +1000 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2019-09-06 19:27:57 +1000 |
commit | 65ce7e65531942fe9d55c12496b843d3db3bb2d3 (patch) | |
tree | 948129cc40aadc65d2fb1109e0a2c16d57ec4c5b /doc | |
parent | b4dca02940ce040305a9ca95896ccb65f43ec29c (diff) |
Update KDF documentation (section 3)
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9662)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_KDF.pod | 259 | ||||
-rw-r--r-- | doc/man3/EVP_KDF_CTX.pod | 274 |
2 files changed, 259 insertions, 274 deletions
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 <openssl/kdf.h> + + 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<EVP_KDF_CTX> 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<EVP_KDF> is a type that holds the implementation of a KDF. + +B<EVP_KDF_CTX> is a context type that holds the algorithm inputs. + +=head2 Algorithm implementation fetching + +EVP_KDF_fetch() fetches an implementation of a KDF I<algorithm>, given +a library context I<libctx> and a set of I<properties>. +See L<provider(7)/Fetching algorithms> for further information. + +The returned value must eventually be freed with +L<EVP_KDF_free(3)>. + +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<kdf>. + +EVP_KDF_CTX_free() frees up the context C<ctx>. If I<ctx> is NULL, nothing +is done. + +EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context +I<ctx>. + +=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<keylen> bytes of key material and places it in the +I<key> buffer. If the algorithm produces a fixed amount of output then an +error will occur unless the C<keylen> parameter is equal to that output size, +as returned by EVP_KDF_size(). + +EVP_KDF_get_params() retrieves details about the implementation +I<kdf>. +The set of parameters given with I<params> 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<ctx> and its underlying context. +The set of parameters given with I<params> 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<ctx>. +The set of parameters given with I<params> 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<OSSL_PARAM> 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<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. + +=head2 Information functions + +EVP_KDF_size() returns the output size if the algorithm produces a fixed amount +of output and B<SIZE_MAX> 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<kdf>. + +EVP_KDF_do_all_ex() traverses all KDF implemented by all activated +providers in the given library context I<libctx>, and for each of the +implementations, calls the given function I<fn> with the implementation method +and the given I<arg> as argument. + +=head1 PARAMETER NAMES + +The standard parameter names are: + +=over 4 + +=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string> + +Some KDF implementations require a password. +For those KDF implementations that support it, this parameter sets the password. + +=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> + +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<OSSL_KDF_PARAM_ITER> ("iter") <unsigned int> + +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<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> + +Some KDF implementations use other cryptographic algorithms, this parameter +sets what property query will be used to fetch the implementation. + +=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string> + +Some KDF implementations use a MAC as an underlying computation +algorithm, this parameter sets what the MAC algorithm should be. + +=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> + +For MAC implementations that use a message digest as an underlying computation +algorithm, this parameter sets what the digest algorithm should be. + +=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> + +Some KDF implementations require a key. +For those KDF implementations that support it, this octet string parameter +sets the key. + +=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <size_t> + +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<OSSL_KDF_PARAM_SCRYPT_MAXMEM> ("macmaxmem_byteslen") <size_t> + +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<EVP_KDF>, or +NULL if allocation failed. + +EVP_KDF_name() returns the name for the given I<kdf>, 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<EVP_KDF_CTX> structure or C<NULL> 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<SIZE_MAX> 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<EVP_KDF-SCRYPT(7)> +L<EVP_KDF-TLS1_PRF(7)> +L<EVP_KDF-PBKDF2(7)> +L<EVP_KDF-HKDF(7)> +L<EVP_KDF-SS(7)> +L<EVP_KDF-SSHKDF(7)> +L<EVP_KDF-X963(7)> +L<EVP_KDF-X942(7)> + +=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<https://www.openssl.org/source/license.html>. + +=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 <openssl/kdf.h> - - 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<EVP_KDF_CTX> 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<EVP_KDF> is a type that holds the implementation of a KDF. - -B<EVP_KDF_CTX> 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<kdf>. - -EVP_KDF_CTX_free() frees up the context C<ctx>. If C<ctx> is C<NULL>, nothing -is done. - -EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context -C<ctx>. - -=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</CONTROLS> below for a description of standard controls. - -EVP_KDF_derive() derives C<keylen> bytes of key material and places it in the -C<key> buffer. If the algorithm produces a fixed amount of output then an -error will occur unless the C<keylen> 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<SIZE_MAX> 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<EVP_KDF_CTRL_SET_PASS> - -This control expects two arguments: C<unsigned char *pass>, C<size_t passlen> - -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<EVP_KDF_CTRL_SET_SALT> - -This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen> - -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<EVP_KDF_CTRL_SET_ITER> - -This control expects one argument: C<int iter> - -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<EVP_KDF_CTRL_SET_MAC> - -This control expects one argument: C<EVP_MAC *mac> - -Some KDF implementations use a MAC as an underlying computation -algorithm, this control sets what the MAC algorithm should be. - -=item B<EVP_KDF_CTRL_SET_MD> - -This control expects one argument: C<EVP_MD *md> - -For MAC implementations that use a message digest as an underlying computation -algorithm, this control sets what the digest algorithm should be. - -=item B<EVP_KDF_CTRL_SET_KEY> - -This control expects two arguments: C<unsigned char *key>, C<size_t keylen> - -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<EVP_KDF_CTRL_SET_MAC_SIZE> - -This control expects one argument: C<size_t size> - -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<EVP_KDF_CTRL_SET_MAXMEM_BYTES> - -This control expects one argument: C<uint64_t maxmem_bytes> - -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<EVP_KDF_CTX> structure or C<NULL> 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<SIZE_MAX> 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<kdf>, 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<NULL>. - -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<EVP_KDF_SCRYPT(7)> -L<EVP_KDF_TLS1_PRF(7)> -L<EVP_KDF_PBKDF2(7)> -L<EVP_KDF_HKDF(7)> -L<EVP_KDF_SS(7)> -L<EVP_KDF_SSHKDF(7)> -L<EVP_KDF_X963(7)> -L<EVP_KDF_X942(7)> - -=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<https://www.openssl.org/source/license.html>. - -=cut |