Re: [PATCH] kernel crypto API interface specification

2014-10-31 Thread Herbert Xu 
On Fri, Oct 31, 2014 at 04:01:04AM +0100, Marek Vasut wrote:

 I can share the last state of the document I wrote. Currently,
 it is not possible for me to keep up with my workload and do
 anything else, so that's all I can do.

Posting your latest revision would be great.

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] kernel crypto API interface specification

2014-10-31 Thread Marek Vasut 
On Friday, October 31, 2014 at 08:23:53 AM, Herbert Xu wrote:
 On Fri, Oct 31, 2014 at 04:01:04AM +0100, Marek Vasut wrote:
  I can share the last state of the document I wrote. Currently,
  it is not possible for me to keep up with my workload and do
  anything else, so that's all I can do.
 
 Posting your latest revision would be great.

Please see below, mine is much less complete than Stephan's though
and likely contains some bugs.

Linux Crypto API :: Drivers
===

This document outlines how to implement drivers for cryptographic hardware.
The Linux Crypto API supports different types of transformations and we will
explain here how to write drivers for each one of them.

Note: Transformation and algorithm are used interchangably

Note: We support multiple transformation types:
  CIPHER ... Simple single-block cipher
  BLKCIPHER  Synchronous multi-block cipher
  ABLKCIPHER ... Asynchronous multi-block cipher
  SHASH  Synchronous multi-block hash
  AHASH  Asynchronous multi-block hash
  AEAD . Authenticated Encryption with Associated Data (MAC)
  COMPRESS . Compression
  RNG .. Random Number Generation

0) Terminology
--
 - The transformation implementation is an actual code or interface to hardware
   which implements a certain trasformation with percisely 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. 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.

1) The struct crypto_alg description

 The struct crypto_alg describes a generic Crypto API algorithm and is common
 for all of the transformations. We will first explain what each entry means
 as this is a fundamental building block. We will not follow the order of
 fields as defined in include/linux/crypto.h , but will instead explain them
 in logical order.

  .cra_name .. Name of the transformation algorithm .
   - This is the name of the transformation itself. This
 field is used by the kernel when looking up the
 providers of particular transformation.
   - Examples: md5, cbc(cast5), rfc4106(gcm(aes))
   - You can find a good approximation for values of this
 field by running:
 $ git grep tcrypt_test crypto/tcrypt.c
  .cra_driver_name ... Name of the transformation provider .
   - This is the name of the provider of the transformation.
 This can be any arbitrary value, but in the usual case,
 this contains the name of the chip or provider and the
 name of the transformation algorithm.
   - Examples: sha1-dcp, atmel-ecb-aes
  .cra_priority .. Priority of this transformation implementation.
   - In case multiple transformations with same .cra_name
 are available to the Crypto API, the kernel will use
 the one with highest .cra_priority .
   - The software implementations of transformations have
 this field set to 0 so they are picked only in case
 no other higher-priority implementation is available.
  .cra_module  Owner of this transformation implementation.
   - Set to THIS_MODULE .

  .cra_blocksize . Minimum block size of this transformation.
   - The size in bytes of the smallest possible unit which
 can be transformed with this algorithm. The users must
 respect this value.
   - In case of HASH transformation, it is possible for a
 smaller block than .cra_blocksize to be passed to the
 crypto API for transformation, in case of any other
 transformation type, an error will be returned upon
 any attempt to transform smaller than .cra_blocksize
 chunks.
   - Examples: SHA1_BLOCK_SIZE, AES_BLOCK_SIZE
   - You can find predefined values for this field in the
 kernel source tree with:
 $ git grep _BLOCK_SIZE include/crypto/
  .cra_alignmask . Alignment mask for the input and output data buffer.

Re: [PATCH] kernel crypto API interface specification

2014-10-31 Thread Stephan Mueller 
Am Freitag, 31. Oktober 2014, 10:09:52 schrieb Marek Vasut:

Hi Marek,

 On Friday, October 31, 2014 at 08:23:53 AM, Herbert Xu wrote:
  On Fri, Oct 31, 2014 at 04:01:04AM +0100, Marek Vasut wrote:
   I can share the last state of the document I wrote. Currently,
   it is not possible for me to keep up with my workload and do
   anything else, so that's all I can do.
  
  Posting your latest revision would be great.
 
 Please see below, mine is much less complete than Stephan's though
 and likely contains some bugs.

Thank you for sharing.

