Latest update

doc/internal/man3/evp_generic_fetch.pod

@@ -0,0 +1,232 @@
+=pod
+
+=head1 NAME
+
+evp_generic_fetch - generic algorithm fetcher and method creator for EVP
+
+=head1 SYNOPSIS
+
+ /* Only for EVP source */
+ #include "evp_locl.h"
+
+ void *evp_generic_fetch(OPENSSL_CTX *libctx, int operation_id,
+                         const char *algorithm, const char *properties,
+                         void *(*new_method)(int nid, const OSSL_DISPATCH *fns,
+                                             OSSL_PROVIDER *prov),
+                         int (*upref_method)(void *),
+                         void (*free_method)(void *));
+
+=head1 DESCRIPTION
+
+evp_generic_fetch() calls ossl_method_construct() with the given
+C<libctx>, C<operation_id>, C<algorithm>, and C<properties> and uses
+it to create an EVP method with the help of the functions
+C<new_method>, C<upref_method>, and C<free_method>.
+
+The three functions are supposed to:
+
+=over 4
+
+=item new_method()
+
+creates an internal method from function pointers found in the
+dispatch table C<fns>.
+
+=item upref_method()
+
+increments the reference counter for the given method, if there is
+one.
+
+=item free_method()
+
+frees the given method.
+
+=back
+
+=head1 RETURN VALUES
+
+evp_generic_fetch() returns a method on success, or B<NULL> on error.
+
+=head1 EXAMPLES
+
+This is a short example of the fictitious EVP API and operation called
+C<EVP_FOO>.
+
+To begin with, let's assume something like this in
+C<include/openssl/core_numbers.h>:
+
+    #define OSSL_OP_FOO                         100
+
+    #define OSSL_OP_FOO_NEWCTX_FUNC            2001
+    #define OSSL_OP_FOO_INIT                   2002
+    #define OSSL_OP_FOO_OPERATE                2003
+    #define OSSL_OP_FOO_CLEANCTX_FUNC          2004
+    #define OSSL_OP_FOO_FREECTX_FUNC           2005
+    OSSL_CORE_MAKE_FUNC(void *,OP_foo_newctx,(void))
+    OSSL_CORE_MAKE_FUNC(int,OP_foo_init,(void *vctx))
+    OSSL_CORE_MAKE_FUNC(int,OP_foo_operate,(void *vctx,
+                                            unsigned char *out, size_t *out_l,
+                                            unsigned char *in, size_t in_l))
+    OSSL_CORE_MAKE_FUNC(void,OP_foo_cleanctx,(void *vctx))
+    OSSL_CORE_MAKE_FUNC(void,OP_foo_freectx,(void *vctx))
+
+And here's the implementation of the FOO method fetcher:
+
+    /* typedef struct evp_foo_st EVP_FOO */
+    struct evp_foo_st {
+        OSSL_PROVIDER *prov;
+        int nid;
+	CRYPTO_REF_COUNT refcnt;
+        OSSL_OP_foo_newctx_fn *newctx;
+        OSSL_OP_foo_init_fn *init;
+        OSSL_OP_foo_operate_fn *operate;
+        OSSL_OP_foo_cleanctx_fn *cleanctx;
+        OSSL_OP_foo_freectx_fn *freectx;
+    };
+
+    /*
+     * In this example, we have a public method creator and destructor.
+     * It's not absolutely necessary, but is in the spirit of OpenSSL.
+     */
+    EVP_FOO *EVP_FOO_meth_from_dispatch(int foo_type, const OSSL_DISPATCH *fns,
+                                        OSSL_PROVIDER *prov)
+    {
+        EVP_FOO *foo = NULL;
+
+        if ((foo = OPENSSL_zalloc(sizeof(*foo))) == NULL)
+            return NULL;
+
+        for (; fns->function_id != 0; fns++) {
+            switch (fns->function_id) {
+            case OSSL_OP_FOO_NEWCTX_FUNC:
+                foo->newctx = OSSL_get_OP_foo_newctx(fns);
+                break;
+            case OSSL_OP_FOO_INIT:
+                foo->init = OSSL_get_OP_foo_init(fns);
+                break;
+            case OSSL_OP_FOO_OPERATE:
+                foo->operate = OSSL_get_OP_foo_operate(fns);
+                break;
+            case OSSL_OP_FOO_CLEANCTX_FUNC:
+                foo->cleanctx = OSSL_get_OP_foo_cleanctx(fns);
+                break;
+            case OSSL_OP_FOO_FREECTX_FUNC:
+                foo->freectx = OSSL_get_OP_foo_freectx(fns);
+                break;
+            }
+        }
+        foo->nid = foo_type;
+        foo->prov = prov;
+        if (prov)
+            ossl_provider_upref(prov);
+
+        return foo;
+    }
+
+    EVP_FOO_meth_free(EVP_FOO *foo)
+    {
+        if (foo != NULL) {
+            OSSL_PROVIDER *prov = foo->prov;
+
+            OPENSSL_free(foo);
+            ossl_provider_free(prov);
+        }
+    }
+
+    static void *foo_from_dispatch(int nid, const OSSL_DISPATCH *fns,
+                                   OSSL_PROVIDER *prov)
+    {
+        return EVP_FOO_meth_from_dispatch(nid, fns, prov);
+    }
+
+    static int foo_upref(void *vfoo)
+    {
+        EVP_FOO *foo = vfoo;
+        int ref = 0;
+
+        CRYPTO_UP_REF(&foo->refcnt, &ref, foo_lock);
+        return 1;
+    }
+
+    static void foo_free(void *vfoo)
+    {
+        EVP_FOO_meth_free(vfoo);
+    }
+
+    EVP_FOO *EVP_FOO_fetch(OPENSSL_CTX *ctx,
+                           const char *algorithm,
+                           const char *properties)
+    {
+        return evp_generic_fetch(ctx, OSSL_OP_FOO, algorithm, properties,
+                                 foo_from_dispatch, foo_upref, foo_free);
+    }
+
+And finally, the library functions:
+
+    /* typedef struct evp_foo_st EVP_FOO_CTX */
+    struct evp_foo_ctx_st {
+        const EVP_FOO *foo;
+        void *provctx;		/* corresponding provider context */
+    };
+
+    int EVP_FOO_CTX_reset(EVP_FOO_CTX *c)
+    {
+        if (c == NULL)
+            return 1;
+        if (c->foo != NULL && c->foo->cleanctx != NULL)
+            c->foo->cleanctx(c->provctx);
+        return 1;
+    }
+
+    EVP_FOO_CTX *EVP_FOO_CTX_new(void)
+    {
+        return OPENSSL_zalloc(sizeof(EVP_FOO_CTX));
+    }
+
+    void EVP_FOO_CTX_free(EVP_FOO_CTX *c)
+    {
+        EVP_FOO_CTX_reset(c);
+        c->foo->freectx(c->provctx);
+        OPENSSL_free(c);
+    }
+
+    int EVP_FooInit(EVP_FOO_CTX *c, const EVP_FOO *foo)
+    {
+        int ok = 1;
+
+        c->foo = foo;
+        if (c->provctx == NULL)
+            c->provctx = c->foo->newctx();
+
+        ok = c->foo->init(c->provctx);
+
+        return ok;
+    }
+
+    int EVP_FooOperate(EVP_FOO_CTX *c, unsigned char *out, size_t *outl,
+                       const unsigned char *in, size_t inl)
+    {
+        int ok = 1;
+
+        ok = c->foo->update(c->provctx, out, inl, &outl, in, inl);
+        return ok;
+    }
+
+=head1 SEE ALSO
+
+L<ossl_method_construct>
+
+=head1 HISTORY
+
+The functions described here were all added in 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

