--- /dev/null
+=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
+++ /dev/null
-=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
projects / thirdparty / openssl.git / commitdiff
