Re: [PATCH 01/19] User-space API definition

Re: [PATCH 01/19] User-space API definition

[Miloslav Trmac]

----- "Herbert Xu" <herbert@gondor.hengli.com.au> wrote:
> Thanks for the updated patch-set.  It does indeed fulfil some
> of the requirements raised earlier.
> 
> However, as far as I can see this still does not address the
> extensibility.  For example, say we want add an interface to
> allow the xoring of two arbitrary data streams using DMA offload,
> this interface would make that quite awkward.
I don't think this would be a problem:

- Expose the xoring as a crypto_tfm, with the usual crypto API string identifier
  (this is supposed to be a crypto API interface, not a generic interface
  to the platform DMA controller, after all).

- Check to see if the operation can be supported using the existing
  attributes, add attributes if necessary.

  In this case, NCR_UPDATE_INPUT_DATA can be used for the read-only
  stream and NCR_UPDATE_OUTPUT_BUFFER for the read-write steram.

- If this is an entirely new crypto transform type, add support to
  the session interface.

  In this case, this would probably mean adding NCR_OP_COMBINE (or
  something similar); SESSION_INIT would only allocate the tfm,
  SESSION_UPDATE would be used for handling blocks of data as they
  come and go.

The interface would have to be extended, but the extension would be completely backward-compatible and the additions to the interface would probably be smaller than the additions to the internal crypto API.  Notably no new ioctl()s would be needed.
    Mirek

Re: [PATCH 01/19] User-space API definition

[Miloslav Trmac]

----- "Kyle Moffett" <kyle@moffetthome.net> wrote:
> On Mon, Sep 6, 2010 at 11:50, Miloslav Trmac <mitr@redhat.com> wrote:
> > ----- "Herbert Xu" <herbert@gondor.hengli.com.au> wrote:
> >> On Mon, Aug 23, 2010 at 11:37:40AM -0400, Miloslav Trmac wrote:
> >> > I have seriously considered the keyring API, and this is what I
> came
> >> up with - but I'd love to be shown a better way.
> >>
> >> FWIW adding a second key management system to the kernel is
> >> totally out of the question.
> >>
> >> If the existing system doesn't work for you, find a way to build
> >> on it so that it does.  Adding a second system that pretty much
> >> does the same thing is unacceptable.
> > It does _not_ do the same thing, same as ramfs and file descriptors
> do not do the same thing although they are both related to files.
> >
> > The kernel keyring service is basically a system-wide data storage
> service.  /dev/crypto needs a quick way to refer to short-lived,
> usually process-local, kernel-space data structures from userspace.
> 
> The problem with the approach you're proposing is that we then have
> two entirely separate classes of keys. 
"We have two entirely separate classes of files: inodes and file descriptors".

Isn't that only a problem if there is actual duplicate functionality?  And is copy_from_user() really enough reason to share the interface?

Like in the inodes/file descriptors case, the fact that you can read contents of both does not automatically mean that a single interface for both is the best option.  The naming does suggest that this should be the case here, but the differences are AFAICS much larger than the commonalities.


> Another potential issue is that keys are never actually "unnamed", in
> that sense.
They are perhaps not "unnamed" from a global point of view, or from the point of view of a few functions that directly manipulate the key, but they are quite anonymous from the process' point of view.

> If encryption keys truly were "anonymous" then you would
> find it impossible to reliably decrypt the data on the other end.  For
> example, every RSA private key should be indexed either by the X.509
> DN or for bare SSH keys by the public modulus information.
Why would that be useful?  The SSH private key should be only available to sshd.  sshd has loaded the key from a file (_that_ is the key's "name", as far as the system administrator is concerned), and then the key is used only privately within the sshd process.  There is no more reason to have a name attached to the loaded private key object than there is a reason to have a name attached to the file descriptor used to read /etc/ssh/sshd_config - the key is an application-internal object and its user-space identifier is merely a "safe pointer into the kernel".

Actually, in a modularly-designed program, only one component of the program works with the key, the rest should not even be aware of the existence of the key, and having a process-wide (or even more general) name for the key can lead to unintended conflicts.  Imagine having the option to give an every file descriptor a name, automatically replacing earlier file descriptors with the same name.

Having a well-known name for the sshd host private key is perhaps useful as an "attack this" sign :)

Same for public keys - when an application does
   public_key = import_from_certificate();
   encrypt_data_using(public_key)
it is not interested in sharing the public key object with other processes - after all, what if another process loaded a different key under the indented name?  Creating a meaningful identifier is about as costly as just importing the key, anyway.

>  Even transient SSL session keys are always put into an SSL session cache by
> apache or whatever to allow them to be reused across multiple TCP
> streams!
The SSL session cache is a quite unusual case.

Also, there is one SSL private key per server DNS name, and one SSL session cache entry per client-server pair, but there are at least four temporary keys, for each connection, and there is absolutely no need to name these.

> So my recommendation would be to create some new operations of the
> existing keyring code:

> (2) Add cryptoapi hooks to automatically register keyring key types
> based on the loaded cryptoapi modules.
Hm, using a different key type for each cipher would at least allow reusing add_key()/KEYCTL_{READ,UPDATE}; I didn't think even these could be useful.

So it's better than absolutely hopeless now :)

Thank you,
    Mirek

Re: [PATCH 01/19] User-space API definition

[Miloslav Trmac]

----- "Herbert Xu" <herbert@gondor.hengli.com.au> wrote:
> On Mon, Aug 23, 2010 at 11:37:40AM -0400, Miloslav Trmac wrote:
> >
> > I can see almost no overlap between the two sets of requirements. 
> Probably the only common use case is handling session keys (e.g. keys
> used in a kerberos ticket), which should be stored in the kernel for
> the duration of the session, made available to each process in the
> session, and available as keys for kernel crypto.  Such keys will be
> in the minority, though, and it seems to me the best approach for
> handling these is to allow key export/import from/to keyring keys in
> addition to export/import from/to data in userspace: the long-term
> storage would be handled by the existing keyring API, which stores the
> key as unformatted binary data, and import into the crypto context
> would convert the key into the internal representation more suitable
> for crypto.
> > 
> > I have seriously considered the keyring API, and this is what I came
> up with - but I'd love to be shown a better way.
> 
> FWIW adding a second key management system to the kernel is
> totally out of the question.
> 
> If the existing system doesn't work for you, find a way to build
> on it so that it does.  Adding a second system that pretty much
> does the same thing is unacceptable.
It does _not_ do the same thing, same as ramfs and file descriptors do not do the same thing although they are both related to files.

The kernel keyring service is basically a system-wide data storage service.  /dev/crypto needs a quick way to refer to short-lived, usually process-local, kernel-space data structures from userspace.

Imagine that instead of
    thread = clone(..., CLONE_THREAD);
you needed to do
    thread_fd = mkstemp("/proc/XXX");
    fork(thread_fd);
That's how "just using the existing keyring" would look like.

Adapting the existing keyring to match the /dev/crypto use case better would make the keyring API at least 25% larger, and introduce completely different key identification and lifetime semantics for a set of keys.

If you can see a way the two can be cleanly integrated, please don't just tell us that we have to do it, tell us how.
 
> Also, the key management for secret keys that you've added should
> not be the only mode offered to the user.  Most people do not need
> the separation between key setting and encryption/decryption.
The "key ID" is not embedded into encryption operation requests (it uses a struct nlattr), so it would be quite possible to supply the raw key instead.
    Mirek

Re: [PATCH 01/19] User-space API definition

[Kyle Moffett]

On Mon, Sep 6, 2010 at 11:50, Miloslav Trmac <mitr@redhat.com> wrote:
> ----- "Herbert Xu" <herbert@gondor.hengli.com.au> wrote:
>> On Mon, Aug 23, 2010 at 11:37:40AM -0400, Miloslav Trmac wrote:
>> > I have seriously considered the keyring API, and this is what I came
>> up with - but I'd love to be shown a better way.
>>
>> FWIW adding a second key management system to the kernel is
>> totally out of the question.
>>
>> If the existing system doesn't work for you, find a way to build
>> on it so that it does.  Adding a second system that pretty much
>> does the same thing is unacceptable.
> It does _not_ do the same thing, same as ramfs and file descriptors do not do the same thing although they are both related to files.
>
> The kernel keyring service is basically a system-wide data storage service.  /dev/crypto needs a quick way to refer to short-lived, usually process-local, kernel-space data structures from userspace.

The problem with the approach you're proposing is that we then have
two entirely separate classes of keys.  First we have the existing
keyring class, which can be securely and revokably passed between
different processes with limited rights, but cannot be handed up to
the kernel's cryptoapi.  Then we have your new class, which are
anonymous keys with a brand new security model (which doesn't even
have LSM hooks yet) and which cannot be referenced by name.

Another potential issue is that keys are never actually "unnamed", in
that sense.  If encryption keys truly were "anonymous" then you would
find it impossible to reliably decrypt the data on the other end.  For
example, every RSA private key should be indexed either by the X.509
DN or for bare SSH keys by the public modulus information.  Even
transient SSL session keys are always put into an SSL session cache by
apache or whatever to allow them to be reused across multiple TCP
streams!  So I would argue that an SSL implementation that uses this
should actually create or use a keyring specifically as an SSL session
cache (with keys indexed by SSL session ID).