doc/internal/man3/ossl_method_construct.pod

@@ -49,6 +49,11 @@ functions given by the sub-system specific method creator through
 C<mcm> and the data in C<mcm_data> (which is passed by
 ossl_method_construct()).
 
+This function assumes that the sub-system method creator implements
+reference counting and acts accordingly (i.e. it will call the
+sub-system destruct() method to decrement the reference count when
+appropriate).
+
 =head2 Structures
 
 A central part of constructing a sub-system specific method is to give
@@ -82,6 +87,8 @@ The method to be looked up should be identified with data from C<data>
 (which is the C<mcm_data> that was passed to ossl_construct_method())
 and the provided property query C<propquery>.
 
+This function is expected to increment the method's reference count.
+
 =item put()
 
 Places the C<method> created by the construct() function (see below)
@@ -96,6 +103,8 @@ The method should be associated with the given property definition
 C<propdef> and any identification data given through C<data> (which is
 the C<mcm_data> that was passed to ossl_construct_method()).
 
+This function is expected to increment the C<method>'s reference count.
+
 =item construct()
 
 Constructs a sub-system method given a dispatch table C<fns>.
@@ -106,9 +115,12 @@ is recommended.
 If such a reference is kept, the I<provider object> reference counter
 must be incremented, using ossl_provider_upref().
 
+This function is expected to set the method's reference count to 1.
+
 =item desctruct()
 
-Destruct the given C<method>.
+Decrement the C<method>'s reference count, and destruct it when
+the reference count reaches zero.
 
 =back
 

doc/internal/man3/ossl_provider_new.pod

@@ -4,7 +4,8 @@
 
 ossl_provider_find, ossl_provider_new, ossl_provider_upref,
 ossl_provider_free, ossl_provider_add_module_location,
-ossl_provider_activate, ossl_provider_forall_loaded,
+ossl_provider_set_fallback, ossl_provider_activate,
+ossl_provider_forall_loaded,
 ossl_provider_name, ossl_provider_dso,
 ossl_provider_module_name, ossl_provider_module_path,
 ossl_provider_teardown, ossl_provider_get_param_types,
@@ -23,6 +24,7 @@ ossl_provider_get_params, ossl_provider_query_operation
 
  /* Setters */
  int ossl_provider_add_module_location(OSSL_PROVIDER *prov, const char *loc);
+ int ossl_provider_set_fallback(OSSL_PROVIDER *prov);
 
  /* Load and initialize the Provider */
  int ossl_provider_activate(OSSL_PROVIDER *prov);
@@ -71,7 +73,7 @@ times as ossl_provider_activate() has.
 
 ossl_provider_find() finds an existing I<provider object> in the
 I<provider object> store by C<name>.
