=head1 NAME
-EVP_KDF_CTX, EVP_KDF_CTX_new_id, EVP_KDF_CTX_free, EVP_KDF_reset,
-EVP_KDF_ctrl, EVP_KDF_vctrl, EVP_KDF_ctrl_str, EVP_KDF_size,
-EVP_KDF_derive - EVP KDF routines
+EVP_KDF, EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_new_id, EVP_KDF_CTX_free,
+EVP_KDF_CTX_kdf, EVP_KDF_reset, EVP_KDF_ctrl, EVP_KDF_vctrl, EVP_KDF_ctrl_str,
+EVP_KDF_size, EVP_KDF_derive, EVP_KDF_nid, EVP_KDF_name,
+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_id(int id);
+ EVP_KDF_CTX *EVP_KDF_CTX_new(const EVP_KDF *kdf);
+ EVP_KDF_CTX *EVP_KDF_CTX_new_id(int nid);
+ const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
void EVP_KDF_reset(EVP_KDF_CTX *ctx);
int EVP_KDF_ctrl(EVP_KDF_CTX *ctx, int cmd, ...);
int EVP_KDF_ctrl_str(EVP_KDF_CTX *ctx, const char *type, const char *value);
size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
+ int EVP_KDF_nid(const EVP_KDF *kdf);
+ const char *EVP_KDF_name(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_id(), inputs to the algorithm are supplied using calls to
-EVP_KDF_ctrl(), EVP_KDF_vctrl() or EVP_KDF_ctrl_str() before calling
-EVP_KDF_derive() to derive the key.
+After creating a C<EVP_KDF_CTX> for the required algorithm using either
+EVP_KDF_CTX_new() or EVP_KDF_CTX_new_id(), inputs to the algorithm are supplied
+using calls to EVP_KDF_ctrl(), EVP_KDF_vctrl() or EVP_KDF_ctrl_str() 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_id() creates a KDF context for the algorithm identified by the
-specified NID.
+EVP_KDF_CTX_new() creates a new context for the KDF type C<kdf>.
+
+EVP_KDF_CTX_new_id() creates a new context for the numerical KDF identity C<nid>.
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
operation to a context C<ctx> in string form. This is intended to be used for
options specified on the command line or in text files.
+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_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().
+EVP_KDF_nid() returns the numeric identity of the given KDF implementation.
+
+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
=head1 RETURN VALUES
-EVP_KDF_CTX_new_id() returns either the newly allocated C<EVP_KDF_CTX>
-structure or C<NULL> if an error occurred.
+EVP_KDF_CTX_new() and EVP_KDF_CTX_new_id() return 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_nid() returns the numeric identity for the given C<kdf>.
+
+EVP_KDF_name() returns the name for the given C<kdf>, if it has been
+added to the object database.
+
+EVP_add_kdf() returns 1 if the given C<kdf> was successfully added to
+the object database, otherwise 0.
+
+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.
projects / openssl.git / blobdiff