It then becomes trivial to share an SSL session cache between 3
independent HTTPS server programs from different vendors, such that
the compromise of *any* of the processes would not in any way
compromise the security of the session keys.  This would be especially
true if the session keys are actually generated by a keyring+cryptoapi
operation in the kernel.

So my recommendation would be to create some new operations of the
existing keyring code:

(1) If you *really* care about anonymous transient keys that are not
identified by an SSL session ID or similar, then add a keyring
operation for "create an anonymous key in keyring X, where the kernel
creates a proper temporary name".  An SSL implementation would default
to using the process-local keyring, which means that everything would
automatically go away on process exit.

(2) Add cryptoapi hooks to automatically register keyring key types
based on the loaded cryptoapi modules.

(3) Add any necessary keyring operations for efficiently performing
zero-copy cryptoapi calls using those key types.

Cheers,
Kyle Moffett

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

On 09/06/2010 08:00 PM, Kyle Moffett wrote:

>> The kernel keyring service is basically a system-wide data storage
>> service.  /dev/crypto needs a quick way to refer to short-lived,
>> usually process-local, kernel-space data structures from
>> userspace.
> The problem with the approach you're proposing is that we then have 
> two entirely separate classes of keys.  First we have the existing 
> keyring class, which can be securely and revokably passed between 
> different processes with limited rights, but cannot be handed up to 
> the kernel's cryptoapi.

I don't think this is the case. The NCR does not store any keys nor
retrieves them. It does delegate the burden of that to userspace
application. NCR exports a wrapped version of the key and the userspace
application stores it. It could use the keyring to store the keys or
could directly store them in the filesystem.


