[RFC] Hardware support notes for the kernel crypto API (2.5+)

[RFC] Hardware support notes for the kernel crypto API (2.5+)

[James Morris]

Below are some initial notes on hardware support for the kernel crypto
API, discussing some initial requirements, vendor documentation status,
GPL driver status, and pointers to resources and earlier discussions on
the topic.

The focus at the moment is on gathering the requirements for generic
hardware crypto devices, which can be used to assist kernel components
(e.g. IPsec, CIFS), and userspace applications (e.g. SSL, IKE).  Some work 
has begun on obtaining documentation from vendors and developing clean GPL 
drivers.

Comments welcome, please consider following up to cryptoapi-devel for 
ongoing discussion.

(This document is also maintained at http://samba.org/~jamesm/crypto/)

------------------------------------------------------------------------------
Linux Kernel Crypto API - Hardware Support Notes
Last updated 15 Dec 2002
------------------------------------------------------------------------------

Requirements
  
  - Crypto hardware will require an asynchronous API with callbacks via
    softirq.
    
  - Multiple card support:
      Request dispatcher, needs to ensure requests are balanced
      across cards.
      
      Allow parallel operation for the same session: need to
      reserve session across all boards and dispatch appropriately.

  - Request dispatcher therefore required, and must have knowledge
    of cards: session support, session id format, algorithms, 
    batching capability, SG support etc.
  
  - Driver might be passed a logical request from the dispatcher
    in the form of:
      
      command = {operation, context, source, destination}
    
    How to handle scatter/gather?

      command = { operation, context, source sg, destination sg}
  
    If the card supports batching, multiple commands may be grouped:
    
      { command, command, command, ... }

  - How to handle card / queue full? (top level API change: all operations
    can fail).  Fall back to software? (async api will be required to
    support software implementations as well).

  - Pipeline management (where appropriate).
  
  - How to support IPsec offload to onboard NIC?
  
  - What will the Kernel & Userspace APIs look like?
  
    Kernel:
      crypto_alloc_tfm() - current simple interface
      crypto_alloc_session() - batching of commands, IPsec offload[?] etc.
                               specify algorithm bundle, preferences, then
                               use api helpers to build and send dispatcher
                               requests.

    Userspace:
      cryptoapifs? (see
      http://www.kerneli.org/pipermail/cryptoapi-devel/2002-December/000320.html)
    
  - Asymmetric crypto?

  - Existing kernel APIs with hardware support:
    - OpenBSD crypto queue
    - Cryptolib by Martin Gadbois,
      http://sources.colubris.com/en/projects/FreeSWAN/
      (what license does cryptolib use?)
    
  - Other discussions/proposals/code:
    - Michael Richardson
      http://mail.nl.linux.org/linux-crypto/2002-07/msg00054.html
      (also see followup threads on cryptoapi-devel)
    - Bart Trojanowski's Generic Engine
      http://www.jukie.net/~bart/genericengine/
      

Hardware documentation status:

  HiFn
    Documentation for Hifn cards available via download at their web site.
  
  IBM
    Can provide driver source for the card, and some general documentation is
    available at http://www.ibm.com/security/cryptocards/
    Software development toolkit is export controlled (contact IBM for more
    info).
    
  Motorola
    Unknown (Steve is working on some Linux drivers though).
    
  Intel
    Crypto documentation for NICs unavailable.
    
  3COM
    Crypto documentation for NICs unavailable.
    
  Broadcom
    No response to emails.
    
  AEP/Baltimore
    Unknown (not contacted yet, Linux driver available).
    
  Corrent
    Unknown (not contacted yet).
   
  Eracom
    Contacted some time ago, documentation had to be purchased (expensive).
    Not sure if this has changed.
    
  Safenet
    Unknown (not contacted yet).  
  

GPL Driver status:

  HiFn 7751
    James Morris (in progress).
  
  HiFn 7951
    David Bryson (in progress).
    Also see http://sourceforge.net/projects/hifn7951/
  
  HiFn 7901
    See http://sources.colubris.com/en/projects/FreeSWAN/
    
  Motorola MPC190, MPC184
    Steve (in progress).
    
  IBM 4758
    Available from IBM on request.

  AEP paep
    A dual licensed GPL/BSD driver is available somewhere.


Summary:
   I don't think we have enough documentation yet, notably none for NICs
   with crypto hardware.

------------------------------------------------------------------------------


- James
--
James Morris
<jmorris@intercode.com.au>

Re: [RFC] Hardware support notes for the kernel crypto API (2.5+)

[Andrew McGregor]

>  - What will the Kernel & Userspace APIs look like?

A socket family?  Most userspace crypto apps, IMO, will deal with 
networking somewhere.

>   - Asymmetric crypto?

Yes please!  A HiFn 6500 can do a 2048-bit DH exchange in about 30ms, 
compared with several seconds for a P3-900.  It's similarly fast for 
everything else, and utterly astonishing for RSA (under a millisecond for a 
signature!).

>  Intel
>    Crypto documentation for NICs unavailable.

I may have some leverage here.  We'll see.

>   Broadcom
>     No response to emails.

But OpenBSD has drivers, and they say that Broadcom were very good to deal 
with.  I suggest writing the OpenBSD driver maintainer and asking who to 
contact.

Andrew

Re: [RFC] Hardware support notes for the kernel crypto API (2.5+)

[James Morris]

On Sun, 15 Dec 2002, Andrew McGregor wrote:

> But OpenBSD has drivers, and they say that Broadcom were very good to deal 
> with.  I suggest writing the OpenBSD driver maintainer and asking who to 
> contact.

The OpenBSD developer said he's given up talking to Broadcom and declined
to provide the email address of his contact.

Although I'm sure we can work something out if we can actually find the
right person to talk to.


- James
-- 
James Morris
<jmorris@intercode.com.au>

Re: [CryptoAPI-devel] Re: [RFC] Hardware support notes for the kernel crypto API (2.5+)

[Justin Clift]

James Morris wrote:
> On Sun, 15 Dec 2002, Andrew McGregor wrote:
> 
> 
>>But OpenBSD has drivers, and they say that Broadcom were very good to deal 
>>with.  I suggest writing the OpenBSD driver maintainer and asking who to 
>>contact.
> 
> 
> The OpenBSD developer said he's given up talking to Broadcom and declined
> to provide the email address of his contact.
> 
> Although I'm sure we can work something out if we can actually find the
> right person to talk to.


Ok, just filled out a request form on their site, asking them who the best person for us to contact is.

***********

Hello,

Is Broadcom interested in having support for their encryption acceleration products (not just the one given in the 
product number above) officially added to Linux?

The Linux "CryptoAPI" project is trying to find out the best person at Broadcom to contect, as we are adding support for 
encryption hardware to the Linux kernel and are wondering you guys would like your products included.

:-)

Regards and best wishes,

Justin Clift

***********

Reckon we should probably hear something back within 3-4 days.  It's worded clearly enough for pretty much anyone there 
to understand, and gives them a solid "reason to contact us" back.

:-)