I am in the last innings to complete a new patch set. I will see to merge your 
documentation with mine.

The upcoming patchset will cover the following changes:

- split out the user space interface documentation (and fix a bug -- I forgot 
a memset(0) in there)

- keep the high-level description in a document in Documentation/crypto/

- put the API function documentation into the header files (I hope that is ok 
that I touch these files to add comments)

-- 
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] kernel crypto API interface specification

2014-10-30 Thread Marek Vasut 
On Thursday, October 16, 2014 at 03:10:07 PM, Herbert Xu wrote:
 On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
  The update adds a complete interface documentation of the kernel crypto
  API. All cipher types supported by the kernel crypto API are documented.
  
  In addition, kernel and user space example code is provided. The sample
  code covers synchronous and asynchronous cipher operation, random
  number generation and performing hashing as well as encryption and
  decryption in user space.
  
  Signed-off-by: Stephan Mueller smuel...@chronox.de
 
 Thanks for the patch Stephan!
 
 Marek Vasut ma...@denx.de has also been working on a set of
 documentation for the crypto API so he might have some comments
 on this.

Sorry for the late reply, thanks for keeping me in the loop.

I can share the last state of the document I wrote. Currently,
it is not possible for me to keep up with my workload and do
anything else, so that's all I can do.

Apologies.

Best regards,
Marek Vasut
--
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] kernel crypto API interface specification

2014-10-16 Thread Stephan Mueller 
Am Mittwoch, 15. Oktober 2014, 13:58:00 schrieb Jason Cooper:

Hi Jason,

 Stephan,
 
 Wow.  This is very thorough.  Herbert and others will be making the
 final call on this, but if I may make a suggestion:

Thanks.
 
 On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
  The update adds a complete interface documentation of the kernel crypto
  API. All cipher types supported by the kernel crypto API are documented.
  
  In addition, kernel and user space example code is provided. The sample
  code covers synchronous and asynchronous cipher operation, random
  number generation and performing hashing as well as encryption and
  decryption in user space.
 
 This really needs to be split into at least two pieces.  The kernel and
 the userspace API.  I'd venture to say the userspace API portion of this
 document is almost ready.  But I'm not certain that the kernel
 interfaces are best described in a specification.

Good idea, I will split it.
 
 APIs within the kernel are intentionally not nailed down and are very
 fluid.  Any attempt to spell them out in a document would mean either a)
 the document would be out of date quickly, or b) the maintainer now has
 to ask for changes to the docs every time a patch with a kernel API
 change comes in.  Neither scenario is good. :-(

Right, but on the other hand having no documentation at all is also bad. I 
know first hand how non-straight-forward it is to use the kernel crypto API as 
I programmed a test kernel module that invokes all cipher types available. 
Even with the examples in testmgr.c, I had a number of trial and errors. For 
crypto, this is not good.

Note, the mistakes you make are not easily seen, which is a problem if you 
want to protect data :-)

The key problem is that the kernel crypto API makes some assumptions on the 
memory layout and the concept of asymmetric requests. Furthermore, the AEAD 
definitions require different data types than offered by the API. That means 
the calling code must first massage the AEAD input data (see CCM IV vs nonce 
or the CCM/GCM tag handling).

Yet, I also see that a separate documentation may easily deviate from the real 
code (I know that first hand as I have to document parts of the kernel for 
some projects :-) ). Therefore I also suggested to take the API call 
documentation out and put it into the header files where the API calls are 
specified.
 
 We certainly don't want to lose all of the effort you've put into
 grokking the API, so we need to find a maintainable place to add it.  I
 personally think adding comments above the respective function
 blocks would work well.

Right, as I also suggested in my follow-up email. Yet, I would like to hear an 
ok from the maintainers that I can touch these files.
 
 The examples (kernel API) are another matter entirely.  Examples that
 aren't up-to-date and usable as a template aren't helpful to anyone.
 Some would even say detrimental.  And since example code isn't actually
 *used* in the real world, it would be an extra burden keeping it up to
 date.  I think these could best be used as a reference to compare all of
 the current users to.  Anything not up to par would generate a patch.
 The best examples should be the current users in the kernel.