-The I<provider object> it finds gets it's reference count
+The I<provider object> it finds gets its reference count
 incremented.
 
 ossl_provider_new() creates a new I<provider object> and stores it in
@@ -84,14 +86,20 @@ To indicate a built-in provider, the C<init_function> argument must
 point at the provider initialization function for that provider.
 
 ossl_provider_free() decrements a I<provider object>'s reference
-counter; if it drops to one, the I<provider object> will be
-inactivated (it's teardown function is called) but kept in the store;
-if it drops down to zero, the associated module will be unloaded if
-one was loaded, and the I<provider object> will be freed.
+counter; if it drops below 2, the I<provider object> is assumed to
+have fallen out of use and will be inactivated (its teardown function
+is called); if it drops down to zero, the I<provider object> is
+assumed to have been taken out of the store, and the associated module
+will be unloaded if one was loaded, and the I<provider object> will be
+freed.
 
 ossl_provider_add_module_location() adds a location to look for a
 provider module.
 
+ossl_provider_set_fallback() marks an available provider as fallback.
+Note that after this call, the I<provider object> pointer that was
+used can simply be dropped, but not freed.
+
 ossl_provider_activate() "activates" the provider for the given
 I<provider object>.
 What "activates" means depends on what type of I<provider object> it
@@ -115,6 +123,8 @@ be located in that module, and called.
 
 ossl_provider_forall_loaded() iterates over all the currently
 "activated" providers, and calls C<cb> for each of them.
+If no providers have been "activated" yet, it tries to activate all
+available fallback providers and tries another iteration.
 
 ossl_provider_name() returns the name that was given with
 ossl_provider_new().
@@ -178,8 +188,8 @@ it has been incremented.
 
 ossl_provider_free() doesn't return any value.
 
-ossl_provider_add_module_location() and ossl_provider_activate()
-return 1 on success, or 0 on error.
+ossl_provider_add_module_location(), ossl_provider_set_fallback() and
+ossl_provider_activate() return 1 on success, or 0 on error.
 
 ossl_provider_name(), ossl_provider_dso(),
 ossl_provider_module_name(), and ossl_provider_module_path() return a

doc/man1/ca.pod

@@ -51,6 +51,7 @@ B<openssl> B<ca>
 [B<-engine id>]
 [B<-subj arg>]
 [B<-utf8>]
+[B<-sigopt nm:v>]
 [B<-create_serial>]
 [B<-rand_serial>]
 [B<-multivalue-rdn>]
@@ -134,6 +135,11 @@ The private key to sign requests with.
 The format of the data in the private key file.
 The default is PEM.
 
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
 =item B<-key password>
 
 The password used to encrypt the private key. Since on some
@@ -753,7 +759,7 @@ L<config(5)>, L<x509v3_config(5)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-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

doc/man1/dgst.pod

@@ -22,6 +22,7 @@ B<openssl dgst>
 [B<-verify filename>]
 [B<-prverify filename>]
 [B<-signature filename>]
+[B<-sigopt nm:v>]
 [B<-hmac key>]
 [B<-fips-fingerprint>]
 [B<-rand file...>]
@@ -78,7 +79,8 @@ Output the digest or signature in binary form.
 
 =item B<-r>
 
-Output the digest in the "coreutils" format used by programs like B<sha1sum>.
+Output the digest in the "coreutils" format, including newlines.
+Used by programs like B<sha1sum>.
 
 =item B<-out filename>
 
@@ -235,7 +237,7 @@ The FIPS-related options were removed in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-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

doc/man1/pkeyutl.pod

@@ -296,20 +296,19 @@ value less than the minimum restriction.
 =head1 DSA ALGORITHM
 
 The DSA algorithm supports signing and verification operations only. Currently
-there are no additional options other than B<digest>. Only the SHA1
-digest can be used and this digest is assumed by default.
+there are no additional B<-pkeyopt> options other than B<digest>. The SHA1
+digest is assumed by default.
 
 =head1 DH ALGORITHM
 
 The DH algorithm only supports the derivation operation and no additional
-options.
+B<-pkeyopt> options.
 
 =head1 EC ALGORITHM
 
 The EC algorithm supports sign, verify and derive operations. The sign and
-verify operations use ECDSA and derive uses ECDH. Currently there are no
-additional options other than B<digest>. Only the SHA1 digest can be used and
-this digest is assumed by default.
+verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for
+the B<-pkeyopt> B<digest> option.
 
 =head1 X25519 and X448 ALGORITHMS
 

doc/man1/req.pod

@@ -46,6 +46,7 @@ B<openssl> B<req>
 [B<-reqopt>]
 [B<-subject>]
 [B<-subj arg>]
+[B<-sigopt nm:v>]
 [B<-batch>]
 [B<-verbose>]
 [B<-engine id>]
@@ -82,6 +83,11 @@ This specifies the input filename to read a request from or standard input
 if this option is not specified. A request is only read if the creation
 options (B<-new> and B<-newkey>) are not specified.
 
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
 =item B<-passin arg>
 
 The input file password source. For more information about the format of B<arg>
@@ -689,7 +695,7 @@ L<x509v3_config(5)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-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

doc/man1/s_client.pod

@@ -559,7 +559,7 @@ further information).
 
 =item B<-bugs>
 