Does it sound ok?

Regards and best wishes,

Justin Clift


> - James


-- 
"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
- Indira Gandhi

Re: [CryptoAPI-devel] Re: [RFC] Hardware support notes for the kernel crypto API (2.5+)

[Jean-Luc Cooke]

Looks good Justin,

I'd put in a bt more "we're doing your work for you" slant, or even a "open
new markets for your company" slant...but then again, they may get
suspisious.

JLC

On Sun, Dec 15, 2002 at 03:34:23PM +1100, Justin Clift wrote:
> Hello,
> 
> Is Broadcom interested in having support for their encryption acceleration products (not just the one given in the 
> product number above) officially added to Linux?
> 
> The Linux "CryptoAPI" project is trying to find out the best person at Broadcom to contect, as we are adding support for 
> encryption hardware to the Linux kernel and are wondering you guys would like your products included.
> 
> :-)
> 
> Regards and best wishes,
> 
> Justin Clift
> 
> ***********
> 
> Reckon we should probably hear something back within 3-4 days.  It's worded clearly enough for pretty much anyone there 
> to understand, and gives them a solid "reason to contact us" back.
> 
> :-)
> 
> Does it sound ok?

-- 
http://www.certainkey.com
Suite 4560 CTTC
1125 Colonel By Dr.
Ottawa ON, K1S 5B6
C: 613.263.2983