Yes, that is what I also fear. Yet, using the asynchronous API may not be 
straight forward. Especially AEAD has some non-obvious requirements that may 
be documented best with an example. Yet, the example may be stripped down 
drastically to focus on the key aspects.
 
  Signed-off-by: Stephan Mueller smuel...@chronox.de
  ---
  
   Documentation/crypto/crypto-API-spec.txt | 2110
   ++ 1 file changed, 2110 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..027fd4f
  --- /dev/null
  +++ b/Documentation/crypto/crypto-API-spec.txt
  @@ -0,0 +1,2110 @@
 
 [snip detailed explanation of current kernel API]
 
  +User space API
  +==
  +
  +The kernel crypto API is accessible from user space. Currently, the
  following +ciphers are accessible:
  +
  +   * Message digest including keyed message digest
  +
  +   * Symmetric ciphers
  +
  +The interface is provided via Netlink using the type AF_ALG. In addition,
  the +setsockopt option type is SOL_ALG. In case the user space header
  files do not +export these flags yet, use the following macros:
  +
  +#ifndef AF_ALG
  +#define AF_ALG 38
  +#endif
  +#ifndef SOL_ALG
  +#define SOL_ALG 279
  +#endif
  +
  +A cipher is accessed with the same name as done for the in-kernel API
  calls.
 Perhaps a reference here to the final location of the kernel API
 explanations?

As I have now split out the user space API documentation from the rest. That 
document now refers back to the initial kernel-related API document.

That said, I added a precise reference to the cipher

Re: [PATCH] kernel crypto API interface specification

2014-10-16 Thread Jason Cooper 
+ Grant, Geert,

Stephan has created some great example code for both the kernel crypto
API and the userspace crypto API.  As examples tend to bitrot, I was
wondering if the code could serve as test code.  Then it would have a
triple role: API regression testing, crypto test suite, and reference
implementation.

Original patch is here:

  https://lkml.kernel.org/r/7502136.9bkwhtz...@myon.chronox.de

On Thu, Oct 16, 2014 at 09:19:08AM +0200, Stephan Mueller wrote:
 Am Mittwoch, 15. Oktober 2014, 13:58:00 schrieb Jason Cooper:
 
 Hi Jason,
 
  Stephan,
  
  Wow.  This is very thorough.  Herbert and others will be making the
  final call on this, but if I may make a suggestion:
 
 Thanks.
  
  On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
   The update adds a complete interface documentation of the kernel crypto
   API. All cipher types supported by the kernel crypto API are documented.
   
   In addition, kernel and user space example code is provided. The sample
   code covers synchronous and asynchronous cipher operation, random
   number generation and performing hashing as well as encryption and
   decryption in user space.
  
  This really needs to be split into at least two pieces.  The kernel and
  the userspace API.  I'd venture to say the userspace API portion of this
  document is almost ready.  But I'm not certain that the kernel
  interfaces are best described in a specification.
 
 Good idea, I will split it.
  
  APIs within the kernel are intentionally not nailed down and are very
  fluid.  Any attempt to spell them out in a document would mean either a)
  the document would be out of date quickly, or b) the maintainer now has
  to ask for changes to the docs every time a patch with a kernel API
  change comes in.  Neither scenario is good. :-(
 
 Right, but on the other hand having no documentation at all is also bad. I 
 know first hand how non-straight-forward it is to use the kernel crypto API 
 as 
 I programmed a test kernel module that invokes all cipher types available. 
 Even with the examples in testmgr.c, I had a number of trial and errors. For 
 crypto, this is not good.
 
 Note, the mistakes you make are not easily seen, which is a problem if you 
 want to protect data :-)
 
 The key problem is that the kernel crypto API makes some assumptions on the 
 memory layout and the concept of asymmetric requests. Furthermore, the AEAD 
 definitions require different data types than offered by the API. That means 
 the calling code must first massage the AEAD input data (see CCM IV vs nonce 
 or the CCM/GCM tag handling).
 
 Yet, I also see that a separate documentation may easily deviate from the 
 real 
 code (I know that first hand as I have to document parts of the kernel for 
 some projects :-) ). Therefore I also suggested to take the API call 
 documentation out and put it into the header files where the API calls are 
 specified.
  
  We certainly don't want to lose all of the effort you've put into
  grokking the API, so we need to find a maintainable place to add it.  I
  personally think adding comments above the respective function
  blocks would work well.
 
 Right, as I also suggested in my follow-up email. Yet, I would like to hear 
 an 
 ok from the maintainers that I can touch these files.

