Add EVP signature with libctx methods.

[openssl.git] / doc / man3 / EVP_DigestSignInit.pod

diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod
index 69dec1c74d4947e8d79d83f0af593b95743af3c5..923de31a31390e0b9d30c0ad087dac9ca60a958a 100644 (file)
--- a/doc/man3/EVP_DigestSignInit.pod
+++ b/doc/man3/EVP_DigestSignInit.pod
@@ -2,16 +2,17 @@
 
 =head1 NAME
 
-EVP_DigestSignInit_ex, EVP_DigestSignInit, EVP_DigestSignUpdate,
+EVP_DigestSignInit_with_libctx, EVP_DigestSignInit, EVP_DigestSignUpdate,
 EVP_DigestSignFinal, EVP_DigestSign - EVP signing functions
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
- int EVP_DigestSignInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
-                           const char *mdname, const char *props,
-                           EVP_PKEY *pkey, OPENSSL_CTX *libctx);
+ int EVP_DigestSignInit_with_libctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
+                                    const char *mdname,
+                                    OPENSSL_CTX *libctx, const char *props,
+                                    EVP_PKEY *pkey);
  int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
                         const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
  int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
@@ -26,12 +27,12 @@ EVP_DigestSignFinal, EVP_DigestSign - EVP signing functions
 The EVP signature routines are a high-level interface to digital signatures.
 Input data is digested first before the signing takes place.
 
-EVP_DigestSignInit_ex() sets up signing context I<ctx> to use a digest with the
-name I<mdname> and private key I<pkey>. The name of the digest to be used is
-passed to the provider of the signature algorithm in use. How that provider
-interprets the digest name is provider specific. The provider may implement
-that digest directly itself or it may (optionally) choose to fetch it (which
-could result in a digest from a different provider being selected). If the
+EVP_DigestSignInit_with_libctx() sets up signing context I<ctx> to use a digest
+with the name I<mdname> and private key I<pkey>. The name of the digest to be
+used is passed to the provider of the signature algorithm in use. How that
+provider interprets the digest name is provider specific. The provider may
+implement that digest directly itself or it may (optionally) choose to fetch it
+(which could result in a digest from a different provider being selected). If the
 provider supports fetching the digest then it may use the I<props> argument for
 the properties to be used during the fetch.
 
@@ -49,18 +50,19 @@ I<pctx> is not NULL, the EVP_PKEY_CTX of the signing operation will be written
 to I<*pctx>: this can be used to set alternative signing options. Note that any
 existing value in I<*pctx> is overwritten. The EVP_PKEY_CTX value returned must
 not be freed directly by the application if I<ctx> is not assigned an
-EVP_PKEY_CTX value before being passed to EVP_DigestSignInit_ex() (which means
-the EVP_PKEY_CTX is created inside EVP_DigestSignInit_ex() and it will be freed
-automatically when the EVP_MD_CTX is freed). If the EVP_PKEY_CTX to be used is
-created by EVP_DigestSignInit_ex then it will use the B<OPENSSL_CTX> specified
-in I<libctx> and the property query string specified in I<props>.
+EVP_PKEY_CTX value before being passed to EVP_DigestSignInit_with_libctx()
+(which means the EVP_PKEY_CTX is created inside EVP_DigestSignInit_with_libctx()
+and it will be freed automatically when the EVP_MD_CTX is freed). If the
+EVP_PKEY_CTX to be used is created by EVP_DigestSignInit_with_libctx then it
+will use the B<OPENSSL_CTX> specified in I<libctx> and the property query string
+specified in I<props>.
 
 The digest I<mdname> may be NULL if the signing algorithm supports it. The
 I<props> argument can always be NULL.
 
-No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit_ex() if the passed
-I<ctx> has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>. See also
-L<SM2(7)>.
+No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit_with_libctx() if the
+passed I<ctx> has already been assigned one via L<EVP_MD_CTX_set_pkey_ctx(3)>.
+See also L<SM2(7)>.
 
 Only EVP_PKEY types that support signing can be used with these functions. This
 includes MAC algorithms where the MAC generation is considered as a form of
@@ -108,10 +110,10 @@ Will ignore any digest provided.
 
 If RSA-PSS is used and restrictions apply then the digest must match.
 
-EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_ex() except
-that the I<mdname> parameter will be inferred from the supplied digest I<type>,
-and I<props> will be NULL. Where supplied the ENGINE I<e> will be used for the
-signing and digest algorithm implementations. I<e> may be NULL.
+EVP_DigestSignInit() works in the same way as EVP_DigestSignInit_with_libctx()
+except that the I<mdname> parameter will be inferred from the supplied
+digest I<type>, and I<props> will be NULL. Where supplied the ENGINE I<e> will
+be used for the signing and digest algorithm implementations. I<e> may be NULL.
 
 EVP_DigestSignUpdate() hashes I<cnt> bytes of data at I<d> into the
 signature context I<ctx>. This function can be called several times on the
@@ -182,7 +184,7 @@ L<RAND(7)>
 EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal()
 were added in OpenSSL 1.0.0.
 
-EVP_DigestSignInit_ex() was added in OpenSSL 3.0.
+EVP_DigestSignInit_with_libctx() was added in OpenSSL 3.0.
 
 EVP_DigestSignUpdate() was converted from a macro to a function in OpenSSL 3.0.