-There are several known bug in SSL and TLS implementations. Adding this
+There are several known bugs in SSL and TLS implementations. Adding this
 option enables various workarounds.
 
 =item B<-comp>
@@ -763,10 +763,6 @@ End the current SSL connection and exit.
 
 Renegotiate the SSL session (TLSv1.2 and below only).
 
-=item B<B>
-
-Send a heartbeat message to the server (DTLS only)
-
 =item B<k>
 
 Send a key update message to the server (TLSv1.3 only)

doc/man1/s_server.pod

@@ -542,7 +542,7 @@ OpenSSL was built.
 
 =item B<-bugs>
 
-There are several known bug in SSL and TLS implementations. Adding this
+There are several known bugs in SSL and TLS implementations. Adding this
 option enables various workarounds.
 
 =item B<-no_comp>
@@ -783,10 +783,6 @@ cause the client to disconnect due to a protocol violation.
 
 Print out some session cache status information.
 
-=item B<B>
-
-Send a heartbeat message to the client (DTLS only)
-
 =item B<k>
 
 Send a key update message to the client (TLSv1.3 only)

doc/man1/s_time.pod

@@ -127,7 +127,7 @@ OpenSSL was built.
 
 =item B<-bugs>
 
-There are several known bug in SSL and TLS implementations. Adding this
+There are several known bugs in SSL and TLS implementations. Adding this
 option enables various workarounds.
 
 =item B<-cipher cipherlist>

doc/man1/ts.pod

@@ -262,7 +262,7 @@ specified, the argument is given to the engine as a key identifier.
 =item B<-I<digest>>
 
 Signing digest to use. Overrides the B<signer_digest> config file
-option. (Optional)
+option. (Mandatory unless specified in the config file)
 
 =item B<-chain> certs_file.pem
 
@@ -460,7 +460,8 @@ command line option. (Optional)
 =item B<signer_digest>
 
 Signing digest to use. The same as the
-B<-I<digest>> command line option. (Optional)
+B<-I<digest>> command line option. (Mandatory unless specified on the command
+line)
 
 =item B<default_policy>
 

doc/man1/verify.pod

@@ -50,6 +50,8 @@ B<openssl> B<verify>
 [B<-verify_name name>]
 [B<-x509_strict>]
 [B<-show_chain>]
+[B<-sm2-id string>]
+[B<-sm2-hex-id hex-string>]
 [B<->]
 [certificates]
 
@@ -316,6 +318,16 @@ Display information about the certificate chain that has been built (if
 successful). Certificates in the chain that came from the untrusted list will be
 flagged as "untrusted".
 
+=item B<-sm2-id>
+
+Specify the ID string to use when verifying an SM2 certificate. The ID string is
+required by the SM2 signature algorithm for signing and verification.
+
+=item B<-sm2-hex-id>
+
+Specify a binary ID string to use when signing or verifying using an SM2
+certificate. The argument for this option is string of hexadecimal digits.
+
 =item B<->
 
 Indicates the last option. All arguments following this are assumed to be
@@ -767,9 +779,11 @@ The B<-show_chain> option was added in OpenSSL 1.1.0.
 The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
 is silently ignored.
 
+The B<-sm2-id> and B<-sm2-hex-id> options were added in OpenSSL 3.0.0.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-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

doc/man1/x509.pod

@@ -52,7 +52,9 @@ B<openssl> B<x509>
 [B<-CAkey filename>]
 [B<-CAcreateserial>]
 [B<-CAserial filename>]
+[B<-new>]
 [B<-force_pubkey filename>]
+[B<-subj arg>]
 [B<-text>]
 [B<-ext extensions>]
 [B<-certopt option>]
@@ -61,6 +63,7 @@ B<openssl> B<x509>
 [B<-clrext>]
 [B<-extfile filename>]
 [B<-extensions section>]
+[B<-sigopt nm:v>]
 [B<-rand file...>]
 [B<-writerand file>]
 [B<-engine id>]
@@ -362,6 +365,11 @@ and the end date to a value determined by the B<-days> option.
 It retains any certificate extensions unless the B<-clrext> option is supplied;
 this includes, for example, any existing key identifier extensions.
 
+=item B<-sigopt nm:v>
+
+Pass options to the signature algorithm during sign or verify operations.
+Names and values of these options are algorithm-specific.
+
 =item B<-passin arg>
 
 The key password source. For more information about the format of B<arg>
@@ -454,15 +462,39 @@ specified then the extensions should either be contained in the unnamed
 L<x509v3_config(5)> manual page for details of the
 extension section format.
 
+=item B<-new>
+
+Generate a certificate from scratch, not using an input certificate
+or certificate request. So the B<-in> option must not be used in this case.
+Instead, the B<-subj> and <-force_pubkey> options need to be given.
+
 =item B<-force_pubkey filename>
 
 When a certificate is created set its public key to the key in B<filename>
 instead of the key contained in the input or given with the B<-signkey> option.
+
 This option is useful for creating self-issued certificates that are not
 self-signed, for instance when the key cannot be used for signing, such as DH.