That's like asking if you can ask a question.  Just do it.  :-)

  The examples (kernel API) are another matter entirely.  Examples that
  aren't up-to-date and usable as a template aren't helpful to anyone.
  Some would even say detrimental.  And since example code isn't actually
  *used* in the real world, it would be an extra burden keeping it up to
  date.  I think these could best be used as a reference to compare all of
  the current users to.  Anything not up to par would generate a patch.
  The best examples should be the current users in the kernel.
 
 Yes, that is what I also fear. Yet, using the asynchronous API may not be 
 straight forward. Especially AEAD has some non-obvious requirements that may 
 be documented best with an example. Yet, the example may be stripped down 
 drastically to focus on the key aspects.

Perhaps extending testmgr.c with your example code would be the best
answer.  There has been a push recently to have more comprehensive test
suites within the kernel.  If the test code is run often, it would make
a reasonable place for 'reference' implementations.

   Signed-off-by: Stephan Mueller smuel...@chronox.de
   ---
   
Documentation/crypto/crypto-API-spec.txt | 2110
++ 1 file changed, 2110 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..027fd4f
   --- /dev/null
   +++ b/Documentation/crypto/crypto-API-spec.txt
   @@ -0,0 +1,2110 @@
  
  [snip detailed explanation of current kernel API]
  
   +User space API

Re: [PATCH] kernel crypto API interface specification

2014-10-16 Thread Jason Cooper 


On Thu, Oct 16, 2014 at 09:25:01AM -0400, Jason Cooper wrote:
 + Grant, Geert,

oops.  It helps if I actually *add* them.  Sorry for the noise.

 Stephan has created some great example code for both the kernel crypto
 API and the userspace crypto API.  As examples tend to bitrot, I was
 wondering if the code could serve as test code.  Then it would have a
 triple role: API regression testing, crypto test suite, and reference
 implementation.
 
 Original patch is here:
 
   https://lkml.kernel.org/r/7502136.9bkwhtz...@myon.chronox.de
 
 On Thu, Oct 16, 2014 at 09:19:08AM +0200, Stephan Mueller wrote:
  Am Mittwoch, 15. Oktober 2014, 13:58:00 schrieb Jason Cooper:
  
  Hi Jason,
  
   Stephan,
   
   Wow.  This is very thorough.  Herbert and others will be making the
   final call on this, but if I may make a suggestion:
  
  Thanks.
   
   On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
The update adds a complete interface documentation of the kernel crypto
API. All cipher types supported by the kernel crypto API are documented.

In addition, kernel and user space example code is provided. The sample
code covers synchronous and asynchronous cipher operation, random
number generation and performing hashing as well as encryption and
decryption in user space.
   
   This really needs to be split into at least two pieces.  The kernel and
   the userspace API.  I'd venture to say the userspace API portion of this
   document is almost ready.  But I'm not certain that the kernel
   interfaces are best described in a specification.
  
  Good idea, I will split it.
   
   APIs within the kernel are intentionally not nailed down and are very
   fluid.  Any attempt to spell them out in a document would mean either a)
   the document would be out of date quickly, or b) the maintainer now has
   to ask for changes to the docs every time a patch with a kernel API
   change comes in.  Neither scenario is good. :-(
  
  Right, but on the other hand having no documentation at all is also bad. I 
  know first hand how non-straight-forward it is to use the kernel crypto API 
  as 
  I programmed a test kernel module that invokes all cipher types available. 
  Even with the examples in testmgr.c, I had a number of trial and errors. 
  For 
  crypto, this is not good.
  
  Note, the mistakes you make are not easily seen, which is a problem if you 
  want to protect data :-)
  
  The key problem is that the kernel crypto API makes some assumptions on the 
  memory layout and the concept of asymmetric requests. Furthermore, the AEAD 
  definitions require different data types than offered by the API. That 
  means 
  the calling code must first massage the AEAD input data (see CCM IV vs 
  nonce 
  or the CCM/GCM tag handling).
  
  Yet, I also see that a separate documentation may easily deviate from the 
  real 
  code (I know that first hand as I have to document parts of the kernel for 
  some projects :-) ). Therefore I also suggested to take the API call 
  documentation out and put it into the header files where the API calls are 
  specified.
   
   We certainly don't want to lose all of the effort you've put into
   grokking the API, so we need to find a maintainable place to add it.  I
   personally think adding comments above the respective function
   blocks would work well.
  
  Right, as I also suggested in my follow-up email. Yet, I would like to hear 
  an 
  ok from the maintainers that I can touch these files.
 
 That's like asking if you can ask a question.  Just do it.  :-)
 
   The examples (kernel API) are another matter entirely.  Examples that
   aren't up-to-date and usable as a template aren't helpful to anyone.
   Some would even say detrimental.  And since example code isn't actually
   *used* in the real world, it would be an extra burden keeping it up to
   date.  I think these could best be used as a reference to compare all of
   the current users to.  Anything not up to par would generate a patch.
   The best examples should be the current users in the kernel.
  
  Yes, that is what I also fear. Yet, using the asynchronous API may not be 
  straight forward. Especially AEAD has some non-obvious requirements that 
  may 
  be documented best with an example. Yet, the example may be stripped down 
  drastically to focus on the key aspects.
 
 Perhaps extending testmgr.c with your example code would be the best
 answer.  There has been a push recently to have more comprehensive test
 suites within the kernel.  If the test code is run often, it would make
 a reasonable place for 'reference' implementations.
 
