Re: [PATCH v2 05/11] crypto: Documentation - SHASH API documentation
Hi Stephan,
On Sun, 2014-11-02 at 21:38 +0100, Stephan Mueller wrote:
The API function calls exported by the kernel crypto API for SHASHes
to be used by consumers are documented.
Signed-off-by: Stephan Mueller smuel...@chronox.de
CC: Marek Vasut ma...@denx.de
---
include/crypto/hash.h | 197
++
1 file changed, 197 insertions(+)
diff --git a/include/crypto/hash.h b/include/crypto/hash.h
index 0d43dbc..7b3a621 100644
--- a/include/crypto/hash.h
+++ b/include/crypto/hash.h
@@ -484,6 +484,33 @@ static inline void ahash_request_set_crypt(struct
ahash_request *req,
req-result = result;
}
+/**
+ * Synchronous message digest API to use the ciphers of type
+ * CRYPTO_ALG_TYPE_SHASH (listed as type shash in /proc/crypto)
+ *
+ * Considering the discussion of the state maintenance for the synchronous
+ * block cipher API, the message digest API is also able to maintain state
super picky comment, so can be ignored, but why mention block ciphers
here... everything after the comma sounds great to me.
+ * information for the caller. Though, the maintenance of the state is a bit
+ * different for the message digest API.
+ *
+ * The synchronous message digest API can store user-related context in in
its
+ * shash_desc request data structure.
+ */
+
+/**
+ * Allocate a cipher handle for a message digest. The returned struct
+ * crypto_shash is the cipher handle that is required for any subsequent
+ * API invocation for that message digest.
+ *
+ * @alg_name is the cra_name / name or cra_driver_name / driver name of the
+ *message digest cipher
+ * @type specifies the type of the cipher (see Documentation/crypto/)
+ * @mask specifies the mask for the cipher (see Documentation/crypto/)
+ *
+ * return value:
+ * allocated cipher handle in case of success
+ * IS_ERR() is true in case of an error, PTR_ERR() returns the error code.
+ */
struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type,
u32 mask);
@@ -492,6 +519,12 @@ static inline struct crypto_tfm *crypto_shash_tfm(struct
crypto_shash *tfm)
return tfm-base;
}
+/**
+ * The referenced message digest handle is zeroized and subsequently
+ * freed.
+ *
+ * @tfm cipher handle to be freed
+ */
static inline void crypto_free_shash(struct crypto_shash *tfm)
{
crypto_destroy_tfm(tfm, crypto_shash_tfm(tfm));
@@ -503,6 +536,15 @@ static inline unsigned int crypto_shash_alignmask(
return crypto_tfm_alg_alignmask(crypto_shash_tfm(tfm));
}
+/**
+ * The block size for the message digest cipher referenced with the cipher
+ * handle is returned.
+ *
+ * @tfm cipher handle
+ *
+ * return value:
+ * block size of cipher
+ */
static inline unsigned int crypto_shash_blocksize(struct crypto_shash *tfm)
{
return crypto_tfm_alg_blocksize(crypto_shash_tfm(tfm));
@@ -518,6 +560,15 @@ static inline struct shash_alg *crypto_shash_alg(struct
crypto_shash *tfm)
return __crypto_shash_alg(crypto_shash_tfm(tfm)-__crt_alg);
}
+/**
+ * The size for the message digest created by the message digest cipher
+ * referenced with the cipher handle is returned.
+ *
+ * @tfm cipher handle
+ *
+ * return value:
+ * block size of cipher
Should this be that it returns the digest size of the cipher?
+ */
static inline unsigned int crypto_shash_digestsize(struct crypto_shash *tfm)
{
return crypto_shash_alg(tfm)-digestsize;
@@ -543,6 +594,60 @@ static inline void crypto_shash_clear_flags(struct
crypto_shash *tfm, u32 flags)
crypto_tfm_clear_flags(crypto_shash_tfm(tfm), flags);
}
+/**
+ * The size of the operational state the cipher needs during operation is
+ * returned for the hash referenced with the cipher handle. This size is
+ * required to calculate the memory requirements to allow the caller
allocating
+ * sufficient memory for operational state.
+ *
+ * The operational state is defined with struct shash_desc where the size of
+ * that data structure is to be calculated as
+ * sizeof(struct shash_desc) + crypto_shash_descsize(alg)
+ *
+ * @tfm cipher handle
+ *
+ * return value:
+ * size of the operational state
+ *
+ * The following example code shall illustrate the use of the operational
+ * state memory:
+ *
+ *struct sdesc {
+ * struct shash_desc shash;
+ * char ctx[];
+ *};
+ *
+ *static struct sdesc *init_sdesc(struct crypto_shash *alg)
+ *{
+ * struct sdesc *sdesc;
+ * int size;
+ *
+ * size = sizeof(struct shash_desc) + crypto_shash_descsize(alg);
+ * sdesc = kmalloc(size, GFP_KERNEL);
+ * if (!sdesc)
+ * return ERR_PTR(-ENOMEM);
+ * sdesc-shash.tfm = alg;
+ * sdesc-shash.flags = 0x0;
+ * return sdesc;
+ *}
+ *
+ *static int calc_hash(struct crypto_shash *alg,
+ *const unsigned char *data, unsigned int datalen,
+ *
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 02/11] crypto: Documentation - userspace interface spec
Hi Stephan,
On Sun, 2014-11-02 at 21:36 +0100, Stephan Mueller wrote:
The userspace interface of the kernel crypto API is documented with
* a general explanation
* a discussion of the memory in-place operation
* the description of the message digest API
* the description of the symmetric cipher API
In addition, a fully self contained example that can readily be used as
a library is added as well.
Signed-off-by: Stephan Mueller smuel...@chronox.de
CC: Marek Vasut ma...@denx.de
---
Documentation/crypto/crypto-API-userspace.txt | 662
++
1 file changed, 662 insertions(+)
create mode 100644 Documentation/crypto/crypto-API-userspace.txt
diff --git a/Documentation/crypto/crypto-API-userspace.txt
b/Documentation/crypto/crypto-API-userspace.txt
new file mode 100644
index 000..30ca6a7
--- /dev/null
+++ b/Documentation/crypto/crypto-API-userspace.txt
@@ -0,0 +1,662 @@
+Introduction
+
+
+The concepts of the kernel crypto API visible to kernel space is fully
+applicable to the user space interface as well. Therefore, the kernel crypto
API
+high level discussion for the in-kernel use cases applies here as well.
+
+The major difference, however, is that user space can only act as a consumer
+and never as a provider of a transformation or cipher algorithm.
+
+The following covers the user space interface exported by the kernel crypto
+API. It provides a fully working sample code at the that can be used as a
at the can probably be deleted.
+library for user space applications that require cryptographic services from
+the kernel.
+
+Some details of the in-kernel kernel crypto API aspects do not
+apply to user space, however. This includes the difference between
synchronous
+and asynchronous invocations. The user space API call is fully synchronous.
+In addition, only a subset of all cipher types are available as documented
+below.
+
+
+User space API general remarks
+==
+
+The kernel crypto API is accessible from user space. Currently, the following
+ciphers are accessible:
+
+ * Message digest including keyed message digest (HMAC, CMAC)
+
+ * Symmetric ciphers
+
+Note, AEAD ciphers are currently not supported via the symmetric cipher
+interface.
+
+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.
+This includes the generic vs. unique naming schema for ciphers as well as the
+enforcement of priorities for generic names.
+
+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.
+
+In-place cipher operation
+=
+
+Just like the in-kernel operation of the kernel crypto API, the user space
+interface allows the cipher operation in-place. That means that the input
buffer
+used for the send/write system call and the output buffer used by the
read/recv
+system call may be one and the same. This is of particular interest for
+symmetric cipher operations where a copying of the output data to its final
+destination can be avoided.
For clarity, it might be helpful to reader if both ways are mentioned.
That you can encrypt in place or have your output place in a separate
destination.
+
+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_name = sha1 /* this is the cipher name */
+};
+
+The salg_type value hash applies to message digests and keyed message
digests.
+Though, a keyed message digest is referenced by the appropriate salg_name and
+providing a key for the cipher operation.
Picky, but maybe now is the time to mention what you mention 2 or 3
paragraphs below about how to set the message digest key.
+
+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
Re: [PATCH v2 03/11] crypto: Documentation - RNG API documentation
Hi Stephan,
Just one quick comment below...
regards,
Joy
On Sun, 2014-11-02 at 21:36 +0100, Stephan Mueller wrote:
The API function calls exported by the kernel crypto API for RNGs to
be used by consumers are documented.
Signed-off-by: Stephan Mueller smuel...@chronox.de
CC: Marek Vasut ma...@denx.de
---
include/crypto/rng.h | 113
+++
1 file changed, 113 insertions(+)
diff --git a/include/crypto/rng.h b/include/crypto/rng.h
index c93f9b9..83c4238 100644
--- a/include/crypto/rng.h
+++ b/include/crypto/rng.h
@@ -20,11 +20,68 @@ extern struct crypto_rng *crypto_default_rng;
int crypto_get_default_rng(void);
void crypto_put_default_rng(void);
+/**
+ * Random number generator API to use the ciphers of type
+ * CRYPTO_ALG_TYPE_RNG (listed as type rng in /proc/crypto)
+ *
+ * Example code:
+ *
+ *static int get_random_numbers(u8 *buf, unsigned int len)
+ *{
+ * struct crypto_rng *rng = NULL;
+ * char *drbg = drbg_nopr_sha256; // Hash DRBG with SHA-256, no PR
+ * int ret;
+ *
+ * if (!buf || !len) {
+ * pr_debug(No output buffer provided\n);
+ * return -EINVAL;
+ * }
+ *
+ * rng = crypto_alloc_rng(drbg, 0, 0);
+ * if (IS_ERR(rng)) {
+ * pr_debug(could not allocate RNG handle for %s\n, drbg);
+ * return -PTR_ERR(rng);
+ * }
+ *
+ * ret = crypto_rng_get_bytes(rng, buf, len);
+ * if (ret 0)
+ * pr_debug(generation of random numbers failed\n);
+ * else if (ret == 0)
+ * pr_debug(RNG returned no data);
+ * else
+ * pr_debug(RNG returned %d bytes of data\n, ret);
+ *
+ *out:
+ * crypto_free_rng(rng);
+ * return ret;
+ *}
+ */
+
static inline struct crypto_rng *__crypto_rng_cast(struct crypto_tfm *tfm)
{
return (struct crypto_rng *)tfm;
}
+/**
+ * Allocate a cipher handle for a random number generator. The returned
struct
+ * crypto_rng is the cipher handle that is required for any subsequent
+ * API invocation for that random number generator.
+ *
+ * For all random number generators, this call creates a new private copy of
+ * the random number generator that does not share a state with other
+ * instances. The only exception is the krng random number generator which
+ * is a kernel crypto API use case for the get_random_bytes() function of the
+ * /dev/random driver.
+ *
+ * @alg_name is the cra_name / name or cra_driver_name / driver name of the
+ *message digest cipher
+ * @type specifies the type of the cipher (see Documentation/crypto/)
+ * @mask specifies the mask for the cipher (see Documentation/crypto/)
+ *
+ * return value:
+ * allocated cipher handle in case of success
+ * IS_ERR() is true in case of an error, PTR_ERR() returns the error code.
+ */
static inline struct crypto_rng *crypto_alloc_rng(const char *alg_name,
u32 type, u32 mask)
{
@@ -40,6 +97,14 @@ static inline struct crypto_tfm *crypto_rng_tfm(struct
crypto_rng *tfm)
return tfm-base;
}
+/**
+ * Return the generic name (cra_name) of the initialized random number
generator
+ *
+ * @tfm cipher handle
+ *
+ * return value:
+ * generic name string
+ */
static inline struct rng_alg *crypto_rng_alg(struct crypto_rng *tfm)
{
return crypto_rng_tfm(tfm)-__crt_alg-cra_rng;
@@ -50,23 +115,71 @@ static inline struct rng_tfm *crypto_rng_crt(struct
crypto_rng *tfm)
return crypto_rng_tfm(tfm)-crt_rng;
}
+/**
+ * The referenced random number generator handle is zeroized and subsequently
+ * freed.
+ *
+ * @tfm cipher handle to be freed
+ */
static inline void crypto_free_rng(struct crypto_rng *tfm)
{
crypto_free_tfm(crypto_rng_tfm(tfm));
}
+/**
+ * This function fills the caller-allocated buffer with random numbers using
the
+ * random number generator referenced by the cipher handle.
+ *
+ * @tfm cipher handle
+ * @rdata output buffer holding the random numbers
+ * @dlen length of the output buffer
+ *
+ * return value:
+ *0 function was successful and returns the number of generated bytes
+ *0 if an error occurred
+ */
static inline int crypto_rng_get_bytes(struct crypto_rng *tfm,
u8 *rdata, unsigned int dlen)
{
return crypto_rng_crt(tfm)-rng_gen_random(tfm, rdata, dlen);
}
+/**
+ * The reset function completely re-initializes the random number generator
+ * referenced by the cipher handle by clearing the current state. The new
state
+ * is initialized with the caller provided seed or automatically, depending
+ * on the random number generator type (the ANSI X9.31 RNG requires
+ * caller-provided seed, the SP800-90A DRBGs perform an automatic seeding).
+ * The seed is provided with the. The provided seed should have the length of
dangling sentence...
+ * the seed size defined for the random