+It can also be used in conjunction with b<-new> and B<-subj> to directly
+generate a certificate containing any desired public key.
 
 The format of the key file can be specified using the B<-keyform> option.
 
+=item B<-subj arg>
+
+When a certificate is created set its subject name to the given value.
+The arg must be formatted as I</type0=value0/type1=value1/type2=...>.
+Keyword characters may be escaped by \ (backslash), and whitespace is retained.
+Empty values are permitted, but the corresponding type will not be included
+in the certificate. Giving a single I</> will lead to an empty sequence of RDNs
+(a NULL subject DN).
+
+Unless the B<-CA> option is given the issuer is set to the same value.
+
+This option can be used in conjunction with the B<-force_pubkey> option
+to create a certificate even without providing an input certificate
+or certificate request.
+
 =back
 
 =head2 Name Options
@@ -922,7 +954,7 @@ the old form must have their links rebuilt using B<c_rehash> or similar.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-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

doc/man3/BN_CTX_start.pod

@@ -27,6 +27,7 @@ calls must be made before calling any other functions that use the
 B<ctx> as an argument.
 
 Finally, BN_CTX_end() must be called before returning from the function.
+If B<ctx> is NULL, nothing is done.
 When BN_CTX_end() is called, the B<BIGNUM> pointers obtained from
 BN_CTX_get() become invalid.
 

doc/man3/BN_new.pod

@@ -27,6 +27,7 @@ OPENSSL_secure_malloc(3) is used to store the value.
 BN_clear() is used to destroy sensitive data such as keys when they
 are no longer needed. It erases the memory used by B<a> and sets it
 to the value 0.
+If B<a> is NULL, nothing is done.
 
 BN_free() frees the components of the B<BIGNUM>, and if it was created
 by BN_new(), also the structure itself. BN_clear_free() additionally

doc/man3/EVP_KDF_CTX.pod

@@ -135,6 +135,17 @@ EVP_KDF_ctrl_str() type string: "iter"
 
 The value string is expected to be a decimal number.
 
+=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.
+
+EVP_KDF_ctrl_str() type string: "mac"
+
+The value string is expected to be the name of a MAC.
+
 =item B<EVP_KDF_CTRL_SET_MD>
 
 This control expects one argument: C<EVP_MD *md>
@@ -168,6 +179,19 @@ 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.
+
+EVP_KDF_ctrl_str() type string: "outlen"
+
+The value string is expected to be a decimal number.
+
 =item B<EVP_KDF_CTRL_SET_MAXMEM_BYTES>
 
 This control expects one argument: C<uint64_t maxmem_bytes>
@@ -204,10 +228,18 @@ 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)>
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
 
 =head1 COPYRIGHT
 
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+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

doc/man3/EVP_MAC.pod

@@ -202,6 +202,9 @@ For MAC implementations that use an underlying computation algorithm,
 these controls set what the algorithm should be, and the engine that
 implements the algorithm if needed.
 
+Note that not all algorithms may support all digests. HMAC does not support
+variable output length digests such as SHAKE128 or SHAKE256.
+
 B<EVP_MAC_CTRL_SET_ENGINE> takes one argument: C<ENGINE *>
 
 B<EVP_MAC_CTRL_SET_MD> takes one argument: C<EVP_MD *>

doc/man3/EVP_MD_fetch.pod

