Projects/AEAD encryption API - Revision history

Newacct at 18:11, 1 August 2010

2010-08-01T18:11:49Z

TomYu at 04:11, 16 February 2010

2010-02-16T04:11:47Z

Ghudson: /* Basic approach */

2009-10-07T13:52:38Z

‎Basic approach

Ghudson: /* Basic approach */

2009-10-07T13:52:05Z

‎Basic approach

Lukeh at 18:37, 14 September 2009

2009-09-14T18:37:12Z

TomYu at 16:53, 16 December 2008

2008-12-16T16:53:34Z

TomYu at 16:05, 15 December 2008

2008-12-15T16:05:32Z

TomYu: formatting cleanup

2008-12-04T20:34:17Z

formatting cleanup

SamHartman: Respond to Love's comments

2008-12-04T14:00:17Z

Respond to Love's comments

SamHartman: start review

2008-11-24T19:23:51Z

start review

@@ Line 25: / Line 25: @@
 </pre>
-The ''flags'' member describes the type of the iov.  The ''data'' member points to  the memory that will be manipulated.  All iov APIs take a pointer to an array of ''krb5_crypto_iov''s along with the size of that array. Buffer contents are manipulated in-place; data is overwritten.  Callers must allocate the right number of krb5_crypto_iov structures before calling into an iov API.
+The ''flags'' member describes the type of the iov.  The ''data'' member points to  the memory that will be manipulated.  All iov APIs take a pointer to the first element of an array of ''krb5_crypto_iov''s along with the size of that array. Buffer contents are manipulated in-place; data is overwritten.  Callers must allocate the right number of krb5_crypto_iov structures before calling into an iov API.
 Several types of krb5_crypto_iov are supported:

← Older revision		Revision as of 04:11, 16 February 2010
Line 1:		Line 1:
−	{{project-~~completed~~}}	+	{{project-rel\|1.7}}

	The Microsoft [[SSPI]] provides an interface for in-place encryption of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff). This interface also permits additional data to be included in the checksum generated to protect integrity. Such a facility is called authenticated encryption with additional data ([[AEAD]]).		The Microsoft [[SSPI]] provides an interface for in-place encryption of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff). This interface also permits additional data to be included in the checksum generated to protect integrity. Such a facility is called authenticated encryption with additional data ([[AEAD]]).

@@ Line 57: / Line 57: @@
 # Zero or more buffers of type KRB5_CRYPTO_TYPE_SIGN_ONLY
 # One buffer of type KRB5_CRYPTO_TYPE_DATA to hold the output
-This indicates that the caller does not know the decomposition of the encrypted data into header, trailer and data.  On successful return, the array is updated to replace the buffer of type KRB5_CRYPTO_TYPE_DATA to point to a subset of the stream buffer.  That subset of the stream buffer will be modified in place to contain the plaintext.
+This indicates that the caller does not know the decomposition of the encrypted data into header, trailer and data.  On successful return, the array is updated to replace the buffer of type KRB5_CRYPTO_TYPE_DATA to point to a subset of the stream buffer.  That subset will be modified in place to contain the plaintext.
 Note that on return from a krb5_c_*_iov call, the lengths in the iov structure are adjusted to reflect actual lengths used.  For example, if the padding length is too large, the length will be reduced.  Lengths are never increased.

@@ Line 54: / Line 54: @@
 An alternate calling sequence is supported for decryption.  The initial iov array may contain:
-# A buffer of type KRB5_CRYPTO_TYPE_STREAM
+# A buffer of type KRB5_CRYPTO_TYPE_STREAM containing the ciphertext (with header and trailer)
-# Zero  or more buffers of type KRB5_CRYPTO_TYPE_SIGN_ONLY
+# Zero or more buffers of type KRB5_CRYPTO_TYPE_SIGN_ONLY
 # One buffer of type KRB5_CRYPTO_TYPE_DATA to hold the output