Signed-off-by: Stephan Mueller smuel...@chronox.de
---

 Documentation/crypto/crypto-API-spec.txt | 2110
 ++ 1 file changed, 2110 insertions(+)
 create mode 100644 Documentation/crypto/crypto-API-spec.txt

diff --git a/Documentation/crypto/crypto-API-spec.txt

Re: [PATCH] kernel crypto API interface specification

2014-10-16 Thread Jason Cooper 
On Thu, Oct 16, 2014 at 09:25:01AM -0400, Jason Cooper wrote:
 + Grant, Geert,
 
 Stephan has created some great example code for both the kernel crypto
 API and the userspace crypto API.  As examples tend to bitrot, I was
 wondering if the code could serve as test code.  Then it would have a
 triple role: API regression testing, crypto test suite, and reference
 implementation.
 
 Original patch is here:
 
   https://lkml.kernel.org/r/7502136.9bkwhtz...@myon.chronox.de
 
 On Thu, Oct 16, 2014 at 09:19:08AM +0200, Stephan Mueller wrote:
  Am Mittwoch, 15. Oktober 2014, 13:58:00 schrieb Jason Cooper:
   On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
...
   Perhaps the userspace API example should be a separate file with this
   text at the top?  Seems odd having it at the end.  Also, if you copied
   it from cryptsetup, is the copyright info correct?
  
  I did not copy it from cryptsetup. I only used it as a basis, especially 
  with 
  the data structure handling in _kcapi_cipher_crypt. But you are right, I 
  changed the license for the user space by taking the cryptsetup license.
 
 Ok.  It looks like Geert and Grant took part in the kernel test
 unconference, so I'm adding them to the Cc.  I hope they can give us
 some pointers as to where we could hook in this code.  Then we can
 simply refer to it from the userspace API document.

tools/testing/selftests/crypto would be a good location for the example
code in the next version of this patch.  Make sure to take a look at
tools/testing/selftests/README.txt.

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] kernel crypto API interface specification

2014-10-16 Thread Jason Cooper 
On Thu, Oct 16, 2014 at 06:50:58PM +0200, Stephan Mueller wrote:
 Am Donnerstag, 16. Oktober 2014, 11:06:05 schrieb Jason Cooper:
 
 Hi Jason,
 
  On Thu, Oct 16, 2014 at 09:25:01AM -0400, Jason Cooper wrote:
   + Grant, Geert,
   
   Stephan has created some great example code for both the kernel crypto
   API and the userspace crypto API.  As examples tend to bitrot, I was
   wondering if the code could serve as test code.  Then it would have a
   triple role: API regression testing, crypto test suite, and reference
   implementation.
   
   Original patch is here:
 https://lkml.kernel.org/r/7502136.9bkwhtz...@myon.chronox.de
   
   On Thu, Oct 16, 2014 at 09:19:08AM +0200, Stephan Mueller wrote:
Am Mittwoch, 15. Oktober 2014, 13:58:00 schrieb Jason Cooper:
 On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
  ...
  
 Perhaps the userspace API example should be a separate file with this
 text at the top?  Seems odd having it at the end.  Also, if you copied
 it from cryptsetup, is the copyright info correct?