> Then we have your new class, which are anonymous keys with a brand
> new security model
> (which doesn't even have LSM hooks yet)

and what would this suggest?

> and which cannot be referenced by name. Another potential issue is
> that keys are never actually "unnamed", in that sense.  If encryption
> keys truly were "anonymous" then you would find it impossible to
> reliably decrypt the data on the other end.  For example, every RSA
> private key should be indexed either by the X.509 DN or for bare SSH
> keys by the public modulus information. 
> Even transient SSL session
> keys are always put into an SSL session cache by apache or whatever
> to allow them to be reused across multiple TCP streams!  So I would
> argue that an SSL implementation that uses this should actually
> create or use a keyring specifically as an SSL session cache (with
> keys indexed by SSL session ID).

Each key of NCR contains a key ID, that is the same in public
and private keys (if generated by NCR), and that could be used to index
it. Secret keys have a key id specified by the user. It does not require
you to use it though.


> It then becomes trivial to share an SSL session cache between 3 
> independent HTTPS server programs from different vendors, such that 
> the compromise of *any* of the processes would not in any way 
> compromise the security of the session keys. 

If you are sharing a cache, the protection given by NCR is actually not
used. Unless of course you start wrapping keys to ensure that noone
unauthorized except from the legitimate systems access them. Doing the
crypto in user-space would be more efficient in that case.

> So my recommendation would be to create some new operations of the 
> existing keyring code:
> (1) If you *really* care about anonymous transient keys that are not 
> identified by an SSL session ID or similar, then add a keyring 
> operation for "create an anonymous key in keyring X, where the
> kernel creates a proper temporary name".  An SSL implementation would
> default to using the process-local keyring, which means that
> everything would automatically go away on process exit.
> (2) Add cryptoapi hooks to automatically register keyring key types 
> based on the loaded cryptoapi modules.
> (3) Add any necessary keyring operations for efficiently performing 
> zero-copy cryptoapi calls using those key types.

I cannot get the big picture of you suggestions. How does this fit to
NCR given the explanation on how keys are (not) stored by NCR. Is your
suggestion about convenience calls to retrieve and store keys from and
to keyring? Or you are suggesting NCR to be using the keyring for its
internal reference of keys?

If it is the latter, what would be the advantage of doing that?

regards.
Nikos

Re: [PATCH 01/19] User-space API definition

[Kyle Moffett]

On Mon, Sep 6, 2010 at 15:13, Nikos Mavrogiannopoulos
<n.mavrogiannopoulos@gmail.com> wrote:
> On 09/06/2010 08:00 PM, Kyle Moffett wrote:
>>> The kernel keyring service is basically a system-wide data storage
>>> service.  /dev/crypto needs a quick way to refer to short-lived,
>>> usually process-local, kernel-space data structures from
>>> userspace.
>>
>> The problem with the approach you're proposing is that we then have
>> two entirely separate classes of keys.  First we have the existing
>> keyring class, which can be securely and revokably passed between
>> different processes with limited rights, but cannot be handed up to
>> the kernel's cryptoapi.
>
> I don't think this is the case. The NCR does not store any keys nor
> retrieves them. It does delegate the burden of that to userspace
> application. NCR exports a wrapped version of the key and the userspace
> application stores it. It could use the keyring to store the keys or
> could directly store them in the filesystem.

Hmm, I'm confused.  You say "The NCR does not store any keys nor
retrieves them", but ~75% of your API is specifically related to
storing keys into kernel memory or retrieving them out of kernel
memory.  Specifically, putting keys into and out of the kernel and
passing them around between processes is the *whole point* of the
keyring API.

So let me ask for some clarification:

You talk a lot in the patches about the API itself, but what is the
intended *use-case* for NCR?

Is it to provide a back-end for code such as enhanced-security OpenSSL
libraries?  For example, a privileged process would loads a key from
disk into the kernel, then fork the unprivileged SSL server process?

Is it just a canonical interface for userspace to encrypt or decrypt
data using the kernel's CryptoAPI?

Cheers,
Kyle Moffett

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

On 09/06/2010 10:42 PM, Kyle Moffett wrote:

>>> The problem with the approach you're proposing is that we then have
>>> two entirely separate classes of keys.  First we have the existing
>>> keyring class, which can be securely and revokably passed between
>>> different processes with limited rights, but cannot be handed up to
>>> the kernel's cryptoapi.
>>
>> I don't think this is the case. The NCR does not store any keys nor
>> retrieves them. It does delegate the burden of that to userspace
>> application. NCR exports a wrapped version of the key and the userspace
>> application stores it. It could use the keyring to store the keys or
>> could directly store them in the filesystem.
> 
> Hmm, I'm confused.  You say "The NCR does not store any keys nor
> retrieves them", but ~75% of your API is specifically related to
> storing keys into kernel memory or retrieving them out of kernel
> memory.
> Specifically, putting keys into and out of the kernel and
> passing them around between processes is the *whole point* of the
> keyring API.

I suppose you mean the reference to the internal representation of the
key. This might be valid for few seconds until the required operation is
over.
This is not really what I would call storage. The storage and retrieval
of keys is being done using two ioctl() the STORAGE_WRAP and STORAGE_UNWRAP.

An example of how NCR works:
1. A Process generates an RSA key pair
2. Stores the (encrypted) pair using the STORAGE_WRAP to a file.

3. Another process loads the file, unwraps it using STORAGE_UNWRAP and
gets a reference to the key
4. Does an RSA decryption using the key
5. Discards the reference to the key

Consider the reference as a file descriptor after you have opened a file
(a wrapped key).

How do you see keyring being involved in a setup like this?

> So let me ask for some clarification:
> You talk a lot in the patches about the API itself, but what is the
> intended *use-case* for NCR?

In short: cryptographic operations.

> Is it to provide a back-end for code such as enhanced-security OpenSSL
> libraries?  For example, a privileged process would loads a key from
> disk into the kernel, then fork the unprivileged SSL server process?

An unprivileged process will load a key from disk to kernel and use it.
The keys leave the NCR framework only encrypted and authenticated.

> Is it just a canonical interface for userspace to encrypt or decrypt
> data using the kernel's CryptoAPI?

I don't understand what do you mean by canonical, but this API can be
used to perform crypto operations. It uses the internal linux API where
possible.

regards,
Nikos

Re: [PATCH 01/19] User-space API definition

[Kyle Moffett]

On Mon, Sep 6, 2010 at 17:11, Nikos Mavrogiannopoulos
<n.mavrogiannopoulos@gmail.com> wrote:
> I suppose you mean the reference to the internal representation of the
> key. This might be valid for few seconds until the required operation is
> over.
>
> This is not really what I would call storage. The storage and retrieval
> of keys is being done using two ioctl() the STORAGE_WRAP and STORAGE_UNWRAP.
>
> An example of how NCR works:
> 1. A Process generates an RSA key pair
> 2. Stores the (encrypted) pair using the STORAGE_WRAP to a file.
>
> 3. Another process loads the file, unwraps it using STORAGE_UNWRAP and
> gets a reference to the key
> 4. Does an RSA decryption using the key
> 5. Discards the reference to the key
>
> Consider the reference as a file descriptor after you have opened a file
> (a wrapped key).
>
> How do you see keyring being involved in a setup like this?

Fundamentally the operations you described are *EXACTLY* the kind of
things that I believe the keyring API should support.  It does not
support them now, but that API is where the described functionality
really belongs.  Please consider just extending the keyring API to
support what you need.

For example, assuming that we automatically register 1 keyring key
type per algo it should be pretty straightforward.

You would want to write a "request_key()" handler for those key types
which can use whatever hardware support is available to automatically
generate a new random key or alternatively pass the operation off to
the /sbin/request-key process to generate and load one from userspace.
 The call might take a *long* time to complete, depending on the key
type and whether or not there is hardware support.

That would allow you to perform the "generate an RSA key" step in
either a trusted "request-key" process or directly in a piece of
hardware, helping to avoid accidental key material leaks from the
unprivileged process.

Then, you would want "KEYCTL_DECRYPT_KEY", and "KEYCTL_ENCRYPT_KEY"
which would use one key to encrypt another into a user buffer (or
decrypt a key from a user buffer).  These would probably need new LSM
hooks and maybe key DAC permission bits.

This would implement the "STORAGE_WRAP" and "STORAGE_UNWRAP"
functionality you want, but it would be extensible to much more than
just what NCR needs.  I could see this being very useful as an
extension to the existing Kerberos or NFS keyring usage.  Other
potential applications include very secure replacements for the SSH or
GPG agent programs.

For the final step of actually performing encryption/decryption of
user data you would then want generic keyctl() ops for
"KEYCTL_ENCRYPT" and "KEYCTL_DECRYPT", which would simply call
CryptoAPI with the user-provided input and output buffers.  Again,
you'd need new LSM hooks, etc.  These are very obviously extensible to
other applications.

It's getting a bit late here, so I apologize if anything I've written
above makes particularly little sense, but hopefully I've gotten the
gist across.

Cheers,
Kyle Moffett

Re: [PATCH 01/19] User-space API definition

[Miloslav Trmac]

----- "Kyle Moffett" <kyle@moffetthome.net> wrote:
> On Fri, Aug 20, 2010 at 04:45, Miloslav Trmač <mitr@redhat.com>
> wrote:
> > * ioctl(NCRIO_KEY_INIT) to allocate a key object; then generate the key
> >  material inside the kernel, load a plaintext key, unwrap a key, or
> >  derive a key.  Similarly the key material can be copied out of the
> >  kernel or wrapped.
> >
> Ugh... We already have one very nice key/keyring API in the kernel
> (see Documentation/keys.txt) that's being used for crypto keys for
> NFSv4, AFS, etc.  Can't you just add a bunch of cryptoapi key types to
> that API instead?
I have examined that API; going purely by the names, having only one facility to manage "keys" does sound reasonable.

Looking at the details, the keyring API is primarily designed for long-term secure storage of unstructured, named blobs, in various namespaces - in some respects it is quite similar to a memory-only filesystem: each key has an explicit name and permissions, there is a hierarchy, and keys are designed to be shared between processes (although in some namespaces they are not).

The keys for crypto are often short-lived, almost exclusively local to a specific process, most don't have an unique name (which means a kernel-choosen integer is a better identifier than an application-choosen string, especially if user-space libraries hide the existence of the kernel crypto API from applications, because choosing an unique string identifier is non-trivial).  The crypto keys also are also formatted for use by a specific algorithm, often using a non-trivial format (e.g. a RSA key should be internally stored as the separate integer components, not as a blob).  They have some attribute flags, with no overlap with the flags in the keyring API.

I can see almost no overlap between the two sets of requirements.  Probably the only common use case is handling session keys (e.g. keys used in a kerberos ticket), which should be stored in the kernel for the duration of the session, made available to each process in the session, and available as keys for kernel crypto.  Such keys will be in the minority, though, and it seems to me the best approach for handling these is to allow key export/import from/to keyring keys in addition to export/import from/to data in userspace: the long-term storage would be handled by the existing keyring API, which stores the key as unformatted binary data, and import into the crypto context would convert the key into the internal representation more suitable for crypto.

I have seriously considered the keyring API, and this is what I came up with - but I'd love to be shown a better way.
    Mirek

Re: [PATCH 01/19] User-space API definition

[Herbert Xu]

On Mon, Aug 23, 2010 at 11:37:40AM -0400, Miloslav Trmac wrote:
>
> I can see almost no overlap between the two sets of requirements.  Probably the only common use case is handling session keys (e.g. keys used in a kerberos ticket), which should be stored in the kernel for the duration of the session, made available to each process in the session, and available as keys for kernel crypto.  Such keys will be in the minority, though, and it seems to me the best approach for handling these is to allow key export/import from/to keyring keys in addition to export/import from/to data in userspace: the long-term storage would be handled by the existing keyring API, which stores the key as unformatted binary data, and import into the crypto context would convert the key into the internal representation more suitable for crypto.
> 
> I have seriously considered the keyring API, and this is what I came up with - but I'd love to be shown a better way.

FWIW adding a second key management system to the kernel is
totally out of the question.

If the existing system doesn't work for you, find a way to build
on it so that it does.  Adding a second system that pretty much
does the same thing is unacceptable.

Also, the key management for secret keys that you've added should
not be the only mode offered to the user.  Most people do not need
the separation between key setting and encryption/decryption.

Cheers,
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

On 09/06/2010 02:17 PM, Herbert Xu wrote:
> On Mon, Aug 23, 2010 at 11:37:40AM -0400, Miloslav Trmac wrote:
>>
>> I can see almost no overlap between the two sets of requirements.  Probably the only common use case is handling session keys (e.g. keys used in a kerberos ticket), which should be stored in the kernel for the duration of the session, made available to each process in the session, and available as keys for kernel crypto.  Such keys will be in the minority, though, and it seems to me the best approach for handling these is to allow key export/import from/to keyring keys in addition to export/import from/to data in userspace: the long-term storage would be handled by the existing keyring API, which stores the key as unformatted binary data, and import into the crypto context would convert the key into the internal representation more suitable for crypto.
>>
>> I have seriously considered the keyring API, and this is what I came up with - but I'd love to be shown a better way.
> 
> FWIW adding a second key management system to the kernel is
> totally out of the question.
> 
> If the existing system doesn't work for you, find a way to build
> on it so that it does.  Adding a second system that pretty much
> does the same thing is unacceptable.
> 
> Also, the key management for secret keys that you've added should
> not be the only mode offered to the user.  Most people do not need
> the separation between key setting and encryption/decryption.

I think this is a misunderstanding. The NCR does not have a keyring. The
only common thing it has with a keyring is the word "key". The fact that
it holds a reference to the key being used for encryption doesn't really
make it a keyring. The kernel Keyring can be used with NCR to store keys
as well as any other keyring.

regards,
Nikos

[PATCH 00/19] RFC, v2: "New" /dev/crypto user-space interface

[Miloslav Trmač]

Hello,
following is a patchset providing an user-space interface to the kernel crypto
API.  It is based on the older, BSD-compatible, implementation, but the
user-space interface is different.

Major changes since the previous post:
* "struct nlattr"-based extensible attributes used for extensibility
  of most operations, both for input and output attributes
* algorithms (ciphers, key wrapping, key derivation) are identified using
  strings in the userspace API
* Full compat_ioctl implementation
* Version number added to the data format used when wrapping keys for storage
* Patch set split into smaller parts, reordered to keep the tree buildable.
  (If you want to review primarily the user-space API, see patches
  1,14,15,17,18.)

  The libtom* patches will probably still be too large for the mailing list;
  the whole patch set is also available at
  http://people.redhat.com/mitr/cryptodev-ncr/v2/ .

Original patch set description follows.

These are the major differences compared to the BSD-like interface:

* The API supports key storage and management inside the kernel.
  An application can thus ask the kernel to generate a key; the key is
  then referenced via an integer identifier, and the application can be
  prevented from accessing the raw key data.  Such a key can, if so configured,
  still be wrapped for key transport to the recipient of the message, and
  unwrapped by the recipient.

  The kernel key storage does not span system reboots, but applications can
  also wrap the keys for persistent storage, receiving an encrypted blob that
  does not reveal the raw key data, but can be later loaded back into the
  kernel.

* More algorithms and mechanisms are supported by the API, including public key
  algorithms (RSA/DSA encryption and signing, D-H key derivation, key wrapping).

Motivations for the extensions: governments are asking for more security
features in the operating systems they procure, which make user-space
implementations impractical.  A few examples:

* Advanced crypto module for OSPP for Common Criteria requires OS services
  implementing several low-level crypto algorithms (e.g. AES, RSA).  This
  requires the separation of crypto services from the consumer of those
  services. (The threat model is that apps tend to have more vulnerabilities
  than libraries and compromise of the app will lead to the ability to access
  key material.) An user-space library is not separated, options are a) root
  running daemon that does crypto, but this would be slow due to context
  switches, scheduler mismatching and all the IPC overhead and b) use crypto
  that is in the kernel.

* FIPS-140-3 calls out for cryptographic functions to be non-debuggable (ptrace)
  meaning that you cannot get to the key material. The solution is the same as
  above.