-This indicates that the caller does not know the decomposition of the encrypted data into header, trailer and data.  On successful return, the array is updated to replace the buffer of type KRB5_CRYPTO_TYPE_STREAM with a buffer of KRB5_CRYPTO_TYPE_DATA pointing to a subset of the stream buffer.  That buffer will be modified in place to contain the plaintext.
+This indicates that the caller does not know the decomposition of the encrypted data into header, trailer and data.  On successful return, the array is updated to replace the buffer of type KRB5_CRYPTO_TYPE_DATA to point to a subset of the stream buffer.  That subset of the stream buffer will be modified in place to contain the plaintext.
 Note that on return from a krb5_c_*_iov call, the lengths in the iov structure are adjusted to reflect actual lengths used.  For example, if the padding length is too large, the length will be reduced.  Lengths are never increased.

← Older revision		Revision as of 18:37, 14 September 2009
Line 1:		Line 1:
−	{{project-~~approved~~}}	+	{{project-completed}}

	The Microsoft [[SSPI]] provides an interface for in-place encryption of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff). This interface also permits additional data to be included in the checksum generated to protect integrity. Such a facility is called authenticated encryption with additional data ([[AEAD]]).		The Microsoft [[SSPI]] provides an interface for in-place encryption of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff). This interface also permits additional data to be included in the checksum generated to protect integrity. Such a facility is called authenticated encryption with additional data ([[AEAD]]).

← Older revision		Revision as of 16:53, 16 December 2008
Line 1:		Line 1:
−	{{project-~~review\|December 5, 2008~~}}	+	{{project-approved}}

	The Microsoft [[SSPI]] provides an interface for in-place encryption of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff). This interface also permits additional data to be included in the checksum generated to protect integrity. Such a facility is called authenticated encryption with additional data ([[AEAD]]).		The Microsoft [[SSPI]] provides an interface for in-place encryption of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff). This interface also permits additional data to be included in the checksum generated to protect integrity. Such a facility is called authenticated encryption with additional data ([[AEAD]]).

← Older revision		Revision as of 16:05, 15 December 2008
Line 160:		Line 160:

	===Approvals===		===Approvals===
		+
		+	# [[User:TomYu\|TomYu]] 11:05, 15 December 2008 (EST)

	===Discussion===		===Discussion===

@@ Line 18: / Line 18: @@
 ==Basic approach==
 A new structure is defined: '''krb5_crypto_iov''' to describe a region of text to be encrypted or decrypted.
-<code>
+<pre>
 typedef struct _krb5_crypto_iov {
     krb5_cryptotype flags;
     krb5_data data;
 } krb5_crypto_iov;
-</code>
+</pre>
 The ''flags'' member describes the type of the iov.  The ''data'' member points to  the memory that will be manipulated.  All iov APIs take a pointer to an array of ''krb5_crypto_iov''s along with the size of that array. Buffer contents are manipulated in-place; data is overwritten.  Callers must allocate the right number of krb5_crypto_iov structures before calling into an iov API.
 Several types of krb5_crypto_iov are supported:
-<code>
+<pre>
 #define KRB5_CRYPTO_TYPE_EMPTY      0   /* [in] ignored */
 #define KRB5_CRYPTO_TYPE_HEADER     1   /* [out] header */
@@ Line 37: / Line 37: @@
 #define KRB5_CRYPTO_TYPE_CHECKSUM   6   /* [out] checksum for MIC */
 #define KRB5_CRYPTO_TYPE_STREAM 7       /* [in, out] An entire encrypted message for decryption*/
-</code>
+</pre>
 Typically the iov array would contain the following on a call to encryption functions:
@@ Line 67: / Line 67: @@
 * The header and trailer are read_only buffers on decryption
 * With the exception of adjusting the length when stream buffers are used, the iov array itself is read-only on decryption.
 ==Implementation notes==
@@ Line 84: / Line 80: @@
 The following APIs are introduced by this project:
-<code>
+<pre>
 krb5_error_code KRB5_CALLCONV
     krb5_c_make_checksum_iov
@@ Line 90: / Line 86: @@
                     const krb5_keyblock *key, krb5_keyusage usage,
                     krb5_crypto_iov *data, size_t num_data);
