Latest update.

doc/man3/EVP_KDF_CTX.pod

@@ -2,17 +2,21 @@
 
 =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, ...);
@@ -20,29 +24,40 @@ EVP_KDF_derive - EVP KDF routines
  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
@@ -61,15 +76,32 @@ EVP_KDF_ctrl_str() allows an application to send an algorithm specific control
 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
 
@@ -213,14 +245,26 @@ The value string is expected to be a decimal number.
 
 =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.
@@ -233,6 +277,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)>
 
 =head1 HISTORY