I did not copy it from cryptsetup. I only used it as a basis, especially
with the data structure handling in _kcapi_cipher_crypt. But you are
right, I changed the license for the user space by taking the
cryptsetup license. 
   Ok.  It looks like Geert and Grant took part in the kernel test
   unconference, so I'm adding them to the Cc.  I hope they can give us
   some pointers as to where we could hook in this code.  Then we can
   simply refer to it from the userspace API document.
  
  tools/testing/selftests/crypto would be a good location for the example
  code in the next version of this patch.  Make sure to take a look at
  tools/testing/selftests/README.txt.
 
 Well, I have written a FIPS 140-2 CAVS test harness covering all ciphers NIST 
 is interested. Maybe this can go there?

Assuming you own the code and are willing to license it under and
compatible license, then yes.  I would keep it a separate test from
other crypto tests, though.

There may be some push back wrt it being FIPS 140-2.  But I think it's
worth considering.

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] kernel crypto API interface specification

2014-10-15 Thread Jason Cooper 
Stephan,

Wow.  This is very thorough.  Herbert and others will be making the
final call on this, but if I may make a suggestion:

On Tue, Oct 14, 2014 at 09:46:50PM +0200, Stephan Mueller wrote:
 The update adds a complete interface documentation of the kernel crypto
 API. All cipher types supported by the kernel crypto API are documented.
 
 In addition, kernel and user space example code is provided. The sample
 code covers synchronous and asynchronous cipher operation, random
 number generation and performing hashing as well as encryption and
 decryption in user space.

This really needs to be split into at least two pieces.  The kernel and
the userspace API.  I'd venture to say the userspace API portion of this
document is almost ready.  But I'm not certain that the kernel
interfaces are best described in a specification.

