Commit addfda2f authored by Stephan Mueller's avatar Stephan Mueller Committed by Herbert Xu
Browse files

crypto: doc - cover new AEAD interface 



The patch updates the DocBook to cover the new AEAD interface
implementation.

Signed-off-by: default avatarStephan Mueller <smueller@chronox.de>
Signed-off-by: default avatarHerbert Xu <herbert@gondor.apana.org.au>
parent b64a2d95

Documentation/DocBook/crypto-API.tmpl

+17 −6
Original line number Diff line number Diff line
@@ -536,8 +536,8 @@ 


     <para>

      For other use cases of AEAD ciphers, the ASCII art applies as

      well, but the caller may not use the GIVCIPHER interface. In

      this case, the caller must generate the IV.

      well, but the caller may not use the AEAD cipher with a separate

      IV generator. In this case, the caller must generate the IV.

     </para>



     <para>
@@ -584,8 +584,8 @@ kernel crypto API | IPSEC Layer 
                                                 |

+-----------+                                    |

|           |            (1)

| givcipher | <-----------------------------------  esp_output

|  (seqiv)  | ---+

|   aead    | <-----------------------------------  esp_output

| (seqniv)  | ---+

+-----------+    |

                 | (2)

+-----------+    |
@@ -620,8 +620,8 @@ kernel crypto API | IPSEC Layer 
     <orderedlist>

      <listitem>

       <para>

        esp_output() invokes crypto_aead_givencrypt() to trigger an encryption

        operation of the GIVCIPHER implementation.

        esp_output() invokes crypto_aead_encrypt() to trigger an encryption

        operation of the AEAD cipher with IV generator.

       </para>



       <para>
@@ -1669,6 +1669,16 @@ read(opfd, out, outlen); 
  </chapter>



  <chapter id="API"><title>Programming Interface</title>

   <para>

    Please note that the kernel crypto API contains the AEAD givcrypt

    API (crypto_aead_giv* and aead_givcrypt_* function calls in

    include/crypto/aead.h). This API is obsolete and will be removed

    in the future. To obtain the functionality of an AEAD cipher with

    internal IV generation, use the IV generator as a regular cipher.

    For example, rfc4106(gcm(aes)) is the AEAD cipher with external

    IV generation and seqniv(rfc4106(gcm(aes))) implies that the kernel

    crypto API generates the IV. Different IV generators are available.

   </para>

   <sect1><title>Block Cipher Context Data Structures</title>

!Pinclude/linux/crypto.h Block Cipher Context Data Structures

!Finclude/crypto/aead.h aead_request
@@ -1724,6 +1734,7 @@ read(opfd, out, outlen); 
!Finclude/crypto/aead.h aead_request_set_callback

!Finclude/crypto/aead.h aead_request_set_crypt

!Finclude/crypto/aead.h aead_request_set_assoc

!Finclude/crypto/aead.h aead_request_set_ad

   </sect1>

   <sect1><title>Synchronous Block Cipher API</title>

!Pinclude/linux/crypto.h Synchronous Block Cipher API

include/crypto/aead.h

+4 −1
Original line number Diff line number Diff line
@@ -50,6 +50,7 @@ 
/**

 *	struct aead_request - AEAD request

 *	@base: Common attributes for async crypto requests

 *	@old: Boolean whether the old or new AEAD API is used

 *	@assoclen: Length in bytes of associated data for authentication

 *	@cryptlen: Length of data to be encrypted or decrypted

 *	@iv: Initialisation vector
@@ -467,7 +468,9 @@ static inline void aead_request_set_callback(struct aead_request *req, 
 * @iv: IV for the cipher operation which must comply with the IV size defined

 *      by crypto_aead_ivsize()

 *

 * Setting the source data and destination data scatter / gather lists.

 * Setting the source data and destination data scatter / gather lists which

 * hold the associated data concatenated with the plaintext or ciphertext. See

 * below for the authentication tag.

 *

 * For encryption, the source is treated as the plaintext and the

 * destination is the ciphertext. For a decryption operation, the use is