Add public API docs for newly added EVP_SIGNATURE related functions
authorMatt Caswell <matt@openssl.org>
Tue, 3 Sep 2019 15:15:21 +0000 (16:15 +0100)
committerMatt Caswell <matt@openssl.org>
Mon, 9 Sep 2019 13:00:00 +0000 (14:00 +0100)
Documentation for EVP_SIGNATURE_*() as well as EVP_PKEY_sign_init_ex(),
EVP_PKEY_verify_init_ex() and EVP_PKEY_verify_recover_init_ex().

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9753)

doc/man3/EVP_PKEY_CTX_ctrl.pod
doc/man3/EVP_PKEY_derive.pod
doc/man3/EVP_PKEY_sign.pod
doc/man3/EVP_PKEY_verify.pod
doc/man3/EVP_PKEY_verify_recover.pod
doc/man3/EVP_SIGNATURE_free.pod [new file with mode: 0644]

index 1787e19..9d1812f 100644 (file)
@@ -161,6 +161,17 @@ up to the size of the DH prime B<p>.
 If B<OSSL_EXCHANGE_PARAM_PAD> is zero (the default) then no padding is
 performed.
 
+=item OSSL_SIGNATURE_PARAM_DIGEST (UTF8 string type)
+
+Sets the name of the digest algorithm used for the input to the signature
+functions.
+
+=item OSSL_SIGNATURE_PARAM_DIGEST_SIZE (size_t type)
+
+Sets the output size of the digest algorithm used for the input to the signature
+functions.
+The internal algorithm that supports this parameter is DSA.
+
 =back
 
 The function EVP_PKEY_CTX_ctrl() sends a control operation to the context
index d6516e7..832498b 100644 (file)
@@ -25,10 +25,10 @@ The EVP_PKEY object associated with B<ctx> must be compatible with that
 algorithm.
 B<exchange> may be NULL in which case the EVP_KEYEXCH algorithm is fetched
 implicitly based on the type of EVP_PKEY associated with B<ctx>.
-See L<EVP_KEYEXCH_fetch(3)> for more information about implict fetches.
+See L<provider(7)/Implicit fetch> for more information about implict fetches.
 
-The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive() except that
-the EVP_KEYEXCH algorithm is always implicitly fetched.
+The EVP_PKEY_derive_init() function is the same as EVP_PKEY_derive_init_ex()
+except that the EVP_KEYEXCH algorithm is always implicitly fetched.
 
 The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally
 be a public key.
index d48edb5..f30affd 100644 (file)
@@ -2,12 +2,14 @@
 
 =head1 NAME
 
-EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
+EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init, EVP_PKEY_sign
+- sign using a public key algorithm
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *signature);
  int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
                    unsigned char *sig, size_t *siglen,
@@ -15,8 +17,18 @@ EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_sign_init() function initializes a public key algorithm
-context using key B<pkey> for a signing operation.
+The EVP_PKEY_sign_init_ex() function initializes a public key algorithm
+context for performing signing using the signature algorithm B<signature>.
+The signature algorithm B<signature> should be fetched using a call to
+L<EVP_SIGNATURE_fetch(3)>.
+The EVP_PKEY object associated with B<ctx> must be compatible with that
+algorithm.
+B<signature> may be NULL in which case the EVP_SIGNATURE algorithm is fetched
+implicitly based on the type of EVP_PKEY associated with B<ctx>.
+See L<provider(7)/Implicit fetch> for more information about implict fetches.
+
+The EVP_PKEY_sign_init() function is the same as EVP_PKEY_sign_init_ex() except
+that the EVP_SIGNATURE algorithm is always implicitly fetched.
 
 The EVP_PKEY_sign() function performs a public key signing operation
 using B<ctx>. The data to be signed is specified using the B<tbs> and
@@ -101,6 +113,7 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
+EVP_PKEY_sign_init_ex() was added in OpenSSL 3.0.
 These functions were added in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
index 0212202..1e04a85 100644 (file)
@@ -2,12 +2,14 @@
 
 =head1 NAME
 
-EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public key algorithm
+EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init, EVP_PKEY_verify
+- signature verification using a public key algorithm
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *signature);
  int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
                      const unsigned char *sig, size_t siglen,