APIs within the kernel are intentionally not nailed down and are very
fluid.  Any attempt to spell them out in a document would mean either a)
the document would be out of date quickly, or b) the maintainer now has
to ask for changes to the docs every time a patch with a kernel API
change comes in.  Neither scenario is good. :-(

We certainly don't want to lose all of the effort you've put into
grokking the API, so we need to find a maintainable place to add it.  I
personally think adding comments above the respective function
blocks would work well.

The examples (kernel API) are another matter entirely.  Examples that
aren't up-to-date and usable as a template aren't helpful to anyone.
Some would even say detrimental.  And since example code isn't actually
*used* in the real world, it would be an extra burden keeping it up to
date.  I think these could best be used as a reference to compare all of
the current users to.  Anything not up to par would generate a patch.
The best examples should be the current users in the kernel.

 Signed-off-by: Stephan Mueller smuel...@chronox.de
 ---
  Documentation/crypto/crypto-API-spec.txt | 2110 
 ++
  1 file changed, 2110 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..027fd4f
 --- /dev/null
 +++ b/Documentation/crypto/crypto-API-spec.txt
 @@ -0,0 +1,2110 @@

[snip detailed explanation of current kernel API]

 +User space API
 +==
 +
 +The kernel crypto API is accessible from user space. Currently, the following
 +ciphers are accessible:
 +
 + * Message digest including keyed message digest
 +
 + * Symmetric ciphers
 +
 +The interface is provided via Netlink using the type AF_ALG. In addition, the
 +setsockopt option type is SOL_ALG. In case the user space header files do not
 +export these flags yet, use the following macros:
 +
 +#ifndef AF_ALG
 +#define AF_ALG 38
 +#endif
 +#ifndef SOL_ALG
 +#define SOL_ALG 279
 +#endif
 +
 +A cipher is accessed with the same name as done for the in-kernel API calls.

Perhaps a reference here to the final location of the kernel API
explanations?

 +
 +To interact with the kernel crypto API, a Netlink socket must be created by
 +the user space application. User space invokes the cipher operation with the
 +send/write system call family. The result of the cipher operation is obtained
 +with the read/recv system call family.
 +
 +The following API calls assume that the Netlink socket descriptor is already
 +opened by the user space application and discusses only the kernel crypto API
 +specific invocations.
 +
 +Message digest API
 +--
 +
 +The message digest type to be used for the cipher operation is selected when
 +invoking the bind syscall. bind requires the caller to provide a filled
 +struct sockaddr data structure. This data structure must be filled as 
 follows:
 +
 +struct sockaddr_alg sa = {
 + .salg_family = AF_ALG,
 + .salg_type = hash, /* this selects the hash logic in the kernel */
 + .salg_nmae = sha1 /* this is the cipher name */
 +};
 +
 +Using the send() system call, the application provides the data that should 
 be
 +processed with the message digest. The send system call allows the following
 +flags to be specified:
 +
 + * MSG_MORE: If this flag is set, the send system call acts like a
 + message digest update function where the final hash is not
 + yet calculated. If the flag is not set, the send system call
 + calculates the final message digest immediately.
 +
 +With the read() system call, the application can read the message digest from
 +the kernel crypto API. If the buffer is too small for the message digest, the
 +flag MSG_TRUNC is set by the kernel.
 +
 +In order to set a message digest key, the calling application must use the
 +setsockopt() option of ALG_SET_KEY.

What happens if this is omitted?

 +
 +
 +Symmetric cipher API
 +
 +
 +The operation is very similar to

[PATCH] kernel crypto API interface specification

2014-10-14 Thread Stephan Mueller 
The update adds a complete interface documentation of the kernel crypto
API. All cipher types supported by the kernel crypto API are documented.

In addition, kernel and user space example code is provided. The sample
code covers synchronous and asynchronous cipher operation, random
number generation and performing hashing as well as encryption and
decryption in user space.

Signed-off-by: Stephan Mueller smuel...@chronox.de
---
 Documentation/crypto/crypto-API-spec.txt | 2110 ++
 1 file changed, 2110 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..027fd4f
--- /dev/null
+++ b/Documentation/crypto/crypto-API-spec.txt
@@ -0,0 +1,2110 @@
+Kernel Crypto API Interface Specification
+=
+
+The kernel crypto API offers a rich set of ciphers and methods to invoke these
+ciphers. 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 the
+structure is given. Based on the architecture, the API can be separated into
+different components. Following the architecture specification the various
+components forming the kernel crypto API are described.
+
+The kernel crypto API refers to all algorithms as transforms. 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:
+
+   * users requesting cryptographic services
+
+   * data transformation implementations (typically ciphers) that
+ can be called by users
+
+This specification is mainly intended for normal users that need cryptographic
+support. It lists all API calls relevant for these users. This API
+specification, however, does not list 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).
+
+Kernel Crypto API Architecture
+==
+
+Cipher 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 raw ciphers. In addition, the
+kernel crypto API provides numerous templates that can be used in conjunction
+with the raw ciphers. Templates include all types of block chaining mode, the
+HMAC mechanism, etc.
+
+Raw ciphers can either be directly used by a caller or invoked together with a
+template. A raw cipher may even be called with multiple templates. However,
+templates cannot be used without a raw cipher.
+
+Synchronous and asynchronous operation
+--
+
+The kernel crypto API provides synchronous and asynchronous API calls.
+
+When using a synchronous API call, 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 operations, the set
+of API calls is small and similar to any other crypto library.
+
+Asynchronous operation is provided by the kernel crypto API which implies that
+the invocation of a cipher operation will complete almost instantly. That
+invocation triggers the cipher operation but it does not signal its completion.
+Before invoking a cipher operation, the caller must provide a callback function
+the kernel crypto API can invoke to signal the completion of the cipher
+operation. Furthermore, the caller must ensure it can handle such asynchronous
+events by applying appropriate locking around its data. The kernel crypto API
+does not perform any special serialization operation to protect the caller's
+data integrity.
+
+Kernel crypto API cipher references and priority
+
+
+A cipher is referenced by the caller with a string. That string has the
+following semantics:
+
+   template(raw cipher)
+
+where template and raw cipher is the aforementioned template and raw 
cipher,
+respectively. If applicable, additional templates may enclose other templates,
+such as
+
+   template1(template2(raw cipher)))
+
+The kernel crypto API may provide multiple implementations of a template or a
+raw cipher. For example, AES on newer x86_64 hardware has the following
+implementations: AES-NI, assembler implementation, or straight C.

Re: [PATCH] kernel crypto API interface specification

2014-10-14 Thread Stephan Mueller 
Am Dienstag, 14. Oktober 2014, 21:46:50 schrieb Stephan Mueller:

Hi,

 The update adds a complete interface documentation of the kernel crypto
 API. All cipher types supported by the kernel crypto API are documented.
 
 In addition, kernel and user space example code is provided. The sample
 code covers synchronous and asynchronous cipher operation, random
 number generation and performing hashing as well as encryption and
 decryption in user space.

I was not sure whether to cover the explanation of the API in a separate 
document or whether to add the function documentation to 
include/linux/crypto.h.

With the first attempt of the documentation, I applied the least invasive 
approach. If it is requested, I would modify the patch such that appropriate 
source code comments to the functions in the header file are added.

-- 
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