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,
+ *
[PATCH v2 05/11] crypto: Documentation - SHASH API documentation
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
+ * 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
+ */
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,
+ * unsigned char *digest) {
+ * struct sdesc *sdesc;
+ * int ret;
+ *
+ * sdesc = init_sdesc(alg);
+ * if (IS_ERR(sdesc)) {
+ * pr_info(trusted_key: can't alloc %s\n, hash_alg);
+ * return PTR_ERR(sdesc);
+ * }
+ *
+ * ret = crypto_shash_digest(sdesc-shash, data, datalen, digest);
+ *