Re: [CryptoAPI-devel] [RFC] Hardware support notes for the kernel crypto API (2.5+)

[Steve Isaacs]

On Saturday 14 December 2002 05:51, James Morris wrote:
>   Motorola
>     Unknown (Steve is working on some Linux drivers though).
>    
The User's Manuals can be downloaded at:
  MPC190
  http://e-www.motorola.com/brdata/PDFDB/docs/MPC190UM.pdf

  MPC184
  http://e-www.motorola.com/brdata/PDFDB/docs/MPC184UM.pdf

Steve

Re: [CryptoAPI-devel] [RFC] Hardware support notes for the kernel crypto API (2.5+)

[Steve Isaacs]

On Saturday 14 December 2002 05:51, James Morris wrote:
>  
>
> GPL Driver status:
>
>   HiFn 7751
>     James Morris (in progress).
>  
>   HiFn 7951
>     David Bryson (in progress).
>     Also see http://sourceforge.net/projects/hifn7951/
>  
>   HiFn 7901
>     See http://sources.colubris.com/en/projects/FreeSWAN/
>    
>   Motorola MPC190, MPC184
>     Steve (in progress).
>    

The driver for the MPC190 is now running with limited capability (although not 
very clean at the moment). Most of what I've done is workout the details of 
configuring the co-processor that are not described in the User's Manuala and 
builtind a basic framework to support mutiple coprocessors (of the same type) 
and callbacks. Motorola has been very helpful with this.

In case you're interrested here are some details (you can pick me apart if you 
want to -- I'm somewhat new to this so I could use some advice):

At this time only MD5 is supported but, now that I've got a better handle on 
the ideosyncrasies, implementing additional transforms should take less 
effort (and time). The driver is able to detect multiple mpc190s on the PCI 
bus and use them dynamically. 

Each mpc190 supports 9 execution "channels" (Motorola's term). The driver 
hides the fact that there are multiple channels or even multiple coprocessors 
and instead only exposes the various transforms (e.g. MD5, DES...). 

The driver internally allocates channels to satisfy cipher requests on an as 
need basis and does support callback from the bottom-half (interrupt tasklet) 
for asynchronous notification of completion of the task. 

To simplify management I implemented an abstract I call a "virtual channel" 
and maintain linked lists of "virtual channels" on idle and busy queues. 
Allocation of a channel is simply moving a channel from the idle queue to the 
busy queue. Deallocation is the reverse. 

Two of the attributes of a "virtual channel" are the base IO address of the 
processor and the offset of the channel to facilitate code that can work with 
any channel. 

Calling tasks are placed on sleep_interruptable queues (there is one for each 
"virtual channel") and are not awakened until after the callback has 
completed (if one was requested).

"Virtual channel" states are maintained internally to help track the progress 
of a channel and include IDLE, BUSY, PENDING, and CALLBACK. The IDLE and BUSY 
states are obvious. The PENDING state identifies a channel that has been 
queued for the bottom-half (interrupt tasklet) to process. The CALLBACK state 
indicates a channel that is awaiting a return from a call to a client 
callback function.

Thoughts for the future:

The MPC184 also uses the channel concept but provides fewer of them (4 versus 
9) and doesn't support all of transforms of the mpc190 (MD4 and HMAC-MD5 are 
missing). At the same time the mpc184 provides AES whereas the mpc190 does 
not. I've been struggling trying to figure out how to extend the "virtual 
channel" scheme to allow concurrent use of both an mpc190 and and mpc184 but 
not have to support both in the same driver (not something I want to do). The 
project which is the true motivation behind all of this has the possibility 
of having both on the bus at the same time.

Steve