* GPOSPP requires auditing for crypto events (so does FIPS-140 level 2 cert).
  To do this you need any crypto to have CAP_AUDIT_WRITE permissions which
  means making everything that links to openssl, libgcrypt, or nss setuid
  root. Making firefox and 400 other applications setuid root is a non-starter.
  So, the solution is again to use crypto in the kernel where auditing needs no
  special permissions.

Other advantages to having kernel crypto available to user space:

* User space will be able to take advantage of kernel drivers for hardware
  crypto accelerators.

* glibc, which in some configurations links to libfreebl3.so for hashes
  necessary for crypt(), will be able to use the kernel implementation; this
  means one less library to load and dynamically link for each such process.

The code is derived from the original cryptodev-linux patch set; most of the
new implementation was written by Nikos Mavrogiannopoulos
<n.mavrogiannopoulos@gmail.com>.  Attributions are included in the respective
source files.

[PATCH 01/19] User-space API definition

[Miloslav Trmač]

This patch introduces the new user-space API, <ncr.h>.

Quick overview:

* open("/dev/crypto") to get a FD, which acts as a namespace for key and
  session identifiers.

* ioctl(NCRIO_KEY_INIT) to allocate a key object; then generate the key
  material inside the kernel, load a plaintext key, unwrap a key, or
  derive a key.  Similarly the key material can be copied out of the
  kernel or wrapped.

* ioctl(NCRIO_SESSION_INIT) to allocate a crypto session (to encrypt,
  decrypt, hash, sign, or verify signature), then
  ioctl(NCRIO_SESSION_UPDATE) to act on chunks of data.  Deallocate the
  session, and optionally retrieve session results (e.g. hash or
  signature), using ioctl(NCRIO_SESSION_FINAL).

  There is also NCRIO_SESSION_ONCE for an one-shot crypto operation
  using a single user->kernel context switch.

Full documentation of the interface is in
Documentation/crypto/userspace.txt .
---
 Documentation/crypto/userspace.txt |  510 ++++++++++++++++++++++++++++++++++++
 include/linux/Kbuild               |    1 +
 include/linux/ncr.h                |  273 +++++++++++++++++++
 3 files changed, 784 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/crypto/userspace.txt
 create mode 100644 include/linux/ncr.h

