<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="info" docName="draft-ocf-v1" ipr="none">
<front>
<title abbrev="OCF v1.0">Open Cryptographic Framework</title>
<author fullname="Michael Richardson" initials="M." surname="Richardson">
<organization></organization>
</author>
<date day="01" month="April" year="2006" />
<abstract>
<t>This document describes an internal API applicable to the Linux and
FreeBSD operating systems. It describes an asynchronous interface to
encryption, authentication (hash) and compression algorithms. This
document describes current practice, and extends the interface to
include compression algorithms.</t>
</abstract>
<note title="Requirements Language">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref
target="RFC2119">RFC 2119</xref>.</t>
</note>
</front>
<middle>
<section title="Introduction">
<t>There are a variety of different encryption, authentication and
compression algorithms. They may be implemented in software, hardware or
various combinations. To facilitate interchange of different algorithms
into network, harddisk, and user-space applications a standard interface
to different methods is required.</t>
</section>
<section title="Overview of API">
<t>This section describes what the API looks like, from a walk-through
perspective.</t>
<t>A kernel subsystem wishing to make use of one of the algorithms
provided by OCF 1.0 should first create a session with
crypto_newsession(). This returns an OCF cryptoid, which is an opaque
64-bit handle to the driver and session within that driver.</t>
<t>To submit the work, a "struct cryptop" structure is allocated (two
are required for encryption and integrity operations), and each are
filled in, a callback function is provided, and then crypto_dispatch()
is called. The callback function is provided with an opaque application
specific pointer.</t>
</section>
<section title="Method descriptions - caller interface">
<section title="new section">
<t>#include <opencrypto/cryptodev.h> </t>
</section>
<section title="new section">
<t>extern int crypto_newsession(u_int64_t *sid, struct cryptoini *cri,
int hard);</t>
</section>
<section title="new section">
<t> extern int crypto_freesession(u_int64_t sid);</t>
</section>
<section title="new section">
<t> extern int32_t crypto_get_driverid(u_int32_t flags);</t>
</section>
<section title="new section">
<t> extern int crypto_register(u_int32_t driverid, int alg, u_int16_t
maxoplen, u_int32_t flags, int (*newses)(void*, u_int32_t*, struct
cryptoini*), int (*freeses)(void*, u_int64_t), int (*process)(void*,
struct cryptop *, int), void *arg);</t>
</section>
<section title="new section">
<t> extern int crypto_kregister(u_int32_t, int, u_int32_t, int
(*)(void*, struct cryptkop *, int), void *arg); </t>
</section>
<section title="new section">
<t>extern int crypto_unregister(u_int32_t driverid, int alg); extern
int crypto_unregister_all(u_int32_t driverid); </t>
</section>
<section title="new section">
<t>extern int crypto_dispatch(struct cryptop *crp); </t>
</section>
<section title="new section">
<t>extern int crypto_kdispatch(struct cryptkop *); #define CRYPTO_SYMQ
0x1 #define CRYPTO_ASYMQ 0x2 </t>
</section>
<section title="new section">
<t>extern int crypto_unblock(u_int32_t, int); </t>
</section>
<section title="new section">
<t>extern void crypto_done(struct cryptop *crp); </t>
</section>
<section title="new section">
<t>extern void crypto_kdone(struct cryptkop *); </t>
</section>
<section title="new section">
<t>extern int crypto_getfeat(int *); </t>
</section>
<section title="new section">
<t>extern void crypto_freereq(struct cryptop *crp); </t>
</section>
<section title="new section">
<t>extern struct cryptop *crypto_getreq(int num); </t>
</section>
<section title="new section">
<t>int crypto_newsession(); </t>
</section>
<t>Called by consumers of cryptographic services (such as the IPsec
stack) that wish to establish a new session with the framework. On
success, the first argument will contain the Session Identifier (SID).
The second argument contains all the necessary information for the
driver to establish the session (keys, algorithms, offsets, etc. </t>
<t>The third argument indicates whether only hardware acceleration is
acceptable. </t>
<t>* int crypto_freesession(); </t>
<t>Called to disestablish a previously-established session. </t>
<t>* int crypto_dispatch(); </t>
<t>Called to process a request, encapsulated in its only argument. The
various fields in that structure contain: </t>
<t><list>
<t>The SID. o The total length in bytes of the buffer to be
processed</t>
<t></t>
</list>o The total length of the result, which for symmetric crypto
operations will be the same as the input length. </t>
<t>o The type of input buffer, as used in the kernel malloc() routine.
This will be used if the framework needs to allocate a new buffer for
the result (or for re-formatting the input). </t>
<t>o The routine that the OCF should invoke upon completion of the
request, whether successful or not. </t>
<t>o The error type, if any errors were encountered. If the EAGAIN error
code is returned, the SID has changed. The consumer should record the
new SID and use it in all subsequent requests. In this case, the request
may be re-submitted immediately. This mechanism is used by the framework
to perform session migration (move a session from one driver to another,
because of availability, performance, or other considerations). </t>
<t>o A bitmask of flags associated with this request. Currently, the
only flag defined is CRYPTO_F_IMBUF, which indicates that the input
buffer is an mbuf chain. </t>
<t>o The input and output buffers. The input buffer may be an mbuf chain
or a contiguous buffer (as identified by the flags). The output buffer
will be of the same type. </t>
<t>o A pointer to opaque data. This is passed through the crypto
framework untouched and is intended for the invoking application's use.
</t>
<t>o A linked list of operation descriptors, which indicate what
operations should be applied, and in what sequence, to the input data.
The descriptors indicate where each operation should start, the length
of the data to be processed, where on the output buffer should the
results be placed, the key material to be used, and various
operation-specific flags (e.g., what Initialization Vector to use for
CBC-mode encryption). </t>
<section title="new section">
<t>* int crypto_kdispatch(); </t>
</section>
<t>Similar to crypto_dispatch(), for public-key operations. </t>
<t></t>
</section>
<section title="method descriptions - driver interface">
<t>* int32_t crypto_get_driverid(); </t>
<t>int crypto_register(); </t>
<t>int crypto_kregister();</t>
<t>int crypto_unregister();</t>
<t> Used by device drivers to register and unregister symmetric and
asymmetric algorithm support with the OCF. </t>
<section title="new section">
<t>void crypto_done(); </t>
<t>void crypto_kdone();</t>
<t>Called by device drivers on completion of a request (symmetric and
asymmetric, respectively).</t>
</section>
</section>
<section title="structure explanations">
<t></t>
</section>
<section title="callback function requirements">
<t></t>
</section>
<section anchor="Security" title="Security Considerations">
<t></t>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t></t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
</references>
</back>
</rfc>