@@ -0,0 +1,162 @@
+=pod
+
+=head1 NAME
+
+EVP_MD_fetch
+- Functions to explicitly fetch algorithm implementations
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_MD *EVP_MD_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+                      const char *properties);
+
+=head1 DESCRIPTION
+
+The B<EVP_MD> object is used for representing a digest method implementation.
+
+Having obtained a digest implementation as an B<EVP_MD> type it can be used to
+calculate the digest of input data using functions such as
+L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
+
+Digest implementations may be obtained in one of three ways, i.e. implicit
+lookup, explicit lookup or user defined.
+
+=over 4
+
+=item Implicit Lookup
+
+With implicit lookup an application can use functions such as L<EVP_sha256(3)>,
+L<EVP_sha512(3)> or L<EVP_blake2b512(3)> to obtain an B<EVP_MD> object. When
+used in a function like L<EVP_DigestInit_ex(3)> the actual implementation to
+be used will be fetched implicitly using default search criteria. Typically,
+(unless the default search criteria have been changed and/or different providers
+have been loaded), this will return an implementation of the appropriate
+algorithm from the default provider.
+
+=item Explicit Lookup
+
+With explicit lookup an application uses the EVP_MD_fetch() function to obtain
+an algorithm implementation. An implementation with the given name and
+satisfying the search criteria specified in the B<properties> parameter will be
+looked for within the available providers and returned. See L<OSSL_PROVIDER(3)>
+for information about providers.
+
+=item User defined
+
+Using the user defined approach an application constructs its own EVP_MD object.
+See L<EVP_MD_meth_new(3)> for details.
+
+=back
+
+The EVP_MD_fetch() function will look for an algorithm within the providers that
+have been loaded into the B<OPENSSL_CTX> given in the B<ctx> parameter. This
+parameter may be NULL in which case the default B<OPENSSL_CTX> will be used. See
+L<OPENSSL_CTX_new(3)> and L<OSSL_PROVIDER_load(3)> for further details.
+
+The B<algorithm> parameter gives the name of the algorithm to be looked up.
+Different algorithms can be made available by loading different providers. The
+built-in default provider algorithm implementation names are: SHA1, SHA224,
+SHA256, SHA384, SHA512, SHA512-224, SHA512-256,SHA3-224, SHA3-256, SHA3-384,
+SHA3-512, SHAKE128, SHAKE256, SM3, BLAKE2b512, BLAKE2s256 and MD5-SHA1.
+
+Additional algorithm implementations may be obtained by loading the "legacy"
+provider. The names of these algorithms are: RIPEMD160, MD2, MD4, MD5, MDC2 and
+whirlpool.
+
+The B<properties> parameter specifies the search criteria that will be used to
+look for an algorithm implementation. Properties are given as a comma delimited
+string of name value pairs. In order for an implementation to match, all the
+properties in the query string must match those defined for that implementation.
+Any properties defined by an implementation but not given in the query string
+are ignored. All algorithm implementations in the default provider have the
+property "default=yes". All algorithm implementations in the legacy provider have
+the property "legacy=yes". All algorithm implementations in the FIPS provider
+have the property "fips=yes". In the event that more than one implementation
+of the given algorithm name matches the specified properties then an unspecified
+one of those implementations may be returned. The B<properties> parameter may be
+NULL in which case any implementation from the available providers with the
+given algorithm name will be returned.
+
+The return value from a call to EVP_MD_fetch() must be freed by the caller using
+L<EVP_MD_meth_free(3)>. Note that EVP_MD objects are reference counted. See
+L<EVP_MD_upref(3)>.
+
+=head1 RETURN VALUES
+
+EVP_MD_fetch() returns a pointer to the algorithm implementation represented by
+an EVP_MD object, or NULL on error.
+
+=head1 EXAMPLES
+
+Fetch any available implementation of SHA256 in the default context:
+
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
+
+Fetch an implementation of SHA256 from the default provider in the default
+context:
+
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
+ ...
+ EVP_MD_meth_free(md);
+
+Fetch an implementation of SHA256 that is not from the default provider in the
+default context:
+
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
+ ...
+ EVP_MD_meth_free(md);
+
+Fetch an implementation of SHA256 from the default provider in the specified
+context:
+
+ EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
+ ...
+ EVP_MD_meth_free(md);
+
+Load the legacy provider into the default context and then fetch an
+implementation of whirlpool from it:
+
+ /* This only needs to be done once - usually at application start up */
+ OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
+
+ EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
+ ...
+ EVP_MD_meth_free(md);
+
+Note that in the above example the property string "legacy=yes" is optional
+since, assuming no other providers have been loaded, the only implmentation of
+the "whirlpool" algorithm is in the "legacy" provider. Also note that the
+default provider should be explicitly loaded if it is required in addition to
+other providers:
+
+ /* This only needs to be done once - usually at application start up */
+ OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
+ OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
+
+ EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
+ EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
+ ...
+ EVP_MD_meth_free(md_whirlpool);
+ EVP_MD_meth_free(md_sha256);
+
+=head1 SEE ALSO
+
+L<EVP_DigestInit(3)>, L<EVP_MD_meth_new(3)>, L<EVP_MD_meth_free(3)>,
+L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(3)>
+
+=head1 HISTORY
+
+The functions described here were added in 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

doc/man3/EVP_MD_meth_new.pod

@@ -11,7 +11,7 @@ EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize,
 EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize,
 EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update,
 EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup,
-EVP_MD_meth_get_ctrl
+EVP_MD_meth_get_ctrl, EVP_MD_upref
 - Routines to build up EVP_MD methods
 
 =head1 SYNOPSIS
@@ -54,17 +54,21 @@ EVP_MD_meth_get_ctrl
  int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd,
                                                int p1, void *p2);
 
+ int EVP_MD_upref(EVP_MD *md);
+
 =head1 DESCRIPTION
 
 The B<EVP_MD> type is a structure for digest method implementation.
 It can also have associated public/private key signing and verifying
 routines.
 
-EVP_MD_meth_new() creates a new B<EVP_MD> structure.
+EVP_MD_meth_new() creates a new B<EVP_MD> structure. Note that B<EVP_MD>
+structures are reference counted.
 
 EVP_MD_meth_dup() creates a copy of B<md>.
 
-EVP_MD_meth_free() destroys a B<EVP_MD> structure.
+EVP_MD_meth_free() decrements the reference count for the B<EVP_MD> structure.
+If the reference count drops to 0 then the structure is freed.
 
 EVP_MD_meth_set_input_blocksize() sets the internal input block size
 for the method B<md> to B<blocksize> bytes.
@@ -158,6 +162,8 @@ EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used
 to retrieve the method data given with the EVP_MD_meth_set_*()
 functions above.
 
+EVP_MD_upref() increments the reference count for an EVP_MD structure.
+
 =head1 RETURN VALUES
 
 EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly
@@ -169,6 +175,8 @@ indicated sizes or flags.
 All other EVP_CIPHER_meth_get_*() functions return pointers to their
 respective B<md> function.
 
