Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
Am Mittwoch, 5. November 2014, 18:15:12 schrieb Tadeusz Struk: Hi Tadeusz, Hi, On 11/02/2014 12:35 PM, Stephan Mueller wrote: + * type: + - blkcipher for symmetric block ciphers blkcipher for synchronous block ciphers + - ablkcipher for asymmetric block ciphers ablkcipher for asynchronous block ciphers + - cipher for single block ciphers that may be used with an + additional template + - shash for symmetric message digest shash for synchronous message digest + - ahash for asymmetric message digest ahash for asynchronous message digest T. Thanks a lot for this hint: I do not know how often I said symmetric or asymmetric when in fact I meant synchronous and asynchronous Maybe I spent too much time in the crypto arena ;-) -- Ciao Stephan -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
Stephan, On Mon, Nov 03, 2014 at 03:18:29PM +0100, Stephan Mueller wrote: Am Montag, 3. November 2014, 08:34:39 schrieb Jonathan Corbet: These are all useful. But I wonder if it would be worth the effort to turn this inti a proper docbook document that automatically has everything together in one place? How do you suggest that is done? The API comments in the header file follow the Doxygen style. Note, Jason Cooper raised the concern that an API documentation separate from the code will surely deviate from the code relatively fast (although I do not really fear that as the kernel crypto API seems to be quite stable over the last years). Agreed. My primary concern was adding it in such a way which facilitates maintenance and keeping it in sync with the code. But as you say, the crypto API doesn't change much. thx, Jason. -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
Hi Stephan, Great docs! I think they will be very useful! Thanks! I only have 2 comments below. regards, Joy On Sun, 2014-11-02 at 21:35 +0100, Stephan Mueller wrote: The design of the kernel crypto API as well as hints to program with the kernel crypto API are given. The documentation contains: * design aspects of crypto API * develper specific hints * references to the API function description Signed-off-by: Stephan Mueller smuel...@chronox.de CC: Marek Vasut ma...@denx.de --- Documentation/crypto/crypto-API-spec.txt | 721 +++ 1 file changed, 721 insertions(+) create mode 100644 Documentation/crypto/crypto-API-spec.txt diff --git a/Documentation/crypto/crypto-API-spec.txt b/Documentation/crypto/crypto-API-spec.txt new file mode 100644 index 000..8a24c98 --- /dev/null +++ b/Documentation/crypto/crypto-API-spec.txt @@ -0,0 +1,721 @@ +Kernel Crypto API Interface Specification += + +The kernel crypto API offers a rich set of cryptographic ciphers as well as +other data transformation mechanisms and methods to invoke these. This document +contains a description of the API and provides example code. + +To understand and properly use the kernel crypto API a brief explanation of its +structure is given. Based on the architecture, the API can be separated into +different components. Following the architecture specification, hints to +developers of ciphers are provided. Pointers to the API function call +documentation are given at the end. + +The kernel crypto API refers to all algorithms as transformation. Therefore, a +cipher handle variable usually has the name tfm. Besides cryptographic +operations, the kernel crypto API also knows compression transforms and handles +them the same way as ciphers. + +The kernel crypto API serves the following entity types: + + * consumers requesting cryptographic services + + * data transformation implementations (typically ciphers) that + can be called by consumers using the kernel crypto API + +This specification is intended for consumers of the kernel crypto API as well +as for developers implementing ciphers. This API specification, however, does +not discusses all API calls available to data transformation implementations +((i.e. implementations of ciphers and other transformations (such as CRC or +even compression algorithms) that can register with the kernel crypto API). + +Note: The terms transformation and cipher algorithm are used interchangably. + + +Terminology +--- + +The transformation implementation is an actual code or interface to hardware +which implements a certain transformation with precisely defined behavior. + +The transformation object (TFM) is an instance of a transformation +implementation. There can be multiple transformation objects associated with +a single transformation implementation. Each of those transformation objects +is held by a crypto API consumer or another transformation. Transformation +object is allocated when a crypto API consumer requests a transformation +implementation. The consumer is then provided with a structure, which contains +a transformation object (TFM). + +The transformation context is private data associated with the transformation +object. + + +Kernel Crypto API Architecture +== + +Cipher algorithm types +-- + +The kernel crypto API provides different API calls for the following cipher +types: + + * Symmetric ciphers + + * AEAD ciphers + + * Message digest, including keyed message digest + + * Random number generation + + * User space interface + + +Ciphers and Templates +- + +The kernel crypto API provides implementations of single block ciphers and +message digests. In addition, the kernel crypto API provides numerous +templates that can be used in conjunction with the single block ciphers and +message digests. Templates include all types of block chaining mode, the HMAC +mechanism, etc. + +Single block ciphers and message digests can either be directly used by a +caller or invoked together with a template to form multi-block ciphers or keyed +message digests. + +A single block cipher may even be called with multiple templates. However, +templates cannot be used without a single cipher. Although you go into further explanation shortly, I think an example or two here might help reader to immediately grab concept. i.e. aes, cbc(aes), ... + + +Synchronous and asynchronous operation +-- + +The kernel crypto API provides synchronous and asynchronous API operations. + +When using the synchronous API operation, the caller invokes a cipher operation +which is performed synchronously by the kernel crypto API. That means, the +caller waits until the cipher
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
Hi, On 11/02/2014 12:35 PM, Stephan Mueller wrote: + * type: + - blkcipher for symmetric block ciphers blkcipher for synchronous block ciphers + - ablkcipher for asymmetric block ciphers ablkcipher for asynchronous block ciphers + - cipher for single block ciphers that may be used with an + additional template + - shash for symmetric message digest shash for synchronous message digest + - ahash for asymmetric message digest ahash for asynchronous message digest T. -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
On Sun, 02 Nov 2014 21:35:11 +0100 Stephan Mueller smuel...@chronox.de wrote: The design of the kernel crypto API as well as hints to program with the kernel crypto API are given. Cool to see this, thanks. Please forgive me if I go into full grumpy editor mode here. There's a lot of good information here, but I think it could be made better with a bit of effort... diff --git a/Documentation/crypto/crypto-API-spec.txt b/Documentation/crypto/crypto-API-spec.txt new file mode 100644 index 000..8a24c98 --- /dev/null +++ b/Documentation/crypto/crypto-API-spec.txt @@ -0,0 +1,721 @@ +Kernel Crypto API Interface Specification += + +The kernel crypto API offers a rich set of cryptographic ciphers as well as +other data transformation mechanisms and methods to invoke these. This document +contains a description of the API and provides example code. + +To understand and properly use the kernel crypto API a brief explanation of its +structure is given. Based on the architecture, the API can be separated into +different components. Following the architecture specification, hints to +developers of ciphers are provided. Pointers to the API function call +documentation are given at the end. + +The kernel crypto API refers to all algorithms as transformation. Therefore, a transformation*s* +cipher handle variable usually has the name tfm. Besides cryptographic +operations, the kernel crypto API also knows compression transforms and handles +them the same way as ciphers. Should that be s/transforms/transformations/ to keep the terminology consistent? +The kernel crypto API serves the following entity types: + + * consumers requesting cryptographic services + + * data transformation implementations (typically ciphers) that + can be called by consumers using the kernel crypto API + +This specification is intended for consumers of the kernel crypto API as well +as for developers implementing ciphers. This API specification, however, does +not discusses all API calls available to data transformation implementations +((i.e. implementations of ciphers and other transformations (such as CRC or +even compression algorithms) that can register with the kernel crypto API). + +Note: The terms transformation and cipher algorithm are used interchangably. + + +Terminology +--- + +The transformation implementation is an actual code or interface to hardware +which implements a certain transformation with precisely defined behavior. + +The transformation object (TFM) is an instance of a transformation +implementation. There can be multiple transformation objects associated with +a single transformation implementation. Each of those transformation objects +is held by a crypto API consumer or another transformation. Transformation +object is allocated when a crypto API consumer requests a transformation +implementation. The consumer is then provided with a structure, which contains +a transformation object (TFM). It seems like it would be good to show what this object is and how to allocate it here, rather than just teasing the reader saying it's possible? +The transformation context is private data associated with the transformation +object. + + +Kernel Crypto API Architecture +== + +Cipher algorithm types +-- + +The kernel crypto API provides different API calls for the following cipher +types: + + * Symmetric ciphers + + * AEAD ciphers + + * Message digest, including keyed message digest + + * Random number generation + + * User space interface + + +Ciphers and Templates +- + +The kernel crypto API provides implementations of single block ciphers and +message digests. In addition, the kernel crypto API provides numerous +templates that can be used in conjunction with the single block ciphers and +message digests. Templates include all types of block chaining mode, the HMAC +mechanism, etc. + +Single block ciphers and message digests can either be directly used by a +caller or invoked together with a template to form multi-block ciphers or keyed +message digests. + +A single block cipher may even be called with multiple templates. However, +templates cannot be used without a single cipher. + + +Synchronous and asynchronous operation +-- + +The kernel crypto API provides synchronous and asynchronous API operations. + +When using the synchronous API operation, the caller invokes a cipher operation +which is performed synchronously by the kernel crypto API. That means, the +caller waits until the cipher operation completes. Therefore, the kernel crypto +API calls work like regular function calls. For synchronous operation, the set +of API calls is small and conceptually similar to any other crypto library. +
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
Am Montag, 3. November 2014, 08:34:39 schrieb Jonathan Corbet: Hi Jonathan, On Sun, 02 Nov 2014 21:35:11 +0100 Stephan Mueller smuel...@chronox.de wrote: The design of the kernel crypto API as well as hints to program with the kernel crypto API are given. Cool to see this, thanks. Please forgive me if I go into full grumpy editor mode here. There's a lot of good information here, but I think it could be made better with a bit of effort... Thanks for your comments. I will include your suggestions into a new patch set. Once you staring at that documentation for too long, you will not find errors any more :-) [...] + + * CRYPTO_ALG_TYPE_CIPHER Raw block cipher + * CRYPTO_ALG_TYPE_COMPRESSCompression + * CRYPTO_ALG_TYPE_AEADAuthenticated Encryption with Associated Data (MAC) + * CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher + * CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher + * CRYPTO_ALG_TYPE_GIVCIPHER What's this one? I would like to ask Herbert what that is -- I looked around in the code and I am not sure what that flag shall indicate. + * CRYPTO_ALG_TYPE_DIGEST Raw message digest + * CRYPTO_ALG_TYPE_HASHAlias for CRYPTO_ALG_TYPE_DIGEST + * CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash + * CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash + * CRYPTO_ALG_TYPE_RNG Random Number Generation + * CRYPTO_ALG_TYPE_PCOMPRESS What's that last one? Same here. [...] +Specifics of asynchronous multi-block cipher + + +There are a couple of specifics to the [ABLKCIPHER] interface. + +First of all, some of the drivers will want to use the Generic ScatterWalk +in case the hardware needs to be fed separate chunks of the scatterlist +which contains the plaintext and will contain the ciphertext. Please refer +below for a description and usage of the Generic ScatterWalk interface. + +It is recommended to enqueue cryptographic transformation requests into +generic crypto queues. This allows for these requests to be processed in +sequence as the cryptographic hardware becomes free. What's a generic crypto queue? That's a new concept. Right. I do not claim to have all completed right from the start. If so, there is much more: the AEAD and RNG implementation details are missing here too. Therefore, I thought I could leave it open for the moment to add in later. [..] These are all useful. But I wonder if it would be worth the effort to turn this inti a proper docbook document that automatically has everything together in one place? How do you suggest that is done? The API comments in the header file follow the Doxygen style. Note, Jason Cooper raised the concern that an API documentation separate from the code will surely deviate from the code relatively fast (although I do not really fear that as the kernel crypto API seems to be quite stable over the last years). Can you point me to an example about what you have in mind? I see the Documentation/DocBook/ files, but I do not see how they integrate Doxygen-like source code comments added to functions. + +Authors +=== + +Stephan Mueller smuel...@chronox.de +Marek Vasut ma...@denx.de jon -- Ciao Stephan -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
On Mon, Nov 03, 2014 at 03:18:29PM +0100, Stephan Mueller wrote: + * CRYPTO_ALG_TYPE_CIPHERRaw block cipher + * CRYPTO_ALG_TYPE_COMPRESS Compression + * CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data (MAC) + * CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher + * CRYPTO_ALG_TYPE_ABLKCIPHERAsynchronous multi-block cipher + * CRYPTO_ALG_TYPE_GIVCIPHER What's this one? I would like to ask Herbert what that is -- I looked around in the code and I am not sure what that flag shall indicate. givcipher is an ablkcipher packed together with an IV generator. Cheers, -- Email: Herbert Xu herb...@gondor.apana.org.au Home Page: http://gondor.apana.org.au/~herbert/ PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
On Mon, Nov 03, 2014 at 03:18:29PM +0100, Stephan Mueller wrote: + * CRYPTO_ALG_TYPE_DIGESTRaw message digest + * CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST + * CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash + * CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash + * CRYPTO_ALG_TYPE_RNG Random Number Generation + * CRYPTO_ALG_TYPE_PCOMPRESS What's that last one? Same here. pcompress is an enhanced version of compress allowing for piece-meal compression/decompression rather than having to shove everything in all at once. Eventually pcompress should replace the compress interface once everything is converted across. Thanks, -- Email: Herbert Xu herb...@gondor.apana.org.au Home Page: http://gondor.apana.org.au/~herbert/ PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
On 11/03/2014 08:49 AM, Herbert Xu wrote: On Mon, Nov 03, 2014 at 03:18:29PM +0100, Stephan Mueller wrote: + * CRYPTO_ALG_TYPE_DIGEST Raw message digest + * CRYPTO_ALG_TYPE_HASHAlias for CRYPTO_ALG_TYPE_DIGEST + * CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash + * CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash + * CRYPTO_ALG_TYPE_RNG Random Number Generation + * CRYPTO_ALG_TYPE_PCOMPRESS What's that last one? Same here. pcompress is an enhanced version of compress allowing for piece-meal compression/decompression rather than having to shove everything in all at once. Eventually pcompress should replace the compress interface once everything is converted across. Herbert, I was looking at adding async support for ALG_TYPE_COMPRESS since the CCP device will support compression/decompression but only as an everything at once invocation. Given what you're saying about pcompress replacing compress, would this be something you'd even consider though? Thanks, Tom Thanks, -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec
On Mon, 03 Nov 2014 15:18:29 +0100 Stephan Mueller smuel...@chronox.de wrote: These are all useful. But I wonder if it would be worth the effort to turn this inti a proper docbook document that automatically has everything together in one place? How do you suggest that is done? See Documentation/kernel-doc-nano-HOWTO.txt for an introduction to the process. This documentation hasn't seen a lot of maintenance recently, but I don't think things have changed too much. Should check that when I get a chance... Thanks, jon -- To unsubscribe from this list: send the line unsubscribe linux-crypto in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
