Difference between revisions of "EVP Signing and Verifying"

From OpenSSLWiki
Jump to: navigation, search
m (Deleted content until we have working examples.)
(Added some hidden changes (the old page is still available; its just HTML comment out).)
Line 1: Line 1:
There are two APIs available for performing sign and verify operations. The older <tt>EVP_Sign*</tt> and <tt>EVP_Verify*</tt> functions, and the newer and more flexible <tt>EVP_DigestSign*</tt> and <tt>EVP_DigestVerify*</tt> functions. Though the APIs are similar, new applications should use the <tt>EVP_DigestSign*</tt> and <tt>EVP_DigestVerify*</tt> functions.
+
There are two APIs available to perform sign and verify operations. The first are the older <tt>EVP_Sign*</tt> and <tt>EVP_Verify*</tt> functions; and the second are the newer and more flexible <tt>EVP_DigestSign*</tt> and <tt>EVP_DigestVerify*</tt> functions. Though the APIs are similar, new applications should use the <tt>EVP_DigestSign*</tt> and <tt>EVP_DigestVerify*</tt> functions.
  
The examples below use the new <tt>EVP_DigestSign*</tt> and <tt>EVP_DigestVerify*</tt> functions.
+
The examples below use the new <tt>EVP_DigestSign*</tt> and <tt>EVP_DigestVerify*</tt> functions to demonstarte signing and verification. The first example uses an HMAC, and the second example uses RSA key pairs. Additionally, the code for the example is available for download.
 +
 
 +
<!--
 +
 
 +
==Overview==
 +
 
 +
In general, signing a message is a three stage process:
 +
 
 +
* Initialize the context with a message digest/hash function and <tt>EVP_PKEY</tt> key
 +
* Add the message data (this step can be repeated as many times as necessary)
 +
* Finalize the context to create the signature
 +
 
 +