-</code>
+</pre>
 Create a checksum in the KRB5_CRYPTO_TYPE_CHECKSUM element over the data and sign_only chunks.  Only the KRB5_CRYPTO_TYPE_CHECKSUM region is modified.
-<code>
+<pre>
 krb5_error_code KRB5_CALLCONV
     krb5_c_verify_checksum_iov
@@ Line 103: / Line 99: @@
                     const krb5_crypto_iov *data, size_t num_data,
                     krb5_boolean *valid);
-</code>
+</pre>
 Confirm that the checksum in the KRB5_CRYPTO_TYPE_CHECKSUM element is a valid checksum of the data and sign_only regions in the iov.
-<code>
+<pre>
 krb5_error_code KRB5_CALLCONV
     krb5_c_encrypt_iov
@@ Line 118: / Line 114: @@
                     krb5_keyusage usage, const krb5_data *cipher_state,
                     krb5_crypto_iov *data, size_t num_data);
-</code>
+</pre>
 Encrypt or decrypt  data in place supporting AEAD.  The iov needs to contain entries as described in [[#Basic approach|the basic overview]].  Data chunks are modified in-place.
-<code>
+<pre>
 krb5_error_code KRB5_CALLCONV
     krb5_c_crypto_length
     (krb5_context context, krb5_enctype enctype,
                     krb5_cryptotype type, unsigned int *size);
-</code>
+</pre>
 Return the length needed for some data structure associated with an encryption system.
-<code>
+<pre>
 krb5_error_code KRB5_CALLCONV
     krb5_c_crypto_length_iov
     (krb5_context context, krb5_enctype enctype,
                     krb5_crypto_iov *data, size_t num_data);
-</code>
+</pre>
 Fill in the lengths in the iov array for header, trailer and padding.  Padding is set to the actual padding required based on the provided  data buffers.  Typically this API is used after setting up the data buffers and sign_only buffers, but before actually allocating header, trailer and padding.
-<code>
+<pre>
 krb5_error_code KRB5_CALLCONV
     krb5_c_padding_length
     (krb5_context context, krb5_enctype enctype,
                     size_t data_length, unsigned int *size);
-</code>
+</pre>
 Return the number of padding octets required to pad ''data_length'' octets of plaintext.
 ==Testing plan==
@@ Line 153: / Line 146: @@
 * Encrypt data with the iov APIs and confirm that if no sign_data is used, the traditional APIs can decrypt.
 * Encrypt data with a constant sign_data and decrypt to confirm that works
 ==Review==

@@ Line 41: / Line 41: @@
 Typically the iov array would contain the following on a call to encryption functions:
 # A header buffer of the appropriate length
-# One  data buffer
+# One or more data buffer
 # Zero or more sign_only buffers
 # A padding buffer of the appropriate length
@@ Line 63: / Line 63: @@
 ===Constraints===
 * relative ordering between sign_only and data chunks may or may not be preserved depending on the crypto system.  Modern crypto systems (not currently specified for use in Kerberos) such as those described in RFC 5116 handle sign_only data in a separate pass from encrypted data.  The existing Kerberos crypto systems have one pass, so an iov containing (data,sign_only,sign_only) will produce different results than one containing (sign_only,data,sign_only).  Thus applications should use a consistent order on sender and receiver but must not depend on this for security.
 * The header buffer must be the first buffer in the iov array.

@@ Line 1: / Line 1: @@
-{{project-early}}
+{{project-review|December 5, 2008}}
 The Microsoft [[SSPI]] provides an interface for in-place encryption  of messages (see [http://msdn2.microsoft.com/en-us/library/cc206927.aspx MS-KILE] section 3.4.5.4ff).  This interface also permits additional data to be included  in the checksum generated to protect integrity.  Such a facility is called authenticated encryption with additional data ([[AEAD]]).
@@ Line 150: / Line 150: @@
 * Encrypt data with the iov APIs and confirm that if no sign_data is used, the traditional APIs can decrypt.
 * Encrypt data with a constant sign_data and decrypt to confirm that works