@@ -15,8 +17,19 @@ EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public ke
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_verify_init() function initializes a public key algorithm
-context using key B<pkey> for a signature verification operation.
+The EVP_PKEY_verify_init_ex() function initializes a public key algorithm
+context for performing signature verification using the signature algorithm
+B<signature>.
+The signature algorithm B<signature> should be fetched using a call to
+L<EVP_SIGNATURE_fetch(3)>.
+The EVP_PKEY object associated with B<ctx> must be compatible with that
+algorithm.
+B<signature> may be NULL in which case the EVP_SIGNATURE algorithm is fetched
+implicitly based on the type of EVP_PKEY associated with B<ctx>.
+See L<provider(7)/Implicit fetch> for more information about implict fetches.
+
+The EVP_PKEY_verify_init() function is the same as EVP_PKEY_verify_init_ex()
+except that the EVP_SIGNATURE algorithm is always implicitly fetched.
 
 The EVP_PKEY_verify() function performs a public key verification operation
 using B<ctx>. The signature is specified using the B<sig> and
@@ -89,7 +102,8 @@ L<EVP_PKEY_derive(3)>
 
 =head1 HISTORY
 
-These functions were added in OpenSSL 1.0.0.
+EVP_PKEY_verify_init_ex() was added in OpenSSL 3.0.
+All other functions were added in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
 
index 2b425a3..737c372 100644 (file)
@@ -2,12 +2,15 @@
 
 =head1 NAME
 
-EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
+EVP_PKEY_verify_recover_init_ex, EVP_PKEY_verify_recover_init,
+EVP_PKEY_verify_recover - recover signature using a public key algorithm
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
+ int EVP_PKEY_verify_recover_init_ex(EVP_PKEY_CTX *ctx,
+                                     EVP_SIGNATURE *signature);
  int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
  int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
                              unsigned char *rout, size_t *routlen,
@@ -15,8 +18,20 @@ EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
-context using key B<pkey> for a verify recover operation.
+The EVP_PKEY_verify_recover_init_ex() function initializes a public key
+algorithm context for performing signature signed data recovery using the
+signature algorithm B<signature>.
+The signature algorithm B<signature> should be fetched using a call to
+L<EVP_SIGNATURE_fetch(3)>.
+The EVP_PKEY object associated with B<ctx> must be compatible with that
+algorithm.
+B<signature> may be NULL in which case the EVP_SIGNATURE algorithm is fetched
+implicitly based on the type of EVP_PKEY associated with B<ctx>.
+See L<provider(7)/Implicit fetch> for more information about implict fetches.
+
+The EVP_PKEY_verify_recover_init() function is the same as
+EVP_PKEY_verify_recover_init_ex() except that the EVP_SIGNATURE algorithm is
+always implicitly fetched.
 
 The EVP_PKEY_verify_recover() function recovers signed data
 using B<ctx>. The signature is specified using the B<sig> and
diff --git a/doc/man3/EVP_SIGNATURE_free.pod b/doc/man3/EVP_SIGNATURE_free.pod
new file mode 100644 (file)
index 0000000..3e39b91
--- /dev/null
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref,
+EVP_SIGNATURE_provider
+- Functions to manage EVP_SIGNATURE algorithm objects
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ EVP_SIGNATURE *EVP_SIGNATURE_fetch(OPENSSL_CTX *ctx, const char *algorithm,
+                                    const char *properties);
+ void EVP_SIGNATURE_free(EVP_SIGNATURE *signature);
+ int EVP_SIGNATURE_up_ref(EVP_SIGNATURE *signature);
+ OSSL_PROVIDER *EVP_SIGNATURE_provider(const EVP_SIGNATURE *signature);
+
+=head1 DESCRIPTION
+
+EVP_SIGNATURE_fetch() fetches the implementation for the given
+B<algorithm> from any provider offering it, within the criteria given
+by the B<properties>.
+The algorithm will be one offering functions for performing signature related
+tasks such as signing and verifying.
+See L<provider(7)/Fetching algorithms> for further information.
+
+The returned value must eventually be freed with EVP_SIGNATURE_free().
+
+EVP_SIGNATURE_free() decrements the reference count for the B<EVP_SIGNATURE>
+structure. Typically this structure will have been obtained from an earlier call
+to EVP_SIGNATURE_fetch(). If the reference count drops to 0 then the
+structure is freed.
+
+EVP_SIGNATURE_up_ref() increments the reference count for an B<EVP_SIGNATURE>
+structure.
+
+EVP_SIGNATURE_provider() returns the provider that I<signature> was fetched from.
+
+=head1 RETURN VALUES
+
+EVP_SIGNATURE_fetch() returns a pointer to an B<EVP_SIGNATURE> for success
+or B<NULL> for failure.
+
+EVP_SIGNATURE_up_ref() returns 1 for success or 0 otherwise.
+
+=head1 SEE ALSO
+
+L<provider(7)/Fetching algorithms>, L<OSSL_PROVIDER(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