In order to initialize, you first need to select a message digest algorithm (refer to [[EVP#Working with Algorithms and Modes|Working with Algorithms and Modes]]). Second, you need to provide a <tt>EVP_PKEY</tt> containing a key for an algorithm that supports signing (refer to [[EVP#Working with EVP_PKEYs|Working with EVP_PKEYs]]). Both the digest and the key are provided to <tt>EVP_DigestSignInit</tt>.
 +
 
 +
To add the message data, you call <tt>EVP_DigestSignUpdate</tt> one or more times.
 +
 
 +
To finalize the operation and retrieve the signature, you call <tt>EVP_DigestSignFinal</tt>.
 +
 
 +
In general, verification follows the same steps. The key difference is the finalization:
 +
 
 +
* Initialize the context with a message digest/hash function and <tt>EVP_PKEY</tt> key
 +
* Add the message data (this step can be repeated as many times as necessary)
 +
* Finalize the context '''''with''''' the previous signature to verify the message
 +
 
 +
When finalizing during verification, you add the signature in the call. <tt>EVP_DigestVerifyFinal</tt> will then perform the validate the signature on the message.
 +
 
 +
==HMAC==
 +
 
 +
The first example shows how to create a signature over a message using an HMAC with <tt>EVP_DigestSignInit</tt>, <tt>EVP_DigestSignUpdate</tt> and <tt>EVP_DigestSignFinal</tt>. The second part shows how to verify a signature over the message using using the same <tt>EVP_DigestSign</tt> functions. You do not use the <tt>EVP_DigestVerify</tt> functions to verify.
 +
 
 +
'''''Note well''''': you do not use <tt>EVP_DigestVerify</tt> to verify an HMAC. <tt>EVP_DigestVerifyInit</tt> will fail with an error 0x608f096: <tt>error:0608F096:digital envelope routines:EVP_PKEY_verify_init:operation not supported for this keytype</tt>.
 +
 
 +
===Signing===
 +
 
 +
===Verifying===
  
'''''Editor's note''''': the examples were removed because they don't work. Stand by...
 
  
<!--
 
  
==Public Key Signing==
+
==Public Key==
  
The first example shows how to create a signature over a message using <tt>EVP_DigestSignInit</tt>, <tt>EVP_DigestSignUpdate</tt> and <tt>EVP_DigestSignFinal</tt>. The second example shows how to verify a signature over the message using <tt>EVP_DigestVerifyInit</tt>, <tt>EVP_DigestVerifyUpdate</tt> and <tt>EVP_DigestVerifyFinal</tt>.
+
The second example shows how to create a signature over a message using public keys with <tt>EVP_DigestSignInit</tt>, <tt>EVP_DigestSignUpdate</tt> and <tt>EVP_DigestSignFinal</tt>. The second example shows how to verify a signature over the message using <tt>EVP_DigestVerifyInit</tt>, <tt>EVP_DigestVerifyUpdate</tt> and <tt>EVP_DigestVerifyFinal</tt>. Unlike HMACs, you do use the <tt>EVP_DigestVerify</tt> functions to verify.
  
===Signing a Message===
+
===Signing===
  
Signing a message is a three stage process:
 
* Initialize the context and identify the message digest/hash function that will be used during the sign operation.
 
* Add message data (this step can be repeated as many times as necessary)
 
* Finalize to create the signature
 
  
In order to initialize the operation, you need to first have first set up a <tt>EVP_PKEY</tt> object containing a public key for an algorithm that supports signing (this includes MAC codes). Refer to [[EVP#Working with EVP_PKEYs|Working with EVP_PKEYs]] for further information. You also need to provide a message digest algorithm (refer to [[EVP#Working with Algorithms and Modes|Working with Algorithms and Modes]]).
 
  
 
<pre>EVP_MD_CTX *mdctx = NULL;
 
<pre>EVP_MD_CTX *mdctx = NULL;
Line 60: Line 87:
 
Refer to [[Manual:EVP_DigestSignInit(3)]] for further details on the EVP_DigestSign* functions, and [[Manual:EVP_SignInit(3)]] for the EVP_Sign* functions.
 
Refer to [[Manual:EVP_DigestSignInit(3)]] for further details on the EVP_DigestSign* functions, and [[Manual:EVP_SignInit(3)]] for the EVP_Sign* functions.
  
===Verifying a Signature===
+
===Verifying===
  
 
Verifying a message is very similar to signing except the EVP_DigestVerify* functions (or EVP_Verify* functions) are used instead. Clearly only a public key is required for a verify operation:
 
Verifying a message is very similar to signing except the EVP_DigestVerify* functions (or EVP_Verify* functions) are used instead. Clearly only a public key is required for a verify operation:
Line 103: Line 130:
 
/* Verify success */;
 
/* Verify success */;
 
</pre>
 
</pre>
 +
 +
-->
  
 
Refer to [[Manual:EVP_DigestVerifyInit(3)]] and [[Manual:EVP_VerifyInit(3)]] for further information on the verify functions.
 
Refer to [[Manual:EVP_DigestVerifyInit(3)]] and [[Manual:EVP_VerifyInit(3)]] for further information on the verify functions.
  
-->
 
  
 
==See also==
 
==See also==

Revision as of 19:45, 15 January 2015

There are two APIs available to perform sign and verify operations. The first are the older EVP_Sign* and EVP_Verify* functions; and the second are the newer and more flexible EVP_DigestSign* and EVP_DigestVerify* functions. Though the APIs are similar, new applications should use the EVP_DigestSign* and EVP_DigestVerify* functions.

The examples below use the new EVP_DigestSign* and EVP_DigestVerify* functions to demonstarte signing and verification. The first example uses an HMAC, and the second example uses RSA key pairs. Additionally, the code for the example is available for download.


Refer to Manual:EVP_DigestVerifyInit(3) and Manual:EVP_VerifyInit(3) for further information on the verify functions.


See also