Re: [PATCH] kernel crypto API interface specification

From: Jason Cooper
Date: Thu Oct 16 2014 - 09:29:17 EST




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.9BkWHTZ0th@xxxxxxxxxxxxxxx
>
> 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 <smueller@xxxxxxxxxx>
> > > > ---
> > > >
> > > > 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 0000000..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 name documentation.
> > >
> > > > +
> > > > +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?
> >
> > Added:
> >
> > "If the key is not set the HMAC operation is performed without the initial
> > HMAC state change caused by the key."
> > >
> > > > +
> > > > +
> > > > +Symmetric cipher API
> > > > +--------------------
> > > > +
> > > > +The operation is very similar to the message digest discussion. During
> > > > +initialization, the struct sockaddr data structure must be filled as
> > > > follows: +
> > > > +struct sockaddr_alg sa = {
> > > > + .salg_family = AF_ALG,
> > > > + .salg_type = "skcipher", /* this selects the symmetric cipher */
> > > > + .salg_name = "cbc(aes)" /* this is the cipher name */
> > > > +};
> > > > +
> > > > +Using the sendmsg() system call, the application provides the data that
> > > > should +be processed for encryption or decryption. In addition, the IV is
> > > > specified +with the data structure provided by the sendmsg() system call.
> > > > +
> > > > +The sendmsg system call parameter of struct msghdr is embedded into the
> > > > +struct cmsghdr data structure. See recv(2) and cmsg(3) for more
> > > > information +on how the cmsghdr data structure is used together with the
> > > > send/recv system +call family. That cmsghdr data structure holds the
> > > > following information +specified with a separate header instances:
> > > > +
> > > > + * specification of the cipher operation type with one of these flags:
> > > > + ALG_OP_ENCRYPT - encryption of data
> > > > + ALG_OP_DECRYPT - decryption of data
> > > > +
> > > > + * specification of the IV information marked with the flag ALG_SET_IV
> > > > +
> > > > +The send system call family allows the following flag to be specified:
> > > > +
> > > > + * MSG_MORE: If this flag is set, the send system call acts like a
> > > > + cipher update function where more input data is expected
> > > > + with a subsequent invocation of the send system call.
> > > > +
> > > > +Note: The kernel reports -EINVAL for any unexpected data. The caller must
> > > > +make sure that all data matches the constraints given in /proc/crypto for
> > > > the +selected cipher.
> > > > +
> > > > +With the read() system call, the application can read the result of the
> > > > +cipher operation from the kernel crypto API. The output buffer must be at
> > > > least +as large as to hold all blocks of the encrypted or decrypted data.
> > > > If the output +data size is smaller, only the as many blocks are returned
> > > > that fit into that
> > > ...only as many blocks...
> >
> > Fixed
> > >
> > > > +output buffer size.
> > > > +
> > > > +User space API example
> > > > +----------------------
> > > > +
> > > > +Compile the following code with the gcc flags of "-Wextra -Wall
> > > > -pedantic". +
> > > > +/*
> > > > + * Code from cryptsetup version 1.6.4 used as a basis
> > > > + */
> > >
> > > Could you specify the git commit and file from cryptsetup? This way, if
> > > the this example becomes out of date, users could easily jump to the
> > > newest version of working code used in the real world.
> >
> > I have not added the git commit as I think the version number is precise. Yet
> > I added the files containing the implementation.
> >
> > I would think that the user space API would not change as much as the kernel
> > API could considering the standard approach by the kernel developers with user
> > space APIs in general.
>
> Agreed.
>
> I got to thinking about this some more last night. Why don't we split
> out the below example code and make it a part of the kernel test
> harness? It could test for API regressions, and be a reference
> implementation at the same time...
>
> > > > +
> > > > +#include <stdio.h>
> > > > +
> > > > +#include <unistd.h>
> > > > +#include <sys/socket.h>
> > > > +#include <sys/types.h>
> > > > +#include <linux/if_alg.h>
> > > > +#include <stdint.h>
> > > > +#include <errno.h>
> > > > +#include <string.h>
> > > > +#include <stdlib.h>
> > > > +
> > > > +#ifndef AF_ALG
> > > > +#define AF_ALG 38
> > > > +#endif
> > > > +#ifndef SOL_ALG
> > > > +#define SOL_ALG 279
> > > > +#endif
> > > > +
> > > > +/************************************************************
> > > > + * Application interfaces
> > > > + ************************************************************/
> > > > +
> > > > +/* Cipher handle */
> > > > +struct kcapi_handle {
> > > > + int tfmfd;
> > > > + int opfd;
> > > > +};
> > > > +
> > > > +/************************************************************
> > > > + * Internal logic
> > > > + ************************************************************/
> > > > +
> > > > +/* The in/out should be aligned to page boundary */
> > > > +static int _kcapi_cipher_crypt(struct kcapi_handle *handle,
> > > > + const unsigned char *in, size_t inlen,
> > > > + unsigned char *out, size_t outlen,
> > > > + const unsigned char *iv, size_t ivlen,
> > > > + uint32_t enc)
> > > > +{
> > > > + int r = 0;
> > > > + ssize_t ret;
> > > > + struct af_alg_iv *alg_iv;
> > > > + struct cmsghdr *header;
> > > > + uint32_t *type;
> > > > + struct iovec iov;
> > > > + int iv_msg_size = iv ? CMSG_SPACE(sizeof(*alg_iv) + ivlen) : 0;
> > > > + char *buffer = NULL;
> > > > + unsigned int bufferlen = CMSG_SPACE(sizeof(*type)) + iv_msg_size;
> > > > + struct msghdr msg;
> > > > +
> > > > + if (!in || !out || !inlen || !outlen)
> > > > + return -EINVAL;
> > > > +
> > > > + if ((!iv && ivlen) || (iv && !ivlen))
> > > > + return -EINVAL;
> > > > +
> > > > + buffer = calloc(1, bufferlen);
> > > > + if (!buffer)
> > > > + return -ENOMEM;
> > > > +
> > > > + iov.iov_base = (void*)(uintptr_t)in;
> > > > + iov.iov_len = inlen;
> > > > + msg.msg_control = buffer;
> > > > + msg.msg_controllen = bufferlen;
> > > > + msg.msg_iov = &iov;
> > > > + msg.msg_iovlen = 1;
> > > > +
> > > > + /* encrypt/decrypt operation */
> > > > + header = CMSG_FIRSTHDR(&msg);
> > > > + header->cmsg_level = SOL_ALG;
> > > > + header->cmsg_type = ALG_SET_OP;
> > > > + header->cmsg_len = CMSG_LEN(sizeof(*type));
> > > > + type = (void*)CMSG_DATA(header);
> > > > + *type = enc;
> > > > +
> > > > + /* set IV */
> > > > + if (iv) {
> > > > + header = CMSG_NXTHDR(&msg, header);
> > > > + header->cmsg_level = SOL_ALG;
> > > > + header->cmsg_type = ALG_SET_IV;
> > > > + header->cmsg_len = iv_msg_size;
> > > > + alg_iv = (void*)CMSG_DATA(header);
> > > > + alg_iv->ivlen = ivlen;
> > > > + memcpy(alg_iv->iv, iv, ivlen);
> > > > + }
> > > > +
> > > > + ret = sendmsg(handle->opfd, &msg, 0);
> > > > + if (ret != (ssize_t)inlen) {
> > > > + r = -EIO;
> > > > + goto bad;
> > > > + }
> > > > +
> > > > + ret = read(handle->opfd, out, outlen);
> > > > + if (ret != (ssize_t)outlen)
> > > > + r = -EIO;
> > > > +bad:
> > > > + memset(buffer, 0, bufferlen);
> > >
> > > Not related to this patch, but you should take a look at:
> > >
> > > http://www.daemonology.net/blog/2014-09-04-how-to-zero-a-buffer.html
> > >
> > > http://www.daemonology.net/blog/2014-09-06-zeroing-buffers-is-insufficient.
> > > html
> >
> > Absolutely. Thanks for hinting to that. I added a memchr after the memset:
> >
> > memset(buffer, 0, bufferlen);
> > _buffer = memchr(buffer, 1, bufferlen);
> > if (_buffer)
> > _buffer = '\0';
> > > > + free(buffer);
> > > > + return r;
> > > > +}
> > > > +
> > > > +
> > > > +/************************************************************
> > > > + * API to application
> > > > + ************************************************************/
> > > > +
> > > > +/*
> > > > + * Initialization of a cipher handle and establishing the connection to
> > > > + * the kernel
> > > > + *
> > > > + * @handle cipher handle filled during the call - output
> > > > + * @type cipher type, one of the following - input:
> > > > + * "hash" for message digests (including keyed message digests)
> > > > + * "skcipher" for symmetric ciphers
> > > > + * @ciphername kernel crypto API cipher name as specified in
> > > > + * /proc/crypto - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + * < 0 in case of error
> > > > + * ENOENT - algorithm not available
> > > > + * ENOTSUP - AF_ALG family not available
> > > > + * EINVAL - accept syscall failed
> > > > + */
> > > > +int kcapi_cipher_init(struct kcapi_handle *handle,
> > > > + const char *type, const char *ciphername)
> > > > +{
> > > > + struct sockaddr_alg sa;
> > > > +
> > > > + memset(&sa, 0, sizeof(sa));
> > > > + sa.salg_family = AF_ALG;
> > > > + snprintf((char *)sa.salg_type, sizeof(sa.salg_type),"%s", type);
> > > > + snprintf((char *)sa.salg_name, sizeof(sa.salg_name),"%s", ciphername);
> > > > +
> > > > + handle->tfmfd = socket(AF_ALG, SOCK_SEQPACKET, 0);
> > > > + if (handle->tfmfd == -1)
> > > > + return -ENOTSUP;
> > > > +
> > > > + if (bind(handle->tfmfd, (struct sockaddr *)&sa, sizeof(sa)) == -1) {
> > > > + close(handle->tfmfd);
> > > > + handle->tfmfd = -1;
> > > > + return -ENOENT;
> > > > + }
> > > > +
> > > > + handle->opfd = accept(handle->tfmfd, NULL, 0);
> > > > + if (handle->opfd == -1) {
> > > > + close(handle->tfmfd);
> > > > + handle->tfmfd = -1;
> > > > + return -EINVAL;
> > > > + }
> > > > +
> > > > + return 0;
> > > > +}
> > > > +
> > > > +/*
> > > > + * Close the cipher handle and release resources
> > > > + *
> > > > + * @handle cipher handle to release - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + */
> > > > +int kcapi_cipher_destory(struct kcapi_handle *handle)
> > > > +{
> > > > + if (handle->tfmfd != -1)
> > > > + close(handle->tfmfd);
> > > > + if (handle->opfd != -1)
> > > > + close(handle->opfd);
> > > > + return 0;
> > > > +}
> > > > +
> > > > +
> > > > +/*
> > > > + * Set the key for the cipher handle
> > > > + *
> > > > + * This call is applicable for keyed message digests and symmetric
> > > > ciphers. + *
> > > > + * @handle cipher handle - input
> > > > + * @key key buffer - input
> > > > + * @keylen length of key buffer - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + * < 0 in case of error
> > > > + */
> > > > +int kcapi_cipher_setkey(struct kcapi_handle *handle,
> > > > + const unsigned char *key, size_t keylen)
> > > > +{
> > > > + if (setsockopt(handle->tfmfd, SOL_ALG, ALG_SET_KEY,
> > > > + key, keylen) == -1)
> > > > + return -EINVAL;
> > > > +
> > > > + return 0;
> > > > +}
> > > > +
> > > > +/*
> > > > + * Message digest update function
> > > > + *
> > > > + * @handle cipher handle - input
> > > > + * @buffer holding the data to add to the message digest - input
> > > > + * @len buffer length - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + * < 0 in case of error
> > > > + */
> > > > +int kcapi_md_update(struct kcapi_handle *handle,
> > > > + const unsigned char *buffer, size_t len)
> > > > +{
> > > > + ssize_t r;
> > > > +
> > > > + r = send(handle->opfd, buffer, len, MSG_MORE);
> > > > + if (r < 0 || (size_t)r < len)
> > > > + return -EIO;
> > > > +
> > > > + return 0;
> > > > +}
> > > > +
> > > > +/*
> > > > + * Message digest finalization function
> > > > + *
> > > > + * @handle cipher handle - input
> > > > + * @buffer filled with the message digest - output
> > > > + * @len buffer length - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + * < 0 in case of error
> > > > + * EIO - data cannot be obtained
> > > > + * ENOMEM - buffer is too small for the complete message digest,
> > > > + * the buffer is filled with the truncated message
> > digest
> > > > + */
> > > > +
> > > > +int kcapi_md_final(struct kcapi_handle *handle,
> > > > + unsigned char *buffer, size_t len)
> > > > +{
> > > > + ssize_t r;
> > > > + struct iovec iov;
> > > > + struct msghdr msg;
> > > > +
> > > > + iov.iov_base = (void*)(uintptr_t)buffer;
> > > > + iov.iov_len = len;
> > > > + msg.msg_name = NULL;
> > > > + msg.msg_namelen = 0;
> > > > + msg.msg_iov = &iov;
> > > > + msg.msg_iovlen = 1;
> > > > + msg.msg_control = NULL;
> > > > + msg.msg_controllen = 0;
> > > > +
> > > > + r = recvmsg(handle->opfd, &msg, 0);
> > > > + if (r < 0)
> > > > + return -EIO;
> > > > + if (msg.msg_flags & MSG_TRUNC)
> > > > + return -ENOMEM;
> > > > +
> > > > + return 0;
> > > > +}
> > > > +
> > > > +/*
> > > > + * Encrypt data
> > > > + *
> > > > + * @handle cipher handle - input
> > > > + * @in plaintext data buffer - input
> > > > + * @inlen length of in buffer - input
> > > > + * @out ciphertext data buffer - output
> > > > + * @outlen length of out buffer - input
> > > > + * @iv buffer holding the IV (may be NULL if IV is not needed) - input
> > > > + * @ivlen length of iv (should be zero if iv is NULL) - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + * < 0 in case of error
> > > > + */
> > > > +int kcapi_cipher_encrypt(struct kcapi_handle *handle,
> > > > + const unsigned char *in, size_t inlen,
> > > > + unsigned char *out, size_t outlen,
> > > > + const unsigned char *iv, size_t ivlen)
> > > > +{
> > > > + return _kcapi_cipher_crypt(handle, in, inlen, out, outlen,
> > > > + iv, ivlen, ALG_OP_ENCRYPT);
> > > > +}
> > > > +
> > > > +/*
> > > > + * Decrypt data
> > > > + *
> > > > + * @handle cipher handle - input
> > > > + * @in ciphertext data buffer - input
> > > > + * @inlen length of in buffer - input
> > > > + * @out plaintext data buffer - output
> > > > + * @outlen length of out buffer - input
> > > > + * @iv buffer holding the IV (may be NULL if IV is not needed) - input
> > > > + * @ivlen length of iv (should be zero if iv is NULL) - input
> > > > + *
> > > > + * return: 0 upon success
> > > > + * < 0 in case of error
> > > > + */
> > > > +int kcapi_cipher_decrypt(struct kcapi_handle *handle,
> > > > + const unsigned char *in, size_t inlen,
> > > > + unsigned char *out, size_t outlen,
> > > > + const unsigned char *iv, size_t ivlen)
> > > > +{
> > > > + return _kcapi_cipher_crypt(handle, in, inlen, out, outlen,
> > > > + iv, ivlen, ALG_OP_DECRYPT);
> > > > +}
> > > > +
> > > > +/************************************************************
> > > > + * Application requiring cryptographic services
> > > > + ************************************************************/
> > > > +
> > > > +static char hex_char_map_l[] = { '0', '1', '2', '3', '4', '5', '6', '7',
> > > > + '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
> > > > +static char hex_char_map_u[] = { '0', '1', '2', '3', '4', '5', '6', '7',
> > > > + '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' };
> > > > +static char hex_char(unsigned int bin, int u)
> > > > +{
> > > > + if (bin < sizeof(hex_char_map_l))
> > > > + return (u) ? hex_char_map_u[bin] : hex_char_map_l[bin];
> > > > + return 'X';
> > > > +}
> > > > +
> > > > +/*
> > > > + * Convert binary string into hex representation
> > > > + * @bin input buffer with binary data
> > > > + * @binlen length of bin
> > > > + * @hex output buffer to store hex data
> > > > + * @hexlen length of already allocated hex buffer (should be at least
> > > > + * twice binlen -- if not, only a fraction of binlen is converted)
> > > > + * @u case of hex characters (0=>lower case, 1=>upper case)
> > > > + */
> > > > +static void bin2hex(const unsigned char *bin, size_t binlen,
> > > > + char *hex, size_t hexlen, int u)
> > > > +{
> > > > + size_t i = 0;
> > > > + size_t chars = (binlen > (hexlen / 2)) ? (hexlen / 2) : binlen;
> > > > +
> > > > + for (i = 0; i < chars; i++) {
> > > > + hex[(i*2)] = hex_char((bin[i] >> 4), u);
> > > > + hex[((i*2)+1)] = hex_char((bin[i] & 0x0f), u);
> > > > + }
> > > > +}
> > > > +
> > > > +int main(int argc, char *argv[])
> > > > +{
> > > > + struct kcapi_handle handle;
> > > > +#define BUFLEN 32
> > > > + unsigned char inbuf[BUFLEN];
> > > > +#define IVLEN 16
> > > > + unsigned char ivbuf[IVLEN];
> > > > + unsigned char outbuf[BUFLEN];
> > > > + unsigned char outbuf2[BUFLEN];
> > > > + char hexbuf[BUFLEN * 2 + 1];
> > > > +
> > > > + (void)argc;
> > > > + (void)argv;
> > > > +
> > > > + /*
> > > > + * Calculate a message digest
> > > > + */
> > > > + if (kcapi_cipher_init(&handle, "hash", "sha256")) {
> > > > + printf("Allocation of hash failed\n");
> > > > + return(1);
> > > > + }
> > > > + memcpy(inbuf, "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f"
> > > > + "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", BUFLEN);
> > > > + if (kcapi_md_update(&handle, inbuf, BUFLEN)) {
> > > > + printf("Hash update of buffer failed\n");
> > > > + return(1);
> > > > + }
> > > > + if (kcapi_md_final(&handle, outbuf, BUFLEN)) {
> > > > + printf("Hash final failed\n");
> > > > + return(1);
> > > > + }
> > > > + kcapi_cipher_destory(&handle);
> > > > + memset(hexbuf, 0, BUFLEN * 2 + 1);
> > > > + bin2hex(outbuf, BUFLEN, hexbuf, BUFLEN * 2 + 1, 0);
> > > > + printf("Calculated hash %s\n", hexbuf);
> > > > +
> > > > + /*
> > > > + * Calculate a keyed message digest
> > > > + */
> > > > + if (kcapi_cipher_init(&handle, "hash", "hmac(sha256)")) {
> > > > + printf("Allocation of HMAC failed\n");
> > > > + return(1);
> > > > + }
> > > > + memcpy(inbuf, "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f"
> > > > + "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", BUFLEN);
> > > > + if (kcapi_cipher_setkey(&handle, inbuf, BUFLEN)) {
> > > > + printf("HMAC setkey failed\n");
> > > > + return(1);
> > > > + }
> > > > + if (kcapi_md_update(&handle, inbuf, BUFLEN)) {
> > > > + printf("HMAC update of buffer failed\n");
> > > > + return(1);
> > > > + }
> > > > + if (kcapi_md_final(&handle, outbuf, BUFLEN)) {
> > > > + printf("HMAC final failed\n");
> > > > + return(1);
> > > > + }
> > > > + kcapi_cipher_destory(&handle);
> > >
> > > Did you test building this?
> >
> > Yes, I did and it worked flawlessly. Just copy out the code and compile as
> > stated in the comments. What are your concerns?
>
> I just spotted 'destory' and casually mentioned it without grepping for
> the other instances. :( It looks like it's been mis-spelled
> consistently. :-P
>
> > See the following code where I call kcapi_cipher_init again.
> > >
> > > > + memset(hexbuf, 0, BUFLEN * 2 + 1);
> > > > + bin2hex(outbuf, BUFLEN, hexbuf, BUFLEN * 2 + 1, 0);
> > > > + printf("Calculated hmac %s\n", hexbuf);
> > > > +
> > > > + /*
> > > > + * Encrypt data
> > > > + */
> > > > + if (kcapi_cipher_init(&handle, "skcipher", "cbc(aes)")) {
> > > > + printf("Allocation of cipher failed\n");
> > > > + return(1);
> > > > + }
> > > > + memcpy(inbuf, "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f"
> > > > + "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", BUFLEN);
> > > > + if (kcapi_cipher_setkey(&handle, inbuf, BUFLEN)) {
> > > > + printf("AES setkey failed\n");
> > > > + return(1);
> > > > + }
> > > > + memcpy(ivbuf, "\x00\x01\x02\x03\x04\x05\x06\x07"
> > > > + "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", IVLEN);
> > > > + if (kcapi_cipher_encrypt(&handle, inbuf, BUFLEN,
> > > > + outbuf, BUFLEN, ivbuf, IVLEN)) {
> > > > + printf("Encryption buffer failed\n");
> > > > + return(1);
> > > > + }
> > > > + memset(hexbuf, 0, BUFLEN * 2 + 1);
> > > > + bin2hex(outbuf, BUFLEN, hexbuf, BUFLEN * 2 + 1, 0);
> > > > + printf("Encrypted data %s\n", hexbuf);
> > > > +
> > > > + /*
> > > > + * Decrypt previously encrypted data
> > > > + */
> > > > + if (kcapi_cipher_decrypt(&handle, outbuf, BUFLEN,
> > > > + outbuf2, BUFLEN, ivbuf, IVLEN)) {
> > > > + printf("Decryption buffer failed\n");
> > > > + return(1);
> > > > + }
> > > > + kcapi_cipher_destory(&handle);
> > > > + memset(hexbuf, 0, BUFLEN * 2 + 1);
> > > > + bin2hex(outbuf2, BUFLEN, hexbuf, BUFLEN * 2 + 1, 0);
> > > > + printf("Decrypted data %s\n", hexbuf);
> > > > + if (!memcmp(inbuf, outbuf2, BUFLEN))
> > > > + printf("Decrypted data match original plaintext as
> > expected\n");
> > > > + else
> > > > + printf("FAILURE: Decrypted data does not match original
> > plaintext\n");
> > > > +
> > > > + return 0;
> > > > +}
> > > > +
> > > > +License of code
> > > > +===============
> > > > +/*
> > > > + * Copyright (C) 2014, Stephan Mueller <smueller@xxxxxxxxxx>
> > > > + *
> > > > + * Redistribution and use in source and binary forms, with or without
> > > > + * modification, are permitted provided that the following conditions
> > > > + * are met:
> > > > + * 1. Redistributions of source code must retain the above copyright
> > > > + * notice, and the entire permission notice in its entirety,
> > > > + * including the disclaimer of warranties.
> > > > + * 2. Redistributions in binary form must reproduce the above copyright
> > > > + * notice, this list of conditions and the following disclaimer in the
> > > > + * documentation and/or other materials provided with the
> > > > distribution.
> > > > + * 3. The name of the author may not be used to endorse or promote
> > > > + * products derived from this software without specific prior
> > > > + * written permission.
> > > > + *
> > > > + * ALTERNATIVELY, this product may be distributed under the terms of
> > > > + * the GNU General Public License, in which case the provisions of the
> > > > GPL2 are + * required INSTEAD OF the above restrictions. (This clause is
> > > > + * necessary due to a potential bad interaction between the GPL and
> > > > + * the restrictions contained in a BSD-style copyright.)
> > > > + *
> > > > + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
> > > > + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
> > > > + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF
> > > > + * WHICH ARE HEREBY DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE
> > > > + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
> > > > + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
> > > > + * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
> > > > + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
> > > > + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
> > > > + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
> > > > + * USE OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH
> > > > + * DAMAGE.
> > > > + */
> > >
> > > 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.
>
> thx,
>
> Jason.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/