+EVP_MD_upref() returns 1 for success or 0 otherwise.
+
 =head1 SEE ALSO
 
 L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
@@ -176,7 +184,8 @@ L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)>
 =head1 HISTORY
 
 The B<EVP_MD> structure was openly available in OpenSSL before version
-1.1.  The functions described here were added in OpenSSL 1.1.
+1.1.  EVP_MD_upref() was added in OpenSSL 3.0. All other functions described
+here were added in OpenSSL 1.1.
 
 =head1 COPYRIGHT
 

doc/man3/EVP_PKEY_set1_RSA.pod

@@ -9,7 +9,7 @@ EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
 EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
 EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
 EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id, EVP_PKEY_set_alias_type,
-EVP_PKEY_set1_engine - EVP_PKEY assignment functions
+EVP_PKEY_set1_engine, EVP_PKEY_get0_engine - EVP_PKEY assignment functions
 
 =head1 SYNOPSIS
 
@@ -45,6 +45,7 @@ EVP_PKEY_set1_engine - EVP_PKEY assignment functions
  int EVP_PKEY_type(int type);
  int EVP_PKEY_set_alias_type(EVP_PKEY *pkey, int type);
 
+ ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
  int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);
 
 =head1 DESCRIPTION
@@ -81,6 +82,8 @@ often seen in practice.
 EVP_PKEY_type() returns the underlying type of the NID B<type>. For example
 EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>.
 
+EVP_PKEY_get0_engine() returns a reference to the ENGINE handling B<pkey>.
+
 EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It
 must be called after the key algorithm and components are set up.
 If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an

doc/man3/HMAC.pod

@@ -63,7 +63,9 @@ If B<md> is NULL, the digest is placed in a static array.  The size of
 the output is placed in B<md_len>, unless it is B<NULL>. Note: passing a NULL
 value for B<md>  to use the static array is not thread safe.
 
-B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
+B<evp_md> is a message digest such as EVP_sha1(), EVP_ripemd160() etc. HMAC does
+not support variable output length digests such as EVP_shake128() and
+EVP_shake256().
 
 HMAC_CTX_new() creates a new HMAC_CTX in heap memory.
 

doc/man3/OCSP_cert_to_id.pod

@@ -19,8 +19,8 @@ OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions
 
  void OCSP_CERTID_free(OCSP_CERTID *id);
 
- int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
- int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b);
+ int OCSP_id_issuer_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b);
+ int OCSP_id_cmp(const OCSP_CERTID *a, const OCSP_CERTID *b);
 
  int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd,
                        ASN1_OCTET_STRING **pikeyHash,

doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod

@@ -58,7 +58,7 @@ B<RFC 4211>
 
 Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.

doc/man3/OSSL_CRMF_MSG_set1_regCtrl_regToken.pod

@@ -98,7 +98,7 @@ RFC 4211
 
 Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.

doc/man3/OSSL_CRMF_MSG_set1_regInfo_certReq.pod

@@ -41,7 +41,7 @@ RFC 4211
 
 Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.

doc/man3/OSSL_CRMF_MSG_set_validity.pod

@@ -97,7 +97,7 @@ RFC 4211
 
 Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.

doc/man3/OSSL_CRMF_pbmp_new.pod

@@ -70,7 +70,7 @@ RFC 4211 section 4.4
 
 Copyright 2007-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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>.

doc/man3/OSSL_PARAM_TYPE.pod

@@ -272,7 +272,9 @@ This example is for setting parameters on some object:
 
 =head2 Example 2
 
-This example is for requesting parameters on some object:
+This example is for requesting parameters on some object, and also
+demonstrates that the requestor isn't obligated to request all
+available parameters:
 
     const char *foo = NULL;
     size_t foo_l;
@@ -289,8 +291,14 @@ could fill in the parameters like this:
 
     /* const OSSL_PARAM *params */
 
-    OSSL_PARAM_set_utf8_ptr(OSSL_PARAM_locate(params, "foo"), "foo value");
-    OSSL_PARAM_set_utf8_string(OSSL_PARAM_locate(params, "bar"), "bar value");
+    const OSSL_PARAM *p;
+
+    if ((p = OSSL_PARAM_locate(params, "foo")) == NULL)
+        OSSL_PARAM_set_utf8_ptr(p, "foo value");
+    if ((p = OSSL_PARAM_locate(params, "bar")) == NULL)
+        OSSL_PARAM_set_utf8_ptr(p, "bar value");
+    if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL)
+        OSSL_PARAM_set_utf8_ptr(p, "cookie value");
 
 =head1 SEE ALSO
 

doc/man3/OSSL_trace_enabled.pod

@@ -40,7 +40,7 @@ The tracing output is divided into types which are enabled
 individually by the application.
 The tracing types are described in detail in
 L<OSSL_trace_set_callback(3)/Trace types>.
-The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
+The fallback type C<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
 with the functions described here.
 
 Tracing for a specific category is enabled if a so called

doc/man3/OSSL_trace_set_channel.pod

@@ -178,9 +178,15 @@ Traces BIGNUM context operations.
 
 =back
 
-There is also C<OSSL_TRACE_CATEGORY_ANY>, which works as a fallback
+There is also C<OSSL_TRACE_CATEGORY_ALL>, which works as a fallback
 and can be used to get I<all> trace output.
 
