deploy openssl/openssl@7c900ef to 3.0

3.0/man3/ECDSA_sign/index.html

@@ -29,7 +29,7 @@
 int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen,
                   unsigned char *sig, unsigned int *siglen,
                   const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
-</code></pre></div><h2 id=description>DESCRIPTION<a class=headerlink href=#description title="Permanent link">&para;</a></h2><p>See <a href=../ECDSA_SIG_new/ >ECDSA_SIG_new(3)</a> for a description of the <strong>ECDSA_SIG</strong> object.</p><p>See <a href=../d2i_X509/ >i2d_ECDSA_SIG(3)</a> and <a href=../d2i_X509/ >d2i_ECDSA_SIG(3)</a> for information about encoding and decoding ECDSA signatures to/from DER.</p><p>All of the functions described below are deprecated. Applications should use the higher level <strong>EVP</strong> interface such as <a href=../EVP_DigestSignInit/ >EVP_DigestSignInit(3)</a> or <a href=../EVP_DigestVerifyInit/ >EVP_DigestVerifyInit(3)</a> instead.</p><p>ECDSA_size() returns the maximum length of a DER encoded ECDSA signature created with the private EC key <em>eckey</em>. To obtain the actual signature size use <a href=../EVP_PKEY_sign/ >EVP_PKEY_sign(3)</a> with a NULL <em>sig</em> parameter.</p><p>ECDSA_sign() computes a digital signature of the <em>dgstlen</em> bytes hash value <em>dgst</em> using the private EC key <em>eckey</em>. The DER encoded signatures is stored in <em>sig</em> and its length is returned in <em>sig_len</em>. Note: <em>sig</em> must point to ECDSA_size(eckey) bytes of memory. The parameter <em>type</em> is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with <em>kinv</em> and <em>rp</em> set to NULL.</p><p>ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned as a newly allocated <strong>ECDSA_SIG</strong> structure (or NULL on error). ECDSA_do_sign() is a wrapper function for ECDSA_do_sign_ex() with <em>kinv</em> and <em>rp</em> set to NULL.</p><p>ECDSA_verify() verifies that the signature in <em>sig</em> of size <em>siglen</em> is a valid ECDSA signature of the hash value <em>dgst</em> of size <em>dgstlen</em> using the public key <em>eckey</em>. The parameter <em>type</em> is ignored.</p><p>ECDSA_do_verify() is similar to ECDSA_verify() except the signature is presented in the form of a pointer to an <strong>ECDSA_SIG</strong> structure.</p><p>The remaining functions utilise the internal <em>kinv</em> and <em>r</em> values used during signature computation. Most applications will never need to call these and some external ECDSA ENGINE implementations may not support them at all if either <em>kinv</em> or <em>r</em> is not NULL.</p><p>ECDSA_sign_setup() may be used to precompute parts of the signing operation. <em>eckey</em> is the private EC key and <em>ctx</em> is a pointer to <strong>BN_CTX</strong> structure (or NULL). The precomputed values or returned in <em>kinv</em> and <em>rp</em> and can be used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().</p><p>ECDSA_sign_ex() computes a digital signature of the <em>dgstlen</em> bytes hash value <em>dgst</em> using the private EC key <em>eckey</em> and the optional pre-computed values <em>kinv</em> and <em>rp</em>. The DER encoded signature is stored in <em>sig</em> and its length is returned in <em>sig_len</em>. Note: <em>sig</em> must point to ECDSA_size(eckey) bytes of memory. The parameter <em>type</em> is ignored.</p><p>ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is returned as a newly allocated <strong>ECDSA_SIG</strong> structure (or NULL on error).</p><h2 id=return-values>RETURN VALUES<a class=headerlink href=#return-values title="Permanent link">&para;</a></h2><p>ECDSA_size() returns the maximum length signature or 0 on error.</p><p>ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful or 0 on error.</p><p>ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated <strong>ECDSA_SIG</strong> structure or NULL on error.</p><p>ECDSA_verify() and ECDSA_do_verify() return 1 for a valid signature, 0 for an invalid signature and -1 on error. The error codes can be obtained by <a href=../ERR_get_error/ >ERR_get_error(3)</a>.</p><h2 id=examples>EXAMPLES<a class=headerlink href=#examples title="Permanent link">&para;</a></h2><p>Creating an ECDSA signature of a given SHA-256 hash value using the named curve prime256v1 (aka P-256). This example uses deprecated functionality. See <a href=#description>&quot;DESCRIPTION&quot;</a>.</p><p>First step: create an EC_KEY object (note: this part is <strong>not</strong> ECDSA specific)</p><div class=highlight><pre><span></span><code>int ret;
+</code></pre></div><h2 id=description>DESCRIPTION<a class=headerlink href=#description title="Permanent link">&para;</a></h2><p>See <a href=../ECDSA_SIG_new/ >ECDSA_SIG_new(3)</a> for a description of the <strong>ECDSA_SIG</strong> object.</p><p>See <a href=../d2i_X509/ >i2d_ECDSA_SIG(3)</a> and <a href=../d2i_X509/ >d2i_ECDSA_SIG(3)</a> for information about encoding and decoding ECDSA signatures to/from DER.</p><p>All of the functions described below are deprecated. Applications should use the higher level <strong>EVP</strong> interface such as <a href=../EVP_DigestSignInit/ >EVP_DigestSignInit(3)</a> or <a href=../EVP_DigestVerifyInit/ >EVP_DigestVerifyInit(3)</a> instead.</p><p>ECDSA_size() returns the maximum length of a DER encoded ECDSA signature created with the private EC key <em>eckey</em>. To obtain the actual signature size use <a href=../EVP_PKEY_sign/ >EVP_PKEY_sign(3)</a> with a NULL <em>sig</em> parameter.</p><p>ECDSA_sign() computes a digital signature of the <em>dgstlen</em> bytes hash value <em>dgst</em> using the private EC key <em>eckey</em>. The DER encoded signatures is stored in <em>sig</em> and its length is returned in <em>siglen</em>. Note: <em>sig</em> must point to ECDSA_size(eckey) bytes of memory. The parameter <em>type</em> is currently ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with <em>kinv</em> and <em>rp</em> set to NULL.</p><p>ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned as a newly allocated <strong>ECDSA_SIG</strong> structure (or NULL on error). ECDSA_do_sign() is a wrapper function for ECDSA_do_sign_ex() with <em>kinv</em> and <em>rp</em> set to NULL.</p><p>ECDSA_verify() verifies that the signature in <em>sig</em> of size <em>siglen</em> is a valid ECDSA signature of the hash value <em>dgst</em> of size <em>dgstlen</em> using the public key <em>eckey</em>. The parameter <em>type</em> is ignored.</p><p>ECDSA_do_verify() is similar to ECDSA_verify() except the signature is presented in the form of a pointer to an <strong>ECDSA_SIG</strong> structure.</p><p>The remaining functions utilise the internal <em>kinv</em> and <em>r</em> values used during signature computation. Most applications will never need to call these and some external ECDSA ENGINE implementations may not support them at all if either <em>kinv</em> or <em>r</em> is not NULL.</p><p>ECDSA_sign_setup() may be used to precompute parts of the signing operation. <em>eckey</em> is the private EC key and <em>ctx</em> is a pointer to <strong>BN_CTX</strong> structure (or NULL). The precomputed values or returned in <em>kinv</em> and <em>rp</em> and can be used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex().</p><p>ECDSA_sign_ex() computes a digital signature of the <em>dgstlen</em> bytes hash value <em>dgst</em> using the private EC key <em>eckey</em> and the optional pre-computed values <em>kinv</em> and <em>rp</em>. The DER encoded signature is stored in <em>sig</em> and its length is returned in <em>siglen</em>. Note: <em>sig</em> must point to ECDSA_size(eckey) bytes of memory. The parameter <em>type</em> is ignored.</p><p>ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is returned as a newly allocated <strong>ECDSA_SIG</strong> structure (or NULL on error).</p><h2 id=return-values>RETURN VALUES<a class=headerlink href=#return-values title="Permanent link">&para;</a></h2><p>ECDSA_size() returns the maximum length signature or 0 on error.</p><p>ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful or 0 on error.</p><p>ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated <strong>ECDSA_SIG</strong> structure or NULL on error.</p><p>ECDSA_verify() and ECDSA_do_verify() return 1 for a valid signature, 0 for an invalid signature and -1 on error. The error codes can be obtained by <a href=../ERR_get_error/ >ERR_get_error(3)</a>.</p><h2 id=examples>EXAMPLES<a class=headerlink href=#examples title="Permanent link">&para;</a></h2><p>Creating an ECDSA signature of a given SHA-256 hash value using the named curve prime256v1 (aka P-256). This example uses deprecated functionality. See <a href=#description>&quot;DESCRIPTION&quot;</a>.</p><p>First step: create an EC_KEY object (note: this part is <strong>not</strong> ECDSA specific)</p><div class=highlight><pre><span></span><code>int ret;
 ECDSA_SIG *sig;
 EC_KEY *eckey;