diff --git a/Documentation/crypto/userspace.txt b/Documentation/crypto/userspace.txt
new file mode 100644
index 0000000..5839fda
--- /dev/null
+++ b/Documentation/crypto/userspace.txt
@@ -0,0 +1,510 @@
+CRYPTO(4)                  Linux Programmer’s Manual                 CRYPTO(4)
+
+NAME
+       /dev/crypto - kernel cryptographic module interface
+
+SYNOPSIS
+       #include <ncr.h>
+       int fd = open("/dev/crypto", O_RDWR);
+       int res = ioctl(fd, NCRIO..., &data);
+
+DESCRIPTION
+       The  /dev/crypto device file provides an ioctl(2) interface to the ker-
+       nel-space crypto implementation.
+
+       Each open(2) of the /dev/crypto file establishes a  separate  namespace
+       within  which  crypto  operations  work.   The  namespace can be shared
+       across threads and processes by  sharing  the  open  file  description.
+       Last  close  of  the  open  file description automatically destroys all
+       objects allocated within the namespace.
+
+       All ioctl(2)s have the same form: The user sets  up  a  data  structure
+       with  input  data,  and  passes  a pointer to the data structure as the
+       third parameter to ioctl(2).  On success, output data is  available  in
+       the same structure.
+
+OPERATION ATTRIBUTES
+       In addition to the fixed members of data structures, a process can pass
+       additional attributes on input of most operations,  and  receive  addi-
+       tional attributes back from the kernel.  If this is supported by a spe-
+       cific operation, the fixed data structure members  for  this  operation
+       include input_size and output_size.
+
+       The  input  attributes immediately follow the fixed data structure as a
+       sequence of correctly aligned (struct nlattr,  attribute  data)  pairs,
+       using the same data layout and formatting rules as netlink(7) messages.
+       The input_size member must be initialized to the total length of  input
+       (including both the fixed data structure and the attributes).
+
+       There  is  an  (unspecified)  upper  limit  on  the  total  size of all
+       attributes, which should be large enough to accommodate any  reasonable
+       application.  If a larger input is provided nevertheless, the operation
+       will fail with EOVERFLOW.
+
+       Output attributes, if any, are written by the kernel in the same format
+       following  the  fixed  data structure (overwriting input attributes, if
+       any).  The output_size member must be initialized to  the  total  space
+       available  for output (including the fixed data structure and space for
+       attributes), and is updated by the kernel with the total space actually
+       used for attributes.
+
+       If  the  space available for output attributes is too small, the opera-
+       tion will fail with ERANGE.
+
+       As a special  case,  input_size  may  be  zero  to  indicate  no  input
+       attributes  are  supplied.  Similarly, output_size may be zero to indi-
+       cate no space for output attributes is  provided;  in  such  case  out-
+       put_size is not overwritten by the kernel with the total space actually
+       used (which is equal to size of the fixed data structure)  and  remains
+       zero when the operation finishes.
+
+       The kernel accepts and silently ignores unknown attributes.
+
+       The kernel will not add new output attributes to existing operations in
+       future  releases  unless  the  new  output  attribute  was   explicitly
+       requested  by  the  application.   (Therefore, the application does not
+       have to allocate any extra space for  output  attributes  it  does  not
+       expect.)
+
+       The following attributes are used in more than one operation:
+
+       NCR_ATTR_ALGORITHM
+              A  NUL-terminated  string specifying an algorithm (to be used in
+              an operation, or as a property of a key), using the Linux crypto
+              API algorithm names.
+
+              Three additional algorithm names are recognized: rsa, dsa, dh.
+
+       NCR_ATTR_IV
+              Unformatted binary data specifying an initialization vector,
+
+       NCR_ATTR_KEY_FLAGS
+              An  32-bit  unsigned integer in native byte order specifying key
+              flags, a combination of NCR_KEY_FLAG_EXPORTABLE (the  key  mate-
+              rial   can   be   exported  in  plaintext  to  user  space)  and
+              NCR_KEY_FLAG_WRAPPABLE (the key material can be wrapped and  the
+              result made available to user space).
+
+       NCR_ATTR_KEY_ID
+              Arbitrary  binary  data which can be used by the application for
+              key identification.
+
+       NCR_ATTR_KEY_TYPE
+              An 32-bit unsigned integer in native byte order  specifying  key
+              type,   one   of  NCR_KEY_TYPE_SECRET,  NCR_KEY_TYPE_PUBLIC  and
+              NCR_KEY_TYPE_PRIVATE.
+
+       NCR_ATTR_WRAPPING_ALGORITHM
+              A NUL-terminated string specifying  a  key  wrapping  algorithm.
+              The  values  walg-aes-rfc3394 and walg-aes-rfc5649 are currently
+              supported.
+
+OPERATIONS
+       The following operations are defined:
+
+       NCRIO_KEY_INIT
+              Allocate a kernel-space key object.  The third ioctl(s)  parame-
+              ter is ignored (key attributes are set later, when the key mate-
+              rial is initialized).  Returns an ncr_key_t descriptor  for  the
+              key  object  (valid within the current /dev/crypto namespace) on
+              success.
+
+              There is a per-process and per-user (not per-namespace) limit on
+              the number key objects that can be allocated.
+
+       NCRIO_KEY_DEINIT
+              Deallocate a kernel-space key object.  The parameter points to a
+              ncr_key_t descriptor of the key object.  After all other  opera-
+              tions using this key object (if any) terminate, the key material
+              will be cleared and the object will be freed.   Note  that  this
+              may  happen  both  before  this  operation returns, and after it
+              returns, depending on other references to this key object.
+
+       NCRIO_KEY_GENERATE
+              Clear existing key material in the  specified  key  object,  and
+              generate new key material.
+
+              The parameter points to struct ncr_key_generate, which specifies
+              the destination key object in its key member.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_ALGORITHM
+                     Mandatory.
+
+              NCR_ATTR_KEY_FLAGS
+                     Optional, flags are unchanged if not present.
+
+              NCR_ATTR_SECRET_KEY_BITS
+                     Mandatory for symmetric keys.  An 32-bit unsigned integer
+                     in native byte order specifying key length in bits.
+
+              Only symmetric keys can be currently generated using this opera-
+              tion.
+
+              In addition to generating the key material, the "persistent" key
+              ID is reset to a random value.
+
+       NCRIO_KEY_GENERATE_PAIR
+              Similar to NCRIO_KEY_GENERATE, except that a pair of public/pri-
+              vate keys is generated.
+
+              The parameter  points  to  struct  ncr_key_generate_pair,  which
+              specifies  the  destination  key  objects in its private_key and
+              public_key members.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_KEY_FLAGS
+                     Optional, flags are unchanged if not present.
+
+              NCR_ATTR_RSA_E
+                     For RSA keys, the public exponent as a big-endian  multi-
+                     ple-precision integer.  Optional, defaults to 65537.
+
+              NCR_ATTR_RSA_MODULUS_BITS
+                     Mandatory  for  RSA  keys.  An 32-bit unsigned integer in
+                     native byte order specifying modulus length in bits.
+
+              NCR_ATTR_DSA_P_BITS
+                     For DSA keys, length of the "p" key parameter in bits  as
+                     an   32-bit   unsigned  integer  in  native  byte  order.
+                     Optional, defaults to 1024.
+
+              NCR_ATTR_DSA_Q_BITS
+                     For DSA keys, length of the "q" key parameter in bits  as
+                     an   32-bit   unsigned  integer  in  native  byte  order.
+                     Optional, defaults to 160.
+
+              NCR_ATTR_DH_BASE
+                     Mandatory for D-H keys.  The prime modulus of a D-H group
+                     as a big-endian multiple-precision integer.
+
+              NCR_ATTR_DH_PRIME
+                     Mandatory  for D-H keys.  The generator of a D-H group as
+                     a big-endian multiple-precision integer.
+
+              The NCR_KEY_FLAG_EXPORTABLE and NCR_KEY_FLAG_WRAPPABLE flags are
+              automatically set on the public key.
+
+              In addition to generating the key material, the "persistent" key
+              ID of both keys is set to a same value derived from  the  public
+              key.
+
+       NCRIO_KEY_DERIVE
+              Derive a new key using one key and additional data.
+
+              The  parameter  points to struct ncr_key_derive, which specifies
+              the source and destination keys in  the  input_key  and  new_key
+              members.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_KEY_FLAGS
+                     Optional, flags are unchanged if not present.
+
+              NCR_ATTR_DERIVATION_ALGORITHM
+                     Mandatory.   A  NUL-terminated  string  specifying  a key
+                     derivation algorithm.  Only dh is currently supported.
+
+              NCR_ATTR_DH_PUBLIC
+                     Mandatory for D-H  derivation.   The  peer’s  public  D-H
+                     value as a big-endian multiple-precision integer.
+
+       NCRIO_KEY_EXPORT
+              Export  key  material in the specified key object to user space.
+              Only keys with the NCR_KEY_FLAG_EXPORTABLE flag can be  exported
+              using this operation.
+
+              The  parameter  points to struct ncr_key_export, which specifies
+              the key to export in the  key  member,  and  a  buffer  for  the
+              exported data in the buffer and buffer_size members.
+
+              On success, size of the exported key is returned.
+
+              Symmetric keys are written directly into the destination buffer.
+              Public and private keys are formatted using ASN.1, except for DH
+              public keys, which are written a raw binary number.
+
+       NCRIO_KEY_IMPORT
+              Clear  existing  key  material  in the specified key object, and
+              import key material from user space.
+
+              The parameter points to struct ncr_key_import,  which  specifies
+              the destination key in the key member, and the input data in the
+              data and data_size members.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_ALGORITHM
+                     Mandatory.
+
+              NCR_ATTR_KEY_FLAGS
+                     Optional, flags are unchanged if not present.
+
+              NCR_ATTR_KEY_ID
+                     Optional, the "persistent" key ID  is  unchanged  if  not
+                     present.
+
+              NCR_ATTR_KEY_TYPE
+                     Mandatory.
+
+              The  data  format  is the same as in the NCRIO_KEY_EXPORT opera-
+              tion.
+
+       NCRIO_KEY_GET_INFO
+              Get metadata of an existing key.
+
+              The parameter points to struct ncr_key_get_info, which specifies
+              key, the key descriptor.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_WANTED_ATTRS
+                     An  array  of  unsigned  16-bit  integers  in native byte
+                     order, specifying  the  set  of  output  attributes  that
+                     should       be       returned.       NCR_ATTR_ALGORITHM,
+                     NCR_ATTR_KEY_FLAGS and  NCR_ATTR_KEY_TYPE  are  currently
+                     supported.   Unsupported  attribute requests are silently
+                     ignored
+
+              The    output     attributes     explicitly     requested     in
+              NCR_ATTR_WANTED_ATTRS,  and  no  other  output  attributes,  are
+              returned.
+
+       NCRIO_KEY_WRAP
+              Wrap one key using another, and write the result to user  space.
+              Only  keys  with  the NCR_KEY_FLAG_WRAPPABLE flag can be wrapped
+              using this operation.
+
+              The parameter points to struct ncr_key_wrap, which specifies the
+              key  to  wrap  in the source_key member, the wrapping key in the
+              wrapping_key member, and a buffer for the wrapped  data  in  the
+              buffer and buffer_size members.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_IV
+                     Optional, an empty IV is used if not present.
+
+              NCR_ATTR_WRAPPING_ALGORITHM
+                     Mandatory.
+
+              Only secret keys can be currently wrapped.
+
+              On success, size of the wrapped key is returned.
+
+       NCRIO_KEY_UNWRAP
+              Unwrap  user-space  data  into  a kernel-space key using another
+              key.
+
+              The parameter points to struct ncr_key_unwrap,  which  specifies
+              the  destination key in the dest_key member, the wrapping key in
+              the wrapping_key member, and the wrapped data in  the  data  and
+              data_size members.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_IV
+                     Optional, an empty IV is used if not present.
+
+              NCR_ATTR_WRAPPING_ALGORITHM
+                     Mandatory.
+
+              The unwrapped key will have the NCR_KEY_FLAG_WRAPPABLE flag set,
+              and the NCR_KEY_FLAG_EXPORTABLE flag clear.
+
+       NCRIO_KEY_STORAGE_WRAP
+              Wrap a key object and associated metadata using the  system-wide
+              storage master key, and write the result to user space.
+
+              Only  keys  with  the NCR_KEY_FLAG_WRAPPABLE flag can be wrapped
+              using this operation.
+
+              The parameter points to struct ncr_key_storage_wrap, which spec-
+              ifies  the  key  to wrap in the key member, and a buffer for the
+              wrapped data in the buffer and buffer_size members.
+
+              On success, size of the wrapped key is returned.
+
+              Both symmetric and asymmetric keys can  be  wrapped  using  this
+              operation.   The  wrapped  data  includes data corresponding the
+              NCR_ATTR_ALGORITHM,  NCR_ATTR_KEY_FLAGS,  NCR_ATTR_KEY_TYPE  and
+              NCR_ATTR_KEY_ID attributes in addition to the raw key material:
+
+       NCRIO_KEY_STORAGE_UNWRAP
+              Unwrap key and associated metadata created using NCRIO_KEY_STOR-
+              AGE_WRAP, and restore  the  information  into  a  specified  key
+              object.
+
+              The  parameter  points  to  struct ncr_key_storage_unwrap, which
+              specifies the destination key in the key member and the  wrapped
+              data in the data and data_size members.
+
+              See NCRIO_KEY_STORAGE_WRAP above for the list of attributes that
+              will be restored.
+
+       NCRIO_SESSION_INIT
+              Allocate a session for performing crypto operations.
+
+              The parameter points to struct ncr_session_init, which specifies
+              the operation to perform, one of NCR_OP_ENCRYPT, NCR_OP_DECRYPT,
+              NCR_OP_SIGN  and  NCR_OP_VERIFY,  in   the   op   member.    Use
+              NCR_OP_SIGN  for  computing  an  unkeyed  hash  as well as keyed
+              hashes and signatures.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_ALGORITHM
+                     Mandatory.
+
+              NCR_ATTR_IV
+                     Mandatory for some operations and algorithms.
+
+              NCR_ATTR_KEY
+                     Mandatory for some operations and algorithms.  An  32-bit
+                     unsigned  integer in native byte order specifying the key
+                     to use for the operation.
+
+              NCR_ATTR_RSA_ENCODING_METHOD
+                     Mandatory for RSA.  An 32-bit unsigned integer in  native
+                     byte  order  specifying  a  RSA  encoding  method, one of
+                     RSA_PKCS1_V1_5, RSA_PKCS1_OAEP and RSA_PKCS1_PSS.
+
+              NCR_ATTR_RSA_OAEP_HASH_ALGORITHM
+                     Mandatory for RSA with RSA_PKCS1_OAEP.  A  NUL-terminated
+                     string  specifying  a  hash  algorithm  used  in the OAEP
+                     encoding method.
+
+              NCR_ATTR_RSA_PSS_SALT_LENGTH
+                     For RSA with RSA_PKCS1_PSS.  An 32-bit  unsigned  integer
+                     in  native  byte  order  specifying  the PSS salt length.
+                     Optional, defaults to 0.
+
+              NCR_ATTR_SIGNATURE_HASH_ALGORITHM
+                     Mandatory for some operations and algorithms.  A NUL-ter-
+                     minated  string  specifying a hash algorithm underlying a
+                     signature, using the same formats as  NCR_ATTR_ALGORITHM.
+
+              On success, an integer descriptor for the created session (valid
+              within the current /dev/crypto namespace) is returned.
+
+       NCRIO_SESSION_UPDATE
+              Update an existing crypto session with new data (for operations,
+              such  as  hashing, for which data can be supplied in pieces), or
+              perform a single operation using the session context (for opera-
+              tions,  such  as  public  key  encryption, that work on separate
+              units of data).
+
+              The parameter points to struct ncr_session_update, which  speci-
+              fies the descriptor of the session in the ses member.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_UPDATE_INPUT_DATA
+                     A  struct ncr_session_input_data specifying input for the
+                     operation in its data and data_size members.
+
+              NCR_ATTR_UPDATE_INPUT_KEY_AS_DATA
+                     An 32-bit unsigned integer in native byte order  specify-
+                     ing  the  key  descriptor serving as input for the opera-
+                     tion.  This can be currently used only to compute or ver-
+                     ify  a  signature  or hash of a symmetric key: the keying
+                     material is directly used as input data for the  underly-
+                     ing hash.
+
+              NCR_ATTR_UPDATE_OUTPUT_BUFFER
+                     Mandatory  for  some operations and algorithms.  A struct
+                     ncr_session_output_buffer specifying buffer for operation
+                     output in its buffer and buffer_size members.  On success
+                     the size of output is written to the variable pointed  to
+                     by the result_size_ptr member.
+
+              It is mandatory to include one of the NCR_ATTR_UPDATE_INPUT_DATA
+              and NCR_ATTR_UPDATE_INPUT_KEY_AS_DATA attributes.
+
+              For the NCR_OP_ENCRYPT and NCR_OP_DECRYPT operations using  sym-
+              metric  ciphers,  the  operation is performed on the input data,
+              resulting in an output data block of the same size;  for  opera-
+              tions  using public-key cryptography, a single operation is per-
+              formed on the input data, resulting in output data.
+
+              For the NCR_OP_SIGN and NCR_OP_VERIFY operations, the input data
+              is  supplied  to the underlying hash function; no output data is
+              produced.
+
+       NCRIO_SESSION_FINAL
+              Finalize an existing crypto session and deallocate it.
+
+              The parameter points to struct ncr_session_final,  which  speci-
+              fies the descriptor of the session in the ses member.
+
+              If     one     of     the     NCR_ATTR_UPDATE_INPUT_DATA     and
+              NCR_ATTR_UPDATE_INPUT_KEY_AS_DATA  attributes  is  present,  all
+              attributes are first processed as if using NCRIO_SESSION_UPDATE;
+              thus, the last update operation can be performed  together  with
+              the finalization in one step.
+
+              The following input attributes are recognized:
+
+              NCR_ATTR_FINAL_INPUT_DATA
+                     Mandatory  for  some operations and algorithms.  A struct
+                     ncr_session_input_data  as  described  above,  specifying
+                     input for the operation.
+
+              NCR_ATTR_FINAL_OUTPUT_BUFFER
+                     Mandatory  for  some operations and algorithms.  A struct
+                     ncr_session_output_buffer as described above,  specifying
+                     buffer for operation output.
+
+              There  is  no  specific  finalization  operation  performed  for
+              NCR_OP_ENCRYPT and NCR_OP_DECRYPT.
+
+              For the NCR_OP_SIGN operation,  the  signature  is  created  and
+              written as output data.
+
+              For  the NCR_OP_VERIFY operation, a signature specified as input
+              is verified and the result of this operation is  returned:  non-
+              zero for a valid signature, zero for an invalid signature.  Note
+              that the ioctl(2) operation return value will  be  non-negative,
+              i.e.  "success",  even  if  the signature verification fails, as
+              long all inputs were specified correctly.
+
+              The session will be deallocated even if the  NCRIO_SESSION_FINAL
+              operation  reports an error, as long as a valid session descrip-
+              tor was specified.
+
+       NCRIO_SESSION_ONCE
+              Perform an one-shot crypto  operation,  allocating  a  temporary
+              session, supplying a single instance of data, and finalizing the
+              session in one operation.
+
+              The parameter points to struct ncr_session_once, which specifies
+              the operation to perform in the op member.
+
+              The  attributes handled as if by passing to a NCRIO_SESSION_INIT
+              operation followed by a NCRIO_SESSION_FINAL operation,  and  the
+              return  value of the NCRIO_SESSION_FINAL is returned on success.
+
+       NCRIO_MASTER_KEY_SET
+              Set the system-wide storage master key.   Only  a  process  with
+              EUID  0  and  the CAP_SYS_ADMIN capability is allowed to perform
+              this operation.  Once a master key is set,  it  can  be  changed
+              only by rebooting the system and setting a different key.
+
+              The  parameter points to struct ncr_master_key_set, which speci-
+              fies the key material in user space using the key  and  key_size
+              members.
+
+              Only  an  AES  key  with  size  16, 24, or 32 bytes is currently
+              acceptable.
+
+CONFIGURATION
+       The NCRIO_KEY_STORAGE_WRAP and NCRIO_KEY_STORAGE_UNWRAP  ioctl()s  work
+       only after a storage master key is configured by the system administra-
+       tor.  See NCRIO_MASTER_KEY_SET above.
+
+FILES
+       /dev/crypto
+
+Linux                             2010-08-20                         CRYPTO(4)
diff --git a/include/linux/Kbuild b/include/linux/Kbuild
index 756f831..41790cd 100644
--- a/include/linux/Kbuild
+++ b/include/linux/Kbuild
@@ -116,6 +116,7 @@ header-y += mmtimer.h
 header-y += mqueue.h
 header-y += mtio.h
 header-y += ncp_no.h