+Note, however, that in this case all trace output will effectively be
+associated with the 'ALL' category, which is undesirable if the
+application intends to include the category name in the trace output.
+In this case it is better to register separate channels for each
+trace category instead.
+
 =head1 RETURN VALUES
 
 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),

doc/man3/X509_get0_sm2_id.pod

@@ -0,0 +1,43 @@
+=pod
+
+=head1 NAME
+
+X509_get0_sm2_id, X509_set_sm2_id - get or set SM2 ID for certificate operations
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ ASN1_OCTET_STRING *X509_get0_sm2_id(X509 *x);
+ void X509_set_sm2_id(X509 *x, ASN1_OCTET_STRING *sm2_id);
+
+=head1 DESCRIPTION
+
+X509_get0_sm2_id() gets the ID value of an SM2 certificate B<x> by returning an
+B<ASN1_OCTET_STRING> object which should not be freed by the caller.
+X509_set_sm2_id() sets the B<sm2_id> value to an SM2 certificate B<x>.
+
+=head1 NOTES
+
+SM2 signature algorithm requires an ID value when generating and verifying a
+signature. The functions described in this manual provide the user with the
+ability to set and retrieve the SM2 ID value.
+
+=head1 RETURN VALUES
+
+X509_set_sm2_id() does not return a value.
+
+=head1 SEE ALSO
+
+L<X509_verify(3)>, L<SM2(7)>
+
+=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

doc/man7/EVP_KDF_SS.pod

@@ -0,0 +1,226 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_SS - The Single Step / One Step EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+The EVP_KDF_SS algorithm implements the Single Step key derivation function (SSKDF).
+SSKDF derives a key using input such as a shared secret key (that was generated
+during the execution of a key establishment scheme) and fixedinfo.
+SSKDF is also informally referred to as 'Concat KDF'.
+
+=head2 Auxilary function
+
+The implementation uses a selectable auxiliary function H, which can be one of:
+
+=over 4
+
+=item B<H(x) = hash(x, digest=md)>
+
+=item B<H(x) = HMAC_hash(x, key=salt, digest=md)>
+
+=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>
+
+=back
+
+Both the HMAC and KMAC implementations set the key using the 'salt' value.
+The hash and HMAC also require the digest to be set.
+
+=head2 Numeric identity
+
+B<EVP_KDF_SS> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+=item B<EVP_KDF_CTRL_SET_MAC>
+
+=item B<EVP_MAC_CTRL_SET_MAC_SIZE>
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+=item B<EVP_KDF_CTRL_SET_KEY>
+
+This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
+
+The shared secret used for key derivation.  This control sets the secret.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "secret"
+
+The value string is used as is.
+
+=item "hexsecret"
+
+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_SSKDF_INFO>
+
+This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
+
+An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "info"
+
+The value string is used as is.
+
+=item "hexinfo"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=back
+
+=head1 NOTES
+
+A context for SSKDF can be obtained by calling:
+
+EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
+
+The output length of an SSKDF is specified via the C<keylen>
+parameter to the L<EVP_KDF_derive(3)> function.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
+and fixedinfo value "label":
+
+  EVP_KDF_CTX *kctx;
+  unsigned char out[10];
+
+  kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
+
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+      error("EVP_KDF_CTRL_SET_MD");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
+      error("EVP_KDF_CTRL_SET_KEY");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
+      error("EVP_KDF_CTRL_SET_SSKDF_INFO");
+  }
+  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+      error("EVP_KDF_derive");
+  }
+
+  EVP_KDF_CTX_free(kctx);
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
+fixedinfo value "label" and salt "salt":
+
+  EVP_KDF_CTX *kctx;
+  unsigned char out[10];
+
+  kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
+
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) {
+      error("EVP_KDF_CTRL_SET_MAC");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+      error("EVP_KDF_CTRL_SET_MD");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
+      error("EVP_KDF_CTRL_SET_KEY");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
+      error("EVP_KDF_CTRL_SET_SSKDF_INFO");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
+      error("EVP_KDF_CTRL_SET_SALT");
+  }
+  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+      error("EVP_KDF_derive");
+  }
+
+  EVP_KDF_CTX_free(kctx);
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
+fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
+
+  EVP_KDF_CTX *kctx;
+  unsigned char out[10];
+
+  kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
+
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) {
+      error("EVP_KDF_CTRL_SET_MAC");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+      error("EVP_KDF_CTRL_SET_MD");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
+      error("EVP_KDF_CTRL_SET_KEY");
+  }
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
+      error("EVP_KDF_CTRL_SET_SSKDF_INFO");
+  }
+  /* If not specified the salt will be set to a default value */
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
+      error("EVP_KDF_CTRL_SET_SALT");
+  }
+  /* If not specified the default size will be the size of the derived key */
+  if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) {
+      error("EVP_KDF_CTRL_SET_MAC_SIZE");
+  }
+  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+      error("EVP_KDF_derive");
+  }
+
+  EVP_KDF_CTX_free(kctx);
+
+
+=head1 CONFORMING TO
+
+NIST SP800-56Cr1.
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_size(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
+(c) 2019, Oracle and/or its affiliates.  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