+header-y += ncr.h
 header-y += neighbour.h
 header-y += net_dropmon.h
 header-y += net_tstamp.h
diff --git a/include/linux/ncr.h b/include/linux/ncr.h
new file mode 100644
index 0000000..c288cb8
--- /dev/null
+++ b/include/linux/ncr.h
@@ -0,0 +1,273 @@
+#ifndef _LINUX_NCR_H
+#define _LINUX_NCR_H
+
+#include <linux/types.h>
+
+/* Serves to make sure the structure is suitably aligned to continue with
+   a struct nlattr without external padding.
+
+   4 is NLA_ALIGNTO from <linux/netlink.h>, but if we
+   included <linux/netlink.h>, the user would have to include <sys/socket.h>
+   as well for no obvious reason.  "4" is fixed by ABI. */
+#define __NL_ATTRIBUTES char __align[] __attribute__((aligned(4)))
+
+/* In all ioctls, input_size specifies size of the ncr_* structure and the
+   following attributes.
+
+   output_size specifies space available for returning output, including the
+   initial ncr_* structure, and is updated by the ioctl() with the space
+   actually used.
+
+   There are two special cases: input_size 0 means not attributes are supplied,
+   and is treated equivalent to sizeof(struct ncr_*).  output_size 0 means no
+   space for output attributes is available, and is not updated. */
+
+/* FIXME: better names for algorithm parameters? */
+/* FIXME: Split key generation/derivation attributes to decrease the number
+   of attributes used for the frequent operations? */
+enum {
+	NCR_ATTR_UNSPEC,	      /* 0 is special in lib/nlattr.c. */
+	NCR_ATTR_ALGORITHM,	      /* NLA_NUL_STRING */
+	NCR_ATTR_DERIVATION_ALGORITHM, /* NLA_NUL_STRING - NCR_DERIVE_* */
+	NCR_ATTR_SIGNATURE_HASH_ALGORITHM, /* NLA_NUL_STRING */
+	NCR_ATTR_WRAPPING_ALGORITHM,  /* NLA_NUL_STRING - NCR_WALG_* */
+	NCR_ATTR_UPDATE_INPUT_DATA,   /* NLA_BINARY - ncr_session_input_data */
+	/* NLA_BINARY - ncr_session_output_buffer */
+	NCR_ATTR_UPDATE_OUTPUT_BUFFER,
+	NCR_ATTR_UPDATE_INPUT_KEY_AS_DATA, /* NLA_U32 - ncr_key_t */
+	NCR_ATTR_FINAL_INPUT_DATA,    /* NLA_BINARY - ncr_session_input_data */
+	/* NLA_BINARY - ncr_session_output_buffer */
+	NCR_ATTR_FINAL_OUTPUT_BUFFER,
+	NCR_ATTR_KEY,	              /* NLA_U32 - ncr_key_t */
+	NCR_ATTR_KEY_FLAGS,	      /* NLA_U32 - NCR_KEY_FLAG_* */
+	NCR_ATTR_KEY_ID,	      /* NLA_BINARY */
+	NCR_ATTR_KEY_TYPE,	      /* NLA_U32 - ncr_key_type_t */
+	NCR_ATTR_IV,		      /* NLA_BINARY */
+	NCR_ATTR_SECRET_KEY_BITS,     /* NLA_U32 */
+	NCR_ATTR_RSA_MODULUS_BITS,    /* NLA_U32 */
+	NCR_ATTR_RSA_E,		      /* NLA_BINARY */
+	NCR_ATTR_RSA_ENCODING_METHOD, /* NLA_U32 - ncr_rsa_type_t */
+	NCR_ATTR_RSA_OAEP_HASH_ALGORITHM, /* NLA_NUL_STRING */
+	NCR_ATTR_RSA_PSS_SALT_LENGTH, /* NLA_U32 */
+	NCR_ATTR_DSA_P_BITS,	      /* NLA_U32 */
+	NCR_ATTR_DSA_Q_BITS,	      /* NLA_U32 */
+	NCR_ATTR_DH_PRIME,	      /* NLA_BINARY */
+	NCR_ATTR_DH_BASE,	      /* NLA_BINARY */
+	NCR_ATTR_DH_PUBLIC,	      /* NLA_BINARY */
+	NCR_ATTR_WANTED_ATTRS,	      /* NLA_BINARY - array of u16 IDs */
+
+	/* Add new attributes here */
+
+	NCR_ATTR_END__,
+	NCR_ATTR_MAX = NCR_ATTR_END__ - 1
+};
+
+#define NCR_CIPHER_MAX_BLOCK_LEN 32
+#define NCR_HASH_MAX_OUTPUT_SIZE  64
+
+#define NCR_WALG_AES_RFC3394 "walg-aes-rfc3394" /* for secret keys only */
+#define NCR_WALG_AES_RFC5649 "walg-aes-rfc5649" /* can wrap arbitrary key */
+
+typedef enum {
+	NCR_KEY_TYPE_INVALID,
+	NCR_KEY_TYPE_SECRET=1,
+	NCR_KEY_TYPE_PUBLIC=2,
+	NCR_KEY_TYPE_PRIVATE=3,
+} ncr_key_type_t;
+
+/* Key handling
+ */
+
+typedef __s32 ncr_key_t;
+
+#define NCR_KEY_INVALID ((ncr_key_t)-1)
+
+#define NCR_KEY_FLAG_EXPORTABLE 1
+#define NCR_KEY_FLAG_WRAPPABLE (1<<1)
+/* when generating a pair the flags correspond to private
+ * and public key usage is implicit. For example when private
+ * key can decrypt then public key can encrypt. If private key
+ * can sign then public key can verify.
+ */
+#define NCR_KEY_FLAG_DECRYPT (1<<2)
+#define NCR_KEY_FLAG_SIGN (1<<3)
+
+struct ncr_key_generate {
+	__u32 input_size, output_size;
+	ncr_key_t key;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_key_generate_pair {
+	__u32 input_size, output_size;
+	ncr_key_t private_key;
+	ncr_key_t public_key;
+	__NL_ATTRIBUTES;
+};
+
+typedef enum {
+	RSA_PKCS1_V1_5, /* both signatures and encryption */
+	RSA_PKCS1_OAEP, /* for encryption only */
+	RSA_PKCS1_PSS, /* for signatures only */
+} ncr_rsa_type_t;
+
+#define NCR_DERIVE_DH "dh"
+
+
+struct ncr_key_derive {
+	__u32 input_size, output_size;
+	ncr_key_t input_key;
+	ncr_key_t new_key;
+	__NL_ATTRIBUTES;
+};
+
+#define MAX_KEY_ID_SIZE 20
+
+struct ncr_key_get_info {
+	__u32 input_size, output_size;
+	ncr_key_t key;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_key_import {
+	__u32 input_size, output_size;
+	ncr_key_t key;
+	const void __user *data;
+	__u32 data_size;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_key_export {
+	__u32 input_size, output_size;
+	ncr_key_t key;
+	void __user *buffer;
+	int buffer_size;
+	__NL_ATTRIBUTES;
+};
+
+#define NCRIO_KEY_INIT			_IO('c', 204)
+/* generate a secret key */
+#define NCRIO_KEY_GENERATE     	_IOWR('c', 205, struct ncr_key_generate)
+/* generate a public key pair */
+#define NCRIO_KEY_GENERATE_PAIR _IOWR('c', 206, struct ncr_key_generate_pair)
+/* derive a new key from an old one */
+#define NCRIO_KEY_DERIVE        _IOWR('c', 207, struct ncr_key_derive)
+/* return information on a key */
+#define NCRIO_KEY_GET_INFO      _IOWR('c', 208, struct ncr_key_get_info)
+/* export a secret key */
+#define NCRIO_KEY_EXPORT       	_IOWR('c', 209, struct ncr_key_export)
+/* import a secret key */
+#define NCRIO_KEY_IMPORT       	_IOWR('c', 210, struct ncr_key_import)
+
+#define NCRIO_KEY_DEINIT       _IOR ('c', 215, ncr_key_t)
+
+/* Key wrap ioctls
+ */
+struct ncr_key_wrap {
+	__u32 input_size, output_size;
+	ncr_key_t wrapping_key;
+	ncr_key_t source_key;
+	void __user *buffer;
+	int buffer_size;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_key_unwrap {
+	__u32 input_size, output_size;
+	ncr_key_t wrapping_key;
+	ncr_key_t dest_key;
+	const void __user *data;
+	__u32 data_size;
+	__NL_ATTRIBUTES;
+};
+
+#define NCRIO_KEY_WRAP        _IOWR('c', 250, struct ncr_key_wrap)
+#define NCRIO_KEY_UNWRAP        _IOWR('c', 251, struct ncr_key_unwrap)
+
+/* Internal ops  */
+struct ncr_master_key_set {
+	__u32 input_size, output_size;
+	const void __user *key;
+	__u32 key_size;
+	__NL_ATTRIBUTES;
+};
+
+#define NCRIO_MASTER_KEY_SET        _IOWR('c', 260, struct ncr_master_key_set)
+
+/* These are similar to key_wrap and unwrap except that will store some extra
+ * fields to be able to recover a key */
+struct ncr_key_storage_wrap {
+	__u32 input_size, output_size;
+	ncr_key_t key;
+	void __user *buffer;
+	int buffer_size;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_key_storage_unwrap {
+	__u32 input_size, output_size;
+	ncr_key_t key;
+	const void __user *data;
+	__u32 data_size;
+	__NL_ATTRIBUTES;
+};
+
+#define NCRIO_KEY_STORAGE_WRAP        _IOWR('c', 261, struct ncr_key_storage_wrap)
+#define NCRIO_KEY_STORAGE_UNWRAP        _IOWR('c', 262, struct ncr_key_storage_wrap)
+
+/* Crypto Operations ioctls
+ */
+
+typedef enum {
+	NCR_OP_ENCRYPT=1,
+	NCR_OP_DECRYPT,
+	NCR_OP_SIGN,
+	NCR_OP_VERIFY,
+} ncr_crypto_op_t;
+
+typedef __s32 ncr_session_t;
+#define NCR_SESSION_INVALID ((ncr_session_t)-1)
+
+struct ncr_session_input_data {
+	const void __user *data;
+	__kernel_size_t data_size;
+};
+
+struct ncr_session_output_buffer {
+	void __user *buffer;
+	__kernel_size_t buffer_size;
+	__kernel_size_t __user *result_size_ptr;
+};
+
+struct ncr_session_init {
+	__u32 input_size, output_size;
+	__u32 op;		/* ncr_crypto_op_t */
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_session_update {
+	__u32 input_size, output_size;
+	ncr_session_t ses;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_session_final {
+	__u32 input_size, output_size;
+	ncr_session_t ses;
+	__NL_ATTRIBUTES;
+};
+
+struct ncr_session_once {
+	__u32 input_size, output_size;
+	ncr_crypto_op_t op;
+	__NL_ATTRIBUTES;
+};
+
+#define NCRIO_SESSION_INIT        _IOWR('c', 300, struct ncr_session_init)
+#define NCRIO_SESSION_UPDATE        _IOWR('c', 301, struct ncr_session_update)
+#define NCRIO_SESSION_FINAL        _IOWR('c', 302, struct ncr_session_final)
+
+/* everything in one call */
+#define NCRIO_SESSION_ONCE        _IOWR('c', 303, struct ncr_session_once)
+
+#endif
-- 
1.7.2.1

Re: [PATCH 01/19] User-space API definition

[Stefan Richter]

Miloslav Trmač wrote:
> --- /dev/null
> +++ b/include/linux/ncr.h
[...]
> +struct ncr_session_input_data {
> +	const void __user *data;
> +	__kernel_size_t data_size;
> +};
> +
> +struct ncr_session_output_buffer {
> +	void __user *buffer;
> +	__kernel_size_t buffer_size;
> +	__kernel_size_t __user *result_size_ptr;
> +};

Why not using fixed-size fit-all members?

struct ncr_session_input_data {
	__u64 data;		/* user pointer, cast to/from u64 */
	__u32 data_size;	/* or __u64? */
};

struct ncr_session_output_buffer {
	__u64 buffer;
	__u64 result_size_ptr;	/* can't this be a direct output member? */
	__u32 buffer_size;	/* or __u64? */
};

And then get rid of all the COMAPT code paths.
-- 
Stefan Richter
-=====-==-=- =--- =-=--
http://arcgraph.de/sr/

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

2010/8/20 Stefan Richter <stefanr@s5r6.in-berlin.de>:

>> +struct ncr_session_input_data {
>> +     const void __user *data;
>> +     __kernel_size_t data_size;
>> +};
>> +
>> +};
> Why not using fixed-size fit-all members?
> struct ncr_session_input_data {
>        __u64 data;             /* user pointer, cast to/from u64 */
>        __u32 data_size;        /* or __u64? */
> };

A reason is that using (void*) is cleaner as an API. It avoids the
pointer to int casting and the warnings that such a cast will have.

regards,
Nikos

Re: [PATCH 01/19] User-space API definition

[Miloslav Trmac]

----- "Stefan Richter" <stefanr@s5r6.in-berlin.de> wrote:
> Miloslav Trmač wrote:
> > --- /dev/null
> > +++ b/include/linux/ncr.h
> [...]
> > +struct ncr_session_input_data {
> > +	const void __user *data;
> > +	__kernel_size_t data_size;
> > +};
> 
> Why not using fixed-size fit-all members?
> 
> struct ncr_session_input_data {
> 	__u64 data;		/* user pointer, cast to/from u64 */
> 	__u32 data_size;	/* or __u64? */
> };
> 
> And then get rid of all the COMAPT code paths.
That would make the interface less natural, and any architecture that wanted to have larger pointers (I understand IBM did this back the '80s, so it can happen again) would result in a significantly worse mess than the widely used compat_ioctl mechanism.
    Mirek

Re: [PATCH 01/19] User-space API definition

[Randy Dunlap]

On Fri, 20 Aug 2010 10:45:44 +0200 Miloslav Trmač wrote:

> +#define NCRIO_KEY_INIT			_IO('c', 204)
> +/* generate a secret key */
> +#define NCRIO_KEY_GENERATE     	_IOWR('c', 205, struct ncr_key_generate)
> +/* generate a public key pair */
> +#define NCRIO_KEY_GENERATE_PAIR _IOWR('c', 206, struct ncr_key_generate_pair)
> +/* derive a new key from an old one */
> +#define NCRIO_KEY_DERIVE        _IOWR('c', 207, struct ncr_key_derive)
> +/* return information on a key */
> +#define NCRIO_KEY_GET_INFO      _IOWR('c', 208, struct ncr_key_get_info)
> +/* export a secret key */
> +#define NCRIO_KEY_EXPORT       	_IOWR('c', 209, struct ncr_key_export)
> +/* import a secret key */
> +#define NCRIO_KEY_IMPORT       	_IOWR('c', 210, struct ncr_key_import)
> +
> +#define NCRIO_KEY_DEINIT       _IOR ('c', 215, ncr_key_t)


Please add (another) 'c' entry to Documentation/ioctl/ioctl-number.txt.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH 01/19] User-space API definition

[Kyle Moffett]

On Fri, Aug 20, 2010 at 04:45, Miloslav Trmač <mitr@redhat.com> wrote:
> This patch introduces the new user-space API, <ncr.h>.
>
> Quick overview:
>
> * open("/dev/crypto") to get a FD, which acts as a namespace for key and
>  session identifiers.
>
> * ioctl(NCRIO_KEY_INIT) to allocate a key object; then generate the key
>  material inside the kernel, load a plaintext key, unwrap a key, or
>  derive a key.  Similarly the key material can be copied out of the
>  kernel or wrapped.
>
> [...snip...]

Ugh... We already have one very nice key/keyring API in the kernel
(see Documentation/keys.txt) that's being used for crypto keys for
NFSv4, AFS, etc.  Can't you just add a bunch of cryptoapi key types to
that API instead?

David Howells added to CC, since I believe he wrote most of that code initially.

Cheers,
Kyle Moffett

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

On 08/21/2010 03:09 PM, Kyle Moffett wrote:

>> This patch introduces the new user-space API, <ncr.h>.
>>
>> Quick overview:
>>
>> * open("/dev/crypto") to get a FD, which acts as a namespace for key and
>>  session identifiers.
>>
>> * ioctl(NCRIO_KEY_INIT) to allocate a key object; then generate the key
>>  material inside the kernel, load a plaintext key, unwrap a key, or
>>  derive a key.  Similarly the key material can be copied out of the
>>  kernel or wrapped.
>>
>> [...snip...]
> 
> Ugh... We already have one very nice key/keyring API in the kernel
> (see Documentation/keys.txt) that's being used for crypto keys for
> NFSv4, AFS, etc.  Can't you just add a bunch of cryptoapi key types to
> that API instead?

It is not that simple. My understanding of the keyring API is that it
allows exporting of the keys to user-space and this crypto API
explicitly prevents that, so enhancing the API that way will remove the
benefits of using it. It would be ideal to combine somehow those
solutions but this is more elaborate work than adding a bunch of new key
types. If anyone is interested in attempting that I'd be glad to help.


regards,
Nikos

Re: [PATCH 01/19] User-space API definition

[David Howells]

Nikos Mavrogiannopoulos <nmav@gnutls.org> wrote:

> It is not that simple. My understanding of the keyring API is that it
> allows exporting of the keys to user-space and this crypto API
> explicitly prevents that

That's simple.  Don't provide a read() key type operation, then.

David

Re: [PATCH 01/19] User-space API definition

[Herbert Xu]

On Fri, Aug 20, 2010 at 10:45:44AM +0200, Miloslav Trmač wrote:
> This patch introduces the new user-space API, <ncr.h>.
> 
> Quick overview:
> 
> * open("/dev/crypto") to get a FD, which acts as a namespace for key and
>   session identifiers.
> 
> * ioctl(NCRIO_KEY_INIT) to allocate a key object; then generate the key
>   material inside the kernel, load a plaintext key, unwrap a key, or
>   derive a key.  Similarly the key material can be copied out of the
>   kernel or wrapped.
> 
> * ioctl(NCRIO_SESSION_INIT) to allocate a crypto session (to encrypt,
>   decrypt, hash, sign, or verify signature), then
>   ioctl(NCRIO_SESSION_UPDATE) to act on chunks of data.  Deallocate the
>   session, and optionally retrieve session results (e.g. hash or
>   signature), using ioctl(NCRIO_SESSION_FINAL).
> 
>   There is also NCRIO_SESSION_ONCE for an one-shot crypto operation
>   using a single user->kernel context switch.
> 
> Full documentation of the interface is in
> Documentation/crypto/userspace.txt .

Thanks for the updated patch-set.  It does indeed fulfil some
of the requirements raised earlier.

However, as far as I can see this still does not address the
extensibility.  For example, say we want add an interface to
allow the xoring of two arbitrary data streams using DMA offload,
this interface would make that quite awkward.

In fact the whole interface is really tailored to the traditional
encryption/hash operations that BSD provided so I think this is not
a good foundation for our user-space API.

I will be looking at this myself so please stay tuned and be ready
to yell if you see that your requirements are not met.

Cheers,
-- 
Email: Herbert Xu <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

2010/9/3 Herbert Xu <herbert@gondor.apana.org.au>:

>> * ioctl(NCRIO_SESSION_INIT) to allocate a crypto session (to encrypt,
>>   decrypt, hash, sign, or verify signature), then
>>   ioctl(NCRIO_SESSION_UPDATE) to act on chunks of data.  Deallocate the
>>   session, and optionally retrieve session results (e.g. hash or
>>   signature), using ioctl(NCRIO_SESSION_FINAL).
>>   There is also NCRIO_SESSION_ONCE for an one-shot crypto operation
>>   using a single user->kernel context switch.
>> Full documentation of the interface is in
>> Documentation/crypto/userspace.txt .
>
> Thanks for the updated patch-set.  It does indeed fulfil some
> of the requirements raised earlier.
>
> However, as far as I can see this still does not address the
> extensibility.  For example, say we want add an interface to
> allow the xoring of two arbitrary data streams using DMA offload,
> this interface would make that quite awkward.

Although I think the current API could handle something like this, I
also think it is undesirable to do so. The API was designed with
cryptographic operations in mind, and its extensibility might better
be judged on how it can incorporate future cryptographic protocols
(sigma-proofs and other zero-knowledge protocols and other protocols
that I might not know of). An XOR operation, doesn't really fit into a
cryptographic API. It could however be included in the current design
with some utility ioctls() that address such helper operations. Even
better, I think a XOR operation deserves a system call, since it is
quite useful in a variety of applications, not only cryptographic
ones.

> In fact the whole interface is really tailored to the traditional
> encryption/hash operations that BSD provided so I think this is not
> a good foundation for our user-space API.

It supports much more than the openbsd API, but indeed it is designed
with cryptographic operations in mind and this limitation can allow a
semi-formal verification of its properties. I'll try to post a link to
the design document as soon.

regards,
Nikos

Re: [PATCH 01/19] User-space API definition

[Nikos Mavrogiannopoulos]

On 09/03/2010 11:18 AM, Herbert Xu wrote:
> I will be looking at this myself so please stay tuned and be ready
> to yell if you see that your requirements are not met.

On 08/20/2010 03:56 PM, Ted Ts'o wrote:
> So I'm bit at a list what's the whole point of this patch series.
> Could you explain that in the documentation, please?  Especially for
> crypto, explaining when something should be used, what the threat
> model is, etc., is often very important.

Hello,
 The document discussing the model, threats and design goals of this
framework can be found at:
https://www.cosic.esat.kuleuven.be/publications/article-1490.pdf

Comments and suggestions are welcome.

regards,
Nikos

PS. The existing (proposed) implementation covers about 90% of the
design goals, the rest are work in progress.