| Message ID | 1404323201-11784-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
Patch applies with some white space issues, builds and links ok with the API. To differentiate the odp-arch repo vs the odp repo as the target for this patch, you will want to change the subject when creating the patch with something like the following command. git format-patch -1 --subject-prefix="PATCH ARCH" Minor nits - there is some content that we need to move out of crypto when the next section is added, things like "Use of Terms" is probably common to the whole doc. On 2 July 2014 13:46, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > crypto_design.dox | 455 > ++++++++++++++++++++++++++++++++++++++++++++++++++ > images/syncmodels.png | Bin 0 -> 17179 bytes > 2 files changed, 455 insertions(+) > create mode 100644 crypto_design.dox > create mode 100644 images/syncmodels.png > > diff --git a/crypto_design.dox b/crypto_design.dox > new file mode 100644 > index 0000000..1ad2ac6 > --- /dev/null > +++ b/crypto_design.dox > @@ -0,0 +1,455 @@ > +/* Copyright (c) 2043, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page crypto_design ODP Design - Crypto API > +For the implimentation of the ODP crypto API please see @ref odp_crypto.h > + > +@tableofcontents > + > +@section revision_history Revision History > +Revision | Issue Data | Description | Author > +---------|------------|-------------|-------- > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, > Alexandru > +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, > miscellaneous formatting, API comments | Bill > +0.3 | 4/22/2014 | Added Use Case section to include results of > design discussions held during ODP team calls | Bill > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to > resolve | Bill > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready for > final review | Bill > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > + > +@section introduction Introduction > +This document describes the ODP v1.0 Crypto API. Cryptography is an > important part of data plane processing as many communication protocols > make use of cryptographic functions. Moreover, many SoCs incorporate > cryptographic hardware that can significantly accelerate these operations > compared to their software equivalents as well as provide validated > hardware functional correctness and security boundaries necessary for > system-level security certifications such as FIPS-140 Level 2 and above. > +@section requirements Requirements > +@subsection use_of_terms Use of Terms > +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 [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > +@subsection uses_of_cryptography Uses of Cryptography > +Crypto functions cover a range of uses and capabilities designed to > support data security, integrity, authentication, and non-repudiation. > +@subsubsection data_security Data Security > +Cryptography supports data security by making use of complex mathematical > transformations that are not feasibly reversible without possession of the > secret key used to encrypt message data. > +@subsubsection data_integrity Data Integrity > +Cryptography supports data integrity through the use of cryptographic > checksums (also known as secure hashes) that ensure the recipient that > message data has not been altered either accidentally or maliciously while > in transit. > +@subsubsection data_authentication Data Authentication > +Cryptography supports data authentication through the uses of Message > Authentication Codes (MACs) that enable the recipient to verify that a > message was sent from an authorized counterparty, and hence was not forged. > +@subsubsection data_non_repudiation Data Non-Repudiation > +Cryptography supports data non-repudiation through the use of digital > signatures that enable a recipient or third party to verify the identity of > the sending party and prevents the sending party from later denying that > they originated a signed message. > +@subsection scope Scope > +ODP v1.0 crypto support is designed to provide a portable framework for > accessing SoC-specific cryptographic functions of most use to the data > plane. This is predominantly symmetric crypto operations used to support > the encryption and decryption of data at line rate using hardware > acceleration and offload. Specifically excluded in this support are public > key operations and other crypto functions mainly used in the control plane. > +@subsection cryptographic_operations_in_the_data_plane Cryptographic > Operations in the Data Plane > +ODP v1.0 crypto APIs cover the following areas: > +@subsubsection ciphering Ciphering > +Ciphering refers to mathematical transformations that use a secret key to > encipher data, transforming the original data (referred to as plaintext) > into ciphertext, thereby making it unintelligible to anyone not in > possession of the key. Similarly, ciphering is also used to decipher data, > allowing someone in possession of the correct key to transform received > ciphertext back into plaintext. Approved block ciphers are listed [here]( > http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be > supported by each ODP implementation. > +@subsubsection hasing Hashing > +A hash is a cryptographic digest of a message that can be used to > represent it for comparison or integrity checking. Hash functions are > designed so that any alteration of a message will alter the hash and that > it is computationally infeasible to craft a message that generates the same > hash value as another message. Secure hash functions approved for > cryptographic use are listed by NIST [here]( > http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD be > supported by each ODP implementation. > +@subsubsection zeroization Zeroization > +To preserve the security of data, certain transient data held in data > buffers MUST be cleared to zeros upon buffer free. Such capability is > referred to as zeroization. ODP supports zeroization as a buffer pool > attribute. > +@subsubsection random_number_generation Random Number Generation > +Because cryptography relies heavily on “unguessable” keys of various > sorts, random number generation (RNG) is an integral part of cryptographic > processing. Random numbers are used in key generation, initialization > vectors (IVs), various types of padding bytes, and various other uses > collectively referred to as nonces, that serve to “harden” cryptographic > processing. > + > +There are two types of random number support of interest. Hardware > random data, also known as entropy, that is the result of inherently random > physical processes, and deterministic random bit generation (DRBG) that is > used in certain certified cryptographic operations. Approved DRBG > algorithms are listed in [NIST SP 800-90A]( > http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify > which algorithms are available on a given implementation. As such ODP > implementations MAY use any approved DRGB algorithm but SHOULD support at > least one of them. Additionally, ODP implementations MUST NOT represent > non-approved algorithms as DRBG implementations. Validated algorithms are > listed in the [NIST DRBG Validation List]( > http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > + > +@subsubsection capability_inquiry Capability Inquiry > +To enable applications to adapt to the implementation models offered > across different SoC platforms, ODP provides APIs to allow applications to > inquire about underlying crypto capabilities. A given ODP implementation > may offer crypto as hardware features, software features, or not available > on a given platform. > +@subsection cryptographic_algorithms Cryptographic Algorithms and > Protocols > +A cryptographic algorithm is a mathematical transform that provides one > of the cryptographic operations described above. They in turn are used as > building blocks in creating cryptographic protocols. These are complete > sets of rules for how to exchange data securely using cryptography. Both > cryptographic algorithm and protocol design are highly specialized > disciplines that involve high levels of public scrutiny and validation. As > a result, applications simply make use of approved cryptographic algorithms > and protocols. > +@subsection cryptographic_operations Cryptographic Operations > +Cryptographic operations may be initiated by software or directly by > hardware as part of the RX or TX packet path processing. For ODP v1.0 > software-initiated cryptographic operations are the primary use case. ODP > provides APIs for performing data ciphering, hashing, random number > generation, and capability inquiry. > +@subsection performance_expectations Performance Expectations > +In the data plane, the total processing budget for a packet may only be a > few hundred cycles, so function invocation overhead MUST be kept to a > minimum. This has several implications. > + > +-# When work is dispatched to a thread, all information needed by the > thread to process the work request SHOULD be immediately at hand. Ideally > any context or variables needed for the operation have been pre-warmed in > the cache to avoid the latency hits associated with cache misses. SoCs > having hardware schedulers generally do this pre-staging of data to > minimize such latencies, and ODP implementations are expected to exploit > such platform capabilities whenever possible.\n\n > + > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of > parameter passing and (depending on the implementation) SHOULD be inlined > as much as possible to avoid call overhead. One technique that has proven > useful is to allow for parameters to be passed as an explicit thread-local > static structure. Such use of “templating” means that a single function can > support a rich set of options but the caller can configure a template > matched to specific use and only vary the one or two parameters that differ > from call to call.\n\n > + > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception > path function processing. Kernel calls and such are acceptable only during > one-time initialization logic or certain types of unusual error recovery > operations. Often the best way to handle the latter is to pass the work to > a dedicated recovery thread (or back to the control plane) rather than > attempting to handle the condition inline. For example, a link-down > condition will trigger various recovery actions that might best be handled > in this manner. > + > +@subsection use_by_existing_code Use by Existing Code > +Most applications wishing to make use of ODP represent substantial > existing investment that must be preserved. Insofar as possible, ODP > functions need to be orthogonal to existing application environments and > structures to permit easy intermixing with pre-existing code. > +@subsection data_references Data References > +Packet data is inherently of variable length however it is often more > efficient to organize memory into fixed-sized buffers that can be chained > together on demand to contain packets. The application SHOULD normally not > need to be aware of such lower-level segmentation and should be able to > treat a packet as a single object. Alternately, especially when dealing > with existing code, data segmentation MUST be explicitly specifiable via > scatter/gather lists. For example, data encryption or decryption may be > invoked on a list of data segments as part of a single function call. > +@subsection chained_operations Chained Operations > +Crypto operations such as hashing and encryption, or decryption and > verification, are very commonly used in combination. For ODP, it is > sufficient to support one cipher and one hash/authentication operation in a > single call and this combination MUST be supported to avoid the call and > dispatch overhead of separate invocations. > +@subsection key_management Key Management and Session Data > +Keying is an area of particular sensitivity in crypto processing since > keys are highly confidential and may be subject to legal requirements for > safeguarding within special hardware enclosures. > + > +A session is the security context used to represent an active set of > crypto operations that need to be applied to a flow on a packet-by-packet > basis. Generally a session is established upon detection of a flow > requiring crypto processing and retained for the life of that flow. It has > been noted that this can involve cooperative processing between the control > and data planes so several requirements stem from this: > + > +-# Session creation MAY need to be handled in an asynchronous manner. > This is to allow these to be created in batches by thread(s) that > specialize in this activity.\n\n > + > +-# Sessions MAY need to reference keying material indirectly via key > handling modules.\n\n > + > +-# Session creation MAY be performed by non-ODP code and communicated to > data plane routines that make use of ODP crypto functions that need to > reference the session information. > + > +ODP session APIs and data structures SHOULD be represented by abstract > data types that encapsulate implementation details for both platform > efficiency and to accommodate these needs. > +Use Cases > +For ODP v1.0 the major use cases of interest involve cryptographic > algorithm acceleration. Cryptographic protocol acceleration is reserved for > future ODP releases. > +Buffers and Data Blocks > +Cryptographic operations may be performed directly on data contained in > ODP packet buffers, or it may be performed on “raw” data blocks operating > entirely under application control. Note that when using raw data blocks > not managed by ODP, the application must perform any needed zeroization > using either its own or ODP-supplied buffer zeroization functions. ODP > automatic support for zeroization is limited to ODP-managed buffers. ODP > buffers allocated from buffer pools designated for crypto use will also > have whatever alignment and/or addressability attributes needed by the > implementation to support crypto API calls. > + > +Note: Some implementations may have difficulty dealing with application > buffer addresses, as these may be virtual addresses that are mapped > discontiguously into physical memory. For such implementations, memory > SHOULD be allocated contiguously and MAY need to be “registered” to have > proper addressability for crypto operations. This area of the design will > be updated based on experience in dealing with different crypto > implementations that have such requirements. > +Synchronization > +ODP operations fall into one of three categories: > + > +-# Inline (Synchronous): Upon return from a call the operation is > complete. Operation is thus completely synchronous to the caller. Inline > is the appropriate model when the invoked function takes relatively few > cycles or when the caller cannot feasibly progress without the results of > the invoked function.\n\n > + > +-# Parallel: Upon return from a call the operation has been initiated, > but is expected to complete shortly. The caller continues to execute until > it needs the result at which point it waits to complete the parallel > operation. The effect is as if the operation were inline except that the > caller was able to execute in parallel with the operation for some > application-determined period of time. Parallel is the appropriate model > when the operation being performed is relatively short (a few dozen up to > perhaps 100 or 200 cycles) and the caller can usefully accomplish other > processing on the same unit of work while the parallel operation is in > progress, but not enough to justify the overhead of a formal queued work > dispatch.\n\n > + > +-# Offloaded (Asynchronous): Upon return from the call the operation has > been queued for execution. A completion event will be queued back to the > scheduler when the event is completed. Offload is the appropriate model > when the invoked function will take a substantial amount of cycles > (thousands to tens of thousands) allowing the invoking thread/core to > service other work until the operation completes. For offloaded work, > completion is indicated by a completion event being posted back to an > application-designated completion queue. Upon receipt the unit of work that > initiated the offloaded operation continues processing with the results of > the call. > + > +The synchronization models of interest are summarized in Figure 1: > + > + > + > +Note: Because few implementations are expected to offer the Parallel mode > of operation as described above, this mode is reserved for potential > future use. For ODP v1.0 only synchronous and asynchronous crypto > operations are defined. > +@section functional_definition Functional Definition > +@subsection abstract_data_types Abstract data types > +The following enumerations define various algorithms used for ciphering > and hashing. These are the basic operations applied to input data. > + > +A particular ODP implementation should map these values to the actual > information to be passed to the crypto engine. As such, the actual values > of these enums is implementation-defined. > + > +Cipher algorithm encoding specifies the algorithm and cipher mode > employed (as per security relevant RFCs - [4305]( > http://tools.ietf.org/html/rfc4305), [4868]( > http://tools.ietf.org/html/rfc4868), [4494]( > http://tools.ietf.org/html/rfc4494)). > + > +@code > +enum odp_cipher_alg { > + ODP_CIPHER_ALG_NULL, > + ODP_CIPHER_ALG_DES, > + ODP_CIPHER_ALG_3DES_CBC, > + ODP_CIPHER_ALG_AES_CBC, > + ODP_CIPHER_ALG_AES_GCM, > + ODP_CIPHER_ALG_AES_CTR, > + ODP_CIPHER_ALG_KASUMI, > + ODP_CIPHER_ALG_SNOW, > + ... > +}; > +@endcode > + > +Authorization algorithm encoding specifies the algorithm and the length > of the authorization used (as per security relevant RFCs - [4305]( > http://tools.ietf.org/html/rfc4305), [4868]( > http://tools.ietf.org/html/rfc4868), [4494]( > http://tools.ietf.org/html/rfc4494)): > + > +@code > +enum odp_auth_alg { > + ODP_AUTH_ALG_NULL, > + ODP_AUTH_MD5_96, > + ODP_AUTH_ALG_SHA1_96, > + ODP_AUTH_ALG_SHA1_160 > + ODP_AUTH_ALG_SHA2_256_128, > + ODP_AUTH_ALG_SHA2_384_192, > + ODP_AUTH_ALG_SHA2_512_256, > + ODP_AUTH_ALG_AES_CMAC_96, > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > + ODP_AUTH_ALG_SNOW, > + ODP_AUTH_ALG_KASUMI, > + ... > +}; > + > +typedef union odp_crypto_alg_t { > + enum odp_cipher_alg cipher; > + enum odp_auth_alg auth; > +}odp_crypto_alg_t; > +@endcode > +@subsection parameter_structures Parameter Structures > +@subsubsection crypto_sessions Crypto Sessions > +The following structure describes a crypto session. All packets / raw > data buffers processed in a session share the data that defines the > session. A crypto session is defined by: > + > +- Operation type : encode or decode\n\n > + > +- Algorithms specifications, keys and , if required, initialization > vectors. When initialization vectors are not provided and they should be > provided automatically by the crypto engine.\n\n > + > +- The operation mode: synchronous or asynchronous. Synchronous operation > blocks the caller until an operation status and result are available. In > synchronous mode there is at most only one outstanding crypto operation in > the calling thread. In asynchronous mode, the caller starts the crypto > operation and later it may receive the status and the result together with > a request context. The operation status and result may also be received by > a different thread.\n\n > + > +- Operation mode parameters: For asynchronous operation a completion > event containing the status, the result and the request context is enqueued > to a completion queue. In case the queue is under the scheduler control, > the scheduler determines who will receive the completion event and when. > When the completion queue is not scheduled, the thread which is supposed to > get the operation output has to explicitly poll the completion queue. > + > +Note that this is an abstract data type and its structure is > implementation-specific. The layout shown here is for illustrative purposes > and the actual layout will vary from one implementation to the next to most > closely align with the structures needed by the underlying SoC platform. > Applications set and reference fields in the session structure via accessor > functions that hide the actual layout. > + > +@code > +typedef enum odp_crypto_op_t { > + ODP_CRYPTO_OP_ENCODE, > + ODP_CRYPTO_OP_DECODE > +}odp_crypto_op_t; > + > +typedef struct odp_key_t { > +}odp_key_t; > + > +typedef struct odp_crypto_session_t { > + odp_crypto_op_t op; > + struct { > + enum odp_cipher_alg cipher_alg; > + odp_key_t *key; > + uint8_t *iv; > + size_t iv_len; > + } cipher; > + > + struct { > + enum odp_auth_alg auth_alg; > + enum odp_auth_len auth_len; > + odp_key_t *key; > + } auth; > + > + enum odp_crypto_op_mode { > + ODP_CRYPTO_SYNC, > + ODP_CRYPTO_ASYNC, > + } op_mode; > + > + struct { > + uint32_t timeout; > + struct { > + odp_queue_t completion_queue; > + } async; > + } op_mode_params; > + > + odp_session_proc_info_t session_proc_info; > +} odp_crxsypto_session_t; > +@endcode > + > +The completion queue contained in the session structure is an in/out > parameter. If provided, then the queue specified is associated with the > session and is used to ensure order preservation on that session. If not > provided, one is created and returned to the caller. Note that this > completion queue is used to order operations performed on this crypto > session. It should not be confused with the completion queue specified on > the odp_crypto_session_create() call (see below) that is used to control > whether that call is itself processed in a synchronous vs. asynchronous > manner. > + > +The following structure comprises processing information. This is > logically divided in two parts: > + > +- Processing input info - When crypto engine provides support for > protocol processing, this information is provided in a higher level common > protocol terminology form and a particular implementation should be able to > derive everything it needs from this definition. In addition, for crypto > engines able to automate tasks like memory allocation for the output a > buffer pool id may be specified.\n\n > + > +- Processing output information - statistics about processed > bytes/packets. These are useful when a session expiration is based on > traffic volume. These statistics may be updated by the software or by the > hardware crypto engine. > + > +Again, this is an abstract type whose specific layout will vary based on > implementation considerations. Access to fields contained in the structure > is only via accessor functions. > + > +@code > +typedef struct { > + uint64_t pkts_processed; > + uint64_t bytes_processed; > + uint64_t pkts_errored; > + uint64_t bytes_errored; > + > + odp_buffer_pool_t out_pool; > + > +} odp_session_proc_info_t; > +@endcode > + > +This enumeration defines which operations are applied and the order. > + > +@code > +enum odp_crypto_combination { > +ODP_CRYPTO_CIPHER_ONLY, > + ODP_CRYPTO_AUTH_ONLY, > + ODP_CRYPTO_AUTH_CIPHERTEXT > +}; > +@endcode > + > +This structure defines a contiguous segment in the input data which > starts at offset offset and is len bytes long. > + > +@code > +struct odp_data_range { > + unsigned offset:16; > + unsigned len:16; > +}; > +@endcode > + > +@subsection api_functions API Functions > + > +@subsubfunction Session Creation > + > +This function is used to create a crypto session. The required parameters > are : > + > +- Operation : encode/decode > +- Processing info : cipher/auth/both > +- Preferred mode : sync or async. > +- Algorithms suites, keys and optional IV > + > +Session creation can be synchronous or asynchronous. Completion event > argument is used to return the status and the session handle. When > completion queue is not provided (synchronous call), the completion event > is available upon function call return. When completion queue is provided > (asynchronous call), the completion event is placed on the completion queue. > + > +@code > +typedef uint64_t odp_crypto_session_t; > + > +struct odp_session_params { > + enum odp_crypto_operation op; > + odp_session_proc_info_t proc_info; > + enum odp_crypto_op_mode pref_mode; > + enum odp_cipher_alg cipher_alg; > + odp_key_t *cipher_key; > + uint8_t *iv; > + size_t iv_len; > + enum odp_auth_alg auth_alg; > + odp_key_t *auth_key; > +}; > + > +enum odp_crypto_ses_create_err { > + ODP_CRYPTO_SES_CREATE_NONE, > + ODP_CRYPTO_SES_CREATE_ENOMEM, > + /* Session creation error codes */ > +}; > + > +void > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, > enum odp_crypto_ses_create_err *status); > + > +void > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, > odp_crypto_session_t *handle); > + > +int odp_crypto_session_create( > + struct odp_session_params *params, > + odp_buffer_t completion_event, > + odp_queue_t completion_queue); > +@endcode > +@subsection crypto_operation Crypto Operation > + > +Crypto operations are described by a parameter structure: > +@code > +struct odp_crypto_op_params { > + odp_crypto_session_t session; > + odp_packet_t pkt; > + odp_packet_t out_pkt; > + uint8_t *override_iv_ptr; > + unsigned hash_result_offset; > + struct odp_data_range cipher_range; > + struct odp_data_range auth_range; > +}; > +@endcode > + > +<table> > +<tr><th>Parameter</th><th>Meaning</th></tr> > +<tr><td>session</td><td>Session to perform the operation</td></tr> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be > returned as the result of the operation. There are three different ways > this parameter is used, depending on the mode of operation requested by the > caller and the capabilities of the underlying implementation:\n\n > + > +-# If out_pkt is the same as pkt this indicates that the operation should > be performed in place.\n\n > +-# If out_pkt is different from pkt this indicates that output should be > placed in the buffer supplied by the caller.\n\n > +-# If out_pkt is omitted (a null/invalid value supplied on input) this > indicates that an output buffer should be allocated by the operation and > returned as part of the completion event associated with the operation.\n\n > + > +Note that not every implementation will support all of these modes and > MAY require that one mode be used in preference to others. Any such > implementation restrictions are communicated as output from session > creation.</td></tr> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this > request</td></tr> > +<tr><td>hash_result_offset</td><td>Offset into the output packet where > the hash result should be stored.</td></tr> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data > to be processed for ciphering.</td></tr> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data to > be processed for authentication.</td></tr> > +</table> > + > +The crypto operation is initiated with a single call that passes the > parameters for the operation and an event (for asynchronous completion). > +@code > +int odp_crypto_operation( > + struct odp_crypto_op_params *params, > + odp_buffer_t completion_event); > +@endcode > + > +Parameter | Meaning > +----------|-------- > +params | The parameter structure describing the crypto operation to be > performed. > +completion_event | The event delivered on completion. It provides > information about the status of the operation, result and request context. > In synchronous mode the event is available upon function call return. In > asynchronous mode, the event is placed on the session / operation > completion queue when the operation finished. > + > +Upon return the return code indicates whether the operation was > synchronous or asynchronous, or if an error occurred that prevented the > operation from being performed. > + > +Get session operation : > +@code > +odp_crypto_op_t > +odp_crypto_session_get_op(odp_crypto_session_t ses); > +@endcode > + > +Get session cipher information : > +@code > +odp_cipher_alg > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > +@endcode > + > +Get session authentication information : > +@code > +odp_auth_alg > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > +@endcode > + > +Change session IV : > +@code > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); > +@emdcode > + > +Change cipher or/and hash keys: > +@code > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t *key); > +@endcode > + > +Destroy crypto session. All pending operations are cancelled. > +@code > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > +@endcode > + > +Get completion event information - algorithm error, output and context. > Note that implementations MAY define their own specific error codes that > have meaning in that context. For application portability it is sufficient > to know whether an operation completed successfully or experienced an error > of some sort. > +@code > +enum crypto_alg_err { > + ODP_CRYPTO_ALG_ERR_NONE, > + ODP_CRYPTO_ALG_ERR_MODE, > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > +}; > + > +enum crypto_hw_err { > + ODP_CRYPTO_HW_ERR_NONE, > + ODP_CRYPTO_HW_ERR_DMA, > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > +}; > + > +struct odp_crypto_compl_status { > + odp_crypto_alg_t alg; > + enum crypto_alg_err alg_err; > + enum crypto_hw_err hw_err; > +}; > + > +void > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > + struct odp_crypto_compl_status *auth, > + struct odp_crypto_compl_status *cipher); > +@endcode > + > +Returns the output packet handle associated with the completion event : > +@code > +odp_packet_t > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > +@endcode > + > +Sets a context handle to be returned with the completion event : > +@code > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, > odp_compl_ctx_t *ctx); > +@endcode > + > +Returns the context associated with the completion event : > +@code > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); > +@endcode > + > +This section describes the API/Interface being defined at a functional > level in technical detail. Sub-sections include header file names, where > implementation files are expected to reside in the ODP git tree, as well as > the name, parameters, abstract data types, functionality, return codes, and > exception conditions of each function call defined by the API/Interface. > Appropriate diagrams, tables, etc. should be used to allow the programmer > tasked with implementing the API/Interface to understand the function to be > implemented as well as error conditions, corner cases, performance > requirements, etc. needed to implement the described API/Interface in a > functionally correct and efficient manner. > + > +@subsubsection random_number_functions Random Number Functions > +As noted earlier, random number support consists of two functions: > +@code > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); > + > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > +@endcode > + > +The difference is that the first provides access to hardware random > number functions that return true random data. This is typically used for > seed values. The second provides a deterministic random bit generator > conforming to NIST standards and is used by various crypto protocols and > algorithms. The use_entropy parameter on odp_hw_random_get is used to > disable any hardware pre-processing normally provided by the function and > is mainly intended to be used for testing/validation purposes. > + > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > +To support zeroization a buffer may be allocated with an > ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be > zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to > odp_buffer_pool_create() that specifies that all buffers allocated from > this pool must be zeroized upon free. Essentially, the buffer security > attribute is set by default from the attributes of the buffer pool that it > is allocated from. > + > +@subsubsection capability_inquiry Capability Inquiry > +To enable applications to determine crypto capabilities. > +@code > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > +@endcode > + > +Inquires whether the specified crypto and auth algorithms are supported. > Responses include: > +- ODP_HW_SYNC_SUPPORT > +- ODP_HW_ASYNC_SUPPORT > +- ODP_SW_SYNC_SUPPORT > +- ODP_SW_ASYNC_SUPPORT > +- ODP_NO_SUPPORT > + > +HW support means the combination is supported in hardware, SW support > means the combination is supported in software by the implementation. No > support means the combination is not supported by the implementation. The > SYNC and ASYNC return options can help the application decide how to invoke > these functions, or it can just check whether or not the response is > ODP_NO_SUPPORT. > + > +@section implementation_considerations Implementation Considerations > +One of the main purposes for the ODP crypto APIs is to provide portable > access across different SoCs whose hardware crypto capabilities largely > overlap but vary in terms of their implementation details. As a result, > implementations need not provide software fill-ins for specific > cryptographic features that are not available as hardware features on that > platform. Presumably applications needing specific features will select > platforms on which these features are present. Therefore, while all APIs > specified here MUST exist in each conforming ODP implementation, it is > acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response > to calls requesting crypto features not present on that platform. > + > +For example, the linux-generic ODP implementation may only implement the > null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not present > error code for any other cipher. This indication will also be returned on > that platform in response to odp_crypto_inquire calls for non-null cipher > algorithms. > + > +@section verification Verification/Testing > +This section describes the verification/test cases needed to ensure that > the defined functionality is implemented correctly and performs adequately. > This should be at a level of detail such that the programmer tasked with > writing test scripts/programs to verify the implementation(s) of the > defined functions can be written to ensure that all relevant functional > variants and error/exception cases are properly tested. > + > +This section needs to be completed before API testing begins. > + > +*/ > \ No newline at end of file > diff --git a/images/syncmodels.png b/images/syncmodels.png > new file mode 100644 > index > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > GIT binary patch > literal 17179 > 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 > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > literal 0 > HcmV?d00001 > > -- > 1.8.3.2 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
OK, thanks. On Wed, Jul 2, 2014 at 1:04 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > Patch applies with some white space issues, builds and links ok with the > API. > > To differentiate the odp-arch repo vs the odp repo as the target for this > patch, you will want to change the subject when creating the patch with > something like the following command. > git format-patch -1 --subject-prefix="PATCH ARCH" > > Minor nits - there is some content that we need to move out of crypto when > the next section is added, things like "Use of Terms" is probably common to > the whole doc. > > > > On 2 July 2014 13:46, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >> --- >> crypto_design.dox | 455 >> ++++++++++++++++++++++++++++++++++++++++++++++++++ >> images/syncmodels.png | Bin 0 -> 17179 bytes >> 2 files changed, 455 insertions(+) >> create mode 100644 crypto_design.dox >> create mode 100644 images/syncmodels.png >> >> diff --git a/crypto_design.dox b/crypto_design.dox >> new file mode 100644 >> index 0000000..1ad2ac6 >> --- /dev/null >> +++ b/crypto_design.dox >> @@ -0,0 +1,455 @@ >> +/* Copyright (c) 2043, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page crypto_design ODP Design - Crypto API >> +For the implimentation of the ODP crypto API please see @ref odp_crypto.h >> + >> +@tableofcontents >> + >> +@section revision_history Revision History >> +Revision | Issue Data | Description | Author >> +---------|------------|-------------|-------- >> +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, >> Alexandru >> +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, >> miscellaneous formatting, API comments | Bill >> +0.3 | 4/22/2014 | Added Use Case section to include results of >> design discussions held during ODP team calls | Bill >> +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to >> resolve | Bill >> +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready for >> final review | Bill >> +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill >> + >> +@section introduction Introduction >> +This document describes the ODP v1.0 Crypto API. Cryptography is an >> important part of data plane processing as many communication protocols >> make use of cryptographic functions. Moreover, many SoCs incorporate >> cryptographic hardware that can significantly accelerate these operations >> compared to their software equivalents as well as provide validated >> hardware functional correctness and security boundaries necessary for >> system-level security certifications such as FIPS-140 Level 2 and above. >> +@section requirements Requirements >> +@subsection use_of_terms Use of Terms >> +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 [RFC 2119]( >> https://tools.ietf.org/html/rfc2119). >> +@subsection uses_of_cryptography Uses of Cryptography >> +Crypto functions cover a range of uses and capabilities designed to >> support data security, integrity, authentication, and non-repudiation. >> +@subsubsection data_security Data Security >> +Cryptography supports data security by making use of complex >> mathematical transformations that are not feasibly reversible without >> possession of the secret key used to encrypt message data. >> +@subsubsection data_integrity Data Integrity >> +Cryptography supports data integrity through the use of cryptographic >> checksums (also known as secure hashes) that ensure the recipient that >> message data has not been altered either accidentally or maliciously while >> in transit. >> +@subsubsection data_authentication Data Authentication >> +Cryptography supports data authentication through the uses of Message >> Authentication Codes (MACs) that enable the recipient to verify that a >> message was sent from an authorized counterparty, and hence was not forged. >> +@subsubsection data_non_repudiation Data Non-Repudiation >> +Cryptography supports data non-repudiation through the use of digital >> signatures that enable a recipient or third party to verify the identity of >> the sending party and prevents the sending party from later denying that >> they originated a signed message. >> +@subsection scope Scope >> +ODP v1.0 crypto support is designed to provide a portable framework for >> accessing SoC-specific cryptographic functions of most use to the data >> plane. This is predominantly symmetric crypto operations used to support >> the encryption and decryption of data at line rate using hardware >> acceleration and offload. Specifically excluded in this support are public >> key operations and other crypto functions mainly used in the control plane. >> +@subsection cryptographic_operations_in_the_data_plane Cryptographic >> Operations in the Data Plane >> +ODP v1.0 crypto APIs cover the following areas: >> +@subsubsection ciphering Ciphering >> +Ciphering refers to mathematical transformations that use a secret key >> to encipher data, transforming the original data (referred to as plaintext) >> into ciphertext, thereby making it unintelligible to anyone not in >> possession of the key. Similarly, ciphering is also used to decipher data, >> allowing someone in possession of the correct key to transform received >> ciphertext back into plaintext. Approved block ciphers are listed [here]( >> http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be >> supported by each ODP implementation. >> +@subsubsection hasing Hashing >> +A hash is a cryptographic digest of a message that can be used to >> represent it for comparison or integrity checking. Hash functions are >> designed so that any alteration of a message will alter the hash and that >> it is computationally infeasible to craft a message that generates the same >> hash value as another message. Secure hash functions approved for >> cryptographic use are listed by NIST [here]( >> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD >> be supported by each ODP implementation. >> +@subsubsection zeroization Zeroization >> +To preserve the security of data, certain transient data held in data >> buffers MUST be cleared to zeros upon buffer free. Such capability is >> referred to as zeroization. ODP supports zeroization as a buffer pool >> attribute. >> +@subsubsection random_number_generation Random Number Generation >> +Because cryptography relies heavily on “unguessable” keys of various >> sorts, random number generation (RNG) is an integral part of cryptographic >> processing. Random numbers are used in key generation, initialization >> vectors (IVs), various types of padding bytes, and various other uses >> collectively referred to as nonces, that serve to “harden” cryptographic >> processing. >> + >> +There are two types of random number support of interest. Hardware >> random data, also known as entropy, that is the result of inherently random >> physical processes, and deterministic random bit generation (DRBG) that is >> used in certain certified cryptographic operations. Approved DRBG >> algorithms are listed in [NIST SP 800-90A]( >> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify >> which algorithms are available on a given implementation. As such ODP >> implementations MAY use any approved DRGB algorithm but SHOULD support at >> least one of them. Additionally, ODP implementations MUST NOT represent >> non-approved algorithms as DRBG implementations. Validated algorithms are >> listed in the [NIST DRBG Validation List]( >> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >> + >> +@subsubsection capability_inquiry Capability Inquiry >> +To enable applications to adapt to the implementation models offered >> across different SoC platforms, ODP provides APIs to allow applications to >> inquire about underlying crypto capabilities. A given ODP implementation >> may offer crypto as hardware features, software features, or not available >> on a given platform. >> +@subsection cryptographic_algorithms Cryptographic Algorithms and >> Protocols >> +A cryptographic algorithm is a mathematical transform that provides one >> of the cryptographic operations described above. They in turn are used as >> building blocks in creating cryptographic protocols. These are complete >> sets of rules for how to exchange data securely using cryptography. Both >> cryptographic algorithm and protocol design are highly specialized >> disciplines that involve high levels of public scrutiny and validation. As >> a result, applications simply make use of approved cryptographic algorithms >> and protocols. >> +@subsection cryptographic_operations Cryptographic Operations >> +Cryptographic operations may be initiated by software or directly by >> hardware as part of the RX or TX packet path processing. For ODP v1.0 >> software-initiated cryptographic operations are the primary use case. ODP >> provides APIs for performing data ciphering, hashing, random number >> generation, and capability inquiry. >> +@subsection performance_expectations Performance Expectations >> +In the data plane, the total processing budget for a packet may only be >> a few hundred cycles, so function invocation overhead MUST be kept to a >> minimum. This has several implications. >> + >> +-# When work is dispatched to a thread, all information needed by the >> thread to process the work request SHOULD be immediately at hand. Ideally >> any context or variables needed for the operation have been pre-warmed in >> the cache to avoid the latency hits associated with cache misses. SoCs >> having hardware schedulers generally do this pre-staging of data to >> minimize such latencies, and ODP implementations are expected to exploit >> such platform capabilities whenever possible.\n\n >> + >> +-# Calls to ODP functions SHOULD NOT involve excessive amounts of >> parameter passing and (depending on the implementation) SHOULD be inlined >> as much as possible to avoid call overhead. One technique that has proven >> useful is to allow for parameters to be passed as an explicit thread-local >> static structure. Such use of “templating” means that a single function can >> support a rich set of options but the caller can configure a template >> matched to specific use and only vary the one or two parameters that differ >> from call to call.\n\n >> + >> +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception >> path function processing. Kernel calls and such are acceptable only during >> one-time initialization logic or certain types of unusual error recovery >> operations. Often the best way to handle the latter is to pass the work to >> a dedicated recovery thread (or back to the control plane) rather than >> attempting to handle the condition inline. For example, a link-down >> condition will trigger various recovery actions that might best be handled >> in this manner. >> + >> +@subsection use_by_existing_code Use by Existing Code >> +Most applications wishing to make use of ODP represent substantial >> existing investment that must be preserved. Insofar as possible, ODP >> functions need to be orthogonal to existing application environments and >> structures to permit easy intermixing with pre-existing code. >> +@subsection data_references Data References >> +Packet data is inherently of variable length however it is often more >> efficient to organize memory into fixed-sized buffers that can be chained >> together on demand to contain packets. The application SHOULD normally not >> need to be aware of such lower-level segmentation and should be able to >> treat a packet as a single object. Alternately, especially when dealing >> with existing code, data segmentation MUST be explicitly specifiable via >> scatter/gather lists. For example, data encryption or decryption may be >> invoked on a list of data segments as part of a single function call. >> +@subsection chained_operations Chained Operations >> +Crypto operations such as hashing and encryption, or decryption and >> verification, are very commonly used in combination. For ODP, it is >> sufficient to support one cipher and one hash/authentication operation in a >> single call and this combination MUST be supported to avoid the call and >> dispatch overhead of separate invocations. >> +@subsection key_management Key Management and Session Data >> +Keying is an area of particular sensitivity in crypto processing since >> keys are highly confidential and may be subject to legal requirements for >> safeguarding within special hardware enclosures. >> + >> +A session is the security context used to represent an active set of >> crypto operations that need to be applied to a flow on a packet-by-packet >> basis. Generally a session is established upon detection of a flow >> requiring crypto processing and retained for the life of that flow. It has >> been noted that this can involve cooperative processing between the control >> and data planes so several requirements stem from this: >> + >> +-# Session creation MAY need to be handled in an asynchronous manner. >> This is to allow these to be created in batches by thread(s) that >> specialize in this activity.\n\n >> + >> +-# Sessions MAY need to reference keying material indirectly via key >> handling modules.\n\n >> + >> +-# Session creation MAY be performed by non-ODP code and communicated to >> data plane routines that make use of ODP crypto functions that need to >> reference the session information. >> + >> +ODP session APIs and data structures SHOULD be represented by abstract >> data types that encapsulate implementation details for both platform >> efficiency and to accommodate these needs. >> +Use Cases >> +For ODP v1.0 the major use cases of interest involve cryptographic >> algorithm acceleration. Cryptographic protocol acceleration is reserved for >> future ODP releases. >> +Buffers and Data Blocks >> +Cryptographic operations may be performed directly on data contained in >> ODP packet buffers, or it may be performed on “raw” data blocks operating >> entirely under application control. Note that when using raw data blocks >> not managed by ODP, the application must perform any needed zeroization >> using either its own or ODP-supplied buffer zeroization functions. ODP >> automatic support for zeroization is limited to ODP-managed buffers. ODP >> buffers allocated from buffer pools designated for crypto use will also >> have whatever alignment and/or addressability attributes needed by the >> implementation to support crypto API calls. >> + >> +Note: Some implementations may have difficulty dealing with application >> buffer addresses, as these may be virtual addresses that are mapped >> discontiguously into physical memory. For such implementations, memory >> SHOULD be allocated contiguously and MAY need to be “registered” to have >> proper addressability for crypto operations. This area of the design will >> be updated based on experience in dealing with different crypto >> implementations that have such requirements. >> +Synchronization >> +ODP operations fall into one of three categories: >> + >> +-# Inline (Synchronous): Upon return from a call the operation is >> complete. Operation is thus completely synchronous to the caller. Inline >> is the appropriate model when the invoked function takes relatively few >> cycles or when the caller cannot feasibly progress without the results of >> the invoked function.\n\n >> + >> +-# Parallel: Upon return from a call the operation has been initiated, >> but is expected to complete shortly. The caller continues to execute until >> it needs the result at which point it waits to complete the parallel >> operation. The effect is as if the operation were inline except that the >> caller was able to execute in parallel with the operation for some >> application-determined period of time. Parallel is the appropriate model >> when the operation being performed is relatively short (a few dozen up to >> perhaps 100 or 200 cycles) and the caller can usefully accomplish other >> processing on the same unit of work while the parallel operation is in >> progress, but not enough to justify the overhead of a formal queued work >> dispatch.\n\n >> + >> +-# Offloaded (Asynchronous): Upon return from the call the operation has >> been queued for execution. A completion event will be queued back to the >> scheduler when the event is completed. Offload is the appropriate model >> when the invoked function will take a substantial amount of cycles >> (thousands to tens of thousands) allowing the invoking thread/core to >> service other work until the operation completes. For offloaded work, >> completion is indicated by a completion event being posted back to an >> application-designated completion queue. Upon receipt the unit of work that >> initiated the offloaded operation continues processing with the results of >> the call. >> + >> +The synchronization models of interest are summarized in Figure 1: >> + >> + >> + >> +Note: Because few implementations are expected to offer the Parallel >> mode of operation as described above, this mode is reserved for potential >> future use. For ODP v1.0 only synchronous and asynchronous crypto >> operations are defined. >> +@section functional_definition Functional Definition >> +@subsection abstract_data_types Abstract data types >> +The following enumerations define various algorithms used for ciphering >> and hashing. These are the basic operations applied to input data. >> + >> +A particular ODP implementation should map these values to the actual >> information to be passed to the crypto engine. As such, the actual values >> of these enums is implementation-defined. >> + >> +Cipher algorithm encoding specifies the algorithm and cipher mode >> employed (as per security relevant RFCs - [4305]( >> http://tools.ietf.org/html/rfc4305), [4868]( >> http://tools.ietf.org/html/rfc4868), [4494]( >> http://tools.ietf.org/html/rfc4494)). >> + >> +@code >> +enum odp_cipher_alg { >> + ODP_CIPHER_ALG_NULL, >> + ODP_CIPHER_ALG_DES, >> + ODP_CIPHER_ALG_3DES_CBC, >> + ODP_CIPHER_ALG_AES_CBC, >> + ODP_CIPHER_ALG_AES_GCM, >> + ODP_CIPHER_ALG_AES_CTR, >> + ODP_CIPHER_ALG_KASUMI, >> + ODP_CIPHER_ALG_SNOW, >> + ... >> +}; >> +@endcode >> + >> +Authorization algorithm encoding specifies the algorithm and the length >> of the authorization used (as per security relevant RFCs - [4305]( >> http://tools.ietf.org/html/rfc4305), [4868]( >> http://tools.ietf.org/html/rfc4868), [4494]( >> http://tools.ietf.org/html/rfc4494)): >> + >> +@code >> +enum odp_auth_alg { >> + ODP_AUTH_ALG_NULL, >> + ODP_AUTH_MD5_96, >> + ODP_AUTH_ALG_SHA1_96, >> + ODP_AUTH_ALG_SHA1_160 >> + ODP_AUTH_ALG_SHA2_256_128, >> + ODP_AUTH_ALG_SHA2_384_192, >> + ODP_AUTH_ALG_SHA2_512_256, >> + ODP_AUTH_ALG_AES_CMAC_96, >> + ODP_AUTH_ALG_AES_XCBC_MAC_96, >> + ODP_AUTH_ALG_SNOW, >> + ODP_AUTH_ALG_KASUMI, >> + ... >> +}; >> + >> +typedef union odp_crypto_alg_t { >> + enum odp_cipher_alg cipher; >> + enum odp_auth_alg auth; >> +}odp_crypto_alg_t; >> +@endcode >> +@subsection parameter_structures Parameter Structures >> +@subsubsection crypto_sessions Crypto Sessions >> +The following structure describes a crypto session. All packets / raw >> data buffers processed in a session share the data that defines the >> session. A crypto session is defined by: >> + >> +- Operation type : encode or decode\n\n >> + >> +- Algorithms specifications, keys and , if required, initialization >> vectors. When initialization vectors are not provided and they should be >> provided automatically by the crypto engine.\n\n >> + >> +- The operation mode: synchronous or asynchronous. Synchronous operation >> blocks the caller until an operation status and result are available. In >> synchronous mode there is at most only one outstanding crypto operation in >> the calling thread. In asynchronous mode, the caller starts the crypto >> operation and later it may receive the status and the result together with >> a request context. The operation status and result may also be received by >> a different thread.\n\n >> + >> +- Operation mode parameters: For asynchronous operation a completion >> event containing the status, the result and the request context is enqueued >> to a completion queue. In case the queue is under the scheduler control, >> the scheduler determines who will receive the completion event and when. >> When the completion queue is not scheduled, the thread which is supposed to >> get the operation output has to explicitly poll the completion queue. >> + >> +Note that this is an abstract data type and its structure is >> implementation-specific. The layout shown here is for illustrative purposes >> and the actual layout will vary from one implementation to the next to most >> closely align with the structures needed by the underlying SoC platform. >> Applications set and reference fields in the session structure via accessor >> functions that hide the actual layout. >> + >> +@code >> +typedef enum odp_crypto_op_t { >> + ODP_CRYPTO_OP_ENCODE, >> + ODP_CRYPTO_OP_DECODE >> +}odp_crypto_op_t; >> + >> +typedef struct odp_key_t { >> +}odp_key_t; >> + >> +typedef struct odp_crypto_session_t { >> + odp_crypto_op_t op; >> + struct { >> + enum odp_cipher_alg cipher_alg; >> + odp_key_t *key; >> + uint8_t *iv; >> + size_t iv_len; >> + } cipher; >> + >> + struct { >> + enum odp_auth_alg auth_alg; >> + enum odp_auth_len auth_len; >> + odp_key_t *key; >> + } auth; >> + >> + enum odp_crypto_op_mode { >> + ODP_CRYPTO_SYNC, >> + ODP_CRYPTO_ASYNC, >> + } op_mode; >> + >> + struct { >> + uint32_t timeout; >> + struct { >> + odp_queue_t completion_queue; >> + } async; >> + } op_mode_params; >> + >> + odp_session_proc_info_t session_proc_info; >> +} odp_crxsypto_session_t; >> +@endcode >> + >> +The completion queue contained in the session structure is an in/out >> parameter. If provided, then the queue specified is associated with the >> session and is used to ensure order preservation on that session. If not >> provided, one is created and returned to the caller. Note that this >> completion queue is used to order operations performed on this crypto >> session. It should not be confused with the completion queue specified on >> the odp_crypto_session_create() call (see below) that is used to control >> whether that call is itself processed in a synchronous vs. asynchronous >> manner. >> + >> +The following structure comprises processing information. This is >> logically divided in two parts: >> + >> +- Processing input info - When crypto engine provides support for >> protocol processing, this information is provided in a higher level common >> protocol terminology form and a particular implementation should be able to >> derive everything it needs from this definition. In addition, for crypto >> engines able to automate tasks like memory allocation for the output a >> buffer pool id may be specified.\n\n >> + >> +- Processing output information - statistics about processed >> bytes/packets. These are useful when a session expiration is based on >> traffic volume. These statistics may be updated by the software or by the >> hardware crypto engine. >> + >> +Again, this is an abstract type whose specific layout will vary based on >> implementation considerations. Access to fields contained in the structure >> is only via accessor functions. >> + >> +@code >> +typedef struct { >> + uint64_t pkts_processed; >> + uint64_t bytes_processed; >> + uint64_t pkts_errored; >> + uint64_t bytes_errored; >> + >> + odp_buffer_pool_t out_pool; >> + >> +} odp_session_proc_info_t; >> +@endcode >> + >> +This enumeration defines which operations are applied and the order. >> + >> +@code >> +enum odp_crypto_combination { >> +ODP_CRYPTO_CIPHER_ONLY, >> + ODP_CRYPTO_AUTH_ONLY, >> + ODP_CRYPTO_AUTH_CIPHERTEXT >> +}; >> +@endcode >> + >> +This structure defines a contiguous segment in the input data which >> starts at offset offset and is len bytes long. >> + >> +@code >> +struct odp_data_range { >> + unsigned offset:16; >> + unsigned len:16; >> +}; >> +@endcode >> + >> +@subsection api_functions API Functions >> + >> +@subsubfunction Session Creation >> + >> +This function is used to create a crypto session. The required >> parameters are : >> + >> +- Operation : encode/decode >> +- Processing info : cipher/auth/both >> +- Preferred mode : sync or async. >> +- Algorithms suites, keys and optional IV >> + >> +Session creation can be synchronous or asynchronous. Completion event >> argument is used to return the status and the session handle. When >> completion queue is not provided (synchronous call), the completion event >> is available upon function call return. When completion queue is provided >> (asynchronous call), the completion event is placed on the completion queue. >> + >> +@code >> +typedef uint64_t odp_crypto_session_t; >> + >> +struct odp_session_params { >> + enum odp_crypto_operation op; >> + odp_session_proc_info_t proc_info; >> + enum odp_crypto_op_mode pref_mode; >> + enum odp_cipher_alg cipher_alg; >> + odp_key_t *cipher_key; >> + uint8_t *iv; >> + size_t iv_len; >> + enum odp_auth_alg auth_alg; >> + odp_key_t *auth_key; >> +}; >> + >> +enum odp_crypto_ses_create_err { >> + ODP_CRYPTO_SES_CREATE_NONE, >> + ODP_CRYPTO_SES_CREATE_ENOMEM, >> + /* Session creation error codes */ >> +}; >> + >> +void >> +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, >> enum odp_crypto_ses_create_err *status); >> + >> +void >> +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, >> odp_crypto_session_t *handle); >> + >> +int odp_crypto_session_create( >> + struct odp_session_params *params, >> + odp_buffer_t completion_event, >> + odp_queue_t completion_queue); >> +@endcode >> +@subsection crypto_operation Crypto Operation >> + >> +Crypto operations are described by a parameter structure: >> +@code >> +struct odp_crypto_op_params { >> + odp_crypto_session_t session; >> + odp_packet_t pkt; >> + odp_packet_t out_pkt; >> + uint8_t *override_iv_ptr; >> + unsigned hash_result_offset; >> + struct odp_data_range cipher_range; >> + struct odp_data_range auth_range; >> +}; >> +@endcode >> + >> +<table> >> +<tr><th>Parameter</th><th>Meaning</th></tr> >> +<tr><td>session</td><td>Session to perform the operation</td></tr> >> +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> >> +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be >> returned as the result of the operation. There are three different ways >> this parameter is used, depending on the mode of operation requested by the >> caller and the capabilities of the underlying implementation:\n\n >> + >> +-# If out_pkt is the same as pkt this indicates that the operation >> should be performed in place.\n\n >> +-# If out_pkt is different from pkt this indicates that output should be >> placed in the buffer supplied by the caller.\n\n >> +-# If out_pkt is omitted (a null/invalid value supplied on input) this >> indicates that an output buffer should be allocated by the operation and >> returned as part of the completion event associated with the operation.\n\n >> + >> +Note that not every implementation will support all of these modes and >> MAY require that one mode be used in preference to others. Any such >> implementation restrictions are communicated as output from session >> creation.</td></tr> >> +<tr><td>override_iv_ptr</td><td>Optional IV to use for this >> request</td></tr> >> +<tr><td>hash_result_offset</td><td>Offset into the output packet where >> the hash result should be stored.</td></tr> >> +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data >> to be processed for ciphering.</td></tr> >> +<tr><td>auth_range</td><td>The byte range (offset:length) of the data to >> be processed for authentication.</td></tr> >> +</table> >> + >> +The crypto operation is initiated with a single call that passes the >> parameters for the operation and an event (for asynchronous completion). >> +@code >> +int odp_crypto_operation( >> + struct odp_crypto_op_params *params, >> + odp_buffer_t completion_event); >> +@endcode >> + >> +Parameter | Meaning >> +----------|-------- >> +params | The parameter structure describing the crypto operation to >> be performed. >> +completion_event | The event delivered on completion. It provides >> information about the status of the operation, result and request context. >> In synchronous mode the event is available upon function call return. In >> asynchronous mode, the event is placed on the session / operation >> completion queue when the operation finished. >> + >> +Upon return the return code indicates whether the operation was >> synchronous or asynchronous, or if an error occurred that prevented the >> operation from being performed. >> + >> +Get session operation : >> +@code >> +odp_crypto_op_t >> +odp_crypto_session_get_op(odp_crypto_session_t ses); >> +@endcode >> + >> +Get session cipher information : >> +@code >> +odp_cipher_alg >> +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); >> +@endcode >> + >> +Get session authentication information : >> +@code >> +odp_auth_alg >> +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >> +@endcode >> + >> +Change session IV : >> +@code >> +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); >> +@emdcode >> + >> +Change cipher or/and hash keys: >> +@code >> +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t *key); >> +@endcode >> + >> +Destroy crypto session. All pending operations are cancelled. >> +@code >> +int odp_crypto_session_destroy(odp_crypto_session_t ses); >> +@endcode >> + >> +Get completion event information - algorithm error, output and context. >> Note that implementations MAY define their own specific error codes that >> have meaning in that context. For application portability it is sufficient >> to know whether an operation completed successfully or experienced an error >> of some sort. >> +@code >> +enum crypto_alg_err { >> + ODP_CRYPTO_ALG_ERR_NONE, >> + ODP_CRYPTO_ALG_ERR_MODE, >> + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >> + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >> + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >> + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >> +}; >> + >> +enum crypto_hw_err { >> + ODP_CRYPTO_HW_ERR_NONE, >> + ODP_CRYPTO_HW_ERR_DMA, >> + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >> +}; >> + >> +struct odp_crypto_compl_status { >> + odp_crypto_alg_t alg; >> + enum crypto_alg_err alg_err; >> + enum crypto_hw_err hw_err; >> +}; >> + >> +void >> +odp_crypto_get_compl_status(odp_buffer_t completion_event, >> + struct odp_crypto_compl_status *auth, >> + struct odp_crypto_compl_status *cipher); >> +@endcode >> + >> +Returns the output packet handle associated with the completion event : >> +@code >> +odp_packet_t >> +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >> +@endcode >> + >> +Sets a context handle to be returned with the completion event : >> +@code >> +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, >> odp_compl_ctx_t *ctx); >> +@endcode >> + >> +Returns the context associated with the completion event : >> +@code >> +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); >> +@endcode >> + >> +This section describes the API/Interface being defined at a functional >> level in technical detail. Sub-sections include header file names, where >> implementation files are expected to reside in the ODP git tree, as well as >> the name, parameters, abstract data types, functionality, return codes, and >> exception conditions of each function call defined by the API/Interface. >> Appropriate diagrams, tables, etc. should be used to allow the programmer >> tasked with implementing the API/Interface to understand the function to be >> implemented as well as error conditions, corner cases, performance >> requirements, etc. needed to implement the described API/Interface in a >> functionally correct and efficient manner. >> + >> +@subsubsection random_number_functions Random Number Functions >> +As noted earlier, random number support consists of two functions: >> +@code >> +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); >> + >> +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >> +@endcode >> + >> +The difference is that the first provides access to hardware random >> number functions that return true random data. This is typically used for >> seed values. The second provides a deterministic random bit generator >> conforming to NIST standards and is used by various crypto protocols and >> algorithms. The use_entropy parameter on odp_hw_random_get is used to >> disable any hardware pre-processing normally provided by the function and >> is mainly intended to be used for testing/validation purposes. >> + >> +@subsubsection buffer_pool_extensions Buffer Pool Extensions >> +To support zeroization a buffer may be allocated with an >> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be >> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to >> odp_buffer_pool_create() that specifies that all buffers allocated from >> this pool must be zeroized upon free. Essentially, the buffer security >> attribute is set by default from the attributes of the buffer pool that it >> is allocated from. >> + >> +@subsubsection capability_inquiry Capability Inquiry >> +To enable applications to determine crypto capabilities. >> +@code >> +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); >> +@endcode >> + >> +Inquires whether the specified crypto and auth algorithms are supported. >> Responses include: >> +- ODP_HW_SYNC_SUPPORT >> +- ODP_HW_ASYNC_SUPPORT >> +- ODP_SW_SYNC_SUPPORT >> +- ODP_SW_ASYNC_SUPPORT >> +- ODP_NO_SUPPORT >> + >> +HW support means the combination is supported in hardware, SW support >> means the combination is supported in software by the implementation. No >> support means the combination is not supported by the implementation. The >> SYNC and ASYNC return options can help the application decide how to invoke >> these functions, or it can just check whether or not the response is >> ODP_NO_SUPPORT. >> + >> +@section implementation_considerations Implementation Considerations >> +One of the main purposes for the ODP crypto APIs is to provide portable >> access across different SoCs whose hardware crypto capabilities largely >> overlap but vary in terms of their implementation details. As a result, >> implementations need not provide software fill-ins for specific >> cryptographic features that are not available as hardware features on that >> platform. Presumably applications needing specific features will select >> platforms on which these features are present. Therefore, while all APIs >> specified here MUST exist in each conforming ODP implementation, it is >> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response >> to calls requesting crypto features not present on that platform. >> + >> +For example, the linux-generic ODP implementation may only implement the >> null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not present >> error code for any other cipher. This indication will also be returned on >> that platform in response to odp_crypto_inquire calls for non-null cipher >> algorithms. >> + >> +@section verification Verification/Testing >> +This section describes the verification/test cases needed to ensure that >> the defined functionality is implemented correctly and performs adequately. >> This should be at a level of detail such that the programmer tasked with >> writing test scripts/programs to verify the implementation(s) of the >> defined functions can be written to ensure that all relevant functional >> variants and error/exception cases are properly tested. >> + >> +This section needs to be completed before API testing begins. >> + >> +*/ >> \ No newline at end of file >> diff --git a/images/syncmodels.png b/images/syncmodels.png >> new file mode 100644 >> index >> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >> GIT binary patch >> literal 17179 >> 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 >> Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b >> >> literal 0 >> HcmV?d00001 >> >> -- >> 1.8.3.2 >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> > > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP >
On 2014-07-02 12:46, Bill Fischofer wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- I have some more nit... 1. Maybe fix the indentation in the code examples... 2. Remove the extra space after comma or dot in the text.. 3. I've said it before remove the version number (v1.0) from the text... doesn't belong in the text... You should know what version of the document you reading right? Cheers, Anders > crypto_design.dox | 455 ++++++++++++++++++++++++++++++++++++++++++++++++++ > images/syncmodels.png | Bin 0 -> 17179 bytes > 2 files changed, 455 insertions(+) > create mode 100644 crypto_design.dox > create mode 100644 images/syncmodels.png > > diff --git a/crypto_design.dox b/crypto_design.dox > new file mode 100644 > index 0000000..1ad2ac6 > --- /dev/null > +++ b/crypto_design.dox > @@ -0,0 +1,455 @@ > +/* Copyright (c) 2043, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page crypto_design ODP Design - Crypto API > +For the implimentation of the ODP crypto API please see @ref odp_crypto.h > + > +@tableofcontents > + > +@section revision_history Revision History > +Revision | Issue Data | Description | Author > +---------|------------|-------------|-------- > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, Alexandru > +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, miscellaneous formatting, API comments | Bill > +0.3 | 4/22/2014 | Added Use Case section to include results of design discussions held during ODP team calls | Bill > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to resolve | Bill > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready for final review | Bill > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > + > +@section introduction Introduction > +This document describes the ODP v1.0 Crypto API. Cryptography is an important part of data plane processing as many communication protocols make use of cryptographic functions. Moreover, many SoCs incorporate cryptographic hardware that can significantly accelerate these operations compared to their software equivalents as well as provide validated hardware functional correctness and security boundaries necessary for system-level security certifications such as FIPS-140 Level 2 and above. > +@section requirements Requirements > +@subsection use_of_terms Use of Terms > +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 [RFC 2119](https://tools.ietf.org/html/rfc2119). > +@subsection uses_of_cryptography Uses of Cryptography > +Crypto functions cover a range of uses and capabilities designed to support data security, integrity, authentication, and non-repudiation. > +@subsubsection data_security Data Security > +Cryptography supports data security by making use of complex mathematical transformations that are not feasibly reversible without possession of the secret key used to encrypt message data. > +@subsubsection data_integrity Data Integrity > +Cryptography supports data integrity through the use of cryptographic checksums (also known as secure hashes) that ensure the recipient that message data has not been altered either accidentally or maliciously while in transit. > +@subsubsection data_authentication Data Authentication > +Cryptography supports data authentication through the uses of Message Authentication Codes (MACs) that enable the recipient to verify that a message was sent from an authorized counterparty, and hence was not forged. > +@subsubsection data_non_repudiation Data Non-Repudiation > +Cryptography supports data non-repudiation through the use of digital signatures that enable a recipient or third party to verify the identity of the sending party and prevents the sending party from later denying that they originated a signed message. > +@subsection scope Scope > +ODP v1.0 crypto support is designed to provide a portable framework for accessing SoC-specific cryptographic functions of most use to the data plane. This is predominantly symmetric crypto operations used to support the encryption and decryption of data at line rate using hardware acceleration and offload. Specifically excluded in this support are public key operations and other crypto functions mainly used in the control plane. > +@subsection cryptographic_operations_in_the_data_plane Cryptographic Operations in the Data Plane > +ODP v1.0 crypto APIs cover the following areas: > +@subsubsection ciphering Ciphering > +Ciphering refers to mathematical transformations that use a secret key to encipher data, transforming the original data (referred to as plaintext) into ciphertext, thereby making it unintelligible to anyone not in possession of the key. Similarly, ciphering is also used to decipher data, allowing someone in possession of the correct key to transform received ciphertext back into plaintext. Approved block ciphers are listed [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be supported by each ODP implementation. > +@subsubsection hasing Hashing > +A hash is a cryptographic digest of a message that can be used to represent it for comparison or integrity checking. Hash functions are designed so that any alteration of a message will alter the hash and that it is computationally infeasible to craft a message that generates the same hash value as another message. Secure hash functions approved for cryptographic use are listed by NIST [here](http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD be supported by each ODP implementation. > +@subsubsection zeroization Zeroization > +To preserve the security of data, certain transient data held in data buffers MUST be cleared to zeros upon buffer free. Such capability is referred to as zeroization. ODP supports zeroization as a buffer pool attribute. > +@subsubsection random_number_generation Random Number Generation > +Because cryptography relies heavily on “unguessable” keys of various sorts, random number generation (RNG) is an integral part of cryptographic processing. Random numbers are used in key generation, initialization vectors (IVs), various types of padding bytes, and various other uses collectively referred to as nonces, that serve to “harden” cryptographic processing. > + > +There are two types of random number support of interest. Hardware random data, also known as entropy, that is the result of inherently random physical processes, and deterministic random bit generation (DRBG) that is used in certain certified cryptographic operations. Approved DRBG algorithms are listed in [NIST SP 800-90A](http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify which algorithms are available on a given implementation. As such ODP implementations MAY use any approved DRGB algorithm but SHOULD support at least one of them. Additionally, ODP implementations MUST NOT represent non-approved algorithms as DRBG implementations. Validated algorithms are listed in the [NIST DRBG Validation List](http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > + > +@subsubsection capability_inquiry Capability Inquiry > +To enable applications to adapt to the implementation models offered across different SoC platforms, ODP provides APIs to allow applications to inquire about underlying crypto capabilities. A given ODP implementation may offer crypto as hardware features, software features, or not available on a given platform. > +@subsection cryptographic_algorithms Cryptographic Algorithms and Protocols > +A cryptographic algorithm is a mathematical transform that provides one of the cryptographic operations described above. They in turn are used as building blocks in creating cryptographic protocols. These are complete sets of rules for how to exchange data securely using cryptography. Both cryptographic algorithm and protocol design are highly specialized disciplines that involve high levels of public scrutiny and validation. As a result, applications simply make use of approved cryptographic algorithms and protocols. > +@subsection cryptographic_operations Cryptographic Operations > +Cryptographic operations may be initiated by software or directly by hardware as part of the RX or TX packet path processing. For ODP v1.0 software-initiated cryptographic operations are the primary use case. ODP provides APIs for performing data ciphering, hashing, random number generation, and capability inquiry. > +@subsection performance_expectations Performance Expectations > +In the data plane, the total processing budget for a packet may only be a few hundred cycles, so function invocation overhead MUST be kept to a minimum. This has several implications. > + > +-# When work is dispatched to a thread, all information needed by the thread to process the work request SHOULD be immediately at hand. Ideally any context or variables needed for the operation have been pre-warmed in the cache to avoid the latency hits associated with cache misses. SoCs having hardware schedulers generally do this pre-staging of data to minimize such latencies, and ODP implementations are expected to exploit such platform capabilities whenever possible.\n\n > + > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of parameter passing and (depending on the implementation) SHOULD be inlined as much as possible to avoid call overhead. One technique that has proven useful is to allow for parameters to be passed as an explicit thread-local static structure. Such use of “templating” means that a single function can support a rich set of options but the caller can configure a template matched to specific use and only vary the one or two parameters that differ from call to call.\n\n > + > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception path function processing. Kernel calls and such are acceptable only during one-time initialization logic or certain types of unusual error recovery operations. Often the best way to handle the latter is to pass the work to a dedicated recovery thread (or back to the control plane) rather than attempting to handle the condition inline. For example, a link-down condition will trigger various recovery actions that might best be handled in this manner. > + > +@subsection use_by_existing_code Use by Existing Code > +Most applications wishing to make use of ODP represent substantial existing investment that must be preserved. Insofar as possible, ODP functions need to be orthogonal to existing application environments and structures to permit easy intermixing with pre-existing code. > +@subsection data_references Data References > +Packet data is inherently of variable length however it is often more efficient to organize memory into fixed-sized buffers that can be chained together on demand to contain packets. The application SHOULD normally not need to be aware of such lower-level segmentation and should be able to treat a packet as a single object. Alternately, especially when dealing with existing code, data segmentation MUST be explicitly specifiable via scatter/gather lists. For example, data encryption or decryption may be invoked on a list of data segments as part of a single function call. > +@subsection chained_operations Chained Operations > +Crypto operations such as hashing and encryption, or decryption and verification, are very commonly used in combination. For ODP, it is sufficient to support one cipher and one hash/authentication operation in a single call and this combination MUST be supported to avoid the call and dispatch overhead of separate invocations. > +@subsection key_management Key Management and Session Data > +Keying is an area of particular sensitivity in crypto processing since keys are highly confidential and may be subject to legal requirements for safeguarding within special hardware enclosures. > + > +A session is the security context used to represent an active set of crypto operations that need to be applied to a flow on a packet-by-packet basis. Generally a session is established upon detection of a flow requiring crypto processing and retained for the life of that flow. It has been noted that this can involve cooperative processing between the control and data planes so several requirements stem from this: > + > +-# Session creation MAY need to be handled in an asynchronous manner. This is to allow these to be created in batches by thread(s) that specialize in this activity.\n\n > + > +-# Sessions MAY need to reference keying material indirectly via key handling modules.\n\n > + > +-# Session creation MAY be performed by non-ODP code and communicated to data plane routines that make use of ODP crypto functions that need to reference the session information. > + > +ODP session APIs and data structures SHOULD be represented by abstract data types that encapsulate implementation details for both platform efficiency and to accommodate these needs. > +Use Cases > +For ODP v1.0 the major use cases of interest involve cryptographic algorithm acceleration. Cryptographic protocol acceleration is reserved for future ODP releases. > +Buffers and Data Blocks > +Cryptographic operations may be performed directly on data contained in ODP packet buffers, or it may be performed on “raw” data blocks operating entirely under application control. Note that when using raw data blocks not managed by ODP, the application must perform any needed zeroization using either its own or ODP-supplied buffer zeroization functions. ODP automatic support for zeroization is limited to ODP-managed buffers. ODP buffers allocated from buffer pools designated for crypto use will also have whatever alignment and/or addressability attributes needed by the implementation to support crypto API calls. > + > +Note: Some implementations may have difficulty dealing with application buffer addresses, as these may be virtual addresses that are mapped discontiguously into physical memory. For such implementations, memory SHOULD be allocated contiguously and MAY need to be “registered” to have proper addressability for crypto operations. This area of the design will be updated based on experience in dealing with different crypto implementations that have such requirements. > +Synchronization > +ODP operations fall into one of three categories: > + > +-# Inline (Synchronous): Upon return from a call the operation is complete. Operation is thus completely synchronous to the caller. Inline is the appropriate model when the invoked function takes relatively few cycles or when the caller cannot feasibly progress without the results of the invoked function.\n\n > + > +-# Parallel: Upon return from a call the operation has been initiated, but is expected to complete shortly. The caller continues to execute until it needs the result at which point it waits to complete the parallel operation. The effect is as if the operation were inline except that the caller was able to execute in parallel with the operation for some application-determined period of time. Parallel is the appropriate model when the operation being performed is relatively short (a few dozen up to perhaps 100 or 200 cycles) and the caller can usefully accomplish other processing on the same unit of work while the parallel operation is in progress, but not enough to justify the overhead of a formal queued work dispatch.\n\n > + > +-# Offloaded (Asynchronous): Upon return from the call the operation has been queued for execution. A completion event will be queued back to the scheduler when the event is completed. Offload is the appropriate model when the invoked function will take a substantial amount of cycles (thousands to tens of thousands) allowing the invoking thread/core to service other work until the operation completes. For offloaded work, completion is indicated by a completion event being posted back to an application-designated completion queue. Upon receipt the unit of work that initiated the offloaded operation continues processing with the results of the call. > + > +The synchronization models of interest are summarized in Figure 1: > + > + > + > +Note: Because few implementations are expected to offer the Parallel mode of operation as described above, this mode is reserved for potential future use. For ODP v1.0 only synchronous and asynchronous crypto operations are defined. > +@section functional_definition Functional Definition > +@subsection abstract_data_types Abstract data types > +The following enumerations define various algorithms used for ciphering and hashing. These are the basic operations applied to input data. > + > +A particular ODP implementation should map these values to the actual information to be passed to the crypto engine. As such, the actual values of these enums is implementation-defined. > + > +Cipher algorithm encoding specifies the algorithm and cipher mode employed (as per security relevant RFCs - [4305](http://tools.ietf.org/html/rfc4305), [4868](http://tools.ietf.org/html/rfc4868), [4494](http://tools.ietf.org/html/rfc4494)). > + > +@code > +enum odp_cipher_alg { > + ODP_CIPHER_ALG_NULL, > + ODP_CIPHER_ALG_DES, > + ODP_CIPHER_ALG_3DES_CBC, > + ODP_CIPHER_ALG_AES_CBC, > + ODP_CIPHER_ALG_AES_GCM, > + ODP_CIPHER_ALG_AES_CTR, > + ODP_CIPHER_ALG_KASUMI, > + ODP_CIPHER_ALG_SNOW, > + ... > +}; > +@endcode > + > +Authorization algorithm encoding specifies the algorithm and the length of the authorization used (as per security relevant RFCs - [4305](http://tools.ietf.org/html/rfc4305), [4868](http://tools.ietf.org/html/rfc4868), [4494](http://tools.ietf.org/html/rfc4494)): > + > +@code > +enum odp_auth_alg { > + ODP_AUTH_ALG_NULL, > + ODP_AUTH_MD5_96, > + ODP_AUTH_ALG_SHA1_96, > + ODP_AUTH_ALG_SHA1_160 > + ODP_AUTH_ALG_SHA2_256_128, > + ODP_AUTH_ALG_SHA2_384_192, > + ODP_AUTH_ALG_SHA2_512_256, > + ODP_AUTH_ALG_AES_CMAC_96, > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > + ODP_AUTH_ALG_SNOW, > + ODP_AUTH_ALG_KASUMI, > + ... > +}; > + > +typedef union odp_crypto_alg_t { > + enum odp_cipher_alg cipher; > + enum odp_auth_alg auth; > +}odp_crypto_alg_t; > +@endcode > +@subsection parameter_structures Parameter Structures > +@subsubsection crypto_sessions Crypto Sessions > +The following structure describes a crypto session. All packets / raw data buffers processed in a session share the data that defines the session. A crypto session is defined by: > + > +- Operation type : encode or decode\n\n > + > +- Algorithms specifications, keys and , if required, initialization vectors. When initialization vectors are not provided and they should be provided automatically by the crypto engine.\n\n > + > +- The operation mode: synchronous or asynchronous. Synchronous operation blocks the caller until an operation status and result are available. In synchronous mode there is at most only one outstanding crypto operation in the calling thread. In asynchronous mode, the caller starts the crypto operation and later it may receive the status and the result together with a request context. The operation status and result may also be received by a different thread.\n\n > + > +- Operation mode parameters: For asynchronous operation a completion event containing the status, the result and the request context is enqueued to a completion queue. In case the queue is under the scheduler control, the scheduler determines who will receive the completion event and when. When the completion queue is not scheduled, the thread which is supposed to get the operation output has to explicitly poll the completion queue. > + > +Note that this is an abstract data type and its structure is implementation-specific. The layout shown here is for illustrative purposes and the actual layout will vary from one implementation to the next to most closely align with the structures needed by the underlying SoC platform. Applications set and reference fields in the session structure via accessor functions that hide the actual layout. > + > +@code > +typedef enum odp_crypto_op_t { > + ODP_CRYPTO_OP_ENCODE, > + ODP_CRYPTO_OP_DECODE > +}odp_crypto_op_t; > + > +typedef struct odp_key_t { > +}odp_key_t; > + > +typedef struct odp_crypto_session_t { > + odp_crypto_op_t op; > + struct { > + enum odp_cipher_alg cipher_alg; > + odp_key_t *key; > + uint8_t *iv; > + size_t iv_len; > + } cipher; > + > + struct { > + enum odp_auth_alg auth_alg; > + enum odp_auth_len auth_len; > + odp_key_t *key; > + } auth; > + > + enum odp_crypto_op_mode { > + ODP_CRYPTO_SYNC, > + ODP_CRYPTO_ASYNC, > + } op_mode; > + > + struct { > + uint32_t timeout; > + struct { > + odp_queue_t completion_queue; > + } async; > + } op_mode_params; > + > + odp_session_proc_info_t session_proc_info; > +} odp_crxsypto_session_t; > +@endcode > + > +The completion queue contained in the session structure is an in/out parameter. If provided, then the queue specified is associated with the session and is used to ensure order preservation on that session. If not provided, one is created and returned to the caller. Note that this completion queue is used to order operations performed on this crypto session. It should not be confused with the completion queue specified on the odp_crypto_session_create() call (see below) that is used to control whether that call is itself processed in a synchronous vs. asynchronous manner. > + > +The following structure comprises processing information. This is logically divided in two parts: > + > +- Processing input info - When crypto engine provides support for protocol processing, this information is provided in a higher level common protocol terminology form and a particular implementation should be able to derive everything it needs from this definition. In addition, for crypto engines able to automate tasks like memory allocation for the output a buffer pool id may be specified.\n\n > + > +- Processing output information - statistics about processed bytes/packets. These are useful when a session expiration is based on traffic volume. These statistics may be updated by the software or by the hardware crypto engine. > + > +Again, this is an abstract type whose specific layout will vary based on implementation considerations. Access to fields contained in the structure is only via accessor functions. > + > +@code > +typedef struct { > + uint64_t pkts_processed; > + uint64_t bytes_processed; > + uint64_t pkts_errored; > + uint64_t bytes_errored; > + > + odp_buffer_pool_t out_pool; > + > +} odp_session_proc_info_t; > +@endcode > + > +This enumeration defines which operations are applied and the order. > + > +@code > +enum odp_crypto_combination { > +ODP_CRYPTO_CIPHER_ONLY, > + ODP_CRYPTO_AUTH_ONLY, > + ODP_CRYPTO_AUTH_CIPHERTEXT > +}; > +@endcode > + > +This structure defines a contiguous segment in the input data which starts at offset offset and is len bytes long. > + > +@code > +struct odp_data_range { > + unsigned offset:16; > + unsigned len:16; > +}; > +@endcode > + > +@subsection api_functions API Functions > + > +@subsubfunction Session Creation > + > +This function is used to create a crypto session. The required parameters are : > + > +- Operation : encode/decode > +- Processing info : cipher/auth/both > +- Preferred mode : sync or async. > +- Algorithms suites, keys and optional IV > + > +Session creation can be synchronous or asynchronous. Completion event argument is used to return the status and the session handle. When completion queue is not provided (synchronous call), the completion event is available upon function call return. When completion queue is provided (asynchronous call), the completion event is placed on the completion queue. > + > +@code > +typedef uint64_t odp_crypto_session_t; > + > +struct odp_session_params { > + enum odp_crypto_operation op; > + odp_session_proc_info_t proc_info; > + enum odp_crypto_op_mode pref_mode; > + enum odp_cipher_alg cipher_alg; > + odp_key_t *cipher_key; > + uint8_t *iv; > + size_t iv_len; > + enum odp_auth_alg auth_alg; > + odp_key_t *auth_key; > +}; > + > +enum odp_crypto_ses_create_err { > + ODP_CRYPTO_SES_CREATE_NONE, > + ODP_CRYPTO_SES_CREATE_ENOMEM, > + /* Session creation error codes */ > +}; > + > +void > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, enum odp_crypto_ses_create_err *status); > + > +void > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, odp_crypto_session_t *handle); > + > +int odp_crypto_session_create( > + struct odp_session_params *params, > + odp_buffer_t completion_event, > + odp_queue_t completion_queue); > +@endcode > +@subsection crypto_operation Crypto Operation > + > +Crypto operations are described by a parameter structure: > +@code > +struct odp_crypto_op_params { > + odp_crypto_session_t session; > + odp_packet_t pkt; > + odp_packet_t out_pkt; > + uint8_t *override_iv_ptr; > + unsigned hash_result_offset; > + struct odp_data_range cipher_range; > + struct odp_data_range auth_range; > +}; > +@endcode > + > +<table> > +<tr><th>Parameter</th><th>Meaning</th></tr> > +<tr><td>session</td><td>Session to perform the operation</td></tr> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be returned as the result of the operation. There are three different ways this parameter is used, depending on the mode of operation requested by the caller and the capabilities of the underlying implementation:\n\n > + > +-# If out_pkt is the same as pkt this indicates that the operation should be performed in place.\n\n > +-# If out_pkt is different from pkt this indicates that output should be placed in the buffer supplied by the caller.\n\n > +-# If out_pkt is omitted (a null/invalid value supplied on input) this indicates that an output buffer should be allocated by the operation and returned as part of the completion event associated with the operation.\n\n > + > +Note that not every implementation will support all of these modes and MAY require that one mode be used in preference to others. Any such implementation restrictions are communicated as output from session creation.</td></tr> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this request</td></tr> > +<tr><td>hash_result_offset</td><td>Offset into the output packet where the hash result should be stored.</td></tr> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data to be processed for ciphering.</td></tr> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data to be processed for authentication.</td></tr> > +</table> > + > +The crypto operation is initiated with a single call that passes the parameters for the operation and an event (for asynchronous completion). > +@code > +int odp_crypto_operation( > + struct odp_crypto_op_params *params, > + odp_buffer_t completion_event); > +@endcode > + > +Parameter | Meaning > +----------|-------- > +params | The parameter structure describing the crypto operation to be performed. > +completion_event | The event delivered on completion. It provides information about the status of the operation, result and request context. In synchronous mode the event is available upon function call return. In asynchronous mode, the event is placed on the session / operation completion queue when the operation finished. > + > +Upon return the return code indicates whether the operation was synchronous or asynchronous, or if an error occurred that prevented the operation from being performed. > + > +Get session operation : > +@code > +odp_crypto_op_t > +odp_crypto_session_get_op(odp_crypto_session_t ses); > +@endcode > + > +Get session cipher information : > +@code > +odp_cipher_alg > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > +@endcode > + > +Get session authentication information : > +@code > +odp_auth_alg > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > +@endcode > + > +Change session IV : > +@code > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); > +@emdcode > + > +Change cipher or/and hash keys: > +@code > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t *key); > +@endcode > + > +Destroy crypto session. All pending operations are cancelled. > +@code > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > +@endcode > + > +Get completion event information - algorithm error, output and context. Note that implementations MAY define their own specific error codes that have meaning in that context. For application portability it is sufficient to know whether an operation completed successfully or experienced an error of some sort. > +@code > +enum crypto_alg_err { > + ODP_CRYPTO_ALG_ERR_NONE, > + ODP_CRYPTO_ALG_ERR_MODE, > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > +}; > + > +enum crypto_hw_err { > + ODP_CRYPTO_HW_ERR_NONE, > + ODP_CRYPTO_HW_ERR_DMA, > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > +}; > + > +struct odp_crypto_compl_status { > + odp_crypto_alg_t alg; > + enum crypto_alg_err alg_err; > + enum crypto_hw_err hw_err; > +}; > + > +void > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > + struct odp_crypto_compl_status *auth, > + struct odp_crypto_compl_status *cipher); > +@endcode > + > +Returns the output packet handle associated with the completion event : > +@code > +odp_packet_t > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > +@endcode > + > +Sets a context handle to be returned with the completion event : > +@code > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, odp_compl_ctx_t *ctx); > +@endcode > + > +Returns the context associated with the completion event : > +@code > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); > +@endcode > + > +This section describes the API/Interface being defined at a functional level in technical detail. Sub-sections include header file names, where implementation files are expected to reside in the ODP git tree, as well as the name, parameters, abstract data types, functionality, return codes, and exception conditions of each function call defined by the API/Interface. Appropriate diagrams, tables, etc. should be used to allow the programmer tasked with implementing the API/Interface to understand the function to be implemented as well as error conditions, corner cases, performance requirements, etc. needed to implement the described API/Interface in a functionally correct and efficient manner. > + > +@subsubsection random_number_functions Random Number Functions > +As noted earlier, random number support consists of two functions: > +@code > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); > + > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > +@endcode > + > +The difference is that the first provides access to hardware random number functions that return true random data. This is typically used for seed values. The second provides a deterministic random bit generator conforming to NIST standards and is used by various crypto protocols and algorithms. The use_entropy parameter on odp_hw_random_get is used to disable any hardware pre-processing normally provided by the function and is mainly intended to be used for testing/validation purposes. > + > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > +To support zeroization a buffer may be allocated with an ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to odp_buffer_pool_create() that specifies that all buffers allocated from this pool must be zeroized upon free. Essentially, the buffer security attribute is set by default from the attributes of the buffer pool that it is allocated from. > + > +@subsubsection capability_inquiry Capability Inquiry > +To enable applications to determine crypto capabilities. > +@code > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > +@endcode > + > +Inquires whether the specified crypto and auth algorithms are supported. Responses include: > +- ODP_HW_SYNC_SUPPORT > +- ODP_HW_ASYNC_SUPPORT > +- ODP_SW_SYNC_SUPPORT > +- ODP_SW_ASYNC_SUPPORT > +- ODP_NO_SUPPORT > + > +HW support means the combination is supported in hardware, SW support means the combination is supported in software by the implementation. No support means the combination is not supported by the implementation. The SYNC and ASYNC return options can help the application decide how to invoke these functions, or it can just check whether or not the response is ODP_NO_SUPPORT. > + > +@section implementation_considerations Implementation Considerations > +One of the main purposes for the ODP crypto APIs is to provide portable access across different SoCs whose hardware crypto capabilities largely overlap but vary in terms of their implementation details. As a result, implementations need not provide software fill-ins for specific cryptographic features that are not available as hardware features on that platform. Presumably applications needing specific features will select platforms on which these features are present. Therefore, while all APIs specified here MUST exist in each conforming ODP implementation, it is acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response to calls requesting crypto features not present on that platform. > + > +For example, the linux-generic ODP implementation may only implement the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not present error code for any other cipher. This indication will also be returned on that platform in response to odp_crypto_inquire calls for non-null cipher algorithms. > + > +@section verification Verification/Testing > +This section describes the verification/test cases needed to ensure that the defined functionality is implemented correctly and performs adequately. This should be at a level of detail such that the programmer tasked with writing test scripts/programs to verify the implementation(s) of the defined functions can be written to ensure that all relevant functional variants and error/exception cases are properly tested. > + > +This section needs to be completed before API testing begins. > + > +*/ > \ No newline at end of file > diff --git a/images/syncmodels.png b/images/syncmodels.png > new file mode 100644 > index 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > GIT binary patch > literal 17179 > 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 > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > literal 0 > HcmV?d00001 > > -- > 1.8.3.2 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
I think it is a good point about the version in the body text, the doc text will probably be present in version 2.0 etc and we don't want to do global replaces every time. Doxygen has a version field that can appear in the footer, we should set that globally, I will take a look. Mike On 2 July 2014 19:29, Anders Roxell <anders.roxell@linaro.org> wrote: > > On 2014-07-02 12:46, Bill Fischofer wrote: > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > --- > > I have some more nit... > > > 1. Maybe fix the indentation in the code examples... > 2. Remove the extra space after comma or dot in the text.. > 3. I've said it before remove the version number (v1.0) from the text... > doesn't belong in the text... You should know what version of the > document you reading right? > > > Cheers, > Anders > > > crypto_design.dox | 455 > ++++++++++++++++++++++++++++++++++++++++++++++++++ > > images/syncmodels.png | Bin 0 -> 17179 bytes > > 2 files changed, 455 insertions(+) > > create mode 100644 crypto_design.dox > > create mode 100644 images/syncmodels.png > > > > diff --git a/crypto_design.dox b/crypto_design.dox > > new file mode 100644 > > index 0000000..1ad2ac6 > > --- /dev/null > > +++ b/crypto_design.dox > > @@ -0,0 +1,455 @@ > > +/* Copyright (c) 2043, Linaro Limited > > + * All rights reserved > > + * > > + * SPDX-License-Identifier: BSD-3-Clause > > + */ > > + > > +/** > > +@page crypto_design ODP Design - Crypto API > > +For the implimentation of the ODP crypto API please see @ref > odp_crypto.h > > + > > +@tableofcontents > > + > > +@section revision_history Revision History > > +Revision | Issue Data | Description | Author > > +---------|------------|-------------|-------- > > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, > Alexandru > > +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, > miscellaneous formatting, API comments | Bill > > +0.3 | 4/22/2014 | Added Use Case section to include results of > design discussions held during ODP team calls | Bill > > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to > resolve | Bill > > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready > for final review | Bill > > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > > + > > +@section introduction Introduction > > +This document describes the ODP v1.0 Crypto API. Cryptography is an > important part of data plane processing as many communication protocols > make use of cryptographic functions. Moreover, many SoCs incorporate > cryptographic hardware that can significantly accelerate these operations > compared to their software equivalents as well as provide validated > hardware functional correctness and security boundaries necessary for > system-level security certifications such as FIPS-140 Level 2 and above. > > +@section requirements Requirements > > +@subsection use_of_terms Use of Terms > > +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 [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > > +@subsection uses_of_cryptography Uses of Cryptography > > +Crypto functions cover a range of uses and capabilities designed to > support data security, integrity, authentication, and non-repudiation. > > +@subsubsection data_security Data Security > > +Cryptography supports data security by making use of complex > mathematical transformations that are not feasibly reversible without > possession of the secret key used to encrypt message data. > > +@subsubsection data_integrity Data Integrity > > +Cryptography supports data integrity through the use of cryptographic > checksums (also known as secure hashes) that ensure the recipient that > message data has not been altered either accidentally or maliciously while > in transit. > > +@subsubsection data_authentication Data Authentication > > +Cryptography supports data authentication through the uses of Message > Authentication Codes (MACs) that enable the recipient to verify that a > message was sent from an authorized counterparty, and hence was not forged. > > +@subsubsection data_non_repudiation Data Non-Repudiation > > +Cryptography supports data non-repudiation through the use of digital > signatures that enable a recipient or third party to verify the identity of > the sending party and prevents the sending party from later denying that > they originated a signed message. > > +@subsection scope Scope > > +ODP v1.0 crypto support is designed to provide a portable framework for > accessing SoC-specific cryptographic functions of most use to the data > plane. This is predominantly symmetric crypto operations used to support > the encryption and decryption of data at line rate using hardware > acceleration and offload. Specifically excluded in this support are public > key operations and other crypto functions mainly used in the control plane. > > +@subsection cryptographic_operations_in_the_data_plane Cryptographic > Operations in the Data Plane > > +ODP v1.0 crypto APIs cover the following areas: > > +@subsubsection ciphering Ciphering > > +Ciphering refers to mathematical transformations that use a secret key > to encipher data, transforming the original data (referred to as plaintext) > into ciphertext, thereby making it unintelligible to anyone not in > possession of the key. Similarly, ciphering is also used to decipher data, > allowing someone in possession of the correct key to transform received > ciphertext back into plaintext. Approved block ciphers are listed [here]( > http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be > supported by each ODP implementation. > > +@subsubsection hasing Hashing > > +A hash is a cryptographic digest of a message that can be used to > represent it for comparison or integrity checking. Hash functions are > designed so that any alteration of a message will alter the hash and that > it is computationally infeasible to craft a message that generates the same > hash value as another message. Secure hash functions approved for > cryptographic use are listed by NIST [here]( > http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD be > supported by each ODP implementation. > > +@subsubsection zeroization Zeroization > > +To preserve the security of data, certain transient data held in data > buffers MUST be cleared to zeros upon buffer free. Such capability is > referred to as zeroization. ODP supports zeroization as a buffer pool > attribute. > > +@subsubsection random_number_generation Random Number Generation > > +Because cryptography relies heavily on “unguessable” keys of various > sorts, random number generation (RNG) is an integral part of cryptographic > processing. Random numbers are used in key generation, initialization > vectors (IVs), various types of padding bytes, and various other uses > collectively referred to as nonces, that serve to “harden” cryptographic > processing. > > + > > +There are two types of random number support of interest. Hardware > random data, also known as entropy, that is the result of inherently random > physical processes, and deterministic random bit generation (DRBG) that is > used in certain certified cryptographic operations. Approved DRBG > algorithms are listed in [NIST SP 800-90A]( > http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify > which algorithms are available on a given implementation. As such ODP > implementations MAY use any approved DRGB algorithm but SHOULD support at > least one of them. Additionally, ODP implementations MUST NOT represent > non-approved algorithms as DRBG implementations. Validated algorithms are > listed in the [NIST DRBG Validation List]( > http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > > + > > +@subsubsection capability_inquiry Capability Inquiry > > +To enable applications to adapt to the implementation models offered > across different SoC platforms, ODP provides APIs to allow applications to > inquire about underlying crypto capabilities. A given ODP implementation > may offer crypto as hardware features, software features, or not available > on a given platform. > > +@subsection cryptographic_algorithms Cryptographic Algorithms and > Protocols > > +A cryptographic algorithm is a mathematical transform that provides one > of the cryptographic operations described above. They in turn are used as > building blocks in creating cryptographic protocols. These are complete > sets of rules for how to exchange data securely using cryptography. Both > cryptographic algorithm and protocol design are highly specialized > disciplines that involve high levels of public scrutiny and validation. As > a result, applications simply make use of approved cryptographic algorithms > and protocols. > > +@subsection cryptographic_operations Cryptographic Operations > > +Cryptographic operations may be initiated by software or directly by > hardware as part of the RX or TX packet path processing. For ODP v1.0 > software-initiated cryptographic operations are the primary use case. ODP > provides APIs for performing data ciphering, hashing, random number > generation, and capability inquiry. > > +@subsection performance_expectations Performance Expectations > > +In the data plane, the total processing budget for a packet may only be > a few hundred cycles, so function invocation overhead MUST be kept to a > minimum. This has several implications. > > + > > +-# When work is dispatched to a thread, all information needed by the > thread to process the work request SHOULD be immediately at hand. Ideally > any context or variables needed for the operation have been pre-warmed in > the cache to avoid the latency hits associated with cache misses. SoCs > having hardware schedulers generally do this pre-staging of data to > minimize such latencies, and ODP implementations are expected to exploit > such platform capabilities whenever possible.\n\n > > + > > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of > parameter passing and (depending on the implementation) SHOULD be inlined > as much as possible to avoid call overhead. One technique that has proven > useful is to allow for parameters to be passed as an explicit thread-local > static structure. Such use of “templating” means that a single function can > support a rich set of options but the caller can configure a template > matched to specific use and only vary the one or two parameters that differ > from call to call.\n\n > > + > > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception > path function processing. Kernel calls and such are acceptable only during > one-time initialization logic or certain types of unusual error recovery > operations. Often the best way to handle the latter is to pass the work to > a dedicated recovery thread (or back to the control plane) rather than > attempting to handle the condition inline. For example, a link-down > condition will trigger various recovery actions that might best be handled > in this manner. > > + > > +@subsection use_by_existing_code Use by Existing Code > > +Most applications wishing to make use of ODP represent substantial > existing investment that must be preserved. Insofar as possible, ODP > functions need to be orthogonal to existing application environments and > structures to permit easy intermixing with pre-existing code. > > +@subsection data_references Data References > > +Packet data is inherently of variable length however it is often more > efficient to organize memory into fixed-sized buffers that can be chained > together on demand to contain packets. The application SHOULD normally not > need to be aware of such lower-level segmentation and should be able to > treat a packet as a single object. Alternately, especially when dealing > with existing code, data segmentation MUST be explicitly specifiable via > scatter/gather lists. For example, data encryption or decryption may be > invoked on a list of data segments as part of a single function call. > > +@subsection chained_operations Chained Operations > > +Crypto operations such as hashing and encryption, or decryption and > verification, are very commonly used in combination. For ODP, it is > sufficient to support one cipher and one hash/authentication operation in a > single call and this combination MUST be supported to avoid the call and > dispatch overhead of separate invocations. > > +@subsection key_management Key Management and Session Data > > +Keying is an area of particular sensitivity in crypto processing since > keys are highly confidential and may be subject to legal requirements for > safeguarding within special hardware enclosures. > > + > > +A session is the security context used to represent an active set of > crypto operations that need to be applied to a flow on a packet-by-packet > basis. Generally a session is established upon detection of a flow > requiring crypto processing and retained for the life of that flow. It has > been noted that this can involve cooperative processing between the control > and data planes so several requirements stem from this: > > + > > +-# Session creation MAY need to be handled in an asynchronous manner. > This is to allow these to be created in batches by thread(s) that > specialize in this activity.\n\n > > + > > +-# Sessions MAY need to reference keying material indirectly via key > handling modules.\n\n > > + > > +-# Session creation MAY be performed by non-ODP code and communicated > to data plane routines that make use of ODP crypto functions that need to > reference the session information. > > + > > +ODP session APIs and data structures SHOULD be represented by abstract > data types that encapsulate implementation details for both platform > efficiency and to accommodate these needs. > > +Use Cases > > +For ODP v1.0 the major use cases of interest involve cryptographic > algorithm acceleration. Cryptographic protocol acceleration is reserved for > future ODP releases. > > +Buffers and Data Blocks > > +Cryptographic operations may be performed directly on data contained in > ODP packet buffers, or it may be performed on “raw” data blocks operating > entirely under application control. Note that when using raw data blocks > not managed by ODP, the application must perform any needed zeroization > using either its own or ODP-supplied buffer zeroization functions. ODP > automatic support for zeroization is limited to ODP-managed buffers. ODP > buffers allocated from buffer pools designated for crypto use will also > have whatever alignment and/or addressability attributes needed by the > implementation to support crypto API calls. > > + > > +Note: Some implementations may have difficulty dealing with application > buffer addresses, as these may be virtual addresses that are mapped > discontiguously into physical memory. For such implementations, memory > SHOULD be allocated contiguously and MAY need to be “registered” to have > proper addressability for crypto operations. This area of the design will > be updated based on experience in dealing with different crypto > implementations that have such requirements. > > +Synchronization > > +ODP operations fall into one of three categories: > > + > > +-# Inline (Synchronous): Upon return from a call the operation is > complete. Operation is thus completely synchronous to the caller. Inline > is the appropriate model when the invoked function takes relatively few > cycles or when the caller cannot feasibly progress without the results of > the invoked function.\n\n > > + > > +-# Parallel: Upon return from a call the operation has been initiated, > but is expected to complete shortly. The caller continues to execute until > it needs the result at which point it waits to complete the parallel > operation. The effect is as if the operation were inline except that the > caller was able to execute in parallel with the operation for some > application-determined period of time. Parallel is the appropriate model > when the operation being performed is relatively short (a few dozen up to > perhaps 100 or 200 cycles) and the caller can usefully accomplish other > processing on the same unit of work while the parallel operation is in > progress, but not enough to justify the overhead of a formal queued work > dispatch.\n\n > > + > > +-# Offloaded (Asynchronous): Upon return from the call the operation > has been queued for execution. A completion event will be queued back to > the scheduler when the event is completed. Offload is the appropriate model > when the invoked function will take a substantial amount of cycles > (thousands to tens of thousands) allowing the invoking thread/core to > service other work until the operation completes. For offloaded work, > completion is indicated by a completion event being posted back to an > application-designated completion queue. Upon receipt the unit of work that > initiated the offloaded operation continues processing with the results of > the call. > > + > > +The synchronization models of interest are summarized in Figure 1: > > + > > + > > + > > +Note: Because few implementations are expected to offer the Parallel > mode of operation as described above, this mode is reserved for potential > future use. For ODP v1.0 only synchronous and asynchronous crypto > operations are defined. > > +@section functional_definition Functional Definition > > +@subsection abstract_data_types Abstract data types > > +The following enumerations define various algorithms used for ciphering > and hashing. These are the basic operations applied to input data. > > + > > +A particular ODP implementation should map these values to the actual > information to be passed to the crypto engine. As such, the actual values > of these enums is implementation-defined. > > + > > +Cipher algorithm encoding specifies the algorithm and cipher mode > employed (as per security relevant RFCs - [4305]( > http://tools.ietf.org/html/rfc4305), [4868]( > http://tools.ietf.org/html/rfc4868), [4494]( > http://tools.ietf.org/html/rfc4494)). > > + > > +@code > > +enum odp_cipher_alg { > > + ODP_CIPHER_ALG_NULL, > > + ODP_CIPHER_ALG_DES, > > + ODP_CIPHER_ALG_3DES_CBC, > > + ODP_CIPHER_ALG_AES_CBC, > > + ODP_CIPHER_ALG_AES_GCM, > > + ODP_CIPHER_ALG_AES_CTR, > > + ODP_CIPHER_ALG_KASUMI, > > + ODP_CIPHER_ALG_SNOW, > > + ... > > +}; > > +@endcode > > + > > +Authorization algorithm encoding specifies the algorithm and the length > of the authorization used (as per security relevant RFCs - [4305]( > http://tools.ietf.org/html/rfc4305), [4868]( > http://tools.ietf.org/html/rfc4868), [4494]( > http://tools.ietf.org/html/rfc4494)): > > + > > +@code > > +enum odp_auth_alg { > > + ODP_AUTH_ALG_NULL, > > + ODP_AUTH_MD5_96, > > + ODP_AUTH_ALG_SHA1_96, > > + ODP_AUTH_ALG_SHA1_160 > > + ODP_AUTH_ALG_SHA2_256_128, > > + ODP_AUTH_ALG_SHA2_384_192, > > + ODP_AUTH_ALG_SHA2_512_256, > > + ODP_AUTH_ALG_AES_CMAC_96, > > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > > + ODP_AUTH_ALG_SNOW, > > + ODP_AUTH_ALG_KASUMI, > > + ... > > +}; > > + > > +typedef union odp_crypto_alg_t { > > + enum odp_cipher_alg cipher; > > + enum odp_auth_alg auth; > > +}odp_crypto_alg_t; > > +@endcode > > +@subsection parameter_structures Parameter Structures > > +@subsubsection crypto_sessions Crypto Sessions > > +The following structure describes a crypto session. All packets / raw > data buffers processed in a session share the data that defines the > session. A crypto session is defined by: > > + > > +- Operation type : encode or decode\n\n > > + > > +- Algorithms specifications, keys and , if required, initialization > vectors. When initialization vectors are not provided and they should be > provided automatically by the crypto engine.\n\n > > + > > +- The operation mode: synchronous or asynchronous. Synchronous > operation blocks the caller until an operation status and result are > available. In synchronous mode there is at most only one outstanding crypto > operation in the calling thread. In asynchronous mode, the caller starts > the crypto operation and later it may receive the status and the result > together with a request context. The operation status and result may also > be received by a different thread.\n\n > > + > > +- Operation mode parameters: For asynchronous operation a completion > event containing the status, the result and the request context is enqueued > to a completion queue. In case the queue is under the scheduler control, > the scheduler determines who will receive the completion event and when. > When the completion queue is not scheduled, the thread which is supposed to > get the operation output has to explicitly poll the completion queue. > > + > > +Note that this is an abstract data type and its structure is > implementation-specific. The layout shown here is for illustrative purposes > and the actual layout will vary from one implementation to the next to most > closely align with the structures needed by the underlying SoC platform. > Applications set and reference fields in the session structure via accessor > functions that hide the actual layout. > > + > > +@code > > +typedef enum odp_crypto_op_t { > > + ODP_CRYPTO_OP_ENCODE, > > + ODP_CRYPTO_OP_DECODE > > +}odp_crypto_op_t; > > + > > +typedef struct odp_key_t { > > +}odp_key_t; > > + > > +typedef struct odp_crypto_session_t { > > + odp_crypto_op_t op; > > + struct { > > + enum odp_cipher_alg cipher_alg; > > + odp_key_t *key; > > + uint8_t *iv; > > + size_t iv_len; > > + } cipher; > > + > > + struct { > > + enum odp_auth_alg auth_alg; > > + enum odp_auth_len auth_len; > > + odp_key_t *key; > > + } auth; > > + > > + enum odp_crypto_op_mode { > > + ODP_CRYPTO_SYNC, > > + ODP_CRYPTO_ASYNC, > > + } op_mode; > > + > > + struct { > > + uint32_t timeout; > > + struct { > > + odp_queue_t completion_queue; > > + } async; > > + } op_mode_params; > > + > > + odp_session_proc_info_t session_proc_info; > > +} odp_crxsypto_session_t; > > +@endcode > > + > > +The completion queue contained in the session structure is an in/out > parameter. If provided, then the queue specified is associated with the > session and is used to ensure order preservation on that session. If not > provided, one is created and returned to the caller. Note that this > completion queue is used to order operations performed on this crypto > session. It should not be confused with the completion queue specified on > the odp_crypto_session_create() call (see below) that is used to control > whether that call is itself processed in a synchronous vs. asynchronous > manner. > > + > > +The following structure comprises processing information. This is > logically divided in two parts: > > + > > +- Processing input info - When crypto engine provides support for > protocol processing, this information is provided in a higher level common > protocol terminology form and a particular implementation should be able to > derive everything it needs from this definition. In addition, for crypto > engines able to automate tasks like memory allocation for the output a > buffer pool id may be specified.\n\n > > + > > +- Processing output information - statistics about processed > bytes/packets. These are useful when a session expiration is based on > traffic volume. These statistics may be updated by the software or by the > hardware crypto engine. > > + > > +Again, this is an abstract type whose specific layout will vary based > on implementation considerations. Access to fields contained in the > structure is only via accessor functions. > > + > > +@code > > +typedef struct { > > + uint64_t pkts_processed; > > + uint64_t bytes_processed; > > + uint64_t pkts_errored; > > + uint64_t bytes_errored; > > + > > + odp_buffer_pool_t out_pool; > > + > > +} odp_session_proc_info_t; > > +@endcode > > + > > +This enumeration defines which operations are applied and the order. > > + > > +@code > > +enum odp_crypto_combination { > > +ODP_CRYPTO_CIPHER_ONLY, > > + ODP_CRYPTO_AUTH_ONLY, > > + ODP_CRYPTO_AUTH_CIPHERTEXT > > +}; > > +@endcode > > + > > +This structure defines a contiguous segment in the input data which > starts at offset offset and is len bytes long. > > + > > +@code > > +struct odp_data_range { > > + unsigned offset:16; > > + unsigned len:16; > > +}; > > +@endcode > > + > > +@subsection api_functions API Functions > > + > > +@subsubfunction Session Creation > > + > > +This function is used to create a crypto session. The required > parameters are : > > + > > +- Operation : encode/decode > > +- Processing info : cipher/auth/both > > +- Preferred mode : sync or async. > > +- Algorithms suites, keys and optional IV > > + > > +Session creation can be synchronous or asynchronous. Completion event > argument is used to return the status and the session handle. When > completion queue is not provided (synchronous call), the completion event > is available upon function call return. When completion queue is provided > (asynchronous call), the completion event is placed on the completion queue. > > + > > +@code > > +typedef uint64_t odp_crypto_session_t; > > + > > +struct odp_session_params { > > + enum odp_crypto_operation op; > > + odp_session_proc_info_t proc_info; > > + enum odp_crypto_op_mode pref_mode; > > + enum odp_cipher_alg cipher_alg; > > + odp_key_t *cipher_key; > > + uint8_t *iv; > > + size_t iv_len; > > + enum odp_auth_alg auth_alg; > > + odp_key_t *auth_key; > > +}; > > + > > +enum odp_crypto_ses_create_err { > > + ODP_CRYPTO_SES_CREATE_NONE, > > + ODP_CRYPTO_SES_CREATE_ENOMEM, > > + /* Session creation error codes */ > > +}; > > + > > +void > > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, > enum odp_crypto_ses_create_err *status); > > + > > +void > > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, > odp_crypto_session_t *handle); > > + > > +int odp_crypto_session_create( > > + struct odp_session_params *params, > > + odp_buffer_t completion_event, > > + odp_queue_t completion_queue); > > +@endcode > > +@subsection crypto_operation Crypto Operation > > + > > +Crypto operations are described by a parameter structure: > > +@code > > +struct odp_crypto_op_params { > > + odp_crypto_session_t session; > > + odp_packet_t pkt; > > + odp_packet_t out_pkt; > > + uint8_t *override_iv_ptr; > > + unsigned hash_result_offset; > > + struct odp_data_range cipher_range; > > + struct odp_data_range auth_range; > > +}; > > +@endcode > > + > > +<table> > > +<tr><th>Parameter</th><th>Meaning</th></tr> > > +<tr><td>session</td><td>Session to perform the operation</td></tr> > > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be > returned as the result of the operation. There are three different ways > this parameter is used, depending on the mode of operation requested by the > caller and the capabilities of the underlying implementation:\n\n > > + > > +-# If out_pkt is the same as pkt this indicates that the operation > should be performed in place.\n\n > > +-# If out_pkt is different from pkt this indicates that output should > be placed in the buffer supplied by the caller.\n\n > > +-# If out_pkt is omitted (a null/invalid value supplied on input) this > indicates that an output buffer should be allocated by the operation and > returned as part of the completion event associated with the operation.\n\n > > + > > +Note that not every implementation will support all of these modes and > MAY require that one mode be used in preference to others. Any such > implementation restrictions are communicated as output from session > creation.</td></tr> > > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this > request</td></tr> > > +<tr><td>hash_result_offset</td><td>Offset into the output packet where > the hash result should be stored.</td></tr> > > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data > to be processed for ciphering.</td></tr> > > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data > to be processed for authentication.</td></tr> > > +</table> > > + > > +The crypto operation is initiated with a single call that passes the > parameters for the operation and an event (for asynchronous completion). > > +@code > > +int odp_crypto_operation( > > + struct odp_crypto_op_params *params, > > + odp_buffer_t completion_event); > > +@endcode > > + > > +Parameter | Meaning > > +----------|-------- > > +params | The parameter structure describing the crypto operation to > be performed. > > +completion_event | The event delivered on completion. It provides > information about the status of the operation, result and request context. > In synchronous mode the event is available upon function call return. In > asynchronous mode, the event is placed on the session / operation > completion queue when the operation finished. > > + > > +Upon return the return code indicates whether the operation was > synchronous or asynchronous, or if an error occurred that prevented the > operation from being performed. > > + > > +Get session operation : > > +@code > > +odp_crypto_op_t > > +odp_crypto_session_get_op(odp_crypto_session_t ses); > > +@endcode > > + > > +Get session cipher information : > > +@code > > +odp_cipher_alg > > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > > +@endcode > > + > > +Get session authentication information : > > +@code > > +odp_auth_alg > > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > > +@endcode > > + > > +Change session IV : > > +@code > > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); > > +@emdcode > > + > > +Change cipher or/and hash keys: > > +@code > > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t > *key); > > +@endcode > > + > > +Destroy crypto session. All pending operations are cancelled. > > +@code > > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > > +@endcode > > + > > +Get completion event information - algorithm error, output and context. > Note that implementations MAY define their own specific error codes that > have meaning in that context. For application portability it is sufficient > to know whether an operation completed successfully or experienced an error > of some sort. > > +@code > > +enum crypto_alg_err { > > + ODP_CRYPTO_ALG_ERR_NONE, > > + ODP_CRYPTO_ALG_ERR_MODE, > > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > > +}; > > + > > +enum crypto_hw_err { > > + ODP_CRYPTO_HW_ERR_NONE, > > + ODP_CRYPTO_HW_ERR_DMA, > > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > > +}; > > + > > +struct odp_crypto_compl_status { > > + odp_crypto_alg_t alg; > > + enum crypto_alg_err alg_err; > > + enum crypto_hw_err hw_err; > > +}; > > + > > +void > > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > > + struct odp_crypto_compl_status *auth, > > + struct odp_crypto_compl_status *cipher); > > +@endcode > > + > > +Returns the output packet handle associated with the completion event : > > +@code > > +odp_packet_t > > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > > +@endcode > > + > > +Sets a context handle to be returned with the completion event : > > +@code > > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, > odp_compl_ctx_t *ctx); > > +@endcode > > + > > +Returns the context associated with the completion event : > > +@code > > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); > > +@endcode > > + > > +This section describes the API/Interface being defined at a functional > level in technical detail. Sub-sections include header file names, where > implementation files are expected to reside in the ODP git tree, as well as > the name, parameters, abstract data types, functionality, return codes, and > exception conditions of each function call defined by the API/Interface. > Appropriate diagrams, tables, etc. should be used to allow the programmer > tasked with implementing the API/Interface to understand the function to be > implemented as well as error conditions, corner cases, performance > requirements, etc. needed to implement the described API/Interface in a > functionally correct and efficient manner. > > + > > +@subsubsection random_number_functions Random Number Functions > > +As noted earlier, random number support consists of two functions: > > +@code > > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); > > + > > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > > +@endcode > > + > > +The difference is that the first provides access to hardware random > number functions that return true random data. This is typically used for > seed values. The second provides a deterministic random bit generator > conforming to NIST standards and is used by various crypto protocols and > algorithms. The use_entropy parameter on odp_hw_random_get is used to > disable any hardware pre-processing normally provided by the function and > is mainly intended to be used for testing/validation purposes. > > + > > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > > +To support zeroization a buffer may be allocated with an > ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be > zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to > odp_buffer_pool_create() that specifies that all buffers allocated from > this pool must be zeroized upon free. Essentially, the buffer security > attribute is set by default from the attributes of the buffer pool that it > is allocated from. > > + > > +@subsubsection capability_inquiry Capability Inquiry > > +To enable applications to determine crypto capabilities. > > +@code > > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > > +@endcode > > + > > +Inquires whether the specified crypto and auth algorithms are > supported. Responses include: > > +- ODP_HW_SYNC_SUPPORT > > +- ODP_HW_ASYNC_SUPPORT > > +- ODP_SW_SYNC_SUPPORT > > +- ODP_SW_ASYNC_SUPPORT > > +- ODP_NO_SUPPORT > > + > > +HW support means the combination is supported in hardware, SW support > means the combination is supported in software by the implementation. No > support means the combination is not supported by the implementation. The > SYNC and ASYNC return options can help the application decide how to invoke > these functions, or it can just check whether or not the response is > ODP_NO_SUPPORT. > > + > > +@section implementation_considerations Implementation Considerations > > +One of the main purposes for the ODP crypto APIs is to provide portable > access across different SoCs whose hardware crypto capabilities largely > overlap but vary in terms of their implementation details. As a result, > implementations need not provide software fill-ins for specific > cryptographic features that are not available as hardware features on that > platform. Presumably applications needing specific features will select > platforms on which these features are present. Therefore, while all APIs > specified here MUST exist in each conforming ODP implementation, it is > acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response > to calls requesting crypto features not present on that platform. > > + > > +For example, the linux-generic ODP implementation may only implement > the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not > present error code for any other cipher. This indication will also be > returned on that platform in response to odp_crypto_inquire calls for > non-null cipher algorithms. > > + > > +@section verification Verification/Testing > > +This section describes the verification/test cases needed to ensure > that the defined functionality is implemented correctly and performs > adequately. This should be at a level of detail such that the programmer > tasked with writing test scripts/programs to verify the implementation(s) > of the defined functions can be written to ensure that all relevant > functional variants and error/exception cases are properly tested. > > + > > +This section needs to be completed before API testing begins. > > + > > +*/ > > \ No newline at end of file > > diff --git a/images/syncmodels.png b/images/syncmodels.png > > new file mode 100644 > > index > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > > GIT binary patch > > literal 17179 > > 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 > > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > > > literal 0 > > HcmV?d00001 > > > > -- > > 1.8.3.2 > > > > > > _______________________________________________ > > lng-odp mailing list > > lng-odp@lists.linaro.org > > http://lists.linaro.org/mailman/listinfo/lng-odp > > -- > Anders Roxell > anders.roxell@linaro.org > M: +46 709 71 42 85 | IRC: roxell > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
On 2014-07-02 12:46, Bill Fischofer wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > crypto_design.dox | 455 ++++++++++++++++++++++++++++++++++++++++++++++++++ > images/syncmodels.png | Bin 0 -> 17179 bytes > 2 files changed, 455 insertions(+) > create mode 100644 crypto_design.dox > create mode 100644 images/syncmodels.png > > diff --git a/crypto_design.dox b/crypto_design.dox > new file mode 100644 > index 0000000..1ad2ac6 > --- /dev/null > +++ b/crypto_design.dox > @@ -0,0 +1,455 @@ > +/* Copyright (c) 2043, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page crypto_design ODP Design - Crypto API > +For the implimentation of the ODP crypto API please see @ref odp_crypto.h > + > +@tableofcontents > + > +@section revision_history Revision History > +Revision | Issue Data | Description | Author > +---------|------------|-------------|-------- > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, Alexandru > +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, miscellaneous formatting, API comments | Bill > +0.3 | 4/22/2014 | Added Use Case section to include results of design discussions held during ODP team calls | Bill > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to resolve | Bill > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready for final review | Bill > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > + > +@section introduction Introduction > +This document describes the ODP v1.0 Crypto API. Cryptography is an important part of data plane processing as many communication protocols make use of cryptographic functions. Moreover, many SoCs incorporate cryptographic hardware that can significantly accelerate these operations compared to their software equivalents as well as provide validated hardware functional correctness and security boundaries necessary for system-level security certifications such as FIPS-140 Level 2 and above. > +@section requirements Requirements > +@subsection use_of_terms Use of Terms > +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 [RFC 2119](https://tools.ietf.org/html/rfc2119). > +@subsection uses_of_cryptography Uses of Cryptography > +Crypto functions cover a range of uses and capabilities designed to support data security, integrity, authentication, and non-repudiation. > +@subsubsection data_security Data Security > +Cryptography supports data security by making use of complex mathematical transformations that are not feasibly reversible without possession of the secret key used to encrypt message data. > +@subsubsection data_integrity Data Integrity > +Cryptography supports data integrity through the use of cryptographic checksums (also known as secure hashes) that ensure the recipient that message data has not been altered either accidentally or maliciously while in transit. > +@subsubsection data_authentication Data Authentication > +Cryptography supports data authentication through the uses of Message Authentication Codes (MACs) that enable the recipient to verify that a message was sent from an authorized counterparty, and hence was not forged. > +@subsubsection data_non_repudiation Data Non-Repudiation > +Cryptography supports data non-repudiation through the use of digital signatures that enable a recipient or third party to verify the identity of the sending party and prevents the sending party from later denying that they originated a signed message. > +@subsection scope Scope > +ODP v1.0 crypto support is designed to provide a portable framework for accessing SoC-specific cryptographic functions of most use to the data plane. This is predominantly symmetric crypto operations used to support the encryption and decryption of data at line rate using hardware acceleration and offload. Specifically excluded in this support are public key operations and other crypto functions mainly used in the control plane. > +@subsection cryptographic_operations_in_the_data_plane Cryptographic Operations in the Data Plane > +ODP v1.0 crypto APIs cover the following areas: > +@subsubsection ciphering Ciphering > +Ciphering refers to mathematical transformations that use a secret key to encipher data, transforming the original data (referred to as plaintext) into ciphertext, thereby making it unintelligible to anyone not in possession of the key. Similarly, ciphering is also used to decipher data, allowing someone in possession of the correct key to transform received ciphertext back into plaintext. Approved block ciphers are listed [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be supported by each ODP implementation. > +@subsubsection hasing Hashing > +A hash is a cryptographic digest of a message that can be used to represent it for comparison or integrity checking. Hash functions are designed so that any alteration of a message will alter the hash and that it is computationally infeasible to craft a message that generates the same hash value as another message. Secure hash functions approved for cryptographic use are listed by NIST [here](http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD be supported by each ODP implementation. > +@subsubsection zeroization Zeroization > +To preserve the security of data, certain transient data held in data buffers MUST be cleared to zeros upon buffer free. Such capability is referred to as zeroization. ODP supports zeroization as a buffer pool attribute. > +@subsubsection random_number_generation Random Number Generation > +Because cryptography relies heavily on “unguessable” keys of various sorts, random number generation (RNG) is an integral part of cryptographic processing. Random numbers are used in key generation, initialization vectors (IVs), various types of padding bytes, and various other uses collectively referred to as nonces, that serve to “harden” cryptographic processing. > + > +There are two types of random number support of interest. Hardware random data, also known as entropy, that is the result of inherently random physical processes, and deterministic random bit generation (DRBG) that is used in certain certified cryptographic operations. Approved DRBG algorithms are listed in [NIST SP 800-90A](http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify which algorithms are available on a given implementation. As such ODP implementations MAY use any approved DRGB algorithm but SHOULD support at least one of them. Additionally, ODP implementations MUST NOT represent non-approved algorithms as DRBG implementations. Validated algorithms are listed in the [NIST DRBG Validation List](http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > + > +@subsubsection capability_inquiry Capability Inquiry > +To enable applications to adapt to the implementation models offered across different SoC platforms, ODP provides APIs to allow applications to inquire about underlying crypto capabilities. A given ODP implementation may offer crypto as hardware features, software features, or not available on a given platform. > +@subsection cryptographic_algorithms Cryptographic Algorithms and Protocols > +A cryptographic algorithm is a mathematical transform that provides one of the cryptographic operations described above. They in turn are used as building blocks in creating cryptographic protocols. These are complete sets of rules for how to exchange data securely using cryptography. Both cryptographic algorithm and protocol design are highly specialized disciplines that involve high levels of public scrutiny and validation. As a result, applications simply make use of approved cryptographic algorithms and protocols. > +@subsection cryptographic_operations Cryptographic Operations > +Cryptographic operations may be initiated by software or directly by hardware as part of the RX or TX packet path processing. For ODP v1.0 software-initiated cryptographic operations are the primary use case. ODP provides APIs for performing data ciphering, hashing, random number generation, and capability inquiry. > +@subsection performance_expectations Performance Expectations > +In the data plane, the total processing budget for a packet may only be a few hundred cycles, so function invocation overhead MUST be kept to a minimum. This has several implications. > + > +-# When work is dispatched to a thread, all information needed by the thread to process the work request SHOULD be immediately at hand. Ideally any context or variables needed for the operation have been pre-warmed in the cache to avoid the latency hits associated with cache misses. SoCs having hardware schedulers generally do this pre-staging of data to minimize such latencies, and ODP implementations are expected to exploit such platform capabilities whenever possible.\n\n > + > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of parameter passing and (depending on the implementation) SHOULD be inlined as much as possible to avoid call overhead. One technique that has proven useful is to allow for parameters to be passed as an explicit thread-local static structure. Such use of “templating” means that a single function can support a rich set of options but the caller can configure a template matched to specific use and only vary the one or two parameters that differ from call to call.\n\n > + > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception path function processing. Kernel calls and such are acceptable only during one-time initialization logic or certain types of unusual error recovery operations. Often the best way to handle the latter is to pass the work to a dedicated recovery thread (or back to the control plane) rather than attempting to handle the condition inline. For example, a link-down condition will trigger various recovery actions that might best be handled in this manner. > + > +@subsection use_by_existing_code Use by Existing Code > +Most applications wishing to make use of ODP represent substantial existing investment that must be preserved. Insofar as possible, ODP functions need to be orthogonal to existing application environments and structures to permit easy intermixing with pre-existing code. > +@subsection data_references Data References > +Packet data is inherently of variable length however it is often more efficient to organize memory into fixed-sized buffers that can be chained together on demand to contain packets. The application SHOULD normally not need to be aware of such lower-level segmentation and should be able to treat a packet as a single object. Alternately, especially when dealing with existing code, data segmentation MUST be explicitly specifiable via scatter/gather lists. For example, data encryption or decryption may be invoked on a list of data segments as part of a single function call. Every time you add a full stop for a sentence, you have to press return and start typing the next sentence. This means that diffs of future changes will be per sentence. Doxygen will still concatenate this as a paragraph with no visual difference in the result. I think the above line will look like this: Packet data is inherently of variable length however it is often more efficient to organize memory into fixed-sized buffers that can be chained together on demand to contain packets. The application SHOULD normally not need to be aware of such lower-level segmentation and should be able to treat a packet as a single object. Alternately, especially when dealing with existing code, data segmentation MUST be explicitly specifiable via scatter/gather lists. For example, data encryption or decryption may be invoked on a list of data segments as part of a single function call. Cheers, Anders > +@subsection chained_operations Chained Operations > +Crypto operations such as hashing and encryption, or decryption and verification, are very commonly used in combination. For ODP, it is sufficient to support one cipher and one hash/authentication operation in a single call and this combination MUST be supported to avoid the call and dispatch overhead of separate invocations. > +@subsection key_management Key Management and Session Data > +Keying is an area of particular sensitivity in crypto processing since keys are highly confidential and may be subject to legal requirements for safeguarding within special hardware enclosures. > + > +A session is the security context used to represent an active set of crypto operations that need to be applied to a flow on a packet-by-packet basis. Generally a session is established upon detection of a flow requiring crypto processing and retained for the life of that flow. It has been noted that this can involve cooperative processing between the control and data planes so several requirements stem from this: > + > +-# Session creation MAY need to be handled in an asynchronous manner. This is to allow these to be created in batches by thread(s) that specialize in this activity.\n\n > + > +-# Sessions MAY need to reference keying material indirectly via key handling modules.\n\n > + > +-# Session creation MAY be performed by non-ODP code and communicated to data plane routines that make use of ODP crypto functions that need to reference the session information. > + > +ODP session APIs and data structures SHOULD be represented by abstract data types that encapsulate implementation details for both platform efficiency and to accommodate these needs. > +Use Cases > +For ODP v1.0 the major use cases of interest involve cryptographic algorithm acceleration. Cryptographic protocol acceleration is reserved for future ODP releases. > +Buffers and Data Blocks > +Cryptographic operations may be performed directly on data contained in ODP packet buffers, or it may be performed on “raw” data blocks operating entirely under application control. Note that when using raw data blocks not managed by ODP, the application must perform any needed zeroization using either its own or ODP-supplied buffer zeroization functions. ODP automatic support for zeroization is limited to ODP-managed buffers. ODP buffers allocated from buffer pools designated for crypto use will also have whatever alignment and/or addressability attributes needed by the implementation to support crypto API calls. > + > +Note: Some implementations may have difficulty dealing with application buffer addresses, as these may be virtual addresses that are mapped discontiguously into physical memory. For such implementations, memory SHOULD be allocated contiguously and MAY need to be “registered” to have proper addressability for crypto operations. This area of the design will be updated based on experience in dealing with different crypto implementations that have such requirements. > +Synchronization > +ODP operations fall into one of three categories: > + > +-# Inline (Synchronous): Upon return from a call the operation is complete. Operation is thus completely synchronous to the caller. Inline is the appropriate model when the invoked function takes relatively few cycles or when the caller cannot feasibly progress without the results of the invoked function.\n\n > + > +-# Parallel: Upon return from a call the operation has been initiated, but is expected to complete shortly. The caller continues to execute until it needs the result at which point it waits to complete the parallel operation. The effect is as if the operation were inline except that the caller was able to execute in parallel with the operation for some application-determined period of time. Parallel is the appropriate model when the operation being performed is relatively short (a few dozen up to perhaps 100 or 200 cycles) and the caller can usefully accomplish other processing on the same unit of work while the parallel operation is in progress, but not enough to justify the overhead of a formal queued work dispatch.\n\n > + > +-# Offloaded (Asynchronous): Upon return from the call the operation has been queued for execution. A completion event will be queued back to the scheduler when the event is completed. Offload is the appropriate model when the invoked function will take a substantial amount of cycles (thousands to tens of thousands) allowing the invoking thread/core to service other work until the operation completes. For offloaded work, completion is indicated by a completion event being posted back to an application-designated completion queue. Upon receipt the unit of work that initiated the offloaded operation continues processing with the results of the call. > + > +The synchronization models of interest are summarized in Figure 1: > + > + > + > +Note: Because few implementations are expected to offer the Parallel mode of operation as described above, this mode is reserved for potential future use. For ODP v1.0 only synchronous and asynchronous crypto operations are defined. > +@section functional_definition Functional Definition > +@subsection abstract_data_types Abstract data types > +The following enumerations define various algorithms used for ciphering and hashing. These are the basic operations applied to input data. > + > +A particular ODP implementation should map these values to the actual information to be passed to the crypto engine. As such, the actual values of these enums is implementation-defined. > + > +Cipher algorithm encoding specifies the algorithm and cipher mode employed (as per security relevant RFCs - [4305](http://tools.ietf.org/html/rfc4305), [4868](http://tools.ietf.org/html/rfc4868), [4494](http://tools.ietf.org/html/rfc4494)). > + > +@code > +enum odp_cipher_alg { > + ODP_CIPHER_ALG_NULL, > + ODP_CIPHER_ALG_DES, > + ODP_CIPHER_ALG_3DES_CBC, > + ODP_CIPHER_ALG_AES_CBC, > + ODP_CIPHER_ALG_AES_GCM, > + ODP_CIPHER_ALG_AES_CTR, > + ODP_CIPHER_ALG_KASUMI, > + ODP_CIPHER_ALG_SNOW, > + ... > +}; > +@endcode > + > +Authorization algorithm encoding specifies the algorithm and the length of the authorization used (as per security relevant RFCs - [4305](http://tools.ietf.org/html/rfc4305), [4868](http://tools.ietf.org/html/rfc4868), [4494](http://tools.ietf.org/html/rfc4494)): > + > +@code > +enum odp_auth_alg { > + ODP_AUTH_ALG_NULL, > + ODP_AUTH_MD5_96, > + ODP_AUTH_ALG_SHA1_96, > + ODP_AUTH_ALG_SHA1_160 > + ODP_AUTH_ALG_SHA2_256_128, > + ODP_AUTH_ALG_SHA2_384_192, > + ODP_AUTH_ALG_SHA2_512_256, > + ODP_AUTH_ALG_AES_CMAC_96, > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > + ODP_AUTH_ALG_SNOW, > + ODP_AUTH_ALG_KASUMI, > + ... > +}; > + > +typedef union odp_crypto_alg_t { > + enum odp_cipher_alg cipher; > + enum odp_auth_alg auth; > +}odp_crypto_alg_t; > +@endcode > +@subsection parameter_structures Parameter Structures > +@subsubsection crypto_sessions Crypto Sessions > +The following structure describes a crypto session. All packets / raw data buffers processed in a session share the data that defines the session. A crypto session is defined by: > + > +- Operation type : encode or decode\n\n > + > +- Algorithms specifications, keys and , if required, initialization vectors. When initialization vectors are not provided and they should be provided automatically by the crypto engine.\n\n > + > +- The operation mode: synchronous or asynchronous. Synchronous operation blocks the caller until an operation status and result are available. In synchronous mode there is at most only one outstanding crypto operation in the calling thread. In asynchronous mode, the caller starts the crypto operation and later it may receive the status and the result together with a request context. The operation status and result may also be received by a different thread.\n\n > + > +- Operation mode parameters: For asynchronous operation a completion event containing the status, the result and the request context is enqueued to a completion queue. In case the queue is under the scheduler control, the scheduler determines who will receive the completion event and when. When the completion queue is not scheduled, the thread which is supposed to get the operation output has to explicitly poll the completion queue. > + > +Note that this is an abstract data type and its structure is implementation-specific. The layout shown here is for illustrative purposes and the actual layout will vary from one implementation to the next to most closely align with the structures needed by the underlying SoC platform. Applications set and reference fields in the session structure via accessor functions that hide the actual layout. > + > +@code > +typedef enum odp_crypto_op_t { > + ODP_CRYPTO_OP_ENCODE, > + ODP_CRYPTO_OP_DECODE > +}odp_crypto_op_t; > + > +typedef struct odp_key_t { > +}odp_key_t; > + > +typedef struct odp_crypto_session_t { > + odp_crypto_op_t op; > + struct { > + enum odp_cipher_alg cipher_alg; > + odp_key_t *key; > + uint8_t *iv; > + size_t iv_len; > + } cipher; > + > + struct { > + enum odp_auth_alg auth_alg; > + enum odp_auth_len auth_len; > + odp_key_t *key; > + } auth; > + > + enum odp_crypto_op_mode { > + ODP_CRYPTO_SYNC, > + ODP_CRYPTO_ASYNC, > + } op_mode; > + > + struct { > + uint32_t timeout; > + struct { > + odp_queue_t completion_queue; > + } async; > + } op_mode_params; > + > + odp_session_proc_info_t session_proc_info; > +} odp_crxsypto_session_t; > +@endcode > + > +The completion queue contained in the session structure is an in/out parameter. If provided, then the queue specified is associated with the session and is used to ensure order preservation on that session. If not provided, one is created and returned to the caller. Note that this completion queue is used to order operations performed on this crypto session. It should not be confused with the completion queue specified on the odp_crypto_session_create() call (see below) that is used to control whether that call is itself processed in a synchronous vs. asynchronous manner. > + > +The following structure comprises processing information. This is logically divided in two parts: > + > +- Processing input info - When crypto engine provides support for protocol processing, this information is provided in a higher level common protocol terminology form and a particular implementation should be able to derive everything it needs from this definition. In addition, for crypto engines able to automate tasks like memory allocation for the output a buffer pool id may be specified.\n\n > + > +- Processing output information - statistics about processed bytes/packets. These are useful when a session expiration is based on traffic volume. These statistics may be updated by the software or by the hardware crypto engine. > + > +Again, this is an abstract type whose specific layout will vary based on implementation considerations. Access to fields contained in the structure is only via accessor functions. > + > +@code > +typedef struct { > + uint64_t pkts_processed; > + uint64_t bytes_processed; > + uint64_t pkts_errored; > + uint64_t bytes_errored; > + > + odp_buffer_pool_t out_pool; > + > +} odp_session_proc_info_t; > +@endcode > + > +This enumeration defines which operations are applied and the order. > + > +@code > +enum odp_crypto_combination { > +ODP_CRYPTO_CIPHER_ONLY, > + ODP_CRYPTO_AUTH_ONLY, > + ODP_CRYPTO_AUTH_CIPHERTEXT > +}; > +@endcode > + > +This structure defines a contiguous segment in the input data which starts at offset offset and is len bytes long. > + > +@code > +struct odp_data_range { > + unsigned offset:16; > + unsigned len:16; > +}; > +@endcode > + > +@subsection api_functions API Functions > + > +@subsubfunction Session Creation > + > +This function is used to create a crypto session. The required parameters are : > + > +- Operation : encode/decode > +- Processing info : cipher/auth/both > +- Preferred mode : sync or async. > +- Algorithms suites, keys and optional IV > + > +Session creation can be synchronous or asynchronous. Completion event argument is used to return the status and the session handle. When completion queue is not provided (synchronous call), the completion event is available upon function call return. When completion queue is provided (asynchronous call), the completion event is placed on the completion queue. > + > +@code > +typedef uint64_t odp_crypto_session_t; > + > +struct odp_session_params { > + enum odp_crypto_operation op; > + odp_session_proc_info_t proc_info; > + enum odp_crypto_op_mode pref_mode; > + enum odp_cipher_alg cipher_alg; > + odp_key_t *cipher_key; > + uint8_t *iv; > + size_t iv_len; > + enum odp_auth_alg auth_alg; > + odp_key_t *auth_key; > +}; > + > +enum odp_crypto_ses_create_err { > + ODP_CRYPTO_SES_CREATE_NONE, > + ODP_CRYPTO_SES_CREATE_ENOMEM, > + /* Session creation error codes */ > +}; > + > +void > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, enum odp_crypto_ses_create_err *status); > + > +void > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, odp_crypto_session_t *handle); > + > +int odp_crypto_session_create( > + struct odp_session_params *params, > + odp_buffer_t completion_event, > + odp_queue_t completion_queue); > +@endcode > +@subsection crypto_operation Crypto Operation > + > +Crypto operations are described by a parameter structure: > +@code > +struct odp_crypto_op_params { > + odp_crypto_session_t session; > + odp_packet_t pkt; > + odp_packet_t out_pkt; > + uint8_t *override_iv_ptr; > + unsigned hash_result_offset; > + struct odp_data_range cipher_range; > + struct odp_data_range auth_range; > +}; > +@endcode > + > +<table> > +<tr><th>Parameter</th><th>Meaning</th></tr> > +<tr><td>session</td><td>Session to perform the operation</td></tr> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be returned as the result of the operation. There are three different ways this parameter is used, depending on the mode of operation requested by the caller and the capabilities of the underlying implementation:\n\n > + > +-# If out_pkt is the same as pkt this indicates that the operation should be performed in place.\n\n > +-# If out_pkt is different from pkt this indicates that output should be placed in the buffer supplied by the caller.\n\n > +-# If out_pkt is omitted (a null/invalid value supplied on input) this indicates that an output buffer should be allocated by the operation and returned as part of the completion event associated with the operation.\n\n > + > +Note that not every implementation will support all of these modes and MAY require that one mode be used in preference to others. Any such implementation restrictions are communicated as output from session creation.</td></tr> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this request</td></tr> > +<tr><td>hash_result_offset</td><td>Offset into the output packet where the hash result should be stored.</td></tr> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data to be processed for ciphering.</td></tr> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data to be processed for authentication.</td></tr> > +</table> > + > +The crypto operation is initiated with a single call that passes the parameters for the operation and an event (for asynchronous completion). > +@code > +int odp_crypto_operation( > + struct odp_crypto_op_params *params, > + odp_buffer_t completion_event); > +@endcode > + > +Parameter | Meaning > +----------|-------- > +params | The parameter structure describing the crypto operation to be performed. > +completion_event | The event delivered on completion. It provides information about the status of the operation, result and request context. In synchronous mode the event is available upon function call return. In asynchronous mode, the event is placed on the session / operation completion queue when the operation finished. > + > +Upon return the return code indicates whether the operation was synchronous or asynchronous, or if an error occurred that prevented the operation from being performed. > + > +Get session operation : > +@code > +odp_crypto_op_t > +odp_crypto_session_get_op(odp_crypto_session_t ses); > +@endcode > + > +Get session cipher information : > +@code > +odp_cipher_alg > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > +@endcode > + > +Get session authentication information : > +@code > +odp_auth_alg > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > +@endcode > + > +Change session IV : > +@code > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); > +@emdcode > + > +Change cipher or/and hash keys: > +@code > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t *key); > +@endcode > + > +Destroy crypto session. All pending operations are cancelled. > +@code > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > +@endcode > + > +Get completion event information - algorithm error, output and context. Note that implementations MAY define their own specific error codes that have meaning in that context. For application portability it is sufficient to know whether an operation completed successfully or experienced an error of some sort. > +@code > +enum crypto_alg_err { > + ODP_CRYPTO_ALG_ERR_NONE, > + ODP_CRYPTO_ALG_ERR_MODE, > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > +}; > + > +enum crypto_hw_err { > + ODP_CRYPTO_HW_ERR_NONE, > + ODP_CRYPTO_HW_ERR_DMA, > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > +}; > + > +struct odp_crypto_compl_status { > + odp_crypto_alg_t alg; > + enum crypto_alg_err alg_err; > + enum crypto_hw_err hw_err; > +}; > + > +void > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > + struct odp_crypto_compl_status *auth, > + struct odp_crypto_compl_status *cipher); > +@endcode > + > +Returns the output packet handle associated with the completion event : > +@code > +odp_packet_t > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > +@endcode > + > +Sets a context handle to be returned with the completion event : > +@code > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, odp_compl_ctx_t *ctx); > +@endcode > + > +Returns the context associated with the completion event : > +@code > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); > +@endcode > + > +This section describes the API/Interface being defined at a functional level in technical detail. Sub-sections include header file names, where implementation files are expected to reside in the ODP git tree, as well as the name, parameters, abstract data types, functionality, return codes, and exception conditions of each function call defined by the API/Interface. Appropriate diagrams, tables, etc. should be used to allow the programmer tasked with implementing the API/Interface to understand the function to be implemented as well as error conditions, corner cases, performance requirements, etc. needed to implement the described API/Interface in a functionally correct and efficient manner. > + > +@subsubsection random_number_functions Random Number Functions > +As noted earlier, random number support consists of two functions: > +@code > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); > + > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > +@endcode > + > +The difference is that the first provides access to hardware random number functions that return true random data. This is typically used for seed values. The second provides a deterministic random bit generator conforming to NIST standards and is used by various crypto protocols and algorithms. The use_entropy parameter on odp_hw_random_get is used to disable any hardware pre-processing normally provided by the function and is mainly intended to be used for testing/validation purposes. > + > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > +To support zeroization a buffer may be allocated with an ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to odp_buffer_pool_create() that specifies that all buffers allocated from this pool must be zeroized upon free. Essentially, the buffer security attribute is set by default from the attributes of the buffer pool that it is allocated from. > + > +@subsubsection capability_inquiry Capability Inquiry > +To enable applications to determine crypto capabilities. > +@code > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > +@endcode > + > +Inquires whether the specified crypto and auth algorithms are supported. Responses include: > +- ODP_HW_SYNC_SUPPORT > +- ODP_HW_ASYNC_SUPPORT > +- ODP_SW_SYNC_SUPPORT > +- ODP_SW_ASYNC_SUPPORT > +- ODP_NO_SUPPORT > + > +HW support means the combination is supported in hardware, SW support means the combination is supported in software by the implementation. No support means the combination is not supported by the implementation. The SYNC and ASYNC return options can help the application decide how to invoke these functions, or it can just check whether or not the response is ODP_NO_SUPPORT. > + > +@section implementation_considerations Implementation Considerations > +One of the main purposes for the ODP crypto APIs is to provide portable access across different SoCs whose hardware crypto capabilities largely overlap but vary in terms of their implementation details. As a result, implementations need not provide software fill-ins for specific cryptographic features that are not available as hardware features on that platform. Presumably applications needing specific features will select platforms on which these features are present. Therefore, while all APIs specified here MUST exist in each conforming ODP implementation, it is acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response to calls requesting crypto features not present on that platform. > + > +For example, the linux-generic ODP implementation may only implement the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not present error code for any other cipher. This indication will also be returned on that platform in response to odp_crypto_inquire calls for non-null cipher algorithms. > + > +@section verification Verification/Testing > +This section describes the verification/test cases needed to ensure that the defined functionality is implemented correctly and performs adequately. This should be at a level of detail such that the programmer tasked with writing test scripts/programs to verify the implementation(s) of the defined functions can be written to ensure that all relevant functional variants and error/exception cases are properly tested. > + > +This section needs to be completed before API testing begins. > + > +*/ > \ No newline at end of file > diff --git a/images/syncmodels.png b/images/syncmodels.png > new file mode 100644 > index 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > GIT binary patch > literal 17179 > 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 > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > literal 0 > HcmV?d00001 > > -- > 1.8.3.2 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
Git is a publication mechanism for docs, not a change control mechanism. Docs will not be 'patched'. New versions will replace old ones as they are approved. On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell <anders.roxell@linaro.org> wrote: > On 2014-07-02 12:46, Bill Fischofer wrote: > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > --- > > crypto_design.dox | 455 > ++++++++++++++++++++++++++++++++++++++++++++++++++ > > images/syncmodels.png | Bin 0 -> 17179 bytes > > 2 files changed, 455 insertions(+) > > create mode 100644 crypto_design.dox > > create mode 100644 images/syncmodels.png > > > > diff --git a/crypto_design.dox b/crypto_design.dox > > new file mode 100644 > > index 0000000..1ad2ac6 > > --- /dev/null > > +++ b/crypto_design.dox > > @@ -0,0 +1,455 @@ > > +/* Copyright (c) 2043, Linaro Limited > > + * All rights reserved > > + * > > + * SPDX-License-Identifier: BSD-3-Clause > > + */ > > + > > +/** > > +@page crypto_design ODP Design - Crypto API > > +For the implimentation of the ODP crypto API please see @ref > odp_crypto.h > > + > > +@tableofcontents > > + > > +@section revision_history Revision History > > +Revision | Issue Data | Description | Author > > +---------|------------|-------------|-------- > > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, > Alexandru > > +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, > miscellaneous formatting, API comments | Bill > > +0.3 | 4/22/2014 | Added Use Case section to include results of > design discussions held during ODP team calls | Bill > > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to > resolve | Bill > > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready > for final review | Bill > > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > > + > > +@section introduction Introduction > > +This document describes the ODP v1.0 Crypto API. Cryptography is an > important part of data plane processing as many communication protocols > make use of cryptographic functions. Moreover, many SoCs incorporate > cryptographic hardware that can significantly accelerate these operations > compared to their software equivalents as well as provide validated > hardware functional correctness and security boundaries necessary for > system-level security certifications such as FIPS-140 Level 2 and above. > > +@section requirements Requirements > > +@subsection use_of_terms Use of Terms > > +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 [RFC 2119]( > https://tools.ietf.org/html/rfc2119). > > +@subsection uses_of_cryptography Uses of Cryptography > > +Crypto functions cover a range of uses and capabilities designed to > support data security, integrity, authentication, and non-repudiation. > > +@subsubsection data_security Data Security > > +Cryptography supports data security by making use of complex > mathematical transformations that are not feasibly reversible without > possession of the secret key used to encrypt message data. > > +@subsubsection data_integrity Data Integrity > > +Cryptography supports data integrity through the use of cryptographic > checksums (also known as secure hashes) that ensure the recipient that > message data has not been altered either accidentally or maliciously while > in transit. > > +@subsubsection data_authentication Data Authentication > > +Cryptography supports data authentication through the uses of Message > Authentication Codes (MACs) that enable the recipient to verify that a > message was sent from an authorized counterparty, and hence was not forged. > > +@subsubsection data_non_repudiation Data Non-Repudiation > > +Cryptography supports data non-repudiation through the use of digital > signatures that enable a recipient or third party to verify the identity of > the sending party and prevents the sending party from later denying that > they originated a signed message. > > +@subsection scope Scope > > +ODP v1.0 crypto support is designed to provide a portable framework for > accessing SoC-specific cryptographic functions of most use to the data > plane. This is predominantly symmetric crypto operations used to support > the encryption and decryption of data at line rate using hardware > acceleration and offload. Specifically excluded in this support are public > key operations and other crypto functions mainly used in the control plane. > > +@subsection cryptographic_operations_in_the_data_plane Cryptographic > Operations in the Data Plane > > +ODP v1.0 crypto APIs cover the following areas: > > +@subsubsection ciphering Ciphering > > +Ciphering refers to mathematical transformations that use a secret key > to encipher data, transforming the original data (referred to as plaintext) > into ciphertext, thereby making it unintelligible to anyone not in > possession of the key. Similarly, ciphering is also used to decipher data, > allowing someone in possession of the correct key to transform received > ciphertext back into plaintext. Approved block ciphers are listed [here]( > http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be > supported by each ODP implementation. > > +@subsubsection hasing Hashing > > +A hash is a cryptographic digest of a message that can be used to > represent it for comparison or integrity checking. Hash functions are > designed so that any alteration of a message will alter the hash and that > it is computationally infeasible to craft a message that generates the same > hash value as another message. Secure hash functions approved for > cryptographic use are listed by NIST [here]( > http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD be > supported by each ODP implementation. > > +@subsubsection zeroization Zeroization > > +To preserve the security of data, certain transient data held in data > buffers MUST be cleared to zeros upon buffer free. Such capability is > referred to as zeroization. ODP supports zeroization as a buffer pool > attribute. > > +@subsubsection random_number_generation Random Number Generation > > +Because cryptography relies heavily on “unguessable” keys of various > sorts, random number generation (RNG) is an integral part of cryptographic > processing. Random numbers are used in key generation, initialization > vectors (IVs), various types of padding bytes, and various other uses > collectively referred to as nonces, that serve to “harden” cryptographic > processing. > > + > > +There are two types of random number support of interest. Hardware > random data, also known as entropy, that is the result of inherently random > physical processes, and deterministic random bit generation (DRBG) that is > used in certain certified cryptographic operations. Approved DRBG > algorithms are listed in [NIST SP 800-90A]( > http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify > which algorithms are available on a given implementation. As such ODP > implementations MAY use any approved DRGB algorithm but SHOULD support at > least one of them. Additionally, ODP implementations MUST NOT represent > non-approved algorithms as DRBG implementations. Validated algorithms are > listed in the [NIST DRBG Validation List]( > http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > > + > > +@subsubsection capability_inquiry Capability Inquiry > > +To enable applications to adapt to the implementation models offered > across different SoC platforms, ODP provides APIs to allow applications to > inquire about underlying crypto capabilities. A given ODP implementation > may offer crypto as hardware features, software features, or not available > on a given platform. > > +@subsection cryptographic_algorithms Cryptographic Algorithms and > Protocols > > +A cryptographic algorithm is a mathematical transform that provides one > of the cryptographic operations described above. They in turn are used as > building blocks in creating cryptographic protocols. These are complete > sets of rules for how to exchange data securely using cryptography. Both > cryptographic algorithm and protocol design are highly specialized > disciplines that involve high levels of public scrutiny and validation. As > a result, applications simply make use of approved cryptographic algorithms > and protocols. > > +@subsection cryptographic_operations Cryptographic Operations > > +Cryptographic operations may be initiated by software or directly by > hardware as part of the RX or TX packet path processing. For ODP v1.0 > software-initiated cryptographic operations are the primary use case. ODP > provides APIs for performing data ciphering, hashing, random number > generation, and capability inquiry. > > +@subsection performance_expectations Performance Expectations > > +In the data plane, the total processing budget for a packet may only be > a few hundred cycles, so function invocation overhead MUST be kept to a > minimum. This has several implications. > > + > > +-# When work is dispatched to a thread, all information needed by the > thread to process the work request SHOULD be immediately at hand. Ideally > any context or variables needed for the operation have been pre-warmed in > the cache to avoid the latency hits associated with cache misses. SoCs > having hardware schedulers generally do this pre-staging of data to > minimize such latencies, and ODP implementations are expected to exploit > such platform capabilities whenever possible.\n\n > > + > > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of > parameter passing and (depending on the implementation) SHOULD be inlined > as much as possible to avoid call overhead. One technique that has proven > useful is to allow for parameters to be passed as an explicit thread-local > static structure. Such use of “templating” means that a single function can > support a rich set of options but the caller can configure a template > matched to specific use and only vary the one or two parameters that differ > from call to call.\n\n > > + > > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception > path function processing. Kernel calls and such are acceptable only during > one-time initialization logic or certain types of unusual error recovery > operations. Often the best way to handle the latter is to pass the work to > a dedicated recovery thread (or back to the control plane) rather than > attempting to handle the condition inline. For example, a link-down > condition will trigger various recovery actions that might best be handled > in this manner. > > + > > +@subsection use_by_existing_code Use by Existing Code > > +Most applications wishing to make use of ODP represent substantial > existing investment that must be preserved. Insofar as possible, ODP > functions need to be orthogonal to existing application environments and > structures to permit easy intermixing with pre-existing code. > > +@subsection data_references Data References > > +Packet data is inherently of variable length however it is often more > efficient to organize memory into fixed-sized buffers that can be chained > together on demand to contain packets. The application SHOULD normally not > need to be aware of such lower-level segmentation and should be able to > treat a packet as a single object. Alternately, especially when dealing > with existing code, data segmentation MUST be explicitly specifiable via > scatter/gather lists. For example, data encryption or decryption may be > invoked on a list of data segments as part of a single function call. > > Every time you add a full stop for a sentence, you have to press return > and start typing the next sentence. > This means that diffs of future changes will be per sentence. > Doxygen will still concatenate this as a paragraph with no visual > difference in the result. > I think the above line will look like this: > > Packet data is inherently of variable length however it is often more > efficient to organize memory into fixed-sized buffers that can be chained > together on demand to contain packets. > The application SHOULD normally not need to be aware of such lower-level > segmentation and should be able to treat a packet as a single object. > Alternately, especially when dealing with existing code, data segmentation > MUST be explicitly specifiable via scatter/gather lists. > For example, data encryption or decryption may be invoked on a list of > data segments as part of a single function call. > > > Cheers, > Anders > > > +@subsection chained_operations Chained Operations > > +Crypto operations such as hashing and encryption, or decryption and > verification, are very commonly used in combination. For ODP, it is > sufficient to support one cipher and one hash/authentication operation in a > single call and this combination MUST be supported to avoid the call and > dispatch overhead of separate invocations. > > +@subsection key_management Key Management and Session Data > > +Keying is an area of particular sensitivity in crypto processing since > keys are highly confidential and may be subject to legal requirements for > safeguarding within special hardware enclosures. > > + > > +A session is the security context used to represent an active set of > crypto operations that need to be applied to a flow on a packet-by-packet > basis. Generally a session is established upon detection of a flow > requiring crypto processing and retained for the life of that flow. It has > been noted that this can involve cooperative processing between the control > and data planes so several requirements stem from this: > > + > > +-# Session creation MAY need to be handled in an asynchronous manner. > This is to allow these to be created in batches by thread(s) that > specialize in this activity.\n\n > > + > > +-# Sessions MAY need to reference keying material indirectly via key > handling modules.\n\n > > + > > +-# Session creation MAY be performed by non-ODP code and communicated > to data plane routines that make use of ODP crypto functions that need to > reference the session information. > > + > > +ODP session APIs and data structures SHOULD be represented by abstract > data types that encapsulate implementation details for both platform > efficiency and to accommodate these needs. > > +Use Cases > > +For ODP v1.0 the major use cases of interest involve cryptographic > algorithm acceleration. Cryptographic protocol acceleration is reserved for > future ODP releases. > > +Buffers and Data Blocks > > +Cryptographic operations may be performed directly on data contained in > ODP packet buffers, or it may be performed on “raw” data blocks operating > entirely under application control. Note that when using raw data blocks > not managed by ODP, the application must perform any needed zeroization > using either its own or ODP-supplied buffer zeroization functions. ODP > automatic support for zeroization is limited to ODP-managed buffers. ODP > buffers allocated from buffer pools designated for crypto use will also > have whatever alignment and/or addressability attributes needed by the > implementation to support crypto API calls. > > + > > +Note: Some implementations may have difficulty dealing with application > buffer addresses, as these may be virtual addresses that are mapped > discontiguously into physical memory. For such implementations, memory > SHOULD be allocated contiguously and MAY need to be “registered” to have > proper addressability for crypto operations. This area of the design will > be updated based on experience in dealing with different crypto > implementations that have such requirements. > > +Synchronization > > +ODP operations fall into one of three categories: > > + > > +-# Inline (Synchronous): Upon return from a call the operation is > complete. Operation is thus completely synchronous to the caller. Inline > is the appropriate model when the invoked function takes relatively few > cycles or when the caller cannot feasibly progress without the results of > the invoked function.\n\n > > + > > +-# Parallel: Upon return from a call the operation has been initiated, > but is expected to complete shortly. The caller continues to execute until > it needs the result at which point it waits to complete the parallel > operation. The effect is as if the operation were inline except that the > caller was able to execute in parallel with the operation for some > application-determined period of time. Parallel is the appropriate model > when the operation being performed is relatively short (a few dozen up to > perhaps 100 or 200 cycles) and the caller can usefully accomplish other > processing on the same unit of work while the parallel operation is in > progress, but not enough to justify the overhead of a formal queued work > dispatch.\n\n > > + > > +-# Offloaded (Asynchronous): Upon return from the call the operation > has been queued for execution. A completion event will be queued back to > the scheduler when the event is completed. Offload is the appropriate model > when the invoked function will take a substantial amount of cycles > (thousands to tens of thousands) allowing the invoking thread/core to > service other work until the operation completes. For offloaded work, > completion is indicated by a completion event being posted back to an > application-designated completion queue. Upon receipt the unit of work that > initiated the offloaded operation continues processing with the results of > the call. > > + > > +The synchronization models of interest are summarized in Figure 1: > > + > > + > > + > > +Note: Because few implementations are expected to offer the Parallel > mode of operation as described above, this mode is reserved for potential > future use. For ODP v1.0 only synchronous and asynchronous crypto > operations are defined. > > +@section functional_definition Functional Definition > > +@subsection abstract_data_types Abstract data types > > +The following enumerations define various algorithms used for ciphering > and hashing. These are the basic operations applied to input data. > > + > > +A particular ODP implementation should map these values to the actual > information to be passed to the crypto engine. As such, the actual values > of these enums is implementation-defined. > > + > > +Cipher algorithm encoding specifies the algorithm and cipher mode > employed (as per security relevant RFCs - [4305]( > http://tools.ietf.org/html/rfc4305), [4868]( > http://tools.ietf.org/html/rfc4868), [4494]( > http://tools.ietf.org/html/rfc4494)). > > + > > +@code > > +enum odp_cipher_alg { > > + ODP_CIPHER_ALG_NULL, > > + ODP_CIPHER_ALG_DES, > > + ODP_CIPHER_ALG_3DES_CBC, > > + ODP_CIPHER_ALG_AES_CBC, > > + ODP_CIPHER_ALG_AES_GCM, > > + ODP_CIPHER_ALG_AES_CTR, > > + ODP_CIPHER_ALG_KASUMI, > > + ODP_CIPHER_ALG_SNOW, > > + ... > > +}; > > +@endcode > > + > > +Authorization algorithm encoding specifies the algorithm and the length > of the authorization used (as per security relevant RFCs - [4305]( > http://tools.ietf.org/html/rfc4305), [4868]( > http://tools.ietf.org/html/rfc4868), [4494]( > http://tools.ietf.org/html/rfc4494)): > > + > > +@code > > +enum odp_auth_alg { > > + ODP_AUTH_ALG_NULL, > > + ODP_AUTH_MD5_96, > > + ODP_AUTH_ALG_SHA1_96, > > + ODP_AUTH_ALG_SHA1_160 > > + ODP_AUTH_ALG_SHA2_256_128, > > + ODP_AUTH_ALG_SHA2_384_192, > > + ODP_AUTH_ALG_SHA2_512_256, > > + ODP_AUTH_ALG_AES_CMAC_96, > > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > > + ODP_AUTH_ALG_SNOW, > > + ODP_AUTH_ALG_KASUMI, > > + ... > > +}; > > + > > +typedef union odp_crypto_alg_t { > > + enum odp_cipher_alg cipher; > > + enum odp_auth_alg auth; > > +}odp_crypto_alg_t; > > +@endcode > > +@subsection parameter_structures Parameter Structures > > +@subsubsection crypto_sessions Crypto Sessions > > +The following structure describes a crypto session. All packets / raw > data buffers processed in a session share the data that defines the > session. A crypto session is defined by: > > + > > +- Operation type : encode or decode\n\n > > + > > +- Algorithms specifications, keys and , if required, initialization > vectors. When initialization vectors are not provided and they should be > provided automatically by the crypto engine.\n\n > > + > > +- The operation mode: synchronous or asynchronous. Synchronous > operation blocks the caller until an operation status and result are > available. In synchronous mode there is at most only one outstanding crypto > operation in the calling thread. In asynchronous mode, the caller starts > the crypto operation and later it may receive the status and the result > together with a request context. The operation status and result may also > be received by a different thread.\n\n > > + > > +- Operation mode parameters: For asynchronous operation a completion > event containing the status, the result and the request context is enqueued > to a completion queue. In case the queue is under the scheduler control, > the scheduler determines who will receive the completion event and when. > When the completion queue is not scheduled, the thread which is supposed to > get the operation output has to explicitly poll the completion queue. > > + > > +Note that this is an abstract data type and its structure is > implementation-specific. The layout shown here is for illustrative purposes > and the actual layout will vary from one implementation to the next to most > closely align with the structures needed by the underlying SoC platform. > Applications set and reference fields in the session structure via accessor > functions that hide the actual layout. > > + > > +@code > > +typedef enum odp_crypto_op_t { > > + ODP_CRYPTO_OP_ENCODE, > > + ODP_CRYPTO_OP_DECODE > > +}odp_crypto_op_t; > > + > > +typedef struct odp_key_t { > > +}odp_key_t; > > + > > +typedef struct odp_crypto_session_t { > > + odp_crypto_op_t op; > > + struct { > > + enum odp_cipher_alg cipher_alg; > > + odp_key_t *key; > > + uint8_t *iv; > > + size_t iv_len; > > + } cipher; > > + > > + struct { > > + enum odp_auth_alg auth_alg; > > + enum odp_auth_len auth_len; > > + odp_key_t *key; > > + } auth; > > + > > + enum odp_crypto_op_mode { > > + ODP_CRYPTO_SYNC, > > + ODP_CRYPTO_ASYNC, > > + } op_mode; > > + > > + struct { > > + uint32_t timeout; > > + struct { > > + odp_queue_t completion_queue; > > + } async; > > + } op_mode_params; > > + > > + odp_session_proc_info_t session_proc_info; > > +} odp_crxsypto_session_t; > > +@endcode > > + > > +The completion queue contained in the session structure is an in/out > parameter. If provided, then the queue specified is associated with the > session and is used to ensure order preservation on that session. If not > provided, one is created and returned to the caller. Note that this > completion queue is used to order operations performed on this crypto > session. It should not be confused with the completion queue specified on > the odp_crypto_session_create() call (see below) that is used to control > whether that call is itself processed in a synchronous vs. asynchronous > manner. > > + > > +The following structure comprises processing information. This is > logically divided in two parts: > > + > > +- Processing input info - When crypto engine provides support for > protocol processing, this information is provided in a higher level common > protocol terminology form and a particular implementation should be able to > derive everything it needs from this definition. In addition, for crypto > engines able to automate tasks like memory allocation for the output a > buffer pool id may be specified.\n\n > > + > > +- Processing output information - statistics about processed > bytes/packets. These are useful when a session expiration is based on > traffic volume. These statistics may be updated by the software or by the > hardware crypto engine. > > + > > +Again, this is an abstract type whose specific layout will vary based > on implementation considerations. Access to fields contained in the > structure is only via accessor functions. > > + > > +@code > > +typedef struct { > > + uint64_t pkts_processed; > > + uint64_t bytes_processed; > > + uint64_t pkts_errored; > > + uint64_t bytes_errored; > > + > > + odp_buffer_pool_t out_pool; > > + > > +} odp_session_proc_info_t; > > +@endcode > > + > > +This enumeration defines which operations are applied and the order. > > + > > +@code > > +enum odp_crypto_combination { > > +ODP_CRYPTO_CIPHER_ONLY, > > + ODP_CRYPTO_AUTH_ONLY, > > + ODP_CRYPTO_AUTH_CIPHERTEXT > > +}; > > +@endcode > > + > > +This structure defines a contiguous segment in the input data which > starts at offset offset and is len bytes long. > > + > > +@code > > +struct odp_data_range { > > + unsigned offset:16; > > + unsigned len:16; > > +}; > > +@endcode > > + > > +@subsection api_functions API Functions > > + > > +@subsubfunction Session Creation > > + > > +This function is used to create a crypto session. The required > parameters are : > > + > > +- Operation : encode/decode > > +- Processing info : cipher/auth/both > > +- Preferred mode : sync or async. > > +- Algorithms suites, keys and optional IV > > + > > +Session creation can be synchronous or asynchronous. Completion event > argument is used to return the status and the session handle. When > completion queue is not provided (synchronous call), the completion event > is available upon function call return. When completion queue is provided > (asynchronous call), the completion event is placed on the completion queue. > > + > > +@code > > +typedef uint64_t odp_crypto_session_t; > > + > > +struct odp_session_params { > > + enum odp_crypto_operation op; > > + odp_session_proc_info_t proc_info; > > + enum odp_crypto_op_mode pref_mode; > > + enum odp_cipher_alg cipher_alg; > > + odp_key_t *cipher_key; > > + uint8_t *iv; > > + size_t iv_len; > > + enum odp_auth_alg auth_alg; > > + odp_key_t *auth_key; > > +}; > > + > > +enum odp_crypto_ses_create_err { > > + ODP_CRYPTO_SES_CREATE_NONE, > > + ODP_CRYPTO_SES_CREATE_ENOMEM, > > + /* Session creation error codes */ > > +}; > > + > > +void > > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, > enum odp_crypto_ses_create_err *status); > > + > > +void > > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, > odp_crypto_session_t *handle); > > + > > +int odp_crypto_session_create( > > + struct odp_session_params *params, > > + odp_buffer_t completion_event, > > + odp_queue_t completion_queue); > > +@endcode > > +@subsection crypto_operation Crypto Operation > > + > > +Crypto operations are described by a parameter structure: > > +@code > > +struct odp_crypto_op_params { > > + odp_crypto_session_t session; > > + odp_packet_t pkt; > > + odp_packet_t out_pkt; > > + uint8_t *override_iv_ptr; > > + unsigned hash_result_offset; > > + struct odp_data_range cipher_range; > > + struct odp_data_range auth_range; > > +}; > > +@endcode > > + > > +<table> > > +<tr><th>Parameter</th><th>Meaning</th></tr> > > +<tr><td>session</td><td>Session to perform the operation</td></tr> > > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be > returned as the result of the operation. There are three different ways > this parameter is used, depending on the mode of operation requested by the > caller and the capabilities of the underlying implementation:\n\n > > + > > +-# If out_pkt is the same as pkt this indicates that the operation > should be performed in place.\n\n > > +-# If out_pkt is different from pkt this indicates that output should > be placed in the buffer supplied by the caller.\n\n > > +-# If out_pkt is omitted (a null/invalid value supplied on input) this > indicates that an output buffer should be allocated by the operation and > returned as part of the completion event associated with the operation.\n\n > > + > > +Note that not every implementation will support all of these modes and > MAY require that one mode be used in preference to others. Any such > implementation restrictions are communicated as output from session > creation.</td></tr> > > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this > request</td></tr> > > +<tr><td>hash_result_offset</td><td>Offset into the output packet where > the hash result should be stored.</td></tr> > > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data > to be processed for ciphering.</td></tr> > > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data > to be processed for authentication.</td></tr> > > +</table> > > + > > +The crypto operation is initiated with a single call that passes the > parameters for the operation and an event (for asynchronous completion). > > +@code > > +int odp_crypto_operation( > > + struct odp_crypto_op_params *params, > > + odp_buffer_t completion_event); > > +@endcode > > + > > +Parameter | Meaning > > +----------|-------- > > +params | The parameter structure describing the crypto operation to > be performed. > > +completion_event | The event delivered on completion. It provides > information about the status of the operation, result and request context. > In synchronous mode the event is available upon function call return. In > asynchronous mode, the event is placed on the session / operation > completion queue when the operation finished. > > + > > +Upon return the return code indicates whether the operation was > synchronous or asynchronous, or if an error occurred that prevented the > operation from being performed. > > + > > +Get session operation : > > +@code > > +odp_crypto_op_t > > +odp_crypto_session_get_op(odp_crypto_session_t ses); > > +@endcode > > + > > +Get session cipher information : > > +@code > > +odp_cipher_alg > > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > > +@endcode > > + > > +Get session authentication information : > > +@code > > +odp_auth_alg > > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > > +@endcode > > + > > +Change session IV : > > +@code > > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); > > +@emdcode > > + > > +Change cipher or/and hash keys: > > +@code > > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t > *key); > > +@endcode > > + > > +Destroy crypto session. All pending operations are cancelled. > > +@code > > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > > +@endcode > > + > > +Get completion event information - algorithm error, output and context. > Note that implementations MAY define their own specific error codes that > have meaning in that context. For application portability it is sufficient > to know whether an operation completed successfully or experienced an error > of some sort. > > +@code > > +enum crypto_alg_err { > > + ODP_CRYPTO_ALG_ERR_NONE, > > + ODP_CRYPTO_ALG_ERR_MODE, > > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > > +}; > > + > > +enum crypto_hw_err { > > + ODP_CRYPTO_HW_ERR_NONE, > > + ODP_CRYPTO_HW_ERR_DMA, > > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > > +}; > > + > > +struct odp_crypto_compl_status { > > + odp_crypto_alg_t alg; > > + enum crypto_alg_err alg_err; > > + enum crypto_hw_err hw_err; > > +}; > > + > > +void > > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > > + struct odp_crypto_compl_status *auth, > > + struct odp_crypto_compl_status *cipher); > > +@endcode > > + > > +Returns the output packet handle associated with the completion event : > > +@code > > +odp_packet_t > > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > > +@endcode > > + > > +Sets a context handle to be returned with the completion event : > > +@code > > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, > odp_compl_ctx_t *ctx); > > +@endcode > > + > > +Returns the context associated with the completion event : > > +@code > > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); > > +@endcode > > + > > +This section describes the API/Interface being defined at a functional > level in technical detail. Sub-sections include header file names, where > implementation files are expected to reside in the ODP git tree, as well as > the name, parameters, abstract data types, functionality, return codes, and > exception conditions of each function call defined by the API/Interface. > Appropriate diagrams, tables, etc. should be used to allow the programmer > tasked with implementing the API/Interface to understand the function to be > implemented as well as error conditions, corner cases, performance > requirements, etc. needed to implement the described API/Interface in a > functionally correct and efficient manner. > > + > > +@subsubsection random_number_functions Random Number Functions > > +As noted earlier, random number support consists of two functions: > > +@code > > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); > > + > > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > > +@endcode > > + > > +The difference is that the first provides access to hardware random > number functions that return true random data. This is typically used for > seed values. The second provides a deterministic random bit generator > conforming to NIST standards and is used by various crypto protocols and > algorithms. The use_entropy parameter on odp_hw_random_get is used to > disable any hardware pre-processing normally provided by the function and > is mainly intended to be used for testing/validation purposes. > > + > > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > > +To support zeroization a buffer may be allocated with an > ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be > zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to > odp_buffer_pool_create() that specifies that all buffers allocated from > this pool must be zeroized upon free. Essentially, the buffer security > attribute is set by default from the attributes of the buffer pool that it > is allocated from. > > + > > +@subsubsection capability_inquiry Capability Inquiry > > +To enable applications to determine crypto capabilities. > > +@code > > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > > +@endcode > > + > > +Inquires whether the specified crypto and auth algorithms are > supported. Responses include: > > +- ODP_HW_SYNC_SUPPORT > > +- ODP_HW_ASYNC_SUPPORT > > +- ODP_SW_SYNC_SUPPORT > > +- ODP_SW_ASYNC_SUPPORT > > +- ODP_NO_SUPPORT > > + > > +HW support means the combination is supported in hardware, SW support > means the combination is supported in software by the implementation. No > support means the combination is not supported by the implementation. The > SYNC and ASYNC return options can help the application decide how to invoke > these functions, or it can just check whether or not the response is > ODP_NO_SUPPORT. > > + > > +@section implementation_considerations Implementation Considerations > > +One of the main purposes for the ODP crypto APIs is to provide portable > access across different SoCs whose hardware crypto capabilities largely > overlap but vary in terms of their implementation details. As a result, > implementations need not provide software fill-ins for specific > cryptographic features that are not available as hardware features on that > platform. Presumably applications needing specific features will select > platforms on which these features are present. Therefore, while all APIs > specified here MUST exist in each conforming ODP implementation, it is > acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response > to calls requesting crypto features not present on that platform. > > + > > +For example, the linux-generic ODP implementation may only implement > the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not > present error code for any other cipher. This indication will also be > returned on that platform in response to odp_crypto_inquire calls for > non-null cipher algorithms. > > + > > +@section verification Verification/Testing > > +This section describes the verification/test cases needed to ensure > that the defined functionality is implemented correctly and performs > adequately. This should be at a level of detail such that the programmer > tasked with writing test scripts/programs to verify the implementation(s) > of the defined functions can be written to ensure that all relevant > functional variants and error/exception cases are properly tested. > > + > > +This section needs to be completed before API testing begins. > > + > > +*/ > > \ No newline at end of file > > diff --git a/images/syncmodels.png b/images/syncmodels.png > > new file mode 100644 > > index > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > > GIT binary patch > > literal 17179 > > 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 > > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > > > literal 0 > > HcmV?d00001 > > > > -- > > 1.8.3.2 > > > > > > _______________________________________________ > > lng-odp mailing list > > lng-odp@lists.linaro.org > > http://lists.linaro.org/mailman/listinfo/lng-odp >
I am confused git is a change control mechanism, and I really hope they do get patched, how will we improve the content ? On 3 July 2014 10:03, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Git is a publication mechanism for docs, not a change control mechanism. > Docs will not be 'patched'. New versions will replace old ones as they > are approved. > > > On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell <anders.roxell@linaro.org> > wrote: > >> On 2014-07-02 12:46, Bill Fischofer wrote: >> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >> > --- >> > crypto_design.dox | 455 >> ++++++++++++++++++++++++++++++++++++++++++++++++++ >> > images/syncmodels.png | Bin 0 -> 17179 bytes >> > 2 files changed, 455 insertions(+) >> > create mode 100644 crypto_design.dox >> > create mode 100644 images/syncmodels.png >> > >> > diff --git a/crypto_design.dox b/crypto_design.dox >> > new file mode 100644 >> > index 0000000..1ad2ac6 >> > --- /dev/null >> > +++ b/crypto_design.dox >> > @@ -0,0 +1,455 @@ >> > +/* Copyright (c) 2043, Linaro Limited >> > + * All rights reserved >> > + * >> > + * SPDX-License-Identifier: BSD-3-Clause >> > + */ >> > + >> > +/** >> > +@page crypto_design ODP Design - Crypto API >> > +For the implimentation of the ODP crypto API please see @ref >> odp_crypto.h >> > + >> > +@tableofcontents >> > + >> > +@section revision_history Revision History >> > +Revision | Issue Data | Description | Author >> > +---------|------------|-------------|-------- >> > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, >> Alexandru >> > +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, >> miscellaneous formatting, API comments | Bill >> > +0.3 | 4/22/2014 | Added Use Case section to include results of >> design discussions held during ODP team calls | Bill >> > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action >> to resolve | Bill >> > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready >> for final review | Bill >> > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill >> > + >> > +@section introduction Introduction >> > +This document describes the ODP v1.0 Crypto API. Cryptography is an >> important part of data plane processing as many communication protocols >> make use of cryptographic functions. Moreover, many SoCs incorporate >> cryptographic hardware that can significantly accelerate these operations >> compared to their software equivalents as well as provide validated >> hardware functional correctness and security boundaries necessary for >> system-level security certifications such as FIPS-140 Level 2 and above. >> > +@section requirements Requirements >> > +@subsection use_of_terms Use of Terms >> > +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 [RFC 2119]( >> https://tools.ietf.org/html/rfc2119). >> > +@subsection uses_of_cryptography Uses of Cryptography >> > +Crypto functions cover a range of uses and capabilities designed to >> support data security, integrity, authentication, and non-repudiation. >> > +@subsubsection data_security Data Security >> > +Cryptography supports data security by making use of complex >> mathematical transformations that are not feasibly reversible without >> possession of the secret key used to encrypt message data. >> > +@subsubsection data_integrity Data Integrity >> > +Cryptography supports data integrity through the use of cryptographic >> checksums (also known as secure hashes) that ensure the recipient that >> message data has not been altered either accidentally or maliciously while >> in transit. >> > +@subsubsection data_authentication Data Authentication >> > +Cryptography supports data authentication through the uses of Message >> Authentication Codes (MACs) that enable the recipient to verify that a >> message was sent from an authorized counterparty, and hence was not forged. >> > +@subsubsection data_non_repudiation Data Non-Repudiation >> > +Cryptography supports data non-repudiation through the use of digital >> signatures that enable a recipient or third party to verify the identity of >> the sending party and prevents the sending party from later denying that >> they originated a signed message. >> > +@subsection scope Scope >> > +ODP v1.0 crypto support is designed to provide a portable framework >> for accessing SoC-specific cryptographic functions of most use to the data >> plane. This is predominantly symmetric crypto operations used to support >> the encryption and decryption of data at line rate using hardware >> acceleration and offload. Specifically excluded in this support are public >> key operations and other crypto functions mainly used in the control plane. >> > +@subsection cryptographic_operations_in_the_data_plane Cryptographic >> Operations in the Data Plane >> > +ODP v1.0 crypto APIs cover the following areas: >> > +@subsubsection ciphering Ciphering >> > +Ciphering refers to mathematical transformations that use a secret key >> to encipher data, transforming the original data (referred to as plaintext) >> into ciphertext, thereby making it unintelligible to anyone not in >> possession of the key. Similarly, ciphering is also used to decipher data, >> allowing someone in possession of the correct key to transform received >> ciphertext back into plaintext. Approved block ciphers are listed [here]( >> http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be >> supported by each ODP implementation. >> > +@subsubsection hasing Hashing >> > +A hash is a cryptographic digest of a message that can be used to >> represent it for comparison or integrity checking. Hash functions are >> designed so that any alteration of a message will alter the hash and that >> it is computationally infeasible to craft a message that generates the same >> hash value as another message. Secure hash functions approved for >> cryptographic use are listed by NIST [here]( >> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD >> be supported by each ODP implementation. >> > +@subsubsection zeroization Zeroization >> > +To preserve the security of data, certain transient data held in data >> buffers MUST be cleared to zeros upon buffer free. Such capability is >> referred to as zeroization. ODP supports zeroization as a buffer pool >> attribute. >> > +@subsubsection random_number_generation Random Number Generation >> > +Because cryptography relies heavily on “unguessable” keys of various >> sorts, random number generation (RNG) is an integral part of cryptographic >> processing. Random numbers are used in key generation, initialization >> vectors (IVs), various types of padding bytes, and various other uses >> collectively referred to as nonces, that serve to “harden” cryptographic >> processing. >> > + >> > +There are two types of random number support of interest. Hardware >> random data, also known as entropy, that is the result of inherently random >> physical processes, and deterministic random bit generation (DRBG) that is >> used in certain certified cryptographic operations. Approved DRBG >> algorithms are listed in [NIST SP 800-90A]( >> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify >> which algorithms are available on a given implementation. As such ODP >> implementations MAY use any approved DRGB algorithm but SHOULD support at >> least one of them. Additionally, ODP implementations MUST NOT represent >> non-approved algorithms as DRBG implementations. Validated algorithms are >> listed in the [NIST DRBG Validation List]( >> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >> > + >> > +@subsubsection capability_inquiry Capability Inquiry >> > +To enable applications to adapt to the implementation models offered >> across different SoC platforms, ODP provides APIs to allow applications to >> inquire about underlying crypto capabilities. A given ODP implementation >> may offer crypto as hardware features, software features, or not available >> on a given platform. >> > +@subsection cryptographic_algorithms Cryptographic Algorithms and >> Protocols >> > +A cryptographic algorithm is a mathematical transform that provides >> one of the cryptographic operations described above. They in turn are used >> as building blocks in creating cryptographic protocols. These are complete >> sets of rules for how to exchange data securely using cryptography. Both >> cryptographic algorithm and protocol design are highly specialized >> disciplines that involve high levels of public scrutiny and validation. As >> a result, applications simply make use of approved cryptographic algorithms >> and protocols. >> > +@subsection cryptographic_operations Cryptographic Operations >> > +Cryptographic operations may be initiated by software or directly by >> hardware as part of the RX or TX packet path processing. For ODP v1.0 >> software-initiated cryptographic operations are the primary use case. ODP >> provides APIs for performing data ciphering, hashing, random number >> generation, and capability inquiry. >> > +@subsection performance_expectations Performance Expectations >> > +In the data plane, the total processing budget for a packet may only >> be a few hundred cycles, so function invocation overhead MUST be kept to a >> minimum. This has several implications. >> > + >> > +-# When work is dispatched to a thread, all information needed by the >> thread to process the work request SHOULD be immediately at hand. Ideally >> any context or variables needed for the operation have been pre-warmed in >> the cache to avoid the latency hits associated with cache misses. SoCs >> having hardware schedulers generally do this pre-staging of data to >> minimize such latencies, and ODP implementations are expected to exploit >> such platform capabilities whenever possible.\n\n >> > + >> > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of >> parameter passing and (depending on the implementation) SHOULD be inlined >> as much as possible to avoid call overhead. One technique that has proven >> useful is to allow for parameters to be passed as an explicit thread-local >> static structure. Such use of “templating” means that a single function can >> support a rich set of options but the caller can configure a template >> matched to specific use and only vary the one or two parameters that differ >> from call to call.\n\n >> > + >> > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception >> path function processing. Kernel calls and such are acceptable only during >> one-time initialization logic or certain types of unusual error recovery >> operations. Often the best way to handle the latter is to pass the work to >> a dedicated recovery thread (or back to the control plane) rather than >> attempting to handle the condition inline. For example, a link-down >> condition will trigger various recovery actions that might best be handled >> in this manner. >> > + >> > +@subsection use_by_existing_code Use by Existing Code >> > +Most applications wishing to make use of ODP represent substantial >> existing investment that must be preserved. Insofar as possible, ODP >> functions need to be orthogonal to existing application environments and >> structures to permit easy intermixing with pre-existing code. >> > +@subsection data_references Data References >> > +Packet data is inherently of variable length however it is often more >> efficient to organize memory into fixed-sized buffers that can be chained >> together on demand to contain packets. The application SHOULD normally not >> need to be aware of such lower-level segmentation and should be able to >> treat a packet as a single object. Alternately, especially when dealing >> with existing code, data segmentation MUST be explicitly specifiable via >> scatter/gather lists. For example, data encryption or decryption may be >> invoked on a list of data segments as part of a single function call. >> >> Every time you add a full stop for a sentence, you have to press return >> and start typing the next sentence. >> This means that diffs of future changes will be per sentence. >> Doxygen will still concatenate this as a paragraph with no visual >> difference in the result. >> I think the above line will look like this: >> >> Packet data is inherently of variable length however it is often more >> efficient to organize memory into fixed-sized buffers that can be chained >> together on demand to contain packets. >> The application SHOULD normally not need to be aware of such lower-level >> segmentation and should be able to treat a packet as a single object. >> Alternately, especially when dealing with existing code, data >> segmentation MUST be explicitly specifiable via scatter/gather lists. >> For example, data encryption or decryption may be invoked on a list of >> data segments as part of a single function call. >> >> >> Cheers, >> Anders >> >> > +@subsection chained_operations Chained Operations >> > +Crypto operations such as hashing and encryption, or decryption and >> verification, are very commonly used in combination. For ODP, it is >> sufficient to support one cipher and one hash/authentication operation in a >> single call and this combination MUST be supported to avoid the call and >> dispatch overhead of separate invocations. >> > +@subsection key_management Key Management and Session Data >> > +Keying is an area of particular sensitivity in crypto processing since >> keys are highly confidential and may be subject to legal requirements for >> safeguarding within special hardware enclosures. >> > + >> > +A session is the security context used to represent an active set of >> crypto operations that need to be applied to a flow on a packet-by-packet >> basis. Generally a session is established upon detection of a flow >> requiring crypto processing and retained for the life of that flow. It has >> been noted that this can involve cooperative processing between the control >> and data planes so several requirements stem from this: >> > + >> > +-# Session creation MAY need to be handled in an asynchronous manner. >> This is to allow these to be created in batches by thread(s) that >> specialize in this activity.\n\n >> > + >> > +-# Sessions MAY need to reference keying material indirectly via key >> handling modules.\n\n >> > + >> > +-# Session creation MAY be performed by non-ODP code and communicated >> to data plane routines that make use of ODP crypto functions that need to >> reference the session information. >> > + >> > +ODP session APIs and data structures SHOULD be represented by abstract >> data types that encapsulate implementation details for both platform >> efficiency and to accommodate these needs. >> > +Use Cases >> > +For ODP v1.0 the major use cases of interest involve cryptographic >> algorithm acceleration. Cryptographic protocol acceleration is reserved for >> future ODP releases. >> > +Buffers and Data Blocks >> > +Cryptographic operations may be performed directly on data contained >> in ODP packet buffers, or it may be performed on “raw” data blocks >> operating entirely under application control. Note that when using raw data >> blocks not managed by ODP, the application must perform any needed >> zeroization using either its own or ODP-supplied buffer zeroization >> functions. ODP automatic support for zeroization is limited to ODP-managed >> buffers. ODP buffers allocated from buffer pools designated for crypto use >> will also have whatever alignment and/or addressability attributes needed >> by the implementation to support crypto API calls. >> > + >> > +Note: Some implementations may have difficulty dealing with >> application buffer addresses, as these may be virtual addresses that are >> mapped discontiguously into physical memory. For such implementations, >> memory SHOULD be allocated contiguously and MAY need to be “registered” to >> have proper addressability for crypto operations. This area of the design >> will be updated based on experience in dealing with different crypto >> implementations that have such requirements. >> > +Synchronization >> > +ODP operations fall into one of three categories: >> > + >> > +-# Inline (Synchronous): Upon return from a call the operation is >> complete. Operation is thus completely synchronous to the caller. Inline >> is the appropriate model when the invoked function takes relatively few >> cycles or when the caller cannot feasibly progress without the results of >> the invoked function.\n\n >> > + >> > +-# Parallel: Upon return from a call the operation has been initiated, >> but is expected to complete shortly. The caller continues to execute until >> it needs the result at which point it waits to complete the parallel >> operation. The effect is as if the operation were inline except that the >> caller was able to execute in parallel with the operation for some >> application-determined period of time. Parallel is the appropriate model >> when the operation being performed is relatively short (a few dozen up to >> perhaps 100 or 200 cycles) and the caller can usefully accomplish other >> processing on the same unit of work while the parallel operation is in >> progress, but not enough to justify the overhead of a formal queued work >> dispatch.\n\n >> > + >> > +-# Offloaded (Asynchronous): Upon return from the call the operation >> has been queued for execution. A completion event will be queued back to >> the scheduler when the event is completed. Offload is the appropriate model >> when the invoked function will take a substantial amount of cycles >> (thousands to tens of thousands) allowing the invoking thread/core to >> service other work until the operation completes. For offloaded work, >> completion is indicated by a completion event being posted back to an >> application-designated completion queue. Upon receipt the unit of work that >> initiated the offloaded operation continues processing with the results of >> the call. >> > + >> > +The synchronization models of interest are summarized in Figure 1: >> > + >> > + >> > + >> > +Note: Because few implementations are expected to offer the Parallel >> mode of operation as described above, this mode is reserved for potential >> future use. For ODP v1.0 only synchronous and asynchronous crypto >> operations are defined. >> > +@section functional_definition Functional Definition >> > +@subsection abstract_data_types Abstract data types >> > +The following enumerations define various algorithms used for >> ciphering and hashing. These are the basic operations applied to input data. >> > + >> > +A particular ODP implementation should map these values to the actual >> information to be passed to the crypto engine. As such, the actual values >> of these enums is implementation-defined. >> > + >> > +Cipher algorithm encoding specifies the algorithm and cipher mode >> employed (as per security relevant RFCs - [4305]( >> http://tools.ietf.org/html/rfc4305), [4868]( >> http://tools.ietf.org/html/rfc4868), [4494]( >> http://tools.ietf.org/html/rfc4494)). >> > + >> > +@code >> > +enum odp_cipher_alg { >> > + ODP_CIPHER_ALG_NULL, >> > + ODP_CIPHER_ALG_DES, >> > + ODP_CIPHER_ALG_3DES_CBC, >> > + ODP_CIPHER_ALG_AES_CBC, >> > + ODP_CIPHER_ALG_AES_GCM, >> > + ODP_CIPHER_ALG_AES_CTR, >> > + ODP_CIPHER_ALG_KASUMI, >> > + ODP_CIPHER_ALG_SNOW, >> > + ... >> > +}; >> > +@endcode >> > + >> > +Authorization algorithm encoding specifies the algorithm and the >> length of the authorization used (as per security relevant RFCs - [4305]( >> http://tools.ietf.org/html/rfc4305), [4868]( >> http://tools.ietf.org/html/rfc4868), [4494]( >> http://tools.ietf.org/html/rfc4494)): >> > + >> > +@code >> > +enum odp_auth_alg { >> > + ODP_AUTH_ALG_NULL, >> > + ODP_AUTH_MD5_96, >> > + ODP_AUTH_ALG_SHA1_96, >> > + ODP_AUTH_ALG_SHA1_160 >> > + ODP_AUTH_ALG_SHA2_256_128, >> > + ODP_AUTH_ALG_SHA2_384_192, >> > + ODP_AUTH_ALG_SHA2_512_256, >> > + ODP_AUTH_ALG_AES_CMAC_96, >> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, >> > + ODP_AUTH_ALG_SNOW, >> > + ODP_AUTH_ALG_KASUMI, >> > + ... >> > +}; >> > + >> > +typedef union odp_crypto_alg_t { >> > + enum odp_cipher_alg cipher; >> > + enum odp_auth_alg auth; >> > +}odp_crypto_alg_t; >> > +@endcode >> > +@subsection parameter_structures Parameter Structures >> > +@subsubsection crypto_sessions Crypto Sessions >> > +The following structure describes a crypto session. All packets / raw >> data buffers processed in a session share the data that defines the >> session. A crypto session is defined by: >> > + >> > +- Operation type : encode or decode\n\n >> > + >> > +- Algorithms specifications, keys and , if required, initialization >> vectors. When initialization vectors are not provided and they should be >> provided automatically by the crypto engine.\n\n >> > + >> > +- The operation mode: synchronous or asynchronous. Synchronous >> operation blocks the caller until an operation status and result are >> available. In synchronous mode there is at most only one outstanding crypto >> operation in the calling thread. In asynchronous mode, the caller starts >> the crypto operation and later it may receive the status and the result >> together with a request context. The operation status and result may also >> be received by a different thread.\n\n >> > + >> > +- Operation mode parameters: For asynchronous operation a completion >> event containing the status, the result and the request context is enqueued >> to a completion queue. In case the queue is under the scheduler control, >> the scheduler determines who will receive the completion event and when. >> When the completion queue is not scheduled, the thread which is supposed to >> get the operation output has to explicitly poll the completion queue. >> > + >> > +Note that this is an abstract data type and its structure is >> implementation-specific. The layout shown here is for illustrative purposes >> and the actual layout will vary from one implementation to the next to most >> closely align with the structures needed by the underlying SoC platform. >> Applications set and reference fields in the session structure via accessor >> functions that hide the actual layout. >> > + >> > +@code >> > +typedef enum odp_crypto_op_t { >> > + ODP_CRYPTO_OP_ENCODE, >> > + ODP_CRYPTO_OP_DECODE >> > +}odp_crypto_op_t; >> > + >> > +typedef struct odp_key_t { >> > +}odp_key_t; >> > + >> > +typedef struct odp_crypto_session_t { >> > + odp_crypto_op_t op; >> > + struct { >> > + enum odp_cipher_alg cipher_alg; >> > + odp_key_t *key; >> > + uint8_t *iv; >> > + size_t iv_len; >> > + } cipher; >> > + >> > + struct { >> > + enum odp_auth_alg auth_alg; >> > + enum odp_auth_len auth_len; >> > + odp_key_t *key; >> > + } auth; >> > + >> > + enum odp_crypto_op_mode { >> > + ODP_CRYPTO_SYNC, >> > + ODP_CRYPTO_ASYNC, >> > + } op_mode; >> > + >> > + struct { >> > + uint32_t timeout; >> > + struct { >> > + odp_queue_t completion_queue; >> > + } async; >> > + } op_mode_params; >> > + >> > + odp_session_proc_info_t session_proc_info; >> > +} odp_crxsypto_session_t; >> > +@endcode >> > + >> > +The completion queue contained in the session structure is an in/out >> parameter. If provided, then the queue specified is associated with the >> session and is used to ensure order preservation on that session. If not >> provided, one is created and returned to the caller. Note that this >> completion queue is used to order operations performed on this crypto >> session. It should not be confused with the completion queue specified on >> the odp_crypto_session_create() call (see below) that is used to control >> whether that call is itself processed in a synchronous vs. asynchronous >> manner. >> > + >> > +The following structure comprises processing information. This is >> logically divided in two parts: >> > + >> > +- Processing input info - When crypto engine provides support for >> protocol processing, this information is provided in a higher level common >> protocol terminology form and a particular implementation should be able to >> derive everything it needs from this definition. In addition, for crypto >> engines able to automate tasks like memory allocation for the output a >> buffer pool id may be specified.\n\n >> > + >> > +- Processing output information - statistics about processed >> bytes/packets. These are useful when a session expiration is based on >> traffic volume. These statistics may be updated by the software or by the >> hardware crypto engine. >> > + >> > +Again, this is an abstract type whose specific layout will vary based >> on implementation considerations. Access to fields contained in the >> structure is only via accessor functions. >> > + >> > +@code >> > +typedef struct { >> > + uint64_t pkts_processed; >> > + uint64_t bytes_processed; >> > + uint64_t pkts_errored; >> > + uint64_t bytes_errored; >> > + >> > + odp_buffer_pool_t out_pool; >> > + >> > +} odp_session_proc_info_t; >> > +@endcode >> > + >> > +This enumeration defines which operations are applied and the order. >> > + >> > +@code >> > +enum odp_crypto_combination { >> > +ODP_CRYPTO_CIPHER_ONLY, >> > + ODP_CRYPTO_AUTH_ONLY, >> > + ODP_CRYPTO_AUTH_CIPHERTEXT >> > +}; >> > +@endcode >> > + >> > +This structure defines a contiguous segment in the input data which >> starts at offset offset and is len bytes long. >> > + >> > +@code >> > +struct odp_data_range { >> > + unsigned offset:16; >> > + unsigned len:16; >> > +}; >> > +@endcode >> > + >> > +@subsection api_functions API Functions >> > + >> > +@subsubfunction Session Creation >> > + >> > +This function is used to create a crypto session. The required >> parameters are : >> > + >> > +- Operation : encode/decode >> > +- Processing info : cipher/auth/both >> > +- Preferred mode : sync or async. >> > +- Algorithms suites, keys and optional IV >> > + >> > +Session creation can be synchronous or asynchronous. Completion event >> argument is used to return the status and the session handle. When >> completion queue is not provided (synchronous call), the completion event >> is available upon function call return. When completion queue is provided >> (asynchronous call), the completion event is placed on the completion queue. >> > + >> > +@code >> > +typedef uint64_t odp_crypto_session_t; >> > + >> > +struct odp_session_params { >> > + enum odp_crypto_operation op; >> > + odp_session_proc_info_t proc_info; >> > + enum odp_crypto_op_mode pref_mode; >> > + enum odp_cipher_alg cipher_alg; >> > + odp_key_t *cipher_key; >> > + uint8_t *iv; >> > + size_t iv_len; >> > + enum odp_auth_alg auth_alg; >> > + odp_key_t *auth_key; >> > +}; >> > + >> > +enum odp_crypto_ses_create_err { >> > + ODP_CRYPTO_SES_CREATE_NONE, >> > + ODP_CRYPTO_SES_CREATE_ENOMEM, >> > + /* Session creation error codes */ >> > +}; >> > + >> > +void >> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, >> enum odp_crypto_ses_create_err *status); >> > + >> > +void >> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, >> odp_crypto_session_t *handle); >> > + >> > +int odp_crypto_session_create( >> > + struct odp_session_params *params, >> > + odp_buffer_t completion_event, >> > + odp_queue_t completion_queue); >> > +@endcode >> > +@subsection crypto_operation Crypto Operation >> > + >> > +Crypto operations are described by a parameter structure: >> > +@code >> > +struct odp_crypto_op_params { >> > + odp_crypto_session_t session; >> > + odp_packet_t pkt; >> > + odp_packet_t out_pkt; >> > + uint8_t *override_iv_ptr; >> > + unsigned hash_result_offset; >> > + struct odp_data_range cipher_range; >> > + struct odp_data_range auth_range; >> > +}; >> > +@endcode >> > + >> > +<table> >> > +<tr><th>Parameter</th><th>Meaning</th></tr> >> > +<tr><td>session</td><td>Session to perform the operation</td></tr> >> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> >> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be >> returned as the result of the operation. There are three different ways >> this parameter is used, depending on the mode of operation requested by the >> caller and the capabilities of the underlying implementation:\n\n >> > + >> > +-# If out_pkt is the same as pkt this indicates that the operation >> should be performed in place.\n\n >> > +-# If out_pkt is different from pkt this indicates that output should >> be placed in the buffer supplied by the caller.\n\n >> > +-# If out_pkt is omitted (a null/invalid value supplied on input) this >> indicates that an output buffer should be allocated by the operation and >> returned as part of the completion event associated with the operation.\n\n >> > + >> > +Note that not every implementation will support all of these modes and >> MAY require that one mode be used in preference to others. Any such >> implementation restrictions are communicated as output from session >> creation.</td></tr> >> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this >> request</td></tr> >> > +<tr><td>hash_result_offset</td><td>Offset into the output packet where >> the hash result should be stored.</td></tr> >> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the >> data to be processed for ciphering.</td></tr> >> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data >> to be processed for authentication.</td></tr> >> > +</table> >> > + >> > +The crypto operation is initiated with a single call that passes the >> parameters for the operation and an event (for asynchronous completion). >> > +@code >> > +int odp_crypto_operation( >> > + struct odp_crypto_op_params *params, >> > + odp_buffer_t completion_event); >> > +@endcode >> > + >> > +Parameter | Meaning >> > +----------|-------- >> > +params | The parameter structure describing the crypto operation to >> be performed. >> > +completion_event | The event delivered on completion. It provides >> information about the status of the operation, result and request context. >> In synchronous mode the event is available upon function call return. In >> asynchronous mode, the event is placed on the session / operation >> completion queue when the operation finished. >> > + >> > +Upon return the return code indicates whether the operation was >> synchronous or asynchronous, or if an error occurred that prevented the >> operation from being performed. >> > + >> > +Get session operation : >> > +@code >> > +odp_crypto_op_t >> > +odp_crypto_session_get_op(odp_crypto_session_t ses); >> > +@endcode >> > + >> > +Get session cipher information : >> > +@code >> > +odp_cipher_alg >> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); >> > +@endcode >> > + >> > +Get session authentication information : >> > +@code >> > +odp_auth_alg >> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >> > +@endcode >> > + >> > +Change session IV : >> > +@code >> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); >> > +@emdcode >> > + >> > +Change cipher or/and hash keys: >> > +@code >> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t >> *key); >> > +@endcode >> > + >> > +Destroy crypto session. All pending operations are cancelled. >> > +@code >> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); >> > +@endcode >> > + >> > +Get completion event information - algorithm error, output and >> context. Note that implementations MAY define their own specific error >> codes that have meaning in that context. For application portability it is >> sufficient to know whether an operation completed successfully or >> experienced an error of some sort. >> > +@code >> > +enum crypto_alg_err { >> > + ODP_CRYPTO_ALG_ERR_NONE, >> > + ODP_CRYPTO_ALG_ERR_MODE, >> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >> > +}; >> > + >> > +enum crypto_hw_err { >> > + ODP_CRYPTO_HW_ERR_NONE, >> > + ODP_CRYPTO_HW_ERR_DMA, >> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >> > +}; >> > + >> > +struct odp_crypto_compl_status { >> > + odp_crypto_alg_t alg; >> > + enum crypto_alg_err alg_err; >> > + enum crypto_hw_err hw_err; >> > +}; >> > + >> > +void >> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, >> > + struct odp_crypto_compl_status *auth, >> > + struct odp_crypto_compl_status *cipher); >> > +@endcode >> > + >> > +Returns the output packet handle associated with the completion event : >> > +@code >> > +odp_packet_t >> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >> > +@endcode >> > + >> > +Sets a context handle to be returned with the completion event : >> > +@code >> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, >> odp_compl_ctx_t *ctx); >> > +@endcode >> > + >> > +Returns the context associated with the completion event : >> > +@code >> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t >> completion_event); >> > +@endcode >> > + >> > +This section describes the API/Interface being defined at a functional >> level in technical detail. Sub-sections include header file names, where >> implementation files are expected to reside in the ODP git tree, as well as >> the name, parameters, abstract data types, functionality, return codes, and >> exception conditions of each function call defined by the API/Interface. >> Appropriate diagrams, tables, etc. should be used to allow the programmer >> tasked with implementing the API/Interface to understand the function to be >> implemented as well as error conditions, corner cases, performance >> requirements, etc. needed to implement the described API/Interface in a >> functionally correct and efficient manner. >> > + >> > +@subsubsection random_number_functions Random Number Functions >> > +As noted earlier, random number support consists of two functions: >> > +@code >> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); >> > + >> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >> > +@endcode >> > + >> > +The difference is that the first provides access to hardware random >> number functions that return true random data. This is typically used for >> seed values. The second provides a deterministic random bit generator >> conforming to NIST standards and is used by various crypto protocols and >> algorithms. The use_entropy parameter on odp_hw_random_get is used to >> disable any hardware pre-processing normally provided by the function and >> is mainly intended to be used for testing/validation purposes. >> > + >> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions >> > +To support zeroization a buffer may be allocated with an >> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be >> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to >> odp_buffer_pool_create() that specifies that all buffers allocated from >> this pool must be zeroized upon free. Essentially, the buffer security >> attribute is set by default from the attributes of the buffer pool that it >> is allocated from. >> > + >> > +@subsubsection capability_inquiry Capability Inquiry >> > +To enable applications to determine crypto capabilities. >> > +@code >> > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); >> > +@endcode >> > + >> > +Inquires whether the specified crypto and auth algorithms are >> supported. Responses include: >> > +- ODP_HW_SYNC_SUPPORT >> > +- ODP_HW_ASYNC_SUPPORT >> > +- ODP_SW_SYNC_SUPPORT >> > +- ODP_SW_ASYNC_SUPPORT >> > +- ODP_NO_SUPPORT >> > + >> > +HW support means the combination is supported in hardware, SW support >> means the combination is supported in software by the implementation. No >> support means the combination is not supported by the implementation. The >> SYNC and ASYNC return options can help the application decide how to invoke >> these functions, or it can just check whether or not the response is >> ODP_NO_SUPPORT. >> > + >> > +@section implementation_considerations Implementation Considerations >> > +One of the main purposes for the ODP crypto APIs is to provide >> portable access across different SoCs whose hardware crypto capabilities >> largely overlap but vary in terms of their implementation details. As a >> result, implementations need not provide software fill-ins for specific >> cryptographic features that are not available as hardware features on that >> platform. Presumably applications needing specific features will select >> platforms on which these features are present. Therefore, while all APIs >> specified here MUST exist in each conforming ODP implementation, it is >> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response >> to calls requesting crypto features not present on that platform. >> > + >> > +For example, the linux-generic ODP implementation may only implement >> the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not >> present error code for any other cipher. This indication will also be >> returned on that platform in response to odp_crypto_inquire calls for >> non-null cipher algorithms. >> > + >> > +@section verification Verification/Testing >> > +This section describes the verification/test cases needed to ensure >> that the defined functionality is implemented correctly and performs >> adequately. This should be at a level of detail such that the programmer >> tasked with writing test scripts/programs to verify the implementation(s) >> of the defined functions can be written to ensure that all relevant >> functional variants and error/exception cases are properly tested. >> > + >> > +This section needs to be completed before API testing begins. >> > + >> > +*/ >> > \ No newline at end of file >> > diff --git a/images/syncmodels.png b/images/syncmodels.png >> > new file mode 100644 >> > index >> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >> > GIT binary patch >> > literal 17179 >> > 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 >> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b >> > >> > literal 0 >> > HcmV?d00001 >> > >> > -- >> > 1.8.3.2 >> > >> > >> > _______________________________________________ >> > lng-odp mailing list >> > lng-odp@lists.linaro.org >> > http://lists.linaro.org/mailman/listinfo/lng-odp >> > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp > >
Design documents require approval by those who aren't going to be reviewing patches. This is different from code. My understanding of the purpose of the odp-architecture repository is to provide a convenient means of distributing documentation and making it available in various forms (Doxygen, PDF) for access through the ODP web site as well as being downloaded. So in this sense we're just using Git as a publication mechanism for docs. On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > I am confused git is a change control mechanism, and I really hope they do > get patched, how will we improve the content ? > > > On 3 July 2014 10:03, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >> Git is a publication mechanism for docs, not a change control mechanism. >> Docs will not be 'patched'. New versions will replace old ones as they >> are approved. >> >> >> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell <anders.roxell@linaro.org> >> wrote: >> >>> On 2014-07-02 12:46, Bill Fischofer wrote: >>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >>> > --- >>> > crypto_design.dox | 455 >>> ++++++++++++++++++++++++++++++++++++++++++++++++++ >>> > images/syncmodels.png | Bin 0 -> 17179 bytes >>> > 2 files changed, 455 insertions(+) >>> > create mode 100644 crypto_design.dox >>> > create mode 100644 images/syncmodels.png >>> > >>> > diff --git a/crypto_design.dox b/crypto_design.dox >>> > new file mode 100644 >>> > index 0000000..1ad2ac6 >>> > --- /dev/null >>> > +++ b/crypto_design.dox >>> > @@ -0,0 +1,455 @@ >>> > +/* Copyright (c) 2043, Linaro Limited >>> > + * All rights reserved >>> > + * >>> > + * SPDX-License-Identifier: BSD-3-Clause >>> > + */ >>> > + >>> > +/** >>> > +@page crypto_design ODP Design - Crypto API >>> > +For the implimentation of the ODP crypto API please see @ref >>> odp_crypto.h >>> > + >>> > +@tableofcontents >>> > + >>> > +@section revision_history Revision History >>> > +Revision | Issue Data | Description | Author >>> > +---------|------------|-------------|-------- >>> > +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, >>> Alexandru >>> > +0.2 | 4/15/2014 | Completed intro, added TOC, started use >>> cases, miscellaneous formatting, API comments | Bill >>> > +0.3 | 4/22/2014 | Added Use Case section to include results of >>> design discussions held during ODP team calls | Bill >>> > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action >>> to resolve | Bill >>> > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready >>> for final review | Bill >>> > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill >>> > + >>> > +@section introduction Introduction >>> > +This document describes the ODP v1.0 Crypto API. Cryptography is an >>> important part of data plane processing as many communication protocols >>> make use of cryptographic functions. Moreover, many SoCs incorporate >>> cryptographic hardware that can significantly accelerate these operations >>> compared to their software equivalents as well as provide validated >>> hardware functional correctness and security boundaries necessary for >>> system-level security certifications such as FIPS-140 Level 2 and above. >>> > +@section requirements Requirements >>> > +@subsection use_of_terms Use of Terms >>> > +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 [RFC 2119]( >>> https://tools.ietf.org/html/rfc2119). >>> > +@subsection uses_of_cryptography Uses of Cryptography >>> > +Crypto functions cover a range of uses and capabilities designed to >>> support data security, integrity, authentication, and non-repudiation. >>> > +@subsubsection data_security Data Security >>> > +Cryptography supports data security by making use of complex >>> mathematical transformations that are not feasibly reversible without >>> possession of the secret key used to encrypt message data. >>> > +@subsubsection data_integrity Data Integrity >>> > +Cryptography supports data integrity through the use of cryptographic >>> checksums (also known as secure hashes) that ensure the recipient that >>> message data has not been altered either accidentally or maliciously while >>> in transit. >>> > +@subsubsection data_authentication Data Authentication >>> > +Cryptography supports data authentication through the uses of Message >>> Authentication Codes (MACs) that enable the recipient to verify that a >>> message was sent from an authorized counterparty, and hence was not forged. >>> > +@subsubsection data_non_repudiation Data Non-Repudiation >>> > +Cryptography supports data non-repudiation through the use of digital >>> signatures that enable a recipient or third party to verify the identity of >>> the sending party and prevents the sending party from later denying that >>> they originated a signed message. >>> > +@subsection scope Scope >>> > +ODP v1.0 crypto support is designed to provide a portable framework >>> for accessing SoC-specific cryptographic functions of most use to the data >>> plane. This is predominantly symmetric crypto operations used to support >>> the encryption and decryption of data at line rate using hardware >>> acceleration and offload. Specifically excluded in this support are public >>> key operations and other crypto functions mainly used in the control plane. >>> > +@subsection cryptographic_operations_in_the_data_plane Cryptographic >>> Operations in the Data Plane >>> > +ODP v1.0 crypto APIs cover the following areas: >>> > +@subsubsection ciphering Ciphering >>> > +Ciphering refers to mathematical transformations that use a secret >>> key to encipher data, transforming the original data (referred to as >>> plaintext) into ciphertext, thereby making it unintelligible to anyone not >>> in possession of the key. Similarly, ciphering is also used to decipher >>> data, allowing someone in possession of the correct key to transform >>> received ciphertext back into plaintext. Approved block ciphers are listed >>> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and >>> SHOULD be supported by each ODP implementation. >>> > +@subsubsection hasing Hashing >>> > +A hash is a cryptographic digest of a message that can be used to >>> represent it for comparison or integrity checking. Hash functions are >>> designed so that any alteration of a message will alter the hash and that >>> it is computationally infeasible to craft a message that generates the same >>> hash value as another message. Secure hash functions approved for >>> cryptographic use are listed by NIST [here]( >>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD >>> be supported by each ODP implementation. >>> > +@subsubsection zeroization Zeroization >>> > +To preserve the security of data, certain transient data held in data >>> buffers MUST be cleared to zeros upon buffer free. Such capability is >>> referred to as zeroization. ODP supports zeroization as a buffer pool >>> attribute. >>> > +@subsubsection random_number_generation Random Number Generation >>> > +Because cryptography relies heavily on “unguessable” keys of various >>> sorts, random number generation (RNG) is an integral part of cryptographic >>> processing. Random numbers are used in key generation, initialization >>> vectors (IVs), various types of padding bytes, and various other uses >>> collectively referred to as nonces, that serve to “harden” cryptographic >>> processing. >>> > + >>> > +There are two types of random number support of interest. Hardware >>> random data, also known as entropy, that is the result of inherently random >>> physical processes, and deterministic random bit generation (DRBG) that is >>> used in certain certified cryptographic operations. Approved DRBG >>> algorithms are listed in [NIST SP 800-90A]( >>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify >>> which algorithms are available on a given implementation. As such ODP >>> implementations MAY use any approved DRGB algorithm but SHOULD support at >>> least one of them. Additionally, ODP implementations MUST NOT represent >>> non-approved algorithms as DRBG implementations. Validated algorithms are >>> listed in the [NIST DRBG Validation List]( >>> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >>> > + >>> > +@subsubsection capability_inquiry Capability Inquiry >>> > +To enable applications to adapt to the implementation models offered >>> across different SoC platforms, ODP provides APIs to allow applications to >>> inquire about underlying crypto capabilities. A given ODP implementation >>> may offer crypto as hardware features, software features, or not available >>> on a given platform. >>> > +@subsection cryptographic_algorithms Cryptographic Algorithms and >>> Protocols >>> > +A cryptographic algorithm is a mathematical transform that provides >>> one of the cryptographic operations described above. They in turn are used >>> as building blocks in creating cryptographic protocols. These are complete >>> sets of rules for how to exchange data securely using cryptography. Both >>> cryptographic algorithm and protocol design are highly specialized >>> disciplines that involve high levels of public scrutiny and validation. As >>> a result, applications simply make use of approved cryptographic algorithms >>> and protocols. >>> > +@subsection cryptographic_operations Cryptographic Operations >>> > +Cryptographic operations may be initiated by software or directly by >>> hardware as part of the RX or TX packet path processing. For ODP v1.0 >>> software-initiated cryptographic operations are the primary use case. ODP >>> provides APIs for performing data ciphering, hashing, random number >>> generation, and capability inquiry. >>> > +@subsection performance_expectations Performance Expectations >>> > +In the data plane, the total processing budget for a packet may only >>> be a few hundred cycles, so function invocation overhead MUST be kept to a >>> minimum. This has several implications. >>> > + >>> > +-# When work is dispatched to a thread, all information needed by the >>> thread to process the work request SHOULD be immediately at hand. Ideally >>> any context or variables needed for the operation have been pre-warmed in >>> the cache to avoid the latency hits associated with cache misses. SoCs >>> having hardware schedulers generally do this pre-staging of data to >>> minimize such latencies, and ODP implementations are expected to exploit >>> such platform capabilities whenever possible.\n\n >>> > + >>> > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of >>> parameter passing and (depending on the implementation) SHOULD be inlined >>> as much as possible to avoid call overhead. One technique that has proven >>> useful is to allow for parameters to be passed as an explicit thread-local >>> static structure. Such use of “templating” means that a single function can >>> support a rich set of options but the caller can configure a template >>> matched to specific use and only vary the one or two parameters that differ >>> from call to call.\n\n >>> > + >>> > +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception >>> path function processing. Kernel calls and such are acceptable only during >>> one-time initialization logic or certain types of unusual error recovery >>> operations. Often the best way to handle the latter is to pass the work to >>> a dedicated recovery thread (or back to the control plane) rather than >>> attempting to handle the condition inline. For example, a link-down >>> condition will trigger various recovery actions that might best be handled >>> in this manner. >>> > + >>> > +@subsection use_by_existing_code Use by Existing Code >>> > +Most applications wishing to make use of ODP represent substantial >>> existing investment that must be preserved. Insofar as possible, ODP >>> functions need to be orthogonal to existing application environments and >>> structures to permit easy intermixing with pre-existing code. >>> > +@subsection data_references Data References >>> > +Packet data is inherently of variable length however it is often more >>> efficient to organize memory into fixed-sized buffers that can be chained >>> together on demand to contain packets. The application SHOULD normally not >>> need to be aware of such lower-level segmentation and should be able to >>> treat a packet as a single object. Alternately, especially when dealing >>> with existing code, data segmentation MUST be explicitly specifiable via >>> scatter/gather lists. For example, data encryption or decryption may be >>> invoked on a list of data segments as part of a single function call. >>> >>> Every time you add a full stop for a sentence, you have to press return >>> and start typing the next sentence. >>> This means that diffs of future changes will be per sentence. >>> Doxygen will still concatenate this as a paragraph with no visual >>> difference in the result. >>> I think the above line will look like this: >>> >>> Packet data is inherently of variable length however it is often more >>> efficient to organize memory into fixed-sized buffers that can be chained >>> together on demand to contain packets. >>> The application SHOULD normally not need to be aware of such lower-level >>> segmentation and should be able to treat a packet as a single object. >>> Alternately, especially when dealing with existing code, data >>> segmentation MUST be explicitly specifiable via scatter/gather lists. >>> For example, data encryption or decryption may be invoked on a list of >>> data segments as part of a single function call. >>> >>> >>> Cheers, >>> Anders >>> >>> > +@subsection chained_operations Chained Operations >>> > +Crypto operations such as hashing and encryption, or decryption and >>> verification, are very commonly used in combination. For ODP, it is >>> sufficient to support one cipher and one hash/authentication operation in a >>> single call and this combination MUST be supported to avoid the call and >>> dispatch overhead of separate invocations. >>> > +@subsection key_management Key Management and Session Data >>> > +Keying is an area of particular sensitivity in crypto processing >>> since keys are highly confidential and may be subject to legal requirements >>> for safeguarding within special hardware enclosures. >>> > + >>> > +A session is the security context used to represent an active set of >>> crypto operations that need to be applied to a flow on a packet-by-packet >>> basis. Generally a session is established upon detection of a flow >>> requiring crypto processing and retained for the life of that flow. It has >>> been noted that this can involve cooperative processing between the control >>> and data planes so several requirements stem from this: >>> > + >>> > +-# Session creation MAY need to be handled in an asynchronous manner. >>> This is to allow these to be created in batches by thread(s) that >>> specialize in this activity.\n\n >>> > + >>> > +-# Sessions MAY need to reference keying material indirectly via key >>> handling modules.\n\n >>> > + >>> > +-# Session creation MAY be performed by non-ODP code and communicated >>> to data plane routines that make use of ODP crypto functions that need to >>> reference the session information. >>> > + >>> > +ODP session APIs and data structures SHOULD be represented by >>> abstract data types that encapsulate implementation details for both >>> platform efficiency and to accommodate these needs. >>> > +Use Cases >>> > +For ODP v1.0 the major use cases of interest involve cryptographic >>> algorithm acceleration. Cryptographic protocol acceleration is reserved for >>> future ODP releases. >>> > +Buffers and Data Blocks >>> > +Cryptographic operations may be performed directly on data contained >>> in ODP packet buffers, or it may be performed on “raw” data blocks >>> operating entirely under application control. Note that when using raw data >>> blocks not managed by ODP, the application must perform any needed >>> zeroization using either its own or ODP-supplied buffer zeroization >>> functions. ODP automatic support for zeroization is limited to ODP-managed >>> buffers. ODP buffers allocated from buffer pools designated for crypto use >>> will also have whatever alignment and/or addressability attributes needed >>> by the implementation to support crypto API calls. >>> > + >>> > +Note: Some implementations may have difficulty dealing with >>> application buffer addresses, as these may be virtual addresses that are >>> mapped discontiguously into physical memory. For such implementations, >>> memory SHOULD be allocated contiguously and MAY need to be “registered” to >>> have proper addressability for crypto operations. This area of the design >>> will be updated based on experience in dealing with different crypto >>> implementations that have such requirements. >>> > +Synchronization >>> > +ODP operations fall into one of three categories: >>> > + >>> > +-# Inline (Synchronous): Upon return from a call the operation is >>> complete. Operation is thus completely synchronous to the caller. Inline >>> is the appropriate model when the invoked function takes relatively few >>> cycles or when the caller cannot feasibly progress without the results of >>> the invoked function.\n\n >>> > + >>> > +-# Parallel: Upon return from a call the operation has been >>> initiated, but is expected to complete shortly. The caller continues to >>> execute until it needs the result at which point it waits to complete the >>> parallel operation. The effect is as if the operation were inline except >>> that the caller was able to execute in parallel with the operation for some >>> application-determined period of time. Parallel is the appropriate model >>> when the operation being performed is relatively short (a few dozen up to >>> perhaps 100 or 200 cycles) and the caller can usefully accomplish other >>> processing on the same unit of work while the parallel operation is in >>> progress, but not enough to justify the overhead of a formal queued work >>> dispatch.\n\n >>> > + >>> > +-# Offloaded (Asynchronous): Upon return from the call the operation >>> has been queued for execution. A completion event will be queued back to >>> the scheduler when the event is completed. Offload is the appropriate model >>> when the invoked function will take a substantial amount of cycles >>> (thousands to tens of thousands) allowing the invoking thread/core to >>> service other work until the operation completes. For offloaded work, >>> completion is indicated by a completion event being posted back to an >>> application-designated completion queue. Upon receipt the unit of work that >>> initiated the offloaded operation continues processing with the results of >>> the call. >>> > + >>> > +The synchronization models of interest are summarized in Figure 1: >>> > + >>> > + >>> > + >>> > +Note: Because few implementations are expected to offer the Parallel >>> mode of operation as described above, this mode is reserved for potential >>> future use. For ODP v1.0 only synchronous and asynchronous crypto >>> operations are defined. >>> > +@section functional_definition Functional Definition >>> > +@subsection abstract_data_types Abstract data types >>> > +The following enumerations define various algorithms used for >>> ciphering and hashing. These are the basic operations applied to input data. >>> > + >>> > +A particular ODP implementation should map these values to the actual >>> information to be passed to the crypto engine. As such, the actual values >>> of these enums is implementation-defined. >>> > + >>> > +Cipher algorithm encoding specifies the algorithm and cipher mode >>> employed (as per security relevant RFCs - [4305]( >>> http://tools.ietf.org/html/rfc4305), [4868]( >>> http://tools.ietf.org/html/rfc4868), [4494]( >>> http://tools.ietf.org/html/rfc4494)). >>> > + >>> > +@code >>> > +enum odp_cipher_alg { >>> > + ODP_CIPHER_ALG_NULL, >>> > + ODP_CIPHER_ALG_DES, >>> > + ODP_CIPHER_ALG_3DES_CBC, >>> > + ODP_CIPHER_ALG_AES_CBC, >>> > + ODP_CIPHER_ALG_AES_GCM, >>> > + ODP_CIPHER_ALG_AES_CTR, >>> > + ODP_CIPHER_ALG_KASUMI, >>> > + ODP_CIPHER_ALG_SNOW, >>> > + ... >>> > +}; >>> > +@endcode >>> > + >>> > +Authorization algorithm encoding specifies the algorithm and the >>> length of the authorization used (as per security relevant RFCs - [4305]( >>> http://tools.ietf.org/html/rfc4305), [4868]( >>> http://tools.ietf.org/html/rfc4868), [4494]( >>> http://tools.ietf.org/html/rfc4494)): >>> > + >>> > +@code >>> > +enum odp_auth_alg { >>> > + ODP_AUTH_ALG_NULL, >>> > + ODP_AUTH_MD5_96, >>> > + ODP_AUTH_ALG_SHA1_96, >>> > + ODP_AUTH_ALG_SHA1_160 >>> > + ODP_AUTH_ALG_SHA2_256_128, >>> > + ODP_AUTH_ALG_SHA2_384_192, >>> > + ODP_AUTH_ALG_SHA2_512_256, >>> > + ODP_AUTH_ALG_AES_CMAC_96, >>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, >>> > + ODP_AUTH_ALG_SNOW, >>> > + ODP_AUTH_ALG_KASUMI, >>> > + ... >>> > +}; >>> > + >>> > +typedef union odp_crypto_alg_t { >>> > + enum odp_cipher_alg cipher; >>> > + enum odp_auth_alg auth; >>> > +}odp_crypto_alg_t; >>> > +@endcode >>> > +@subsection parameter_structures Parameter Structures >>> > +@subsubsection crypto_sessions Crypto Sessions >>> > +The following structure describes a crypto session. All packets / raw >>> data buffers processed in a session share the data that defines the >>> session. A crypto session is defined by: >>> > + >>> > +- Operation type : encode or decode\n\n >>> > + >>> > +- Algorithms specifications, keys and , if required, initialization >>> vectors. When initialization vectors are not provided and they should be >>> provided automatically by the crypto engine.\n\n >>> > + >>> > +- The operation mode: synchronous or asynchronous. Synchronous >>> operation blocks the caller until an operation status and result are >>> available. In synchronous mode there is at most only one outstanding crypto >>> operation in the calling thread. In asynchronous mode, the caller starts >>> the crypto operation and later it may receive the status and the result >>> together with a request context. The operation status and result may also >>> be received by a different thread.\n\n >>> > + >>> > +- Operation mode parameters: For asynchronous operation a completion >>> event containing the status, the result and the request context is enqueued >>> to a completion queue. In case the queue is under the scheduler control, >>> the scheduler determines who will receive the completion event and when. >>> When the completion queue is not scheduled, the thread which is supposed to >>> get the operation output has to explicitly poll the completion queue. >>> > + >>> > +Note that this is an abstract data type and its structure is >>> implementation-specific. The layout shown here is for illustrative purposes >>> and the actual layout will vary from one implementation to the next to most >>> closely align with the structures needed by the underlying SoC platform. >>> Applications set and reference fields in the session structure via accessor >>> functions that hide the actual layout. >>> > + >>> > +@code >>> > +typedef enum odp_crypto_op_t { >>> > + ODP_CRYPTO_OP_ENCODE, >>> > + ODP_CRYPTO_OP_DECODE >>> > +}odp_crypto_op_t; >>> > + >>> > +typedef struct odp_key_t { >>> > +}odp_key_t; >>> > + >>> > +typedef struct odp_crypto_session_t { >>> > + odp_crypto_op_t op; >>> > + struct { >>> > + enum odp_cipher_alg cipher_alg; >>> > + odp_key_t *key; >>> > + uint8_t *iv; >>> > + size_t iv_len; >>> > + } cipher; >>> > + >>> > + struct { >>> > + enum odp_auth_alg auth_alg; >>> > + enum odp_auth_len auth_len; >>> > + odp_key_t *key; >>> > + } auth; >>> > + >>> > + enum odp_crypto_op_mode { >>> > + ODP_CRYPTO_SYNC, >>> > + ODP_CRYPTO_ASYNC, >>> > + } op_mode; >>> > + >>> > + struct { >>> > + uint32_t timeout; >>> > + struct { >>> > + odp_queue_t completion_queue; >>> > + } async; >>> > + } op_mode_params; >>> > + >>> > + odp_session_proc_info_t session_proc_info; >>> > +} odp_crxsypto_session_t; >>> > +@endcode >>> > + >>> > +The completion queue contained in the session structure is an in/out >>> parameter. If provided, then the queue specified is associated with the >>> session and is used to ensure order preservation on that session. If not >>> provided, one is created and returned to the caller. Note that this >>> completion queue is used to order operations performed on this crypto >>> session. It should not be confused with the completion queue specified on >>> the odp_crypto_session_create() call (see below) that is used to control >>> whether that call is itself processed in a synchronous vs. asynchronous >>> manner. >>> > + >>> > +The following structure comprises processing information. This is >>> logically divided in two parts: >>> > + >>> > +- Processing input info - When crypto engine provides support for >>> protocol processing, this information is provided in a higher level common >>> protocol terminology form and a particular implementation should be able to >>> derive everything it needs from this definition. In addition, for crypto >>> engines able to automate tasks like memory allocation for the output a >>> buffer pool id may be specified.\n\n >>> > + >>> > +- Processing output information - statistics about processed >>> bytes/packets. These are useful when a session expiration is based on >>> traffic volume. These statistics may be updated by the software or by the >>> hardware crypto engine. >>> > + >>> > +Again, this is an abstract type whose specific layout will vary based >>> on implementation considerations. Access to fields contained in the >>> structure is only via accessor functions. >>> > + >>> > +@code >>> > +typedef struct { >>> > + uint64_t pkts_processed; >>> > + uint64_t bytes_processed; >>> > + uint64_t pkts_errored; >>> > + uint64_t bytes_errored; >>> > + >>> > + odp_buffer_pool_t out_pool; >>> > + >>> > +} odp_session_proc_info_t; >>> > +@endcode >>> > + >>> > +This enumeration defines which operations are applied and the order. >>> > + >>> > +@code >>> > +enum odp_crypto_combination { >>> > +ODP_CRYPTO_CIPHER_ONLY, >>> > + ODP_CRYPTO_AUTH_ONLY, >>> > + ODP_CRYPTO_AUTH_CIPHERTEXT >>> > +}; >>> > +@endcode >>> > + >>> > +This structure defines a contiguous segment in the input data which >>> starts at offset offset and is len bytes long. >>> > + >>> > +@code >>> > +struct odp_data_range { >>> > + unsigned offset:16; >>> > + unsigned len:16; >>> > +}; >>> > +@endcode >>> > + >>> > +@subsection api_functions API Functions >>> > + >>> > +@subsubfunction Session Creation >>> > + >>> > +This function is used to create a crypto session. The required >>> parameters are : >>> > + >>> > +- Operation : encode/decode >>> > +- Processing info : cipher/auth/both >>> > +- Preferred mode : sync or async. >>> > +- Algorithms suites, keys and optional IV >>> > + >>> > +Session creation can be synchronous or asynchronous. Completion event >>> argument is used to return the status and the session handle. When >>> completion queue is not provided (synchronous call), the completion event >>> is available upon function call return. When completion queue is provided >>> (asynchronous call), the completion event is placed on the completion queue. >>> > + >>> > +@code >>> > +typedef uint64_t odp_crypto_session_t; >>> > + >>> > +struct odp_session_params { >>> > + enum odp_crypto_operation op; >>> > + odp_session_proc_info_t proc_info; >>> > + enum odp_crypto_op_mode pref_mode; >>> > + enum odp_cipher_alg cipher_alg; >>> > + odp_key_t *cipher_key; >>> > + uint8_t *iv; >>> > + size_t iv_len; >>> > + enum odp_auth_alg auth_alg; >>> > + odp_key_t *auth_key; >>> > +}; >>> > + >>> > +enum odp_crypto_ses_create_err { >>> > + ODP_CRYPTO_SES_CREATE_NONE, >>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, >>> > + /* Session creation error codes */ >>> > +}; >>> > + >>> > +void >>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, >>> enum odp_crypto_ses_create_err *status); >>> > + >>> > +void >>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, >>> odp_crypto_session_t *handle); >>> > + >>> > +int odp_crypto_session_create( >>> > + struct odp_session_params *params, >>> > + odp_buffer_t completion_event, >>> > + odp_queue_t completion_queue); >>> > +@endcode >>> > +@subsection crypto_operation Crypto Operation >>> > + >>> > +Crypto operations are described by a parameter structure: >>> > +@code >>> > +struct odp_crypto_op_params { >>> > + odp_crypto_session_t session; >>> > + odp_packet_t pkt; >>> > + odp_packet_t out_pkt; >>> > + uint8_t *override_iv_ptr; >>> > + unsigned hash_result_offset; >>> > + struct odp_data_range cipher_range; >>> > + struct odp_data_range auth_range; >>> > +}; >>> > +@endcode >>> > + >>> > +<table> >>> > +<tr><th>Parameter</th><th>Meaning</th></tr> >>> > +<tr><td>session</td><td>Session to perform the operation</td></tr> >>> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> >>> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be >>> returned as the result of the operation. There are three different ways >>> this parameter is used, depending on the mode of operation requested by the >>> caller and the capabilities of the underlying implementation:\n\n >>> > + >>> > +-# If out_pkt is the same as pkt this indicates that the operation >>> should be performed in place.\n\n >>> > +-# If out_pkt is different from pkt this indicates that output should >>> be placed in the buffer supplied by the caller.\n\n >>> > +-# If out_pkt is omitted (a null/invalid value supplied on input) >>> this indicates that an output buffer should be allocated by the operation >>> and returned as part of the completion event associated with the >>> operation.\n\n >>> > + >>> > +Note that not every implementation will support all of these modes >>> and MAY require that one mode be used in preference to others. Any such >>> implementation restrictions are communicated as output from session >>> creation.</td></tr> >>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this >>> request</td></tr> >>> > +<tr><td>hash_result_offset</td><td>Offset into the output packet >>> where the hash result should be stored.</td></tr> >>> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the >>> data to be processed for ciphering.</td></tr> >>> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the data >>> to be processed for authentication.</td></tr> >>> > +</table> >>> > + >>> > +The crypto operation is initiated with a single call that passes the >>> parameters for the operation and an event (for asynchronous completion). >>> > +@code >>> > +int odp_crypto_operation( >>> > + struct odp_crypto_op_params *params, >>> > + odp_buffer_t completion_event); >>> > +@endcode >>> > + >>> > +Parameter | Meaning >>> > +----------|-------- >>> > +params | The parameter structure describing the crypto operation >>> to be performed. >>> > +completion_event | The event delivered on completion. It provides >>> information about the status of the operation, result and request context. >>> In synchronous mode the event is available upon function call return. In >>> asynchronous mode, the event is placed on the session / operation >>> completion queue when the operation finished. >>> > + >>> > +Upon return the return code indicates whether the operation was >>> synchronous or asynchronous, or if an error occurred that prevented the >>> operation from being performed. >>> > + >>> > +Get session operation : >>> > +@code >>> > +odp_crypto_op_t >>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); >>> > +@endcode >>> > + >>> > +Get session cipher information : >>> > +@code >>> > +odp_cipher_alg >>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); >>> > +@endcode >>> > + >>> > +Get session authentication information : >>> > +@code >>> > +odp_auth_alg >>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >>> > +@endcode >>> > + >>> > +Change session IV : >>> > +@code >>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); >>> > +@emdcode >>> > + >>> > +Change cipher or/and hash keys: >>> > +@code >>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t >>> *key); >>> > +@endcode >>> > + >>> > +Destroy crypto session. All pending operations are cancelled. >>> > +@code >>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); >>> > +@endcode >>> > + >>> > +Get completion event information - algorithm error, output and >>> context. Note that implementations MAY define their own specific error >>> codes that have meaning in that context. For application portability it is >>> sufficient to know whether an operation completed successfully or >>> experienced an error of some sort. >>> > +@code >>> > +enum crypto_alg_err { >>> > + ODP_CRYPTO_ALG_ERR_NONE, >>> > + ODP_CRYPTO_ALG_ERR_MODE, >>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >>> > +}; >>> > + >>> > +enum crypto_hw_err { >>> > + ODP_CRYPTO_HW_ERR_NONE, >>> > + ODP_CRYPTO_HW_ERR_DMA, >>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >>> > +}; >>> > + >>> > +struct odp_crypto_compl_status { >>> > + odp_crypto_alg_t alg; >>> > + enum crypto_alg_err alg_err; >>> > + enum crypto_hw_err hw_err; >>> > +}; >>> > + >>> > +void >>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, >>> > + struct odp_crypto_compl_status *auth, >>> > + struct odp_crypto_compl_status *cipher); >>> > +@endcode >>> > + >>> > +Returns the output packet handle associated with the completion event >>> : >>> > +@code >>> > +odp_packet_t >>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >>> > +@endcode >>> > + >>> > +Sets a context handle to be returned with the completion event : >>> > +@code >>> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, >>> odp_compl_ctx_t *ctx); >>> > +@endcode >>> > + >>> > +Returns the context associated with the completion event : >>> > +@code >>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t >>> completion_event); >>> > +@endcode >>> > + >>> > +This section describes the API/Interface being defined at a >>> functional level in technical detail. Sub-sections include header file >>> names, where implementation files are expected to reside in the ODP git >>> tree, as well as the name, parameters, abstract data types, functionality, >>> return codes, and exception conditions of each function call defined by the >>> API/Interface. Appropriate diagrams, tables, etc. should be used to allow >>> the programmer tasked with implementing the API/Interface to understand the >>> function to be implemented as well as error conditions, corner cases, >>> performance requirements, etc. needed to implement the described >>> API/Interface in a functionally correct and efficient manner. >>> > + >>> > +@subsubsection random_number_functions Random Number Functions >>> > +As noted earlier, random number support consists of two functions: >>> > +@code >>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); >>> > + >>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >>> > +@endcode >>> > + >>> > +The difference is that the first provides access to hardware random >>> number functions that return true random data. This is typically used for >>> seed values. The second provides a deterministic random bit generator >>> conforming to NIST standards and is used by various crypto protocols and >>> algorithms. The use_entropy parameter on odp_hw_random_get is used to >>> disable any hardware pre-processing normally provided by the function and >>> is mainly intended to be used for testing/validation purposes. >>> > + >>> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions >>> > +To support zeroization a buffer may be allocated with an >>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be >>> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to >>> odp_buffer_pool_create() that specifies that all buffers allocated from >>> this pool must be zeroized upon free. Essentially, the buffer security >>> attribute is set by default from the attributes of the buffer pool that it >>> is allocated from. >>> > + >>> > +@subsubsection capability_inquiry Capability Inquiry >>> > +To enable applications to determine crypto capabilities. >>> > +@code >>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); >>> > +@endcode >>> > + >>> > +Inquires whether the specified crypto and auth algorithms are >>> supported. Responses include: >>> > +- ODP_HW_SYNC_SUPPORT >>> > +- ODP_HW_ASYNC_SUPPORT >>> > +- ODP_SW_SYNC_SUPPORT >>> > +- ODP_SW_ASYNC_SUPPORT >>> > +- ODP_NO_SUPPORT >>> > + >>> > +HW support means the combination is supported in hardware, SW support >>> means the combination is supported in software by the implementation. No >>> support means the combination is not supported by the implementation. The >>> SYNC and ASYNC return options can help the application decide how to invoke >>> these functions, or it can just check whether or not the response is >>> ODP_NO_SUPPORT. >>> > + >>> > +@section implementation_considerations Implementation Considerations >>> > +One of the main purposes for the ODP crypto APIs is to provide >>> portable access across different SoCs whose hardware crypto capabilities >>> largely overlap but vary in terms of their implementation details. As a >>> result, implementations need not provide software fill-ins for specific >>> cryptographic features that are not available as hardware features on that >>> platform. Presumably applications needing specific features will select >>> platforms on which these features are present. Therefore, while all APIs >>> specified here MUST exist in each conforming ODP implementation, it is >>> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response >>> to calls requesting crypto features not present on that platform. >>> > + >>> > +For example, the linux-generic ODP implementation may only implement >>> the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not >>> present error code for any other cipher. This indication will also be >>> returned on that platform in response to odp_crypto_inquire calls for >>> non-null cipher algorithms. >>> > + >>> > +@section verification Verification/Testing >>> > +This section describes the verification/test cases needed to ensure >>> that the defined functionality is implemented correctly and performs >>> adequately. This should be at a level of detail such that the programmer >>> tasked with writing test scripts/programs to verify the implementation(s) >>> of the defined functions can be written to ensure that all relevant >>> functional variants and error/exception cases are properly tested. >>> > + >>> > +This section needs to be completed before API testing begins. >>> > + >>> > +*/ >>> > \ No newline at end of file >>> > diff --git a/images/syncmodels.png b/images/syncmodels.png >>> > new file mode 100644 >>> > index >>> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >>> > GIT binary patch >>> > literal 17179 >>> > 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 >>> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b >>> > >>> > literal 0 >>> > HcmV?d00001 >>> > >>> > -- >>> > 1.8.3.2 >>> > >>> > >>> > _______________________________________________ >>> > lng-odp mailing list >>> > lng-odp@lists.linaro.org >>> > http://lists.linaro.org/mailman/listinfo/lng-odp >>> >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP >
I agree we need approval, but approval can be of a review of the patch to the text. I hope we don't need wholesale changes that need a complete re write and thus approval of a whole new document. For example a new patch which may add a new function to an API but we would hopefully not change any of the existing text in the main. Thus we can then make changes in manageable chunks, I agree that large new additions will come in via a pre approved hugue patch, created from a sequence of sprints just have we have done so far. I would argue that these small changes are likely given the additions already discovered by starting the validation testing work and the feedback it is generating with the need to be more specific in architectural areas. Mike On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Design documents require approval by those who aren't going to be > reviewing patches. This is different from code. My understanding of the > purpose of the odp-architecture repository is to provide a convenient means > of distributing documentation and making it available in various forms > (Doxygen, PDF) for access through the ODP web site as well as being > downloaded. > > So in this sense we're just using Git as a publication mechanism for docs. > > > On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> I am confused git is a change control mechanism, and I really hope they >> do get patched, how will we improve the content ? >> >> >> On 3 July 2014 10:03, Bill Fischofer <bill.fischofer@linaro.org> wrote: >> >>> Git is a publication mechanism for docs, not a change control mechanism. >>> Docs will not be 'patched'. New versions will replace old ones as they >>> are approved. >>> >>> >>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell <anders.roxell@linaro.org> >>> wrote: >>> >>>> On 2014-07-02 12:46, Bill Fischofer wrote: >>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >>>> > --- >>>> > crypto_design.dox | 455 >>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ >>>> > images/syncmodels.png | Bin 0 -> 17179 bytes >>>> > 2 files changed, 455 insertions(+) >>>> > create mode 100644 crypto_design.dox >>>> > create mode 100644 images/syncmodels.png >>>> > >>>> > diff --git a/crypto_design.dox b/crypto_design.dox >>>> > new file mode 100644 >>>> > index 0000000..1ad2ac6 >>>> > --- /dev/null >>>> > +++ b/crypto_design.dox >>>> > @@ -0,0 +1,455 @@ >>>> > +/* Copyright (c) 2043, Linaro Limited >>>> > + * All rights reserved >>>> > + * >>>> > + * SPDX-License-Identifier: BSD-3-Clause >>>> > + */ >>>> > + >>>> > +/** >>>> > +@page crypto_design ODP Design - Crypto API >>>> > +For the implimentation of the ODP crypto API please see @ref >>>> odp_crypto.h >>>> > + >>>> > +@tableofcontents >>>> > + >>>> > +@section revision_history Revision History >>>> > +Revision | Issue Data | Description | Author >>>> > +---------|------------|-------------|-------- >>>> > +0.1 | 4/9/2014 | Introduction started, Basic Functions | >>>> Bill, Alexandru >>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, started use >>>> cases, miscellaneous formatting, API comments | Bill >>>> > +0.3 | 4/22/2014 | Added Use Case section to include results of >>>> design discussions held during ODP team calls | Bill >>>> > +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action >>>> to resolve | Bill >>>> > +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready >>>> for final review | Bill >>>> > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill >>>> > + >>>> > +@section introduction Introduction >>>> > +This document describes the ODP v1.0 Crypto API. Cryptography is an >>>> important part of data plane processing as many communication protocols >>>> make use of cryptographic functions. Moreover, many SoCs incorporate >>>> cryptographic hardware that can significantly accelerate these operations >>>> compared to their software equivalents as well as provide validated >>>> hardware functional correctness and security boundaries necessary for >>>> system-level security certifications such as FIPS-140 Level 2 and above. >>>> > +@section requirements Requirements >>>> > +@subsection use_of_terms Use of Terms >>>> > +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 [RFC 2119]( >>>> https://tools.ietf.org/html/rfc2119). >>>> > +@subsection uses_of_cryptography Uses of Cryptography >>>> > +Crypto functions cover a range of uses and capabilities designed to >>>> support data security, integrity, authentication, and non-repudiation. >>>> > +@subsubsection data_security Data Security >>>> > +Cryptography supports data security by making use of complex >>>> mathematical transformations that are not feasibly reversible without >>>> possession of the secret key used to encrypt message data. >>>> > +@subsubsection data_integrity Data Integrity >>>> > +Cryptography supports data integrity through the use of >>>> cryptographic checksums (also known as secure hashes) that ensure the >>>> recipient that message data has not been altered either accidentally or >>>> maliciously while in transit. >>>> > +@subsubsection data_authentication Data Authentication >>>> > +Cryptography supports data authentication through the uses of >>>> Message Authentication Codes (MACs) that enable the recipient to verify >>>> that a message was sent from an authorized counterparty, and hence was not >>>> forged. >>>> > +@subsubsection data_non_repudiation Data Non-Repudiation >>>> > +Cryptography supports data non-repudiation through the use of >>>> digital signatures that enable a recipient or third party to verify the >>>> identity of the sending party and prevents the sending party from later >>>> denying that they originated a signed message. >>>> > +@subsection scope Scope >>>> > +ODP v1.0 crypto support is designed to provide a portable framework >>>> for accessing SoC-specific cryptographic functions of most use to the data >>>> plane. This is predominantly symmetric crypto operations used to support >>>> the encryption and decryption of data at line rate using hardware >>>> acceleration and offload. Specifically excluded in this support are public >>>> key operations and other crypto functions mainly used in the control plane. >>>> > +@subsection cryptographic_operations_in_the_data_plane Cryptographic >>>> Operations in the Data Plane >>>> > +ODP v1.0 crypto APIs cover the following areas: >>>> > +@subsubsection ciphering Ciphering >>>> > +Ciphering refers to mathematical transformations that use a secret >>>> key to encipher data, transforming the original data (referred to as >>>> plaintext) into ciphertext, thereby making it unintelligible to anyone not >>>> in possession of the key. Similarly, ciphering is also used to decipher >>>> data, allowing someone in possession of the correct key to transform >>>> received ciphertext back into plaintext. Approved block ciphers are listed >>>> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and >>>> SHOULD be supported by each ODP implementation. >>>> > +@subsubsection hasing Hashing >>>> > +A hash is a cryptographic digest of a message that can be used to >>>> represent it for comparison or integrity checking. Hash functions are >>>> designed so that any alteration of a message will alter the hash and that >>>> it is computationally infeasible to craft a message that generates the same >>>> hash value as another message. Secure hash functions approved for >>>> cryptographic use are listed by NIST [here]( >>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD >>>> be supported by each ODP implementation. >>>> > +@subsubsection zeroization Zeroization >>>> > +To preserve the security of data, certain transient data held in >>>> data buffers MUST be cleared to zeros upon buffer free. Such capability is >>>> referred to as zeroization. ODP supports zeroization as a buffer pool >>>> attribute. >>>> > +@subsubsection random_number_generation Random Number Generation >>>> > +Because cryptography relies heavily on “unguessable” keys of various >>>> sorts, random number generation (RNG) is an integral part of cryptographic >>>> processing. Random numbers are used in key generation, initialization >>>> vectors (IVs), various types of padding bytes, and various other uses >>>> collectively referred to as nonces, that serve to “harden” cryptographic >>>> processing. >>>> > + >>>> > +There are two types of random number support of interest. Hardware >>>> random data, also known as entropy, that is the result of inherently random >>>> physical processes, and deterministic random bit generation (DRBG) that is >>>> used in certain certified cryptographic operations. Approved DRBG >>>> algorithms are listed in [NIST SP 800-90A]( >>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify >>>> which algorithms are available on a given implementation. As such ODP >>>> implementations MAY use any approved DRGB algorithm but SHOULD support at >>>> least one of them. Additionally, ODP implementations MUST NOT represent >>>> non-approved algorithms as DRBG implementations. Validated algorithms are >>>> listed in the [NIST DRBG Validation List]( >>>> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >>>> > + >>>> > +@subsubsection capability_inquiry Capability Inquiry >>>> > +To enable applications to adapt to the implementation models offered >>>> across different SoC platforms, ODP provides APIs to allow applications to >>>> inquire about underlying crypto capabilities. A given ODP implementation >>>> may offer crypto as hardware features, software features, or not available >>>> on a given platform. >>>> > +@subsection cryptographic_algorithms Cryptographic Algorithms and >>>> Protocols >>>> > +A cryptographic algorithm is a mathematical transform that provides >>>> one of the cryptographic operations described above. They in turn are used >>>> as building blocks in creating cryptographic protocols. These are complete >>>> sets of rules for how to exchange data securely using cryptography. Both >>>> cryptographic algorithm and protocol design are highly specialized >>>> disciplines that involve high levels of public scrutiny and validation. As >>>> a result, applications simply make use of approved cryptographic algorithms >>>> and protocols. >>>> > +@subsection cryptographic_operations Cryptographic Operations >>>> > +Cryptographic operations may be initiated by software or directly by >>>> hardware as part of the RX or TX packet path processing. For ODP v1.0 >>>> software-initiated cryptographic operations are the primary use case. ODP >>>> provides APIs for performing data ciphering, hashing, random number >>>> generation, and capability inquiry. >>>> > +@subsection performance_expectations Performance Expectations >>>> > +In the data plane, the total processing budget for a packet may only >>>> be a few hundred cycles, so function invocation overhead MUST be kept to a >>>> minimum. This has several implications. >>>> > + >>>> > +-# When work is dispatched to a thread, all information needed by >>>> the thread to process the work request SHOULD be immediately at hand. >>>> Ideally any context or variables needed for the operation have been >>>> pre-warmed in the cache to avoid the latency hits associated with cache >>>> misses. SoCs having hardware schedulers generally do this pre-staging of >>>> data to minimize such latencies, and ODP implementations are expected to >>>> exploit such platform capabilities whenever possible.\n\n >>>> > + >>>> > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of >>>> parameter passing and (depending on the implementation) SHOULD be inlined >>>> as much as possible to avoid call overhead. One technique that has proven >>>> useful is to allow for parameters to be passed as an explicit thread-local >>>> static structure. Such use of “templating” means that a single function can >>>> support a rich set of options but the caller can configure a template >>>> matched to specific use and only vary the one or two parameters that differ >>>> from call to call.\n\n >>>> > + >>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any >>>> non-exception path function processing. Kernel calls and such are >>>> acceptable only during one-time initialization logic or certain types of >>>> unusual error recovery operations. Often the best way to handle the latter >>>> is to pass the work to a dedicated recovery thread (or back to the control >>>> plane) rather than attempting to handle the condition inline. For example, >>>> a link-down condition will trigger various recovery actions that might best >>>> be handled in this manner. >>>> > + >>>> > +@subsection use_by_existing_code Use by Existing Code >>>> > +Most applications wishing to make use of ODP represent substantial >>>> existing investment that must be preserved. Insofar as possible, ODP >>>> functions need to be orthogonal to existing application environments and >>>> structures to permit easy intermixing with pre-existing code. >>>> > +@subsection data_references Data References >>>> > +Packet data is inherently of variable length however it is often >>>> more efficient to organize memory into fixed-sized buffers that can be >>>> chained together on demand to contain packets. The application SHOULD >>>> normally not need to be aware of such lower-level segmentation and should >>>> be able to treat a packet as a single object. Alternately, especially when >>>> dealing with existing code, data segmentation MUST be explicitly >>>> specifiable via scatter/gather lists. For example, data encryption or >>>> decryption may be invoked on a list of data segments as part of a single >>>> function call. >>>> >>>> Every time you add a full stop for a sentence, you have to press return >>>> and start typing the next sentence. >>>> This means that diffs of future changes will be per sentence. >>>> Doxygen will still concatenate this as a paragraph with no visual >>>> difference in the result. >>>> I think the above line will look like this: >>>> >>>> Packet data is inherently of variable length however it is often more >>>> efficient to organize memory into fixed-sized buffers that can be chained >>>> together on demand to contain packets. >>>> The application SHOULD normally not need to be aware of such >>>> lower-level segmentation and should be able to treat a packet as a single >>>> object. >>>> Alternately, especially when dealing with existing code, data >>>> segmentation MUST be explicitly specifiable via scatter/gather lists. >>>> For example, data encryption or decryption may be invoked on a list of >>>> data segments as part of a single function call. >>>> >>>> >>>> Cheers, >>>> Anders >>>> >>>> > +@subsection chained_operations Chained Operations >>>> > +Crypto operations such as hashing and encryption, or decryption and >>>> verification, are very commonly used in combination. For ODP, it is >>>> sufficient to support one cipher and one hash/authentication operation in a >>>> single call and this combination MUST be supported to avoid the call and >>>> dispatch overhead of separate invocations. >>>> > +@subsection key_management Key Management and Session Data >>>> > +Keying is an area of particular sensitivity in crypto processing >>>> since keys are highly confidential and may be subject to legal requirements >>>> for safeguarding within special hardware enclosures. >>>> > + >>>> > +A session is the security context used to represent an active set of >>>> crypto operations that need to be applied to a flow on a packet-by-packet >>>> basis. Generally a session is established upon detection of a flow >>>> requiring crypto processing and retained for the life of that flow. It has >>>> been noted that this can involve cooperative processing between the control >>>> and data planes so several requirements stem from this: >>>> > + >>>> > +-# Session creation MAY need to be handled in an asynchronous >>>> manner. This is to allow these to be created in batches by thread(s) that >>>> specialize in this activity.\n\n >>>> > + >>>> > +-# Sessions MAY need to reference keying material indirectly via key >>>> handling modules.\n\n >>>> > + >>>> > +-# Session creation MAY be performed by non-ODP code and >>>> communicated to data plane routines that make use of ODP crypto functions >>>> that need to reference the session information. >>>> > + >>>> > +ODP session APIs and data structures SHOULD be represented by >>>> abstract data types that encapsulate implementation details for both >>>> platform efficiency and to accommodate these needs. >>>> > +Use Cases >>>> > +For ODP v1.0 the major use cases of interest involve cryptographic >>>> algorithm acceleration. Cryptographic protocol acceleration is reserved for >>>> future ODP releases. >>>> > +Buffers and Data Blocks >>>> > +Cryptographic operations may be performed directly on data contained >>>> in ODP packet buffers, or it may be performed on “raw” data blocks >>>> operating entirely under application control. Note that when using raw data >>>> blocks not managed by ODP, the application must perform any needed >>>> zeroization using either its own or ODP-supplied buffer zeroization >>>> functions. ODP automatic support for zeroization is limited to ODP-managed >>>> buffers. ODP buffers allocated from buffer pools designated for crypto use >>>> will also have whatever alignment and/or addressability attributes needed >>>> by the implementation to support crypto API calls. >>>> > + >>>> > +Note: Some implementations may have difficulty dealing with >>>> application buffer addresses, as these may be virtual addresses that are >>>> mapped discontiguously into physical memory. For such implementations, >>>> memory SHOULD be allocated contiguously and MAY need to be “registered” to >>>> have proper addressability for crypto operations. This area of the design >>>> will be updated based on experience in dealing with different crypto >>>> implementations that have such requirements. >>>> > +Synchronization >>>> > +ODP operations fall into one of three categories: >>>> > + >>>> > +-# Inline (Synchronous): Upon return from a call the operation is >>>> complete. Operation is thus completely synchronous to the caller. Inline >>>> is the appropriate model when the invoked function takes relatively few >>>> cycles or when the caller cannot feasibly progress without the results of >>>> the invoked function.\n\n >>>> > + >>>> > +-# Parallel: Upon return from a call the operation has been >>>> initiated, but is expected to complete shortly. The caller continues to >>>> execute until it needs the result at which point it waits to complete the >>>> parallel operation. The effect is as if the operation were inline except >>>> that the caller was able to execute in parallel with the operation for some >>>> application-determined period of time. Parallel is the appropriate model >>>> when the operation being performed is relatively short (a few dozen up to >>>> perhaps 100 or 200 cycles) and the caller can usefully accomplish other >>>> processing on the same unit of work while the parallel operation is in >>>> progress, but not enough to justify the overhead of a formal queued work >>>> dispatch.\n\n >>>> > + >>>> > +-# Offloaded (Asynchronous): Upon return from the call the operation >>>> has been queued for execution. A completion event will be queued back to >>>> the scheduler when the event is completed. Offload is the appropriate model >>>> when the invoked function will take a substantial amount of cycles >>>> (thousands to tens of thousands) allowing the invoking thread/core to >>>> service other work until the operation completes. For offloaded work, >>>> completion is indicated by a completion event being posted back to an >>>> application-designated completion queue. Upon receipt the unit of work that >>>> initiated the offloaded operation continues processing with the results of >>>> the call. >>>> > + >>>> > +The synchronization models of interest are summarized in Figure 1: >>>> > + >>>> > + >>>> > + >>>> > +Note: Because few implementations are expected to offer the Parallel >>>> mode of operation as described above, this mode is reserved for potential >>>> future use. For ODP v1.0 only synchronous and asynchronous crypto >>>> operations are defined. >>>> > +@section functional_definition Functional Definition >>>> > +@subsection abstract_data_types Abstract data types >>>> > +The following enumerations define various algorithms used for >>>> ciphering and hashing. These are the basic operations applied to input data. >>>> > + >>>> > +A particular ODP implementation should map these values to the >>>> actual information to be passed to the crypto engine. As such, the actual >>>> values of these enums is implementation-defined. >>>> > + >>>> > +Cipher algorithm encoding specifies the algorithm and cipher mode >>>> employed (as per security relevant RFCs - [4305]( >>>> http://tools.ietf.org/html/rfc4305), [4868]( >>>> http://tools.ietf.org/html/rfc4868), [4494]( >>>> http://tools.ietf.org/html/rfc4494)). >>>> > + >>>> > +@code >>>> > +enum odp_cipher_alg { >>>> > + ODP_CIPHER_ALG_NULL, >>>> > + ODP_CIPHER_ALG_DES, >>>> > + ODP_CIPHER_ALG_3DES_CBC, >>>> > + ODP_CIPHER_ALG_AES_CBC, >>>> > + ODP_CIPHER_ALG_AES_GCM, >>>> > + ODP_CIPHER_ALG_AES_CTR, >>>> > + ODP_CIPHER_ALG_KASUMI, >>>> > + ODP_CIPHER_ALG_SNOW, >>>> > + ... >>>> > +}; >>>> > +@endcode >>>> > + >>>> > +Authorization algorithm encoding specifies the algorithm and the >>>> length of the authorization used (as per security relevant RFCs - [4305]( >>>> http://tools.ietf.org/html/rfc4305), [4868]( >>>> http://tools.ietf.org/html/rfc4868), [4494]( >>>> http://tools.ietf.org/html/rfc4494)): >>>> > + >>>> > +@code >>>> > +enum odp_auth_alg { >>>> > + ODP_AUTH_ALG_NULL, >>>> > + ODP_AUTH_MD5_96, >>>> > + ODP_AUTH_ALG_SHA1_96, >>>> > + ODP_AUTH_ALG_SHA1_160 >>>> > + ODP_AUTH_ALG_SHA2_256_128, >>>> > + ODP_AUTH_ALG_SHA2_384_192, >>>> > + ODP_AUTH_ALG_SHA2_512_256, >>>> > + ODP_AUTH_ALG_AES_CMAC_96, >>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, >>>> > + ODP_AUTH_ALG_SNOW, >>>> > + ODP_AUTH_ALG_KASUMI, >>>> > + ... >>>> > +}; >>>> > + >>>> > +typedef union odp_crypto_alg_t { >>>> > + enum odp_cipher_alg cipher; >>>> > + enum odp_auth_alg auth; >>>> > +}odp_crypto_alg_t; >>>> > +@endcode >>>> > +@subsection parameter_structures Parameter Structures >>>> > +@subsubsection crypto_sessions Crypto Sessions >>>> > +The following structure describes a crypto session. All packets / >>>> raw data buffers processed in a session share the data that defines the >>>> session. A crypto session is defined by: >>>> > + >>>> > +- Operation type : encode or decode\n\n >>>> > + >>>> > +- Algorithms specifications, keys and , if required, initialization >>>> vectors. When initialization vectors are not provided and they should be >>>> provided automatically by the crypto engine.\n\n >>>> > + >>>> > +- The operation mode: synchronous or asynchronous. Synchronous >>>> operation blocks the caller until an operation status and result are >>>> available. In synchronous mode there is at most only one outstanding crypto >>>> operation in the calling thread. In asynchronous mode, the caller starts >>>> the crypto operation and later it may receive the status and the result >>>> together with a request context. The operation status and result may also >>>> be received by a different thread.\n\n >>>> > + >>>> > +- Operation mode parameters: For asynchronous operation a completion >>>> event containing the status, the result and the request context is enqueued >>>> to a completion queue. In case the queue is under the scheduler control, >>>> the scheduler determines who will receive the completion event and when. >>>> When the completion queue is not scheduled, the thread which is supposed to >>>> get the operation output has to explicitly poll the completion queue. >>>> > + >>>> > +Note that this is an abstract data type and its structure is >>>> implementation-specific. The layout shown here is for illustrative purposes >>>> and the actual layout will vary from one implementation to the next to most >>>> closely align with the structures needed by the underlying SoC platform. >>>> Applications set and reference fields in the session structure via accessor >>>> functions that hide the actual layout. >>>> > + >>>> > +@code >>>> > +typedef enum odp_crypto_op_t { >>>> > + ODP_CRYPTO_OP_ENCODE, >>>> > + ODP_CRYPTO_OP_DECODE >>>> > +}odp_crypto_op_t; >>>> > + >>>> > +typedef struct odp_key_t { >>>> > +}odp_key_t; >>>> > + >>>> > +typedef struct odp_crypto_session_t { >>>> > + odp_crypto_op_t op; >>>> > + struct { >>>> > + enum odp_cipher_alg cipher_alg; >>>> > + odp_key_t *key; >>>> > + uint8_t *iv; >>>> > + size_t iv_len; >>>> > + } cipher; >>>> > + >>>> > + struct { >>>> > + enum odp_auth_alg auth_alg; >>>> > + enum odp_auth_len auth_len; >>>> > + odp_key_t *key; >>>> > + } auth; >>>> > + >>>> > + enum odp_crypto_op_mode { >>>> > + ODP_CRYPTO_SYNC, >>>> > + ODP_CRYPTO_ASYNC, >>>> > + } op_mode; >>>> > + >>>> > + struct { >>>> > + uint32_t timeout; >>>> > + struct { >>>> > + odp_queue_t completion_queue; >>>> > + } async; >>>> > + } op_mode_params; >>>> > + >>>> > + odp_session_proc_info_t session_proc_info; >>>> > +} odp_crxsypto_session_t; >>>> > +@endcode >>>> > + >>>> > +The completion queue contained in the session structure is an in/out >>>> parameter. If provided, then the queue specified is associated with the >>>> session and is used to ensure order preservation on that session. If not >>>> provided, one is created and returned to the caller. Note that this >>>> completion queue is used to order operations performed on this crypto >>>> session. It should not be confused with the completion queue specified on >>>> the odp_crypto_session_create() call (see below) that is used to control >>>> whether that call is itself processed in a synchronous vs. asynchronous >>>> manner. >>>> > + >>>> > +The following structure comprises processing information. This is >>>> logically divided in two parts: >>>> > + >>>> > +- Processing input info - When crypto engine provides support for >>>> protocol processing, this information is provided in a higher level common >>>> protocol terminology form and a particular implementation should be able to >>>> derive everything it needs from this definition. In addition, for crypto >>>> engines able to automate tasks like memory allocation for the output a >>>> buffer pool id may be specified.\n\n >>>> > + >>>> > +- Processing output information - statistics about processed >>>> bytes/packets. These are useful when a session expiration is based on >>>> traffic volume. These statistics may be updated by the software or by the >>>> hardware crypto engine. >>>> > + >>>> > +Again, this is an abstract type whose specific layout will vary >>>> based on implementation considerations. Access to fields contained in the >>>> structure is only via accessor functions. >>>> > + >>>> > +@code >>>> > +typedef struct { >>>> > + uint64_t pkts_processed; >>>> > + uint64_t bytes_processed; >>>> > + uint64_t pkts_errored; >>>> > + uint64_t bytes_errored; >>>> > + >>>> > + odp_buffer_pool_t out_pool; >>>> > + >>>> > +} odp_session_proc_info_t; >>>> > +@endcode >>>> > + >>>> > +This enumeration defines which operations are applied and the order. >>>> > + >>>> > +@code >>>> > +enum odp_crypto_combination { >>>> > +ODP_CRYPTO_CIPHER_ONLY, >>>> > + ODP_CRYPTO_AUTH_ONLY, >>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT >>>> > +}; >>>> > +@endcode >>>> > + >>>> > +This structure defines a contiguous segment in the input data which >>>> starts at offset offset and is len bytes long. >>>> > + >>>> > +@code >>>> > +struct odp_data_range { >>>> > + unsigned offset:16; >>>> > + unsigned len:16; >>>> > +}; >>>> > +@endcode >>>> > + >>>> > +@subsection api_functions API Functions >>>> > + >>>> > +@subsubfunction Session Creation >>>> > + >>>> > +This function is used to create a crypto session. The required >>>> parameters are : >>>> > + >>>> > +- Operation : encode/decode >>>> > +- Processing info : cipher/auth/both >>>> > +- Preferred mode : sync or async. >>>> > +- Algorithms suites, keys and optional IV >>>> > + >>>> > +Session creation can be synchronous or asynchronous. Completion >>>> event argument is used to return the status and the session handle. When >>>> completion queue is not provided (synchronous call), the completion event >>>> is available upon function call return. When completion queue is provided >>>> (asynchronous call), the completion event is placed on the completion queue. >>>> > + >>>> > +@code >>>> > +typedef uint64_t odp_crypto_session_t; >>>> > + >>>> > +struct odp_session_params { >>>> > + enum odp_crypto_operation op; >>>> > + odp_session_proc_info_t proc_info; >>>> > + enum odp_crypto_op_mode pref_mode; >>>> > + enum odp_cipher_alg cipher_alg; >>>> > + odp_key_t *cipher_key; >>>> > + uint8_t *iv; >>>> > + size_t iv_len; >>>> > + enum odp_auth_alg auth_alg; >>>> > + odp_key_t *auth_key; >>>> > +}; >>>> > + >>>> > +enum odp_crypto_ses_create_err { >>>> > + ODP_CRYPTO_SES_CREATE_NONE, >>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, >>>> > + /* Session creation error codes */ >>>> > +}; >>>> > + >>>> > +void >>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t >>>> completion_event, enum odp_crypto_ses_create_err *status); >>>> > + >>>> > +void >>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t >>>> completion_event, odp_crypto_session_t *handle); >>>> > + >>>> > +int odp_crypto_session_create( >>>> > + struct odp_session_params *params, >>>> > + odp_buffer_t completion_event, >>>> > + odp_queue_t completion_queue); >>>> > +@endcode >>>> > +@subsection crypto_operation Crypto Operation >>>> > + >>>> > +Crypto operations are described by a parameter structure: >>>> > +@code >>>> > +struct odp_crypto_op_params { >>>> > + odp_crypto_session_t session; >>>> > + odp_packet_t pkt; >>>> > + odp_packet_t out_pkt; >>>> > + uint8_t *override_iv_ptr; >>>> > + unsigned hash_result_offset; >>>> > + struct odp_data_range cipher_range; >>>> > + struct odp_data_range auth_range; >>>> > +}; >>>> > +@endcode >>>> > + >>>> > +<table> >>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> >>>> > +<tr><td>session</td><td>Session to perform the operation</td></tr> >>>> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> >>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be >>>> returned as the result of the operation. There are three different ways >>>> this parameter is used, depending on the mode of operation requested by the >>>> caller and the capabilities of the underlying implementation:\n\n >>>> > + >>>> > +-# If out_pkt is the same as pkt this indicates that the operation >>>> should be performed in place.\n\n >>>> > +-# If out_pkt is different from pkt this indicates that output >>>> should be placed in the buffer supplied by the caller.\n\n >>>> > +-# If out_pkt is omitted (a null/invalid value supplied on input) >>>> this indicates that an output buffer should be allocated by the operation >>>> and returned as part of the completion event associated with the >>>> operation.\n\n >>>> > + >>>> > +Note that not every implementation will support all of these modes >>>> and MAY require that one mode be used in preference to others. Any such >>>> implementation restrictions are communicated as output from session >>>> creation.</td></tr> >>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this >>>> request</td></tr> >>>> > +<tr><td>hash_result_offset</td><td>Offset into the output packet >>>> where the hash result should be stored.</td></tr> >>>> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the >>>> data to be processed for ciphering.</td></tr> >>>> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the >>>> data to be processed for authentication.</td></tr> >>>> > +</table> >>>> > + >>>> > +The crypto operation is initiated with a single call that passes the >>>> parameters for the operation and an event (for asynchronous completion). >>>> > +@code >>>> > +int odp_crypto_operation( >>>> > + struct odp_crypto_op_params *params, >>>> > + odp_buffer_t completion_event); >>>> > +@endcode >>>> > + >>>> > +Parameter | Meaning >>>> > +----------|-------- >>>> > +params | The parameter structure describing the crypto operation >>>> to be performed. >>>> > +completion_event | The event delivered on completion. It provides >>>> information about the status of the operation, result and request context. >>>> In synchronous mode the event is available upon function call return. In >>>> asynchronous mode, the event is placed on the session / operation >>>> completion queue when the operation finished. >>>> > + >>>> > +Upon return the return code indicates whether the operation was >>>> synchronous or asynchronous, or if an error occurred that prevented the >>>> operation from being performed. >>>> > + >>>> > +Get session operation : >>>> > +@code >>>> > +odp_crypto_op_t >>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); >>>> > +@endcode >>>> > + >>>> > +Get session cipher information : >>>> > +@code >>>> > +odp_cipher_alg >>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); >>>> > +@endcode >>>> > + >>>> > +Get session authentication information : >>>> > +@code >>>> > +odp_auth_alg >>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >>>> > +@endcode >>>> > + >>>> > +Change session IV : >>>> > +@code >>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); >>>> > +@emdcode >>>> > + >>>> > +Change cipher or/and hash keys: >>>> > +@code >>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t >>>> *key); >>>> > +@endcode >>>> > + >>>> > +Destroy crypto session. All pending operations are cancelled. >>>> > +@code >>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); >>>> > +@endcode >>>> > + >>>> > +Get completion event information - algorithm error, output and >>>> context. Note that implementations MAY define their own specific error >>>> codes that have meaning in that context. For application portability it is >>>> sufficient to know whether an operation completed successfully or >>>> experienced an error of some sort. >>>> > +@code >>>> > +enum crypto_alg_err { >>>> > + ODP_CRYPTO_ALG_ERR_NONE, >>>> > + ODP_CRYPTO_ALG_ERR_MODE, >>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >>>> > +}; >>>> > + >>>> > +enum crypto_hw_err { >>>> > + ODP_CRYPTO_HW_ERR_NONE, >>>> > + ODP_CRYPTO_HW_ERR_DMA, >>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >>>> > +}; >>>> > + >>>> > +struct odp_crypto_compl_status { >>>> > + odp_crypto_alg_t alg; >>>> > + enum crypto_alg_err alg_err; >>>> > + enum crypto_hw_err hw_err; >>>> > +}; >>>> > + >>>> > +void >>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, >>>> > + struct odp_crypto_compl_status *auth, >>>> > + struct odp_crypto_compl_status *cipher); >>>> > +@endcode >>>> > + >>>> > +Returns the output packet handle associated with the completion >>>> event : >>>> > +@code >>>> > +odp_packet_t >>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >>>> > +@endcode >>>> > + >>>> > +Sets a context handle to be returned with the completion event : >>>> > +@code >>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, >>>> odp_compl_ctx_t *ctx); >>>> > +@endcode >>>> > + >>>> > +Returns the context associated with the completion event : >>>> > +@code >>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t >>>> completion_event); >>>> > +@endcode >>>> > + >>>> > +This section describes the API/Interface being defined at a >>>> functional level in technical detail. Sub-sections include header file >>>> names, where implementation files are expected to reside in the ODP git >>>> tree, as well as the name, parameters, abstract data types, functionality, >>>> return codes, and exception conditions of each function call defined by the >>>> API/Interface. Appropriate diagrams, tables, etc. should be used to allow >>>> the programmer tasked with implementing the API/Interface to understand the >>>> function to be implemented as well as error conditions, corner cases, >>>> performance requirements, etc. needed to implement the described >>>> API/Interface in a functionally correct and efficient manner. >>>> > + >>>> > +@subsubsection random_number_functions Random Number Functions >>>> > +As noted earlier, random number support consists of two functions: >>>> > +@code >>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool >>>> use_entropy); >>>> > + >>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >>>> > +@endcode >>>> > + >>>> > +The difference is that the first provides access to hardware random >>>> number functions that return true random data. This is typically used for >>>> seed values. The second provides a deterministic random bit generator >>>> conforming to NIST standards and is used by various crypto protocols and >>>> algorithms. The use_entropy parameter on odp_hw_random_get is used to >>>> disable any hardware pre-processing normally provided by the function and >>>> is mainly intended to be used for testing/validation purposes. >>>> > + >>>> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions >>>> > +To support zeroization a buffer may be allocated with an >>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be >>>> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to >>>> odp_buffer_pool_create() that specifies that all buffers allocated from >>>> this pool must be zeroized upon free. Essentially, the buffer security >>>> attribute is set by default from the attributes of the buffer pool that it >>>> is allocated from. >>>> > + >>>> > +@subsubsection capability_inquiry Capability Inquiry >>>> > +To enable applications to determine crypto capabilities. >>>> > +@code >>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); >>>> > +@endcode >>>> > + >>>> > +Inquires whether the specified crypto and auth algorithms are >>>> supported. Responses include: >>>> > +- ODP_HW_SYNC_SUPPORT >>>> > +- ODP_HW_ASYNC_SUPPORT >>>> > +- ODP_SW_SYNC_SUPPORT >>>> > +- ODP_SW_ASYNC_SUPPORT >>>> > +- ODP_NO_SUPPORT >>>> > + >>>> > +HW support means the combination is supported in hardware, SW >>>> support means the combination is supported in software by the >>>> implementation. No support means the combination is not supported by the >>>> implementation. The SYNC and ASYNC return options can help the application >>>> decide how to invoke these functions, or it can just check whether or not >>>> the response is ODP_NO_SUPPORT. >>>> > + >>>> > +@section implementation_considerations Implementation Considerations >>>> > +One of the main purposes for the ODP crypto APIs is to provide >>>> portable access across different SoCs whose hardware crypto capabilities >>>> largely overlap but vary in terms of their implementation details. As a >>>> result, implementations need not provide software fill-ins for specific >>>> cryptographic features that are not available as hardware features on that >>>> platform. Presumably applications needing specific features will select >>>> platforms on which these features are present. Therefore, while all APIs >>>> specified here MUST exist in each conforming ODP implementation, it is >>>> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response >>>> to calls requesting crypto features not present on that platform. >>>> > + >>>> > +For example, the linux-generic ODP implementation may only implement >>>> the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not >>>> present error code for any other cipher. This indication will also be >>>> returned on that platform in response to odp_crypto_inquire calls for >>>> non-null cipher algorithms. >>>> > + >>>> > +@section verification Verification/Testing >>>> > +This section describes the verification/test cases needed to ensure >>>> that the defined functionality is implemented correctly and performs >>>> adequately. This should be at a level of detail such that the programmer >>>> tasked with writing test scripts/programs to verify the implementation(s) >>>> of the defined functions can be written to ensure that all relevant >>>> functional variants and error/exception cases are properly tested. >>>> > + >>>> > +This section needs to be completed before API testing begins. >>>> > + >>>> > +*/ >>>> > \ No newline at end of file >>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png >>>> > new file mode 100644 >>>> > index >>>> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >>>> > GIT binary patch >>>> > literal 17179 >>>> > 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 >>>> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b >>>> > >>>> > literal 0 >>>> > HcmV?d00001 >>>> > >>>> > -- >>>> > 1.8.3.2 >>>> > >>>> > >>>> > _______________________________________________ >>>> > lng-odp mailing list >>>> > lng-odp@lists.linaro.org >>>> > http://lists.linaro.org/mailman/listinfo/lng-odp >>>> >>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> http://lists.linaro.org/mailman/listinfo/lng-odp >>> >>> >> >> >> -- >> *Mike Holmes* >> Linaro Technical Manager / Lead >> LNG - ODP >> > >
The people who review and approve these docs want to see docs with things like change bars, not patches. The patch mechanism is simply inappropriate for this activity and we shouldn't try to force-fit it for something it's not designed to address. Again, the primary users of the odp-architecture git repository are those who want access to complete docs, not those who are creating, reviewing, and approving them. That's why we have a separate repository from the main odp git repository so that "patches" can be handled differently between them. My preference would be to grant push rights to those adding items to this repository rather than going through the artifice of patches. It would be more straightforward and consistent with the actual workflow. Git would still be doing version tracking so it would be possible to see the complete change history for any given doc easily. On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > I agree we need approval, but approval can be of a review of the patch to > the text. > > I hope we don't need wholesale changes that need a complete re write and > thus approval of a whole new document. For example a new patch which may > add a new function to an API but we would hopefully not change any of the > existing text in the main. > > Thus we can then make changes in manageable chunks, I agree that large > new additions will come in via a pre approved hugue patch, created from a > sequence of sprints just have we have done so far. > > I would argue that these small changes are likely given the additions > already discovered by starting the validation testing work and the feedback > it is generating with the need to be more specific in architectural areas. > > Mike > > > On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >> Design documents require approval by those who aren't going to be >> reviewing patches. This is different from code. My understanding of the >> purpose of the odp-architecture repository is to provide a convenient means >> of distributing documentation and making it available in various forms >> (Doxygen, PDF) for access through the ODP web site as well as being >> downloaded. >> >> So in this sense we're just using Git as a publication mechanism for docs. >> >> >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes <mike.holmes@linaro.org> >> wrote: >> >>> I am confused git is a change control mechanism, and I really hope they >>> do get patched, how will we improve the content ? >>> >>> >>> On 3 July 2014 10:03, Bill Fischofer <bill.fischofer@linaro.org> wrote: >>> >>>> Git is a publication mechanism for docs, not a change control >>>> mechanism. Docs will not be 'patched'. New versions will replace old ones >>>> as they are approved. >>>> >>>> >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell <anders.roxell@linaro.org >>>> > wrote: >>>> >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >>>>> > --- >>>>> > crypto_design.dox | 455 >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes >>>>> > 2 files changed, 455 insertions(+) >>>>> > create mode 100644 crypto_design.dox >>>>> > create mode 100644 images/syncmodels.png >>>>> > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox >>>>> > new file mode 100644 >>>>> > index 0000000..1ad2ac6 >>>>> > --- /dev/null >>>>> > +++ b/crypto_design.dox >>>>> > @@ -0,0 +1,455 @@ >>>>> > +/* Copyright (c) 2043, Linaro Limited >>>>> > + * All rights reserved >>>>> > + * >>>>> > + * SPDX-License-Identifier: BSD-3-Clause >>>>> > + */ >>>>> > + >>>>> > +/** >>>>> > +@page crypto_design ODP Design - Crypto API >>>>> > +For the implimentation of the ODP crypto API please see @ref >>>>> odp_crypto.h >>>>> > + >>>>> > +@tableofcontents >>>>> > + >>>>> > +@section revision_history Revision History >>>>> > +Revision | Issue Data | Description | Author >>>>> > +---------|------------|-------------|-------- >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic Functions | >>>>> Bill, Alexandru >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, started use >>>>> cases, miscellaneous formatting, API comments | Bill >>>>> > +0.3 | 4/22/2014 | Added Use Case section to include results >>>>> of design discussions held during ODP team calls | Bill >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto >>>>> sprint--action to resolve | Bill >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review >>>>> comments--ready for final review | Bill >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill >>>>> > + >>>>> > +@section introduction Introduction >>>>> > +This document describes the ODP v1.0 Crypto API. Cryptography is an >>>>> important part of data plane processing as many communication protocols >>>>> make use of cryptographic functions. Moreover, many SoCs incorporate >>>>> cryptographic hardware that can significantly accelerate these operations >>>>> compared to their software equivalents as well as provide validated >>>>> hardware functional correctness and security boundaries necessary for >>>>> system-level security certifications such as FIPS-140 Level 2 and above. >>>>> > +@section requirements Requirements >>>>> > +@subsection use_of_terms Use of Terms >>>>> > +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 [RFC 2119]( >>>>> https://tools.ietf.org/html/rfc2119). >>>>> > +@subsection uses_of_cryptography Uses of Cryptography >>>>> > +Crypto functions cover a range of uses and capabilities designed to >>>>> support data security, integrity, authentication, and non-repudiation. >>>>> > +@subsubsection data_security Data Security >>>>> > +Cryptography supports data security by making use of complex >>>>> mathematical transformations that are not feasibly reversible without >>>>> possession of the secret key used to encrypt message data. >>>>> > +@subsubsection data_integrity Data Integrity >>>>> > +Cryptography supports data integrity through the use of >>>>> cryptographic checksums (also known as secure hashes) that ensure the >>>>> recipient that message data has not been altered either accidentally or >>>>> maliciously while in transit. >>>>> > +@subsubsection data_authentication Data Authentication >>>>> > +Cryptography supports data authentication through the uses of >>>>> Message Authentication Codes (MACs) that enable the recipient to verify >>>>> that a message was sent from an authorized counterparty, and hence was not >>>>> forged. >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation >>>>> > +Cryptography supports data non-repudiation through the use of >>>>> digital signatures that enable a recipient or third party to verify the >>>>> identity of the sending party and prevents the sending party from later >>>>> denying that they originated a signed message. >>>>> > +@subsection scope Scope >>>>> > +ODP v1.0 crypto support is designed to provide a portable framework >>>>> for accessing SoC-specific cryptographic functions of most use to the data >>>>> plane. This is predominantly symmetric crypto operations used to support >>>>> the encryption and decryption of data at line rate using hardware >>>>> acceleration and offload. Specifically excluded in this support are public >>>>> key operations and other crypto functions mainly used in the control plane. >>>>> > +@subsection cryptographic_operations_in_the_data_plane >>>>> Cryptographic Operations in the Data Plane >>>>> > +ODP v1.0 crypto APIs cover the following areas: >>>>> > +@subsubsection ciphering Ciphering >>>>> > +Ciphering refers to mathematical transformations that use a secret >>>>> key to encipher data, transforming the original data (referred to as >>>>> plaintext) into ciphertext, thereby making it unintelligible to anyone not >>>>> in possession of the key. Similarly, ciphering is also used to decipher >>>>> data, allowing someone in possession of the correct key to transform >>>>> received ciphertext back into plaintext. Approved block ciphers are listed >>>>> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and >>>>> SHOULD be supported by each ODP implementation. >>>>> > +@subsubsection hasing Hashing >>>>> > +A hash is a cryptographic digest of a message that can be used to >>>>> represent it for comparison or integrity checking. Hash functions are >>>>> designed so that any alteration of a message will alter the hash and that >>>>> it is computationally infeasible to craft a message that generates the same >>>>> hash value as another message. Secure hash functions approved for >>>>> cryptographic use are listed by NIST [here]( >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and >>>>> SHOULD be supported by each ODP implementation. >>>>> > +@subsubsection zeroization Zeroization >>>>> > +To preserve the security of data, certain transient data held in >>>>> data buffers MUST be cleared to zeros upon buffer free. Such capability is >>>>> referred to as zeroization. ODP supports zeroization as a buffer pool >>>>> attribute. >>>>> > +@subsubsection random_number_generation Random Number Generation >>>>> > +Because cryptography relies heavily on “unguessable” keys of >>>>> various sorts, random number generation (RNG) is an integral part of >>>>> cryptographic processing. Random numbers are used in key generation, >>>>> initialization vectors (IVs), various types of padding bytes, and various >>>>> other uses collectively referred to as nonces, that serve to “harden” >>>>> cryptographic processing. >>>>> > + >>>>> > +There are two types of random number support of interest. Hardware >>>>> random data, also known as entropy, that is the result of inherently random >>>>> physical processes, and deterministic random bit generation (DRBG) that is >>>>> used in certain certified cryptographic operations. Approved DRBG >>>>> algorithms are listed in [NIST SP 800-90A]( >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not >>>>> specify which algorithms are available on a given implementation. As such >>>>> ODP implementations MAY use any approved DRGB algorithm but SHOULD support >>>>> at least one of them. Additionally, ODP implementations MUST NOT represent >>>>> non-approved algorithms as DRBG implementations. Validated algorithms are >>>>> listed in the [NIST DRBG Validation List]( >>>>> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >>>>> > + >>>>> > +@subsubsection capability_inquiry Capability Inquiry >>>>> > +To enable applications to adapt to the implementation models >>>>> offered across different SoC platforms, ODP provides APIs to allow >>>>> applications to inquire about underlying crypto capabilities. A given ODP >>>>> implementation may offer crypto as hardware features, software features, or >>>>> not available on a given platform. >>>>> > +@subsection cryptographic_algorithms Cryptographic Algorithms and >>>>> Protocols >>>>> > +A cryptographic algorithm is a mathematical transform that provides >>>>> one of the cryptographic operations described above. They in turn are used >>>>> as building blocks in creating cryptographic protocols. These are complete >>>>> sets of rules for how to exchange data securely using cryptography. Both >>>>> cryptographic algorithm and protocol design are highly specialized >>>>> disciplines that involve high levels of public scrutiny and validation. As >>>>> a result, applications simply make use of approved cryptographic algorithms >>>>> and protocols. >>>>> > +@subsection cryptographic_operations Cryptographic Operations >>>>> > +Cryptographic operations may be initiated by software or directly >>>>> by hardware as part of the RX or TX packet path processing. For ODP v1.0 >>>>> software-initiated cryptographic operations are the primary use case. ODP >>>>> provides APIs for performing data ciphering, hashing, random number >>>>> generation, and capability inquiry. >>>>> > +@subsection performance_expectations Performance Expectations >>>>> > +In the data plane, the total processing budget for a packet may >>>>> only be a few hundred cycles, so function invocation overhead MUST be kept >>>>> to a minimum. This has several implications. >>>>> > + >>>>> > +-# When work is dispatched to a thread, all information needed by >>>>> the thread to process the work request SHOULD be immediately at hand. >>>>> Ideally any context or variables needed for the operation have been >>>>> pre-warmed in the cache to avoid the latency hits associated with cache >>>>> misses. SoCs having hardware schedulers generally do this pre-staging of >>>>> data to minimize such latencies, and ODP implementations are expected to >>>>> exploit such platform capabilities whenever possible.\n\n >>>>> > + >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of >>>>> parameter passing and (depending on the implementation) SHOULD be inlined >>>>> as much as possible to avoid call overhead. One technique that has proven >>>>> useful is to allow for parameters to be passed as an explicit thread-local >>>>> static structure. Such use of “templating” means that a single function can >>>>> support a rich set of options but the caller can configure a template >>>>> matched to specific use and only vary the one or two parameters that differ >>>>> from call to call.\n\n >>>>> > + >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any >>>>> non-exception path function processing. Kernel calls and such are >>>>> acceptable only during one-time initialization logic or certain types of >>>>> unusual error recovery operations. Often the best way to handle the latter >>>>> is to pass the work to a dedicated recovery thread (or back to the control >>>>> plane) rather than attempting to handle the condition inline. For example, >>>>> a link-down condition will trigger various recovery actions that might best >>>>> be handled in this manner. >>>>> > + >>>>> > +@subsection use_by_existing_code Use by Existing Code >>>>> > +Most applications wishing to make use of ODP represent substantial >>>>> existing investment that must be preserved. Insofar as possible, ODP >>>>> functions need to be orthogonal to existing application environments and >>>>> structures to permit easy intermixing with pre-existing code. >>>>> > +@subsection data_references Data References >>>>> > +Packet data is inherently of variable length however it is often >>>>> more efficient to organize memory into fixed-sized buffers that can be >>>>> chained together on demand to contain packets. The application SHOULD >>>>> normally not need to be aware of such lower-level segmentation and should >>>>> be able to treat a packet as a single object. Alternately, especially when >>>>> dealing with existing code, data segmentation MUST be explicitly >>>>> specifiable via scatter/gather lists. For example, data encryption or >>>>> decryption may be invoked on a list of data segments as part of a single >>>>> function call. >>>>> >>>>> Every time you add a full stop for a sentence, you have to press return >>>>> and start typing the next sentence. >>>>> This means that diffs of future changes will be per sentence. >>>>> Doxygen will still concatenate this as a paragraph with no visual >>>>> difference in the result. >>>>> I think the above line will look like this: >>>>> >>>>> Packet data is inherently of variable length however it is often more >>>>> efficient to organize memory into fixed-sized buffers that can be chained >>>>> together on demand to contain packets. >>>>> The application SHOULD normally not need to be aware of such >>>>> lower-level segmentation and should be able to treat a packet as a single >>>>> object. >>>>> Alternately, especially when dealing with existing code, data >>>>> segmentation MUST be explicitly specifiable via scatter/gather lists. >>>>> For example, data encryption or decryption may be invoked on a list of >>>>> data segments as part of a single function call. >>>>> >>>>> >>>>> Cheers, >>>>> Anders >>>>> >>>>> > +@subsection chained_operations Chained Operations >>>>> > +Crypto operations such as hashing and encryption, or decryption and >>>>> verification, are very commonly used in combination. For ODP, it is >>>>> sufficient to support one cipher and one hash/authentication operation in a >>>>> single call and this combination MUST be supported to avoid the call and >>>>> dispatch overhead of separate invocations. >>>>> > +@subsection key_management Key Management and Session Data >>>>> > +Keying is an area of particular sensitivity in crypto processing >>>>> since keys are highly confidential and may be subject to legal requirements >>>>> for safeguarding within special hardware enclosures. >>>>> > + >>>>> > +A session is the security context used to represent an active set >>>>> of crypto operations that need to be applied to a flow on a >>>>> packet-by-packet basis. Generally a session is established upon detection >>>>> of a flow requiring crypto processing and retained for the life of that >>>>> flow. It has been noted that this can involve cooperative processing >>>>> between the control and data planes so several requirements stem from this: >>>>> > + >>>>> > +-# Session creation MAY need to be handled in an asynchronous >>>>> manner. This is to allow these to be created in batches by thread(s) that >>>>> specialize in this activity.\n\n >>>>> > + >>>>> > +-# Sessions MAY need to reference keying material indirectly via >>>>> key handling modules.\n\n >>>>> > + >>>>> > +-# Session creation MAY be performed by non-ODP code and >>>>> communicated to data plane routines that make use of ODP crypto functions >>>>> that need to reference the session information. >>>>> > + >>>>> > +ODP session APIs and data structures SHOULD be represented by >>>>> abstract data types that encapsulate implementation details for both >>>>> platform efficiency and to accommodate these needs. >>>>> > +Use Cases >>>>> > +For ODP v1.0 the major use cases of interest involve cryptographic >>>>> algorithm acceleration. Cryptographic protocol acceleration is reserved for >>>>> future ODP releases. >>>>> > +Buffers and Data Blocks >>>>> > +Cryptographic operations may be performed directly on data >>>>> contained in ODP packet buffers, or it may be performed on “raw” data >>>>> blocks operating entirely under application control. Note that when using >>>>> raw data blocks not managed by ODP, the application must perform any needed >>>>> zeroization using either its own or ODP-supplied buffer zeroization >>>>> functions. ODP automatic support for zeroization is limited to ODP-managed >>>>> buffers. ODP buffers allocated from buffer pools designated for crypto use >>>>> will also have whatever alignment and/or addressability attributes needed >>>>> by the implementation to support crypto API calls. >>>>> > + >>>>> > +Note: Some implementations may have difficulty dealing with >>>>> application buffer addresses, as these may be virtual addresses that are >>>>> mapped discontiguously into physical memory. For such implementations, >>>>> memory SHOULD be allocated contiguously and MAY need to be “registered” to >>>>> have proper addressability for crypto operations. This area of the design >>>>> will be updated based on experience in dealing with different crypto >>>>> implementations that have such requirements. >>>>> > +Synchronization >>>>> > +ODP operations fall into one of three categories: >>>>> > + >>>>> > +-# Inline (Synchronous): Upon return from a call the operation is >>>>> complete. Operation is thus completely synchronous to the caller. Inline >>>>> is the appropriate model when the invoked function takes relatively few >>>>> cycles or when the caller cannot feasibly progress without the results of >>>>> the invoked function.\n\n >>>>> > + >>>>> > +-# Parallel: Upon return from a call the operation has been >>>>> initiated, but is expected to complete shortly. The caller continues to >>>>> execute until it needs the result at which point it waits to complete the >>>>> parallel operation. The effect is as if the operation were inline except >>>>> that the caller was able to execute in parallel with the operation for some >>>>> application-determined period of time. Parallel is the appropriate model >>>>> when the operation being performed is relatively short (a few dozen up to >>>>> perhaps 100 or 200 cycles) and the caller can usefully accomplish other >>>>> processing on the same unit of work while the parallel operation is in >>>>> progress, but not enough to justify the overhead of a formal queued work >>>>> dispatch.\n\n >>>>> > + >>>>> > +-# Offloaded (Asynchronous): Upon return from the call the >>>>> operation has been queued for execution. A completion event will be queued >>>>> back to the scheduler when the event is completed. Offload is the >>>>> appropriate model when the invoked function will take a substantial amount >>>>> of cycles (thousands to tens of thousands) allowing the invoking >>>>> thread/core to service other work until the operation completes. For >>>>> offloaded work, completion is indicated by a completion event being posted >>>>> back to an application-designated completion queue. Upon receipt the unit >>>>> of work that initiated the offloaded operation continues processing with >>>>> the results of the call. >>>>> > + >>>>> > +The synchronization models of interest are summarized in Figure 1: >>>>> > + >>>>> > + >>>>> > + >>>>> > +Note: Because few implementations are expected to offer the >>>>> Parallel mode of operation as described above, this mode is reserved for >>>>> potential future use. For ODP v1.0 only synchronous and asynchronous crypto >>>>> operations are defined. >>>>> > +@section functional_definition Functional Definition >>>>> > +@subsection abstract_data_types Abstract data types >>>>> > +The following enumerations define various algorithms used for >>>>> ciphering and hashing. These are the basic operations applied to input data. >>>>> > + >>>>> > +A particular ODP implementation should map these values to the >>>>> actual information to be passed to the crypto engine. As such, the actual >>>>> values of these enums is implementation-defined. >>>>> > + >>>>> > +Cipher algorithm encoding specifies the algorithm and cipher mode >>>>> employed (as per security relevant RFCs - [4305]( >>>>> http://tools.ietf.org/html/rfc4305), [4868]( >>>>> http://tools.ietf.org/html/rfc4868), [4494]( >>>>> http://tools.ietf.org/html/rfc4494)). >>>>> > + >>>>> > +@code >>>>> > +enum odp_cipher_alg { >>>>> > + ODP_CIPHER_ALG_NULL, >>>>> > + ODP_CIPHER_ALG_DES, >>>>> > + ODP_CIPHER_ALG_3DES_CBC, >>>>> > + ODP_CIPHER_ALG_AES_CBC, >>>>> > + ODP_CIPHER_ALG_AES_GCM, >>>>> > + ODP_CIPHER_ALG_AES_CTR, >>>>> > + ODP_CIPHER_ALG_KASUMI, >>>>> > + ODP_CIPHER_ALG_SNOW, >>>>> > + ... >>>>> > +}; >>>>> > +@endcode >>>>> > + >>>>> > +Authorization algorithm encoding specifies the algorithm and the >>>>> length of the authorization used (as per security relevant RFCs - [4305]( >>>>> http://tools.ietf.org/html/rfc4305), [4868]( >>>>> http://tools.ietf.org/html/rfc4868), [4494]( >>>>> http://tools.ietf.org/html/rfc4494)): >>>>> > + >>>>> > +@code >>>>> > +enum odp_auth_alg { >>>>> > + ODP_AUTH_ALG_NULL, >>>>> > + ODP_AUTH_MD5_96, >>>>> > + ODP_AUTH_ALG_SHA1_96, >>>>> > + ODP_AUTH_ALG_SHA1_160 >>>>> > + ODP_AUTH_ALG_SHA2_256_128, >>>>> > + ODP_AUTH_ALG_SHA2_384_192, >>>>> > + ODP_AUTH_ALG_SHA2_512_256, >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, >>>>> > + ODP_AUTH_ALG_SNOW, >>>>> > + ODP_AUTH_ALG_KASUMI, >>>>> > + ... >>>>> > +}; >>>>> > + >>>>> > +typedef union odp_crypto_alg_t { >>>>> > + enum odp_cipher_alg cipher; >>>>> > + enum odp_auth_alg auth; >>>>> > +}odp_crypto_alg_t; >>>>> > +@endcode >>>>> > +@subsection parameter_structures Parameter Structures >>>>> > +@subsubsection crypto_sessions Crypto Sessions >>>>> > +The following structure describes a crypto session. All packets / >>>>> raw data buffers processed in a session share the data that defines the >>>>> session. A crypto session is defined by: >>>>> > + >>>>> > +- Operation type : encode or decode\n\n >>>>> > + >>>>> > +- Algorithms specifications, keys and , if required, initialization >>>>> vectors. When initialization vectors are not provided and they should be >>>>> provided automatically by the crypto engine.\n\n >>>>> > + >>>>> > +- The operation mode: synchronous or asynchronous. Synchronous >>>>> operation blocks the caller until an operation status and result are >>>>> available. In synchronous mode there is at most only one outstanding crypto >>>>> operation in the calling thread. In asynchronous mode, the caller starts >>>>> the crypto operation and later it may receive the status and the result >>>>> together with a request context. The operation status and result may also >>>>> be received by a different thread.\n\n >>>>> > + >>>>> > +- Operation mode parameters: For asynchronous operation a >>>>> completion event containing the status, the result and the request context >>>>> is enqueued to a completion queue. In case the queue is under the scheduler >>>>> control, the scheduler determines who will receive the completion event and >>>>> when. When the completion queue is not scheduled, the thread which is >>>>> supposed to get the operation output has to explicitly poll the completion >>>>> queue. >>>>> > + >>>>> > +Note that this is an abstract data type and its structure is >>>>> implementation-specific. The layout shown here is for illustrative purposes >>>>> and the actual layout will vary from one implementation to the next to most >>>>> closely align with the structures needed by the underlying SoC platform. >>>>> Applications set and reference fields in the session structure via accessor >>>>> functions that hide the actual layout. >>>>> > + >>>>> > +@code >>>>> > +typedef enum odp_crypto_op_t { >>>>> > + ODP_CRYPTO_OP_ENCODE, >>>>> > + ODP_CRYPTO_OP_DECODE >>>>> > +}odp_crypto_op_t; >>>>> > + >>>>> > +typedef struct odp_key_t { >>>>> > +}odp_key_t; >>>>> > + >>>>> > +typedef struct odp_crypto_session_t { >>>>> > + odp_crypto_op_t op; >>>>> > + struct { >>>>> > + enum odp_cipher_alg cipher_alg; >>>>> > + odp_key_t *key; >>>>> > + uint8_t *iv; >>>>> > + size_t iv_len; >>>>> > + } cipher; >>>>> > + >>>>> > + struct { >>>>> > + enum odp_auth_alg auth_alg; >>>>> > + enum odp_auth_len auth_len; >>>>> > + odp_key_t *key; >>>>> > + } auth; >>>>> > + >>>>> > + enum odp_crypto_op_mode { >>>>> > + ODP_CRYPTO_SYNC, >>>>> > + ODP_CRYPTO_ASYNC, >>>>> > + } op_mode; >>>>> > + >>>>> > + struct { >>>>> > + uint32_t timeout; >>>>> > + struct { >>>>> > + odp_queue_t completion_queue; >>>>> > + } async; >>>>> > + } op_mode_params; >>>>> > + >>>>> > + odp_session_proc_info_t session_proc_info; >>>>> > +} odp_crxsypto_session_t; >>>>> > +@endcode >>>>> > + >>>>> > +The completion queue contained in the session structure is an >>>>> in/out parameter. If provided, then the queue specified is associated with >>>>> the session and is used to ensure order preservation on that session. If >>>>> not provided, one is created and returned to the caller. Note that this >>>>> completion queue is used to order operations performed on this crypto >>>>> session. It should not be confused with the completion queue specified on >>>>> the odp_crypto_session_create() call (see below) that is used to control >>>>> whether that call is itself processed in a synchronous vs. asynchronous >>>>> manner. >>>>> > + >>>>> > +The following structure comprises processing information. This is >>>>> logically divided in two parts: >>>>> > + >>>>> > +- Processing input info - When crypto engine provides support for >>>>> protocol processing, this information is provided in a higher level common >>>>> protocol terminology form and a particular implementation should be able to >>>>> derive everything it needs from this definition. In addition, for crypto >>>>> engines able to automate tasks like memory allocation for the output a >>>>> buffer pool id may be specified.\n\n >>>>> > + >>>>> > +- Processing output information - statistics about processed >>>>> bytes/packets. These are useful when a session expiration is based on >>>>> traffic volume. These statistics may be updated by the software or by the >>>>> hardware crypto engine. >>>>> > + >>>>> > +Again, this is an abstract type whose specific layout will vary >>>>> based on implementation considerations. Access to fields contained in the >>>>> structure is only via accessor functions. >>>>> > + >>>>> > +@code >>>>> > +typedef struct { >>>>> > + uint64_t pkts_processed; >>>>> > + uint64_t bytes_processed; >>>>> > + uint64_t pkts_errored; >>>>> > + uint64_t bytes_errored; >>>>> > + >>>>> > + odp_buffer_pool_t out_pool; >>>>> > + >>>>> > +} odp_session_proc_info_t; >>>>> > +@endcode >>>>> > + >>>>> > +This enumeration defines which operations are applied and the order. >>>>> > + >>>>> > +@code >>>>> > +enum odp_crypto_combination { >>>>> > +ODP_CRYPTO_CIPHER_ONLY, >>>>> > + ODP_CRYPTO_AUTH_ONLY, >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT >>>>> > +}; >>>>> > +@endcode >>>>> > + >>>>> > +This structure defines a contiguous segment in the input data which >>>>> starts at offset offset and is len bytes long. >>>>> > + >>>>> > +@code >>>>> > +struct odp_data_range { >>>>> > + unsigned offset:16; >>>>> > + unsigned len:16; >>>>> > +}; >>>>> > +@endcode >>>>> > + >>>>> > +@subsection api_functions API Functions >>>>> > + >>>>> > +@subsubfunction Session Creation >>>>> > + >>>>> > +This function is used to create a crypto session. The required >>>>> parameters are : >>>>> > + >>>>> > +- Operation : encode/decode >>>>> > +- Processing info : cipher/auth/both >>>>> > +- Preferred mode : sync or async. >>>>> > +- Algorithms suites, keys and optional IV >>>>> > + >>>>> > +Session creation can be synchronous or asynchronous. Completion >>>>> event argument is used to return the status and the session handle. When >>>>> completion queue is not provided (synchronous call), the completion event >>>>> is available upon function call return. When completion queue is provided >>>>> (asynchronous call), the completion event is placed on the completion queue. >>>>> > + >>>>> > +@code >>>>> > +typedef uint64_t odp_crypto_session_t; >>>>> > + >>>>> > +struct odp_session_params { >>>>> > + enum odp_crypto_operation op; >>>>> > + odp_session_proc_info_t proc_info; >>>>> > + enum odp_crypto_op_mode pref_mode; >>>>> > + enum odp_cipher_alg cipher_alg; >>>>> > + odp_key_t *cipher_key; >>>>> > + uint8_t *iv; >>>>> > + size_t iv_len; >>>>> > + enum odp_auth_alg auth_alg; >>>>> > + odp_key_t *auth_key; >>>>> > +}; >>>>> > + >>>>> > +enum odp_crypto_ses_create_err { >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, >>>>> > + /* Session creation error codes */ >>>>> > +}; >>>>> > + >>>>> > +void >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t >>>>> completion_event, enum odp_crypto_ses_create_err *status); >>>>> > + >>>>> > +void >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t >>>>> completion_event, odp_crypto_session_t *handle); >>>>> > + >>>>> > +int odp_crypto_session_create( >>>>> > + struct odp_session_params *params, >>>>> > + odp_buffer_t completion_event, >>>>> > + odp_queue_t completion_queue); >>>>> > +@endcode >>>>> > +@subsection crypto_operation Crypto Operation >>>>> > + >>>>> > +Crypto operations are described by a parameter structure: >>>>> > +@code >>>>> > +struct odp_crypto_op_params { >>>>> > + odp_crypto_session_t session; >>>>> > + odp_packet_t pkt; >>>>> > + odp_packet_t out_pkt; >>>>> > + uint8_t *override_iv_ptr; >>>>> > + unsigned hash_result_offset; >>>>> > + struct odp_data_range cipher_range; >>>>> > + struct odp_data_range auth_range; >>>>> > +}; >>>>> > +@endcode >>>>> > + >>>>> > +<table> >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> >>>>> > +<tr><td>session</td><td>Session to perform the operation</td></tr> >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be >>>>> returned as the result of the operation. There are three different ways >>>>> this parameter is used, depending on the mode of operation requested by the >>>>> caller and the capabilities of the underlying implementation:\n\n >>>>> > + >>>>> > +-# If out_pkt is the same as pkt this indicates that the operation >>>>> should be performed in place.\n\n >>>>> > +-# If out_pkt is different from pkt this indicates that output >>>>> should be placed in the buffer supplied by the caller.\n\n >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied on input) >>>>> this indicates that an output buffer should be allocated by the operation >>>>> and returned as part of the completion event associated with the >>>>> operation.\n\n >>>>> > + >>>>> > +Note that not every implementation will support all of these modes >>>>> and MAY require that one mode be used in preference to others. Any such >>>>> implementation restrictions are communicated as output from session >>>>> creation.</td></tr> >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this >>>>> request</td></tr> >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the output packet >>>>> where the hash result should be stored.</td></tr> >>>>> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the >>>>> data to be processed for ciphering.</td></tr> >>>>> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the >>>>> data to be processed for authentication.</td></tr> >>>>> > +</table> >>>>> > + >>>>> > +The crypto operation is initiated with a single call that passes >>>>> the parameters for the operation and an event (for asynchronous completion). >>>>> > +@code >>>>> > +int odp_crypto_operation( >>>>> > + struct odp_crypto_op_params *params, >>>>> > + odp_buffer_t completion_event); >>>>> > +@endcode >>>>> > + >>>>> > +Parameter | Meaning >>>>> > +----------|-------- >>>>> > +params | The parameter structure describing the crypto operation >>>>> to be performed. >>>>> > +completion_event | The event delivered on completion. It provides >>>>> information about the status of the operation, result and request context. >>>>> In synchronous mode the event is available upon function call return. In >>>>> asynchronous mode, the event is placed on the session / operation >>>>> completion queue when the operation finished. >>>>> > + >>>>> > +Upon return the return code indicates whether the operation was >>>>> synchronous or asynchronous, or if an error occurred that prevented the >>>>> operation from being performed. >>>>> > + >>>>> > +Get session operation : >>>>> > +@code >>>>> > +odp_crypto_op_t >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); >>>>> > +@endcode >>>>> > + >>>>> > +Get session cipher information : >>>>> > +@code >>>>> > +odp_cipher_alg >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); >>>>> > +@endcode >>>>> > + >>>>> > +Get session authentication information : >>>>> > +@code >>>>> > +odp_auth_alg >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >>>>> > +@endcode >>>>> > + >>>>> > +Change session IV : >>>>> > +@code >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t >>>>> *iv); >>>>> > +@emdcode >>>>> > + >>>>> > +Change cipher or/and hash keys: >>>>> > +@code >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t >>>>> *key); >>>>> > +@endcode >>>>> > + >>>>> > +Destroy crypto session. All pending operations are cancelled. >>>>> > +@code >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); >>>>> > +@endcode >>>>> > + >>>>> > +Get completion event information - algorithm error, output and >>>>> context. Note that implementations MAY define their own specific error >>>>> codes that have meaning in that context. For application portability it is >>>>> sufficient to know whether an operation completed successfully or >>>>> experienced an error of some sort. >>>>> > +@code >>>>> > +enum crypto_alg_err { >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >>>>> > +}; >>>>> > + >>>>> > +enum crypto_hw_err { >>>>> > + ODP_CRYPTO_HW_ERR_NONE, >>>>> > + ODP_CRYPTO_HW_ERR_DMA, >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >>>>> > +}; >>>>> > + >>>>> > +struct odp_crypto_compl_status { >>>>> > + odp_crypto_alg_t alg; >>>>> > + enum crypto_alg_err alg_err; >>>>> > + enum crypto_hw_err hw_err; >>>>> > +}; >>>>> > + >>>>> > +void >>>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, >>>>> > + struct odp_crypto_compl_status *auth, >>>>> > + struct odp_crypto_compl_status *cipher); >>>>> > +@endcode >>>>> > + >>>>> > +Returns the output packet handle associated with the completion >>>>> event : >>>>> > +@code >>>>> > +odp_packet_t >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >>>>> > +@endcode >>>>> > + >>>>> > +Sets a context handle to be returned with the completion event : >>>>> > +@code >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, >>>>> odp_compl_ctx_t *ctx); >>>>> > +@endcode >>>>> > + >>>>> > +Returns the context associated with the completion event : >>>>> > +@code >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t >>>>> completion_event); >>>>> > +@endcode >>>>> > + >>>>> > +This section describes the API/Interface being defined at a >>>>> functional level in technical detail. Sub-sections include header file >>>>> names, where implementation files are expected to reside in the ODP git >>>>> tree, as well as the name, parameters, abstract data types, functionality, >>>>> return codes, and exception conditions of each function call defined by the >>>>> API/Interface. Appropriate diagrams, tables, etc. should be used to allow >>>>> the programmer tasked with implementing the API/Interface to understand the >>>>> function to be implemented as well as error conditions, corner cases, >>>>> performance requirements, etc. needed to implement the described >>>>> API/Interface in a functionally correct and efficient manner. >>>>> > + >>>>> > +@subsubsection random_number_functions Random Number Functions >>>>> > +As noted earlier, random number support consists of two functions: >>>>> > +@code >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool >>>>> use_entropy); >>>>> > + >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >>>>> > +@endcode >>>>> > + >>>>> > +The difference is that the first provides access to hardware random >>>>> number functions that return true random data. This is typically used for >>>>> seed values. The second provides a deterministic random bit generator >>>>> conforming to NIST standards and is used by various crypto protocols and >>>>> algorithms. The use_entropy parameter on odp_hw_random_get is used to >>>>> disable any hardware pre-processing normally provided by the function and >>>>> is mainly intended to be used for testing/validation purposes. >>>>> > + >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions >>>>> > +To support zeroization a buffer may be allocated with an >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be >>>>> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to >>>>> odp_buffer_pool_create() that specifies that all buffers allocated from >>>>> this pool must be zeroized upon free. Essentially, the buffer security >>>>> attribute is set by default from the attributes of the buffer pool that it >>>>> is allocated from. >>>>> > + >>>>> > +@subsubsection capability_inquiry Capability Inquiry >>>>> > +To enable applications to determine crypto capabilities. >>>>> > +@code >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); >>>>> > +@endcode >>>>> > + >>>>> > +Inquires whether the specified crypto and auth algorithms are >>>>> supported. Responses include: >>>>> > +- ODP_HW_SYNC_SUPPORT >>>>> > +- ODP_HW_ASYNC_SUPPORT >>>>> > +- ODP_SW_SYNC_SUPPORT >>>>> > +- ODP_SW_ASYNC_SUPPORT >>>>> > +- ODP_NO_SUPPORT >>>>> > + >>>>> > +HW support means the combination is supported in hardware, SW >>>>> support means the combination is supported in software by the >>>>> implementation. No support means the combination is not supported by the >>>>> implementation. The SYNC and ASYNC return options can help the application >>>>> decide how to invoke these functions, or it can just check whether or not >>>>> the response is ODP_NO_SUPPORT. >>>>> > + >>>>> > +@section implementation_considerations Implementation Considerations >>>>> > +One of the main purposes for the ODP crypto APIs is to provide >>>>> portable access across different SoCs whose hardware crypto capabilities >>>>> largely overlap but vary in terms of their implementation details. As a >>>>> result, implementations need not provide software fill-ins for specific >>>>> cryptographic features that are not available as hardware features on that >>>>> platform. Presumably applications needing specific features will select >>>>> platforms on which these features are present. Therefore, while all APIs >>>>> specified here MUST exist in each conforming ODP implementation, it is >>>>> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response >>>>> to calls requesting crypto features not present on that platform. >>>>> > + >>>>> > +For example, the linux-generic ODP implementation may only >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature >>>>> not present error code for any other cipher. This indication will also be >>>>> returned on that platform in response to odp_crypto_inquire calls for >>>>> non-null cipher algorithms. >>>>> > + >>>>> > +@section verification Verification/Testing >>>>> > +This section describes the verification/test cases needed to ensure >>>>> that the defined functionality is implemented correctly and performs >>>>> adequately. This should be at a level of detail such that the programmer >>>>> tasked with writing test scripts/programs to verify the implementation(s) >>>>> of the defined functions can be written to ensure that all relevant >>>>> functional variants and error/exception cases are properly tested. >>>>> > + >>>>> > +This section needs to be completed before API testing begins. >>>>> > + >>>>> > +*/ >>>>> > \ No newline at end of file >>>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png >>>>> > new file mode 100644 >>>>> > index >>>>> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >>>>> > GIT binary patch >>>>> > literal 17179 >>>>> > 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 >>>>> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b >>>>> > >>>>> > literal 0 >>>>> > HcmV?d00001 >>>>> > >>>>> > -- >>>>> > 1.8.3.2 >>>>> > >>>>> > >>>>> > _______________________________________________ >>>>> > lng-odp mailing list >>>>> > lng-odp@lists.linaro.org >>>>> > http://lists.linaro.org/mailman/listinfo/lng-odp >>>>> >>>> >>>> >>>> _______________________________________________ >>>> lng-odp mailing list >>>> lng-odp@lists.linaro.org >>>> http://lists.linaro.org/mailman/listinfo/lng-odp >>>> >>>> >>> >>> >>> -- >>> *Mike Holmes* >>> Linaro Technical Manager / Lead >>> LNG - ODP >>> >> >> > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP >
On 2014-07-03 10:01, Bill Fischofer wrote: > The people who review and approve these docs want to see docs with things > like change bars, not patches. The patch mechanism is simply inappropriate > for this activity and we shouldn't try to force-fit it for something it's > not designed to address. > > Again, the primary users of the odp-architecture git repository are those > who want access to complete docs, not those who are creating, reviewing, > and approving them. That's why we have a separate repository from the main > odp git repository so that "patches" can be handled differently between > them. That is why we use doxygen so that people reviewing for approval can look at the end result... However, isn't it better if anyone on the list can review the patch and send patches when that is needed? SC approval should only be required for major revisions. Possibly only a final read through review for every ODP release. > > My preference would be to grant push rights to those adding items to this > repository rather than going through the artifice of patches. It would be > more straightforward and consistent with the actual workflow. Git would > still be doing version tracking so it would be possible to see the complete > change history for any given doc easily. We should use git as a revision control system as it is, to allow us to make small changes when we discover them. Cheers, Anders > > > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > > > I agree we need approval, but approval can be of a review of the patch to > > the text. > > > > I hope we don't need wholesale changes that need a complete re write and > > thus approval of a whole new document. For example a new patch which may > > add a new function to an API but we would hopefully not change any of the > > existing text in the main. > > > > Thus we can then make changes in manageable chunks, I agree that large > > new additions will come in via a pre approved hugue patch, created from a > > sequence of sprints just have we have done so far. > > > > I would argue that these small changes are likely given the additions > > already discovered by starting the validation testing work and the feedback > > it is generating with the need to be more specific in architectural areas. > > > > Mike > > > > > > On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > >> Design documents require approval by those who aren't going to be > >> reviewing patches. This is different from code. My understanding of the > >> purpose of the odp-architecture repository is to provide a convenient means > >> of distributing documentation and making it available in various forms > >> (Doxygen, PDF) for access through the ODP web site as well as being > >> downloaded. > >> > >> So in this sense we're just using Git as a publication mechanism for docs. > >> > >> > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes <mike.holmes@linaro.org> > >> wrote: > >> > >>> I am confused git is a change control mechanism, and I really hope they > >>> do get patched, how will we improve the content ? > >>> > >>> > >>> On 3 July 2014 10:03, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >>> > >>>> Git is a publication mechanism for docs, not a change control > >>>> mechanism. Docs will not be 'patched'. New versions will replace old ones > >>>> as they are approved. > >>>> > >>>> > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell <anders.roxell@linaro.org > >>>> > wrote: > >>>> > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > >>>>> > --- > >>>>> > crypto_design.dox | 455 > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes > >>>>> > 2 files changed, 455 insertions(+) > >>>>> > create mode 100644 crypto_design.dox > >>>>> > create mode 100644 images/syncmodels.png > >>>>> > > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox > >>>>> > new file mode 100644 > >>>>> > index 0000000..1ad2ac6 > >>>>> > --- /dev/null > >>>>> > +++ b/crypto_design.dox > >>>>> > @@ -0,0 +1,455 @@ > >>>>> > +/* Copyright (c) 2043, Linaro Limited > >>>>> > + * All rights reserved > >>>>> > + * > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause > >>>>> > + */ > >>>>> > + > >>>>> > +/** > >>>>> > +@page crypto_design ODP Design - Crypto API > >>>>> > +For the implimentation of the ODP crypto API please see @ref > >>>>> odp_crypto.h > >>>>> > + > >>>>> > +@tableofcontents > >>>>> > + > >>>>> > +@section revision_history Revision History > >>>>> > +Revision | Issue Data | Description | Author > >>>>> > +---------|------------|-------------|-------- > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic Functions | > >>>>> Bill, Alexandru > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, started use > >>>>> cases, miscellaneous formatting, API comments | Bill > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to include results > >>>>> of design discussions held during ODP team calls | Bill > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto > >>>>> sprint--action to resolve | Bill > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review > >>>>> comments--ready for final review | Bill > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > >>>>> > + > >>>>> > +@section introduction Introduction > >>>>> > +This document describes the ODP v1.0 Crypto API. Cryptography is an > >>>>> important part of data plane processing as many communication protocols > >>>>> make use of cryptographic functions. Moreover, many SoCs incorporate > >>>>> cryptographic hardware that can significantly accelerate these operations > >>>>> compared to their software equivalents as well as provide validated > >>>>> hardware functional correctness and security boundaries necessary for > >>>>> system-level security certifications such as FIPS-140 Level 2 and above. > >>>>> > +@section requirements Requirements > >>>>> > +@subsection use_of_terms Use of Terms > >>>>> > +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 [RFC 2119]( > >>>>> https://tools.ietf.org/html/rfc2119). > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography > >>>>> > +Crypto functions cover a range of uses and capabilities designed to > >>>>> support data security, integrity, authentication, and non-repudiation. > >>>>> > +@subsubsection data_security Data Security > >>>>> > +Cryptography supports data security by making use of complex > >>>>> mathematical transformations that are not feasibly reversible without > >>>>> possession of the secret key used to encrypt message data. > >>>>> > +@subsubsection data_integrity Data Integrity > >>>>> > +Cryptography supports data integrity through the use of > >>>>> cryptographic checksums (also known as secure hashes) that ensure the > >>>>> recipient that message data has not been altered either accidentally or > >>>>> maliciously while in transit. > >>>>> > +@subsubsection data_authentication Data Authentication > >>>>> > +Cryptography supports data authentication through the uses of > >>>>> Message Authentication Codes (MACs) that enable the recipient to verify > >>>>> that a message was sent from an authorized counterparty, and hence was not > >>>>> forged. > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation > >>>>> > +Cryptography supports data non-repudiation through the use of > >>>>> digital signatures that enable a recipient or third party to verify the > >>>>> identity of the sending party and prevents the sending party from later > >>>>> denying that they originated a signed message. > >>>>> > +@subsection scope Scope > >>>>> > +ODP v1.0 crypto support is designed to provide a portable framework > >>>>> for accessing SoC-specific cryptographic functions of most use to the data > >>>>> plane. This is predominantly symmetric crypto operations used to support > >>>>> the encryption and decryption of data at line rate using hardware > >>>>> acceleration and offload. Specifically excluded in this support are public > >>>>> key operations and other crypto functions mainly used in the control plane. > >>>>> > +@subsection cryptographic_operations_in_the_data_plane > >>>>> Cryptographic Operations in the Data Plane > >>>>> > +ODP v1.0 crypto APIs cover the following areas: > >>>>> > +@subsubsection ciphering Ciphering > >>>>> > +Ciphering refers to mathematical transformations that use a secret > >>>>> key to encipher data, transforming the original data (referred to as > >>>>> plaintext) into ciphertext, thereby making it unintelligible to anyone not > >>>>> in possession of the key. Similarly, ciphering is also used to decipher > >>>>> data, allowing someone in possession of the correct key to transform > >>>>> received ciphertext back into plaintext. Approved block ciphers are listed > >>>>> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and > >>>>> SHOULD be supported by each ODP implementation. > >>>>> > +@subsubsection hasing Hashing > >>>>> > +A hash is a cryptographic digest of a message that can be used to > >>>>> represent it for comparison or integrity checking. Hash functions are > >>>>> designed so that any alteration of a message will alter the hash and that > >>>>> it is computationally infeasible to craft a message that generates the same > >>>>> hash value as another message. Secure hash functions approved for > >>>>> cryptographic use are listed by NIST [here]( > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and > >>>>> SHOULD be supported by each ODP implementation. > >>>>> > +@subsubsection zeroization Zeroization > >>>>> > +To preserve the security of data, certain transient data held in > >>>>> data buffers MUST be cleared to zeros upon buffer free. Such capability is > >>>>> referred to as zeroization. ODP supports zeroization as a buffer pool > >>>>> attribute. > >>>>> > +@subsubsection random_number_generation Random Number Generation > >>>>> > +Because cryptography relies heavily on “unguessable” keys of > >>>>> various sorts, random number generation (RNG) is an integral part of > >>>>> cryptographic processing. Random numbers are used in key generation, > >>>>> initialization vectors (IVs), various types of padding bytes, and various > >>>>> other uses collectively referred to as nonces, that serve to “harden” > >>>>> cryptographic processing. > >>>>> > + > >>>>> > +There are two types of random number support of interest. Hardware > >>>>> random data, also known as entropy, that is the result of inherently random > >>>>> physical processes, and deterministic random bit generation (DRBG) that is > >>>>> used in certain certified cryptographic operations. Approved DRBG > >>>>> algorithms are listed in [NIST SP 800-90A]( > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not > >>>>> specify which algorithms are available on a given implementation. As such > >>>>> ODP implementations MAY use any approved DRGB algorithm but SHOULD support > >>>>> at least one of them. Additionally, ODP implementations MUST NOT represent > >>>>> non-approved algorithms as DRBG implementations. Validated algorithms are > >>>>> listed in the [NIST DRBG Validation List]( > >>>>> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > >>>>> > + > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > >>>>> > +To enable applications to adapt to the implementation models > >>>>> offered across different SoC platforms, ODP provides APIs to allow > >>>>> applications to inquire about underlying crypto capabilities. A given ODP > >>>>> implementation may offer crypto as hardware features, software features, or > >>>>> not available on a given platform. > >>>>> > +@subsection cryptographic_algorithms Cryptographic Algorithms and > >>>>> Protocols > >>>>> > +A cryptographic algorithm is a mathematical transform that provides > >>>>> one of the cryptographic operations described above. They in turn are used > >>>>> as building blocks in creating cryptographic protocols. These are complete > >>>>> sets of rules for how to exchange data securely using cryptography. Both > >>>>> cryptographic algorithm and protocol design are highly specialized > >>>>> disciplines that involve high levels of public scrutiny and validation. As > >>>>> a result, applications simply make use of approved cryptographic algorithms > >>>>> and protocols. > >>>>> > +@subsection cryptographic_operations Cryptographic Operations > >>>>> > +Cryptographic operations may be initiated by software or directly > >>>>> by hardware as part of the RX or TX packet path processing. For ODP v1.0 > >>>>> software-initiated cryptographic operations are the primary use case. ODP > >>>>> provides APIs for performing data ciphering, hashing, random number > >>>>> generation, and capability inquiry. > >>>>> > +@subsection performance_expectations Performance Expectations > >>>>> > +In the data plane, the total processing budget for a packet may > >>>>> only be a few hundred cycles, so function invocation overhead MUST be kept > >>>>> to a minimum. This has several implications. > >>>>> > + > >>>>> > +-# When work is dispatched to a thread, all information needed by > >>>>> the thread to process the work request SHOULD be immediately at hand. > >>>>> Ideally any context or variables needed for the operation have been > >>>>> pre-warmed in the cache to avoid the latency hits associated with cache > >>>>> misses. SoCs having hardware schedulers generally do this pre-staging of > >>>>> data to minimize such latencies, and ODP implementations are expected to > >>>>> exploit such platform capabilities whenever possible.\n\n > >>>>> > + > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive amounts of > >>>>> parameter passing and (depending on the implementation) SHOULD be inlined > >>>>> as much as possible to avoid call overhead. One technique that has proven > >>>>> useful is to allow for parameters to be passed as an explicit thread-local > >>>>> static structure. Such use of “templating” means that a single function can > >>>>> support a rich set of options but the caller can configure a template > >>>>> matched to specific use and only vary the one or two parameters that differ > >>>>> from call to call.\n\n > >>>>> > + > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any > >>>>> non-exception path function processing. Kernel calls and such are > >>>>> acceptable only during one-time initialization logic or certain types of > >>>>> unusual error recovery operations. Often the best way to handle the latter > >>>>> is to pass the work to a dedicated recovery thread (or back to the control > >>>>> plane) rather than attempting to handle the condition inline. For example, > >>>>> a link-down condition will trigger various recovery actions that might best > >>>>> be handled in this manner. > >>>>> > + > >>>>> > +@subsection use_by_existing_code Use by Existing Code > >>>>> > +Most applications wishing to make use of ODP represent substantial > >>>>> existing investment that must be preserved. Insofar as possible, ODP > >>>>> functions need to be orthogonal to existing application environments and > >>>>> structures to permit easy intermixing with pre-existing code. > >>>>> > +@subsection data_references Data References > >>>>> > +Packet data is inherently of variable length however it is often > >>>>> more efficient to organize memory into fixed-sized buffers that can be > >>>>> chained together on demand to contain packets. The application SHOULD > >>>>> normally not need to be aware of such lower-level segmentation and should > >>>>> be able to treat a packet as a single object. Alternately, especially when > >>>>> dealing with existing code, data segmentation MUST be explicitly > >>>>> specifiable via scatter/gather lists. For example, data encryption or > >>>>> decryption may be invoked on a list of data segments as part of a single > >>>>> function call. > >>>>> > >>>>> Every time you add a full stop for a sentence, you have to press return > >>>>> and start typing the next sentence. > >>>>> This means that diffs of future changes will be per sentence. > >>>>> Doxygen will still concatenate this as a paragraph with no visual > >>>>> difference in the result. > >>>>> I think the above line will look like this: > >>>>> > >>>>> Packet data is inherently of variable length however it is often more > >>>>> efficient to organize memory into fixed-sized buffers that can be chained > >>>>> together on demand to contain packets. > >>>>> The application SHOULD normally not need to be aware of such > >>>>> lower-level segmentation and should be able to treat a packet as a single > >>>>> object. > >>>>> Alternately, especially when dealing with existing code, data > >>>>> segmentation MUST be explicitly specifiable via scatter/gather lists. > >>>>> For example, data encryption or decryption may be invoked on a list of > >>>>> data segments as part of a single function call. > >>>>> > >>>>> > >>>>> Cheers, > >>>>> Anders > >>>>> > >>>>> > +@subsection chained_operations Chained Operations > >>>>> > +Crypto operations such as hashing and encryption, or decryption and > >>>>> verification, are very commonly used in combination. For ODP, it is > >>>>> sufficient to support one cipher and one hash/authentication operation in a > >>>>> single call and this combination MUST be supported to avoid the call and > >>>>> dispatch overhead of separate invocations. > >>>>> > +@subsection key_management Key Management and Session Data > >>>>> > +Keying is an area of particular sensitivity in crypto processing > >>>>> since keys are highly confidential and may be subject to legal requirements > >>>>> for safeguarding within special hardware enclosures. > >>>>> > + > >>>>> > +A session is the security context used to represent an active set > >>>>> of crypto operations that need to be applied to a flow on a > >>>>> packet-by-packet basis. Generally a session is established upon detection > >>>>> of a flow requiring crypto processing and retained for the life of that > >>>>> flow. It has been noted that this can involve cooperative processing > >>>>> between the control and data planes so several requirements stem from this: > >>>>> > + > >>>>> > +-# Session creation MAY need to be handled in an asynchronous > >>>>> manner. This is to allow these to be created in batches by thread(s) that > >>>>> specialize in this activity.\n\n > >>>>> > + > >>>>> > +-# Sessions MAY need to reference keying material indirectly via > >>>>> key handling modules.\n\n > >>>>> > + > >>>>> > +-# Session creation MAY be performed by non-ODP code and > >>>>> communicated to data plane routines that make use of ODP crypto functions > >>>>> that need to reference the session information. > >>>>> > + > >>>>> > +ODP session APIs and data structures SHOULD be represented by > >>>>> abstract data types that encapsulate implementation details for both > >>>>> platform efficiency and to accommodate these needs. > >>>>> > +Use Cases > >>>>> > +For ODP v1.0 the major use cases of interest involve cryptographic > >>>>> algorithm acceleration. Cryptographic protocol acceleration is reserved for > >>>>> future ODP releases. > >>>>> > +Buffers and Data Blocks > >>>>> > +Cryptographic operations may be performed directly on data > >>>>> contained in ODP packet buffers, or it may be performed on “raw” data > >>>>> blocks operating entirely under application control. Note that when using > >>>>> raw data blocks not managed by ODP, the application must perform any needed > >>>>> zeroization using either its own or ODP-supplied buffer zeroization > >>>>> functions. ODP automatic support for zeroization is limited to ODP-managed > >>>>> buffers. ODP buffers allocated from buffer pools designated for crypto use > >>>>> will also have whatever alignment and/or addressability attributes needed > >>>>> by the implementation to support crypto API calls. > >>>>> > + > >>>>> > +Note: Some implementations may have difficulty dealing with > >>>>> application buffer addresses, as these may be virtual addresses that are > >>>>> mapped discontiguously into physical memory. For such implementations, > >>>>> memory SHOULD be allocated contiguously and MAY need to be “registered” to > >>>>> have proper addressability for crypto operations. This area of the design > >>>>> will be updated based on experience in dealing with different crypto > >>>>> implementations that have such requirements. > >>>>> > +Synchronization > >>>>> > +ODP operations fall into one of three categories: > >>>>> > + > >>>>> > +-# Inline (Synchronous): Upon return from a call the operation is > >>>>> complete. Operation is thus completely synchronous to the caller. Inline > >>>>> is the appropriate model when the invoked function takes relatively few > >>>>> cycles or when the caller cannot feasibly progress without the results of > >>>>> the invoked function.\n\n > >>>>> > + > >>>>> > +-# Parallel: Upon return from a call the operation has been > >>>>> initiated, but is expected to complete shortly. The caller continues to > >>>>> execute until it needs the result at which point it waits to complete the > >>>>> parallel operation. The effect is as if the operation were inline except > >>>>> that the caller was able to execute in parallel with the operation for some > >>>>> application-determined period of time. Parallel is the appropriate model > >>>>> when the operation being performed is relatively short (a few dozen up to > >>>>> perhaps 100 or 200 cycles) and the caller can usefully accomplish other > >>>>> processing on the same unit of work while the parallel operation is in > >>>>> progress, but not enough to justify the overhead of a formal queued work > >>>>> dispatch.\n\n > >>>>> > + > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call the > >>>>> operation has been queued for execution. A completion event will be queued > >>>>> back to the scheduler when the event is completed. Offload is the > >>>>> appropriate model when the invoked function will take a substantial amount > >>>>> of cycles (thousands to tens of thousands) allowing the invoking > >>>>> thread/core to service other work until the operation completes. For > >>>>> offloaded work, completion is indicated by a completion event being posted > >>>>> back to an application-designated completion queue. Upon receipt the unit > >>>>> of work that initiated the offloaded operation continues processing with > >>>>> the results of the call. > >>>>> > + > >>>>> > +The synchronization models of interest are summarized in Figure 1: > >>>>> > + > >>>>> > + > >>>>> > + > >>>>> > +Note: Because few implementations are expected to offer the > >>>>> Parallel mode of operation as described above, this mode is reserved for > >>>>> potential future use. For ODP v1.0 only synchronous and asynchronous crypto > >>>>> operations are defined. > >>>>> > +@section functional_definition Functional Definition > >>>>> > +@subsection abstract_data_types Abstract data types > >>>>> > +The following enumerations define various algorithms used for > >>>>> ciphering and hashing. These are the basic operations applied to input data. > >>>>> > + > >>>>> > +A particular ODP implementation should map these values to the > >>>>> actual information to be passed to the crypto engine. As such, the actual > >>>>> values of these enums is implementation-defined. > >>>>> > + > >>>>> > +Cipher algorithm encoding specifies the algorithm and cipher mode > >>>>> employed (as per security relevant RFCs - [4305]( > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > >>>>> http://tools.ietf.org/html/rfc4494)). > >>>>> > + > >>>>> > +@code > >>>>> > +enum odp_cipher_alg { > >>>>> > + ODP_CIPHER_ALG_NULL, > >>>>> > + ODP_CIPHER_ALG_DES, > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, > >>>>> > + ODP_CIPHER_ALG_AES_CBC, > >>>>> > + ODP_CIPHER_ALG_AES_GCM, > >>>>> > + ODP_CIPHER_ALG_AES_CTR, > >>>>> > + ODP_CIPHER_ALG_KASUMI, > >>>>> > + ODP_CIPHER_ALG_SNOW, > >>>>> > + ... > >>>>> > +}; > >>>>> > +@endcode > >>>>> > + > >>>>> > +Authorization algorithm encoding specifies the algorithm and the > >>>>> length of the authorization used (as per security relevant RFCs - [4305]( > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > >>>>> http://tools.ietf.org/html/rfc4494)): > >>>>> > + > >>>>> > +@code > >>>>> > +enum odp_auth_alg { > >>>>> > + ODP_AUTH_ALG_NULL, > >>>>> > + ODP_AUTH_MD5_96, > >>>>> > + ODP_AUTH_ALG_SHA1_96, > >>>>> > + ODP_AUTH_ALG_SHA1_160 > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > >>>>> > + ODP_AUTH_ALG_SNOW, > >>>>> > + ODP_AUTH_ALG_KASUMI, > >>>>> > + ... > >>>>> > +}; > >>>>> > + > >>>>> > +typedef union odp_crypto_alg_t { > >>>>> > + enum odp_cipher_alg cipher; > >>>>> > + enum odp_auth_alg auth; > >>>>> > +}odp_crypto_alg_t; > >>>>> > +@endcode > >>>>> > +@subsection parameter_structures Parameter Structures > >>>>> > +@subsubsection crypto_sessions Crypto Sessions > >>>>> > +The following structure describes a crypto session. All packets / > >>>>> raw data buffers processed in a session share the data that defines the > >>>>> session. A crypto session is defined by: > >>>>> > + > >>>>> > +- Operation type : encode or decode\n\n > >>>>> > + > >>>>> > +- Algorithms specifications, keys and , if required, initialization > >>>>> vectors. When initialization vectors are not provided and they should be > >>>>> provided automatically by the crypto engine.\n\n > >>>>> > + > >>>>> > +- The operation mode: synchronous or asynchronous. Synchronous > >>>>> operation blocks the caller until an operation status and result are > >>>>> available. In synchronous mode there is at most only one outstanding crypto > >>>>> operation in the calling thread. In asynchronous mode, the caller starts > >>>>> the crypto operation and later it may receive the status and the result > >>>>> together with a request context. The operation status and result may also > >>>>> be received by a different thread.\n\n > >>>>> > + > >>>>> > +- Operation mode parameters: For asynchronous operation a > >>>>> completion event containing the status, the result and the request context > >>>>> is enqueued to a completion queue. In case the queue is under the scheduler > >>>>> control, the scheduler determines who will receive the completion event and > >>>>> when. When the completion queue is not scheduled, the thread which is > >>>>> supposed to get the operation output has to explicitly poll the completion > >>>>> queue. > >>>>> > + > >>>>> > +Note that this is an abstract data type and its structure is > >>>>> implementation-specific. The layout shown here is for illustrative purposes > >>>>> and the actual layout will vary from one implementation to the next to most > >>>>> closely align with the structures needed by the underlying SoC platform. > >>>>> Applications set and reference fields in the session structure via accessor > >>>>> functions that hide the actual layout. > >>>>> > + > >>>>> > +@code > >>>>> > +typedef enum odp_crypto_op_t { > >>>>> > + ODP_CRYPTO_OP_ENCODE, > >>>>> > + ODP_CRYPTO_OP_DECODE > >>>>> > +}odp_crypto_op_t; > >>>>> > + > >>>>> > +typedef struct odp_key_t { > >>>>> > +}odp_key_t; > >>>>> > + > >>>>> > +typedef struct odp_crypto_session_t { > >>>>> > + odp_crypto_op_t op; > >>>>> > + struct { > >>>>> > + enum odp_cipher_alg cipher_alg; > >>>>> > + odp_key_t *key; > >>>>> > + uint8_t *iv; > >>>>> > + size_t iv_len; > >>>>> > + } cipher; > >>>>> > + > >>>>> > + struct { > >>>>> > + enum odp_auth_alg auth_alg; > >>>>> > + enum odp_auth_len auth_len; > >>>>> > + odp_key_t *key; > >>>>> > + } auth; > >>>>> > + > >>>>> > + enum odp_crypto_op_mode { > >>>>> > + ODP_CRYPTO_SYNC, > >>>>> > + ODP_CRYPTO_ASYNC, > >>>>> > + } op_mode; > >>>>> > + > >>>>> > + struct { > >>>>> > + uint32_t timeout; > >>>>> > + struct { > >>>>> > + odp_queue_t completion_queue; > >>>>> > + } async; > >>>>> > + } op_mode_params; > >>>>> > + > >>>>> > + odp_session_proc_info_t session_proc_info; > >>>>> > +} odp_crxsypto_session_t; > >>>>> > +@endcode > >>>>> > + > >>>>> > +The completion queue contained in the session structure is an > >>>>> in/out parameter. If provided, then the queue specified is associated with > >>>>> the session and is used to ensure order preservation on that session. If > >>>>> not provided, one is created and returned to the caller. Note that this > >>>>> completion queue is used to order operations performed on this crypto > >>>>> session. It should not be confused with the completion queue specified on > >>>>> the odp_crypto_session_create() call (see below) that is used to control > >>>>> whether that call is itself processed in a synchronous vs. asynchronous > >>>>> manner. > >>>>> > + > >>>>> > +The following structure comprises processing information. This is > >>>>> logically divided in two parts: > >>>>> > + > >>>>> > +- Processing input info - When crypto engine provides support for > >>>>> protocol processing, this information is provided in a higher level common > >>>>> protocol terminology form and a particular implementation should be able to > >>>>> derive everything it needs from this definition. In addition, for crypto > >>>>> engines able to automate tasks like memory allocation for the output a > >>>>> buffer pool id may be specified.\n\n > >>>>> > + > >>>>> > +- Processing output information - statistics about processed > >>>>> bytes/packets. These are useful when a session expiration is based on > >>>>> traffic volume. These statistics may be updated by the software or by the > >>>>> hardware crypto engine. > >>>>> > + > >>>>> > +Again, this is an abstract type whose specific layout will vary > >>>>> based on implementation considerations. Access to fields contained in the > >>>>> structure is only via accessor functions. > >>>>> > + > >>>>> > +@code > >>>>> > +typedef struct { > >>>>> > + uint64_t pkts_processed; > >>>>> > + uint64_t bytes_processed; > >>>>> > + uint64_t pkts_errored; > >>>>> > + uint64_t bytes_errored; > >>>>> > + > >>>>> > + odp_buffer_pool_t out_pool; > >>>>> > + > >>>>> > +} odp_session_proc_info_t; > >>>>> > +@endcode > >>>>> > + > >>>>> > +This enumeration defines which operations are applied and the order. > >>>>> > + > >>>>> > +@code > >>>>> > +enum odp_crypto_combination { > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, > >>>>> > + ODP_CRYPTO_AUTH_ONLY, > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT > >>>>> > +}; > >>>>> > +@endcode > >>>>> > + > >>>>> > +This structure defines a contiguous segment in the input data which > >>>>> starts at offset offset and is len bytes long. > >>>>> > + > >>>>> > +@code > >>>>> > +struct odp_data_range { > >>>>> > + unsigned offset:16; > >>>>> > + unsigned len:16; > >>>>> > +}; > >>>>> > +@endcode > >>>>> > + > >>>>> > +@subsection api_functions API Functions > >>>>> > + > >>>>> > +@subsubfunction Session Creation > >>>>> > + > >>>>> > +This function is used to create a crypto session. The required > >>>>> parameters are : > >>>>> > + > >>>>> > +- Operation : encode/decode > >>>>> > +- Processing info : cipher/auth/both > >>>>> > +- Preferred mode : sync or async. > >>>>> > +- Algorithms suites, keys and optional IV > >>>>> > + > >>>>> > +Session creation can be synchronous or asynchronous. Completion > >>>>> event argument is used to return the status and the session handle. When > >>>>> completion queue is not provided (synchronous call), the completion event > >>>>> is available upon function call return. When completion queue is provided > >>>>> (asynchronous call), the completion event is placed on the completion queue. > >>>>> > + > >>>>> > +@code > >>>>> > +typedef uint64_t odp_crypto_session_t; > >>>>> > + > >>>>> > +struct odp_session_params { > >>>>> > + enum odp_crypto_operation op; > >>>>> > + odp_session_proc_info_t proc_info; > >>>>> > + enum odp_crypto_op_mode pref_mode; > >>>>> > + enum odp_cipher_alg cipher_alg; > >>>>> > + odp_key_t *cipher_key; > >>>>> > + uint8_t *iv; > >>>>> > + size_t iv_len; > >>>>> > + enum odp_auth_alg auth_alg; > >>>>> > + odp_key_t *auth_key; > >>>>> > +}; > >>>>> > + > >>>>> > +enum odp_crypto_ses_create_err { > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, > >>>>> > + /* Session creation error codes */ > >>>>> > +}; > >>>>> > + > >>>>> > +void > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t > >>>>> completion_event, enum odp_crypto_ses_create_err *status); > >>>>> > + > >>>>> > +void > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t > >>>>> completion_event, odp_crypto_session_t *handle); > >>>>> > + > >>>>> > +int odp_crypto_session_create( > >>>>> > + struct odp_session_params *params, > >>>>> > + odp_buffer_t completion_event, > >>>>> > + odp_queue_t completion_queue); > >>>>> > +@endcode > >>>>> > +@subsection crypto_operation Crypto Operation > >>>>> > + > >>>>> > +Crypto operations are described by a parameter structure: > >>>>> > +@code > >>>>> > +struct odp_crypto_op_params { > >>>>> > + odp_crypto_session_t session; > >>>>> > + odp_packet_t pkt; > >>>>> > + odp_packet_t out_pkt; > >>>>> > + uint8_t *override_iv_ptr; > >>>>> > + unsigned hash_result_offset; > >>>>> > + struct odp_data_range cipher_range; > >>>>> > + struct odp_data_range auth_range; > >>>>> > +}; > >>>>> > +@endcode > >>>>> > + > >>>>> > +<table> > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> > >>>>> > +<tr><td>session</td><td>Session to perform the operation</td></tr> > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be > >>>>> returned as the result of the operation. There are three different ways > >>>>> this parameter is used, depending on the mode of operation requested by the > >>>>> caller and the capabilities of the underlying implementation:\n\n > >>>>> > + > >>>>> > +-# If out_pkt is the same as pkt this indicates that the operation > >>>>> should be performed in place.\n\n > >>>>> > +-# If out_pkt is different from pkt this indicates that output > >>>>> should be placed in the buffer supplied by the caller.\n\n > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied on input) > >>>>> this indicates that an output buffer should be allocated by the operation > >>>>> and returned as part of the completion event associated with the > >>>>> operation.\n\n > >>>>> > + > >>>>> > +Note that not every implementation will support all of these modes > >>>>> and MAY require that one mode be used in preference to others. Any such > >>>>> implementation restrictions are communicated as output from session > >>>>> creation.</td></tr> > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this > >>>>> request</td></tr> > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the output packet > >>>>> where the hash result should be stored.</td></tr> > >>>>> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of the > >>>>> data to be processed for ciphering.</td></tr> > >>>>> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the > >>>>> data to be processed for authentication.</td></tr> > >>>>> > +</table> > >>>>> > + > >>>>> > +The crypto operation is initiated with a single call that passes > >>>>> the parameters for the operation and an event (for asynchronous completion). > >>>>> > +@code > >>>>> > +int odp_crypto_operation( > >>>>> > + struct odp_crypto_op_params *params, > >>>>> > + odp_buffer_t completion_event); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Parameter | Meaning > >>>>> > +----------|-------- > >>>>> > +params | The parameter structure describing the crypto operation > >>>>> to be performed. > >>>>> > +completion_event | The event delivered on completion. It provides > >>>>> information about the status of the operation, result and request context. > >>>>> In synchronous mode the event is available upon function call return. In > >>>>> asynchronous mode, the event is placed on the session / operation > >>>>> completion queue when the operation finished. > >>>>> > + > >>>>> > +Upon return the return code indicates whether the operation was > >>>>> synchronous or asynchronous, or if an error occurred that prevented the > >>>>> operation from being performed. > >>>>> > + > >>>>> > +Get session operation : > >>>>> > +@code > >>>>> > +odp_crypto_op_t > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Get session cipher information : > >>>>> > +@code > >>>>> > +odp_cipher_alg > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Get session authentication information : > >>>>> > +@code > >>>>> > +odp_auth_alg > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Change session IV : > >>>>> > +@code > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t > >>>>> *iv); > >>>>> > +@emdcode > >>>>> > + > >>>>> > +Change cipher or/and hash keys: > >>>>> > +@code > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t > >>>>> *key); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Destroy crypto session. All pending operations are cancelled. > >>>>> > +@code > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Get completion event information - algorithm error, output and > >>>>> context. Note that implementations MAY define their own specific error > >>>>> codes that have meaning in that context. For application portability it is > >>>>> sufficient to know whether an operation completed successfully or > >>>>> experienced an error of some sort. > >>>>> > +@code > >>>>> > +enum crypto_alg_err { > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > >>>>> > +}; > >>>>> > + > >>>>> > +enum crypto_hw_err { > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > >>>>> > +}; > >>>>> > + > >>>>> > +struct odp_crypto_compl_status { > >>>>> > + odp_crypto_alg_t alg; > >>>>> > + enum crypto_alg_err alg_err; > >>>>> > + enum crypto_hw_err hw_err; > >>>>> > +}; > >>>>> > + > >>>>> > +void > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > >>>>> > + struct odp_crypto_compl_status *auth, > >>>>> > + struct odp_crypto_compl_status *cipher); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Returns the output packet handle associated with the completion > >>>>> event : > >>>>> > +@code > >>>>> > +odp_packet_t > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Sets a context handle to be returned with the completion event : > >>>>> > +@code > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, > >>>>> odp_compl_ctx_t *ctx); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Returns the context associated with the completion event : > >>>>> > +@code > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t > >>>>> completion_event); > >>>>> > +@endcode > >>>>> > + > >>>>> > +This section describes the API/Interface being defined at a > >>>>> functional level in technical detail. Sub-sections include header file > >>>>> names, where implementation files are expected to reside in the ODP git > >>>>> tree, as well as the name, parameters, abstract data types, functionality, > >>>>> return codes, and exception conditions of each function call defined by the > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be used to allow > >>>>> the programmer tasked with implementing the API/Interface to understand the > >>>>> function to be implemented as well as error conditions, corner cases, > >>>>> performance requirements, etc. needed to implement the described > >>>>> API/Interface in a functionally correct and efficient manner. > >>>>> > + > >>>>> > +@subsubsection random_number_functions Random Number Functions > >>>>> > +As noted earlier, random number support consists of two functions: > >>>>> > +@code > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool > >>>>> use_entropy); > >>>>> > + > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > >>>>> > +@endcode > >>>>> > + > >>>>> > +The difference is that the first provides access to hardware random > >>>>> number functions that return true random data. This is typically used for > >>>>> seed values. The second provides a deterministic random bit generator > >>>>> conforming to NIST standards and is used by various crypto protocols and > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get is used to > >>>>> disable any hardware pre-processing normally provided by the function and > >>>>> is mainly intended to be used for testing/validation purposes. > >>>>> > + > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > >>>>> > +To support zeroization a buffer may be allocated with an > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be > >>>>> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to > >>>>> odp_buffer_pool_create() that specifies that all buffers allocated from > >>>>> this pool must be zeroized upon free. Essentially, the buffer security > >>>>> attribute is set by default from the attributes of the buffer pool that it > >>>>> is allocated from. > >>>>> > + > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > >>>>> > +To enable applications to determine crypto capabilities. > >>>>> > +@code > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > >>>>> > +@endcode > >>>>> > + > >>>>> > +Inquires whether the specified crypto and auth algorithms are > >>>>> supported. Responses include: > >>>>> > +- ODP_HW_SYNC_SUPPORT > >>>>> > +- ODP_HW_ASYNC_SUPPORT > >>>>> > +- ODP_SW_SYNC_SUPPORT > >>>>> > +- ODP_SW_ASYNC_SUPPORT > >>>>> > +- ODP_NO_SUPPORT > >>>>> > + > >>>>> > +HW support means the combination is supported in hardware, SW > >>>>> support means the combination is supported in software by the > >>>>> implementation. No support means the combination is not supported by the > >>>>> implementation. The SYNC and ASYNC return options can help the application > >>>>> decide how to invoke these functions, or it can just check whether or not > >>>>> the response is ODP_NO_SUPPORT. > >>>>> > + > >>>>> > +@section implementation_considerations Implementation Considerations > >>>>> > +One of the main purposes for the ODP crypto APIs is to provide > >>>>> portable access across different SoCs whose hardware crypto capabilities > >>>>> largely overlap but vary in terms of their implementation details. As a > >>>>> result, implementations need not provide software fill-ins for specific > >>>>> cryptographic features that are not available as hardware features on that > >>>>> platform. Presumably applications needing specific features will select > >>>>> platforms on which these features are present. Therefore, while all APIs > >>>>> specified here MUST exist in each conforming ODP implementation, it is > >>>>> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response > >>>>> to calls requesting crypto features not present on that platform. > >>>>> > + > >>>>> > +For example, the linux-generic ODP implementation may only > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature > >>>>> not present error code for any other cipher. This indication will also be > >>>>> returned on that platform in response to odp_crypto_inquire calls for > >>>>> non-null cipher algorithms. > >>>>> > + > >>>>> > +@section verification Verification/Testing > >>>>> > +This section describes the verification/test cases needed to ensure > >>>>> that the defined functionality is implemented correctly and performs > >>>>> adequately. This should be at a level of detail such that the programmer > >>>>> tasked with writing test scripts/programs to verify the implementation(s) > >>>>> of the defined functions can be written to ensure that all relevant > >>>>> functional variants and error/exception cases are properly tested. > >>>>> > + > >>>>> > +This section needs to be completed before API testing begins. > >>>>> > + > >>>>> > +*/ > >>>>> > \ No newline at end of file > >>>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png > >>>>> > new file mode 100644 > >>>>> > index > >>>>> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > >>>>> > GIT binary patch > >>>>> > literal 17179 > >>>>> > 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 > >>>>> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > >>>>> > > >>>>> > literal 0 > >>>>> > HcmV?d00001 > >>>>> > > >>>>> > -- > >>>>> > 1.8.3.2 > >>>>> > > >>>>> > > >>>>> > _______________________________________________ > >>>>> > lng-odp mailing list > >>>>> > lng-odp@lists.linaro.org > >>>>> > http://lists.linaro.org/mailman/listinfo/lng-odp > >>>>> > >>>> > >>>> > >>>> _______________________________________________ > >>>> lng-odp mailing list > >>>> lng-odp@lists.linaro.org > >>>> http://lists.linaro.org/mailman/listinfo/lng-odp > >>>> > >>>> > >>> > >>> > >>> -- > >>> *Mike Holmes* > >>> Linaro Technical Manager / Lead > >>> LNG - ODP > >>> > >> > >> > > > > > > -- > > *Mike Holmes* > > Linaro Technical Manager / Lead > > LNG - ODP > >
Can everyone please weigh in with their thoughts, we need consensus on this before we can make progress with the Arch doc. Thanks BIll / Mike On 3 July 2014 11:25, Anders Roxell <anders.roxell@linaro.org> wrote: > On 2014-07-03 10:01, Bill Fischofer wrote: > > The people who review and approve these docs want to see docs with things > > like change bars, not patches. The patch mechanism is simply > inappropriate > > for this activity and we shouldn't try to force-fit it for something it's > > not designed to address. > > > > Again, the primary users of the odp-architecture git repository are those > > who want access to complete docs, not those who are creating, reviewing, > > and approving them. That's why we have a separate repository from the > main > > odp git repository so that "patches" can be handled differently between > > them. > > That is why we use doxygen so that people reviewing for approval can look > at the end result... However, isn't it better if anyone on the list can > review the patch and send patches when that is needed? > > SC approval should only be required for major revisions. > Possibly only a final read through review for every ODP release. > > > > > My preference would be to grant push rights to those adding items to this > > repository rather than going through the artifice of patches. It would > be > > more straightforward and consistent with the actual workflow. Git would > > still be doing version tracking so it would be possible to see the > complete > > change history for any given doc easily. > > We should use git as a revision control system as it is, to allow us to > make small changes when we discover them. > > > Cheers, > Anders > > > > > > > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > > > > > I agree we need approval, but approval can be of a review of the patch > to > > > the text. > > > > > > I hope we don't need wholesale changes that need a complete re write > and > > > thus approval of a whole new document. For example a new patch which > may > > > add a new function to an API but we would hopefully not change any of > the > > > existing text in the main. > > > > > > Thus we can then make changes in manageable chunks, I agree that large > > > new additions will come in via a pre approved hugue patch, created > from a > > > sequence of sprints just have we have done so far. > > > > > > I would argue that these small changes are likely given the additions > > > already discovered by starting the validation testing work and the > feedback > > > it is generating with the need to be more specific in architectural > areas. > > > > > > Mike > > > > > > > > > On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > > > > > >> Design documents require approval by those who aren't going to be > > >> reviewing patches. This is different from code. My understanding of > the > > >> purpose of the odp-architecture repository is to provide a convenient > means > > >> of distributing documentation and making it available in various forms > > >> (Doxygen, PDF) for access through the ODP web site as well as being > > >> downloaded. > > >> > > >> So in this sense we're just using Git as a publication mechanism for > docs. > > >> > > >> > > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes <mike.holmes@linaro.org> > > >> wrote: > > >> > > >>> I am confused git is a change control mechanism, and I really hope > they > > >>> do get patched, how will we improve the content ? > > >>> > > >>> > > >>> On 3 July 2014 10:03, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > > >>> > > >>>> Git is a publication mechanism for docs, not a change control > > >>>> mechanism. Docs will not be 'patched'. New versions will replace > old ones > > >>>> as they are approved. > > >>>> > > >>>> > > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell < > anders.roxell@linaro.org > > >>>> > wrote: > > >>>> > > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: > > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > > >>>>> > --- > > >>>>> > crypto_design.dox | 455 > > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ > > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes > > >>>>> > 2 files changed, 455 insertions(+) > > >>>>> > create mode 100644 crypto_design.dox > > >>>>> > create mode 100644 images/syncmodels.png > > >>>>> > > > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox > > >>>>> > new file mode 100644 > > >>>>> > index 0000000..1ad2ac6 > > >>>>> > --- /dev/null > > >>>>> > +++ b/crypto_design.dox > > >>>>> > @@ -0,0 +1,455 @@ > > >>>>> > +/* Copyright (c) 2043, Linaro Limited > > >>>>> > + * All rights reserved > > >>>>> > + * > > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause > > >>>>> > + */ > > >>>>> > + > > >>>>> > +/** > > >>>>> > +@page crypto_design ODP Design - Crypto API > > >>>>> > +For the implimentation of the ODP crypto API please see @ref > > >>>>> odp_crypto.h > > >>>>> > + > > >>>>> > +@tableofcontents > > >>>>> > + > > >>>>> > +@section revision_history Revision History > > >>>>> > +Revision | Issue Data | Description | Author > > >>>>> > +---------|------------|-------------|-------- > > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic Functions | > > >>>>> Bill, Alexandru > > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, started use > > >>>>> cases, miscellaneous formatting, API comments | Bill > > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to include > results > > >>>>> of design discussions held during ODP team calls | Bill > > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto > > >>>>> sprint--action to resolve | Bill > > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review > > >>>>> comments--ready for final review | Bill > > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill > > >>>>> > + > > >>>>> > +@section introduction Introduction > > >>>>> > +This document describes the ODP v1.0 Crypto API. Cryptography > is an > > >>>>> important part of data plane processing as many communication > protocols > > >>>>> make use of cryptographic functions. Moreover, many SoCs > incorporate > > >>>>> cryptographic hardware that can significantly accelerate these > operations > > >>>>> compared to their software equivalents as well as provide validated > > >>>>> hardware functional correctness and security boundaries necessary > for > > >>>>> system-level security certifications such as FIPS-140 Level 2 and > above. > > >>>>> > +@section requirements Requirements > > >>>>> > +@subsection use_of_terms Use of Terms > > >>>>> > +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 [RFC 2119]( > > >>>>> https://tools.ietf.org/html/rfc2119). > > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography > > >>>>> > +Crypto functions cover a range of uses and capabilities > designed to > > >>>>> support data security, integrity, authentication, and > non-repudiation. > > >>>>> > +@subsubsection data_security Data Security > > >>>>> > +Cryptography supports data security by making use of complex > > >>>>> mathematical transformations that are not feasibly reversible > without > > >>>>> possession of the secret key used to encrypt message data. > > >>>>> > +@subsubsection data_integrity Data Integrity > > >>>>> > +Cryptography supports data integrity through the use of > > >>>>> cryptographic checksums (also known as secure hashes) that ensure > the > > >>>>> recipient that message data has not been altered either > accidentally or > > >>>>> maliciously while in transit. > > >>>>> > +@subsubsection data_authentication Data Authentication > > >>>>> > +Cryptography supports data authentication through the uses of > > >>>>> Message Authentication Codes (MACs) that enable the recipient to > verify > > >>>>> that a message was sent from an authorized counterparty, and hence > was not > > >>>>> forged. > > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation > > >>>>> > +Cryptography supports data non-repudiation through the use of > > >>>>> digital signatures that enable a recipient or third party to > verify the > > >>>>> identity of the sending party and prevents the sending party from > later > > >>>>> denying that they originated a signed message. > > >>>>> > +@subsection scope Scope > > >>>>> > +ODP v1.0 crypto support is designed to provide a portable > framework > > >>>>> for accessing SoC-specific cryptographic functions of most use to > the data > > >>>>> plane. This is predominantly symmetric crypto operations used to > support > > >>>>> the encryption and decryption of data at line rate using hardware > > >>>>> acceleration and offload. Specifically excluded in this support > are public > > >>>>> key operations and other crypto functions mainly used in the > control plane. > > >>>>> > +@subsection cryptographic_operations_in_the_data_plane > > >>>>> Cryptographic Operations in the Data Plane > > >>>>> > +ODP v1.0 crypto APIs cover the following areas: > > >>>>> > +@subsubsection ciphering Ciphering > > >>>>> > +Ciphering refers to mathematical transformations that use a > secret > > >>>>> key to encipher data, transforming the original data (referred to > as > > >>>>> plaintext) into ciphertext, thereby making it unintelligible to > anyone not > > >>>>> in possession of the key. Similarly, ciphering is also used to > decipher > > >>>>> data, allowing someone in possession of the correct key to > transform > > >>>>> received ciphertext back into plaintext. Approved block ciphers > are listed > > >>>>> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) > and > > >>>>> SHOULD be supported by each ODP implementation. > > >>>>> > +@subsubsection hasing Hashing > > >>>>> > +A hash is a cryptographic digest of a message that can be used > to > > >>>>> represent it for comparison or integrity checking. Hash functions > are > > >>>>> designed so that any alteration of a message will alter the hash > and that > > >>>>> it is computationally infeasible to craft a message that generates > the same > > >>>>> hash value as another message. Secure hash functions approved for > > >>>>> cryptographic use are listed by NIST [here]( > > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and > > >>>>> SHOULD be supported by each ODP implementation. > > >>>>> > +@subsubsection zeroization Zeroization > > >>>>> > +To preserve the security of data, certain transient data held in > > >>>>> data buffers MUST be cleared to zeros upon buffer free. Such > capability is > > >>>>> referred to as zeroization. ODP supports zeroization as a buffer > pool > > >>>>> attribute. > > >>>>> > +@subsubsection random_number_generation Random Number Generation > > >>>>> > +Because cryptography relies heavily on “unguessable” keys of > > >>>>> various sorts, random number generation (RNG) is an integral part > of > > >>>>> cryptographic processing. Random numbers are used in key > generation, > > >>>>> initialization vectors (IVs), various types of padding bytes, and > various > > >>>>> other uses collectively referred to as nonces, that serve to > “harden” > > >>>>> cryptographic processing. > > >>>>> > + > > >>>>> > +There are two types of random number support of interest. > Hardware > > >>>>> random data, also known as entropy, that is the result of > inherently random > > >>>>> physical processes, and deterministic random bit generation (DRBG) > that is > > >>>>> used in certain certified cryptographic operations. Approved DRBG > > >>>>> algorithms are listed in [NIST SP 800-90A]( > > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not > > >>>>> specify which algorithms are available on a given implementation. > As such > > >>>>> ODP implementations MAY use any approved DRGB algorithm but SHOULD > support > > >>>>> at least one of them. Additionally, ODP implementations MUST NOT > represent > > >>>>> non-approved algorithms as DRBG implementations. Validated > algorithms are > > >>>>> listed in the [NIST DRBG Validation List]( > > >>>>> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > > >>>>> > + > > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > > >>>>> > +To enable applications to adapt to the implementation models > > >>>>> offered across different SoC platforms, ODP provides APIs to allow > > >>>>> applications to inquire about underlying crypto capabilities. A > given ODP > > >>>>> implementation may offer crypto as hardware features, software > features, or > > >>>>> not available on a given platform. > > >>>>> > +@subsection cryptographic_algorithms Cryptographic Algorithms > and > > >>>>> Protocols > > >>>>> > +A cryptographic algorithm is a mathematical transform that > provides > > >>>>> one of the cryptographic operations described above. They in turn > are used > > >>>>> as building blocks in creating cryptographic protocols. These are > complete > > >>>>> sets of rules for how to exchange data securely using > cryptography. Both > > >>>>> cryptographic algorithm and protocol design are highly specialized > > >>>>> disciplines that involve high levels of public scrutiny and > validation. As > > >>>>> a result, applications simply make use of approved cryptographic > algorithms > > >>>>> and protocols. > > >>>>> > +@subsection cryptographic_operations Cryptographic Operations > > >>>>> > +Cryptographic operations may be initiated by software or > directly > > >>>>> by hardware as part of the RX or TX packet path processing. For > ODP v1.0 > > >>>>> software-initiated cryptographic operations are the primary use > case. ODP > > >>>>> provides APIs for performing data ciphering, hashing, random number > > >>>>> generation, and capability inquiry. > > >>>>> > +@subsection performance_expectations Performance Expectations > > >>>>> > +In the data plane, the total processing budget for a packet may > > >>>>> only be a few hundred cycles, so function invocation overhead MUST > be kept > > >>>>> to a minimum. This has several implications. > > >>>>> > + > > >>>>> > +-# When work is dispatched to a thread, all information needed > by > > >>>>> the thread to process the work request SHOULD be immediately at > hand. > > >>>>> Ideally any context or variables needed for the operation have been > > >>>>> pre-warmed in the cache to avoid the latency hits associated with > cache > > >>>>> misses. SoCs having hardware schedulers generally do this > pre-staging of > > >>>>> data to minimize such latencies, and ODP implementations are > expected to > > >>>>> exploit such platform capabilities whenever possible.\n\n > > >>>>> > + > > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive amounts > of > > >>>>> parameter passing and (depending on the implementation) SHOULD be > inlined > > >>>>> as much as possible to avoid call overhead. One technique that has > proven > > >>>>> useful is to allow for parameters to be passed as an explicit > thread-local > > >>>>> static structure. Such use of “templating” means that a single > function can > > >>>>> support a rich set of options but the caller can configure a > template > > >>>>> matched to specific use and only vary the one or two parameters > that differ > > >>>>> from call to call.\n\n > > >>>>> > + > > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any > > >>>>> non-exception path function processing. Kernel calls and such are > > >>>>> acceptable only during one-time initialization logic or certain > types of > > >>>>> unusual error recovery operations. Often the best way to handle > the latter > > >>>>> is to pass the work to a dedicated recovery thread (or back to the > control > > >>>>> plane) rather than attempting to handle the condition inline. For > example, > > >>>>> a link-down condition will trigger various recovery actions that > might best > > >>>>> be handled in this manner. > > >>>>> > + > > >>>>> > +@subsection use_by_existing_code Use by Existing Code > > >>>>> > +Most applications wishing to make use of ODP represent > substantial > > >>>>> existing investment that must be preserved. Insofar as possible, > ODP > > >>>>> functions need to be orthogonal to existing application > environments and > > >>>>> structures to permit easy intermixing with pre-existing code. > > >>>>> > +@subsection data_references Data References > > >>>>> > +Packet data is inherently of variable length however it is often > > >>>>> more efficient to organize memory into fixed-sized buffers that > can be > > >>>>> chained together on demand to contain packets. The application > SHOULD > > >>>>> normally not need to be aware of such lower-level segmentation and > should > > >>>>> be able to treat a packet as a single object. Alternately, > especially when > > >>>>> dealing with existing code, data segmentation MUST be explicitly > > >>>>> specifiable via scatter/gather lists. For example, data encryption > or > > >>>>> decryption may be invoked on a list of data segments as part of a > single > > >>>>> function call. > > >>>>> > > >>>>> Every time you add a full stop for a sentence, you have to press > return > > >>>>> and start typing the next sentence. > > >>>>> This means that diffs of future changes will be per sentence. > > >>>>> Doxygen will still concatenate this as a paragraph with no visual > > >>>>> difference in the result. > > >>>>> I think the above line will look like this: > > >>>>> > > >>>>> Packet data is inherently of variable length however it is often > more > > >>>>> efficient to organize memory into fixed-sized buffers that can be > chained > > >>>>> together on demand to contain packets. > > >>>>> The application SHOULD normally not need to be aware of such > > >>>>> lower-level segmentation and should be able to treat a packet as a > single > > >>>>> object. > > >>>>> Alternately, especially when dealing with existing code, data > > >>>>> segmentation MUST be explicitly specifiable via scatter/gather > lists. > > >>>>> For example, data encryption or decryption may be invoked on a > list of > > >>>>> data segments as part of a single function call. > > >>>>> > > >>>>> > > >>>>> Cheers, > > >>>>> Anders > > >>>>> > > >>>>> > +@subsection chained_operations Chained Operations > > >>>>> > +Crypto operations such as hashing and encryption, or decryption > and > > >>>>> verification, are very commonly used in combination. For ODP, it is > > >>>>> sufficient to support one cipher and one hash/authentication > operation in a > > >>>>> single call and this combination MUST be supported to avoid the > call and > > >>>>> dispatch overhead of separate invocations. > > >>>>> > +@subsection key_management Key Management and Session Data > > >>>>> > +Keying is an area of particular sensitivity in crypto processing > > >>>>> since keys are highly confidential and may be subject to legal > requirements > > >>>>> for safeguarding within special hardware enclosures. > > >>>>> > + > > >>>>> > +A session is the security context used to represent an active > set > > >>>>> of crypto operations that need to be applied to a flow on a > > >>>>> packet-by-packet basis. Generally a session is established upon > detection > > >>>>> of a flow requiring crypto processing and retained for the life of > that > > >>>>> flow. It has been noted that this can involve cooperative > processing > > >>>>> between the control and data planes so several requirements stem > from this: > > >>>>> > + > > >>>>> > +-# Session creation MAY need to be handled in an asynchronous > > >>>>> manner. This is to allow these to be created in batches by > thread(s) that > > >>>>> specialize in this activity.\n\n > > >>>>> > + > > >>>>> > +-# Sessions MAY need to reference keying material indirectly via > > >>>>> key handling modules.\n\n > > >>>>> > + > > >>>>> > +-# Session creation MAY be performed by non-ODP code and > > >>>>> communicated to data plane routines that make use of ODP crypto > functions > > >>>>> that need to reference the session information. > > >>>>> > + > > >>>>> > +ODP session APIs and data structures SHOULD be represented by > > >>>>> abstract data types that encapsulate implementation details for > both > > >>>>> platform efficiency and to accommodate these needs. > > >>>>> > +Use Cases > > >>>>> > +For ODP v1.0 the major use cases of interest involve > cryptographic > > >>>>> algorithm acceleration. Cryptographic protocol acceleration is > reserved for > > >>>>> future ODP releases. > > >>>>> > +Buffers and Data Blocks > > >>>>> > +Cryptographic operations may be performed directly on data > > >>>>> contained in ODP packet buffers, or it may be performed on “raw” > data > > >>>>> blocks operating entirely under application control. Note that > when using > > >>>>> raw data blocks not managed by ODP, the application must perform > any needed > > >>>>> zeroization using either its own or ODP-supplied buffer zeroization > > >>>>> functions. ODP automatic support for zeroization is limited to > ODP-managed > > >>>>> buffers. ODP buffers allocated from buffer pools designated for > crypto use > > >>>>> will also have whatever alignment and/or addressability attributes > needed > > >>>>> by the implementation to support crypto API calls. > > >>>>> > + > > >>>>> > +Note: Some implementations may have difficulty dealing with > > >>>>> application buffer addresses, as these may be virtual addresses > that are > > >>>>> mapped discontiguously into physical memory. For such > implementations, > > >>>>> memory SHOULD be allocated contiguously and MAY need to be > “registered” to > > >>>>> have proper addressability for crypto operations. This area of the > design > > >>>>> will be updated based on experience in dealing with different > crypto > > >>>>> implementations that have such requirements. > > >>>>> > +Synchronization > > >>>>> > +ODP operations fall into one of three categories: > > >>>>> > + > > >>>>> > +-# Inline (Synchronous): Upon return from a call the operation > is > > >>>>> complete. Operation is thus completely synchronous to the caller. > Inline > > >>>>> is the appropriate model when the invoked function takes > relatively few > > >>>>> cycles or when the caller cannot feasibly progress without the > results of > > >>>>> the invoked function.\n\n > > >>>>> > + > > >>>>> > +-# Parallel: Upon return from a call the operation has been > > >>>>> initiated, but is expected to complete shortly. The caller > continues to > > >>>>> execute until it needs the result at which point it waits to > complete the > > >>>>> parallel operation. The effect is as if the operation were inline > except > > >>>>> that the caller was able to execute in parallel with the operation > for some > > >>>>> application-determined period of time. Parallel is the appropriate > model > > >>>>> when the operation being performed is relatively short (a few > dozen up to > > >>>>> perhaps 100 or 200 cycles) and the caller can usefully accomplish > other > > >>>>> processing on the same unit of work while the parallel operation > is in > > >>>>> progress, but not enough to justify the overhead of a formal > queued work > > >>>>> dispatch.\n\n > > >>>>> > + > > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call the > > >>>>> operation has been queued for execution. A completion event will > be queued > > >>>>> back to the scheduler when the event is completed. Offload is the > > >>>>> appropriate model when the invoked function will take a > substantial amount > > >>>>> of cycles (thousands to tens of thousands) allowing the invoking > > >>>>> thread/core to service other work until the operation completes. > For > > >>>>> offloaded work, completion is indicated by a completion event > being posted > > >>>>> back to an application-designated completion queue. Upon receipt > the unit > > >>>>> of work that initiated the offloaded operation continues > processing with > > >>>>> the results of the call. > > >>>>> > + > > >>>>> > +The synchronization models of interest are summarized in Figure > 1: > > >>>>> > + > > >>>>> > + > > >>>>> > + > > >>>>> > +Note: Because few implementations are expected to offer the > > >>>>> Parallel mode of operation as described above, this mode is > reserved for > > >>>>> potential future use. For ODP v1.0 only synchronous and > asynchronous crypto > > >>>>> operations are defined. > > >>>>> > +@section functional_definition Functional Definition > > >>>>> > +@subsection abstract_data_types Abstract data types > > >>>>> > +The following enumerations define various algorithms used for > > >>>>> ciphering and hashing. These are the basic operations applied to > input data. > > >>>>> > + > > >>>>> > +A particular ODP implementation should map these values to the > > >>>>> actual information to be passed to the crypto engine. As such, the > actual > > >>>>> values of these enums is implementation-defined. > > >>>>> > + > > >>>>> > +Cipher algorithm encoding specifies the algorithm and cipher > mode > > >>>>> employed (as per security relevant RFCs - [4305]( > > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > > >>>>> http://tools.ietf.org/html/rfc4494)). > > >>>>> > + > > >>>>> > +@code > > >>>>> > +enum odp_cipher_alg { > > >>>>> > + ODP_CIPHER_ALG_NULL, > > >>>>> > + ODP_CIPHER_ALG_DES, > > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, > > >>>>> > + ODP_CIPHER_ALG_AES_CBC, > > >>>>> > + ODP_CIPHER_ALG_AES_GCM, > > >>>>> > + ODP_CIPHER_ALG_AES_CTR, > > >>>>> > + ODP_CIPHER_ALG_KASUMI, > > >>>>> > + ODP_CIPHER_ALG_SNOW, > > >>>>> > + ... > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Authorization algorithm encoding specifies the algorithm and the > > >>>>> length of the authorization used (as per security relevant RFCs - > [4305]( > > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > > >>>>> http://tools.ietf.org/html/rfc4494)): > > >>>>> > + > > >>>>> > +@code > > >>>>> > +enum odp_auth_alg { > > >>>>> > + ODP_AUTH_ALG_NULL, > > >>>>> > + ODP_AUTH_MD5_96, > > >>>>> > + ODP_AUTH_ALG_SHA1_96, > > >>>>> > + ODP_AUTH_ALG_SHA1_160 > > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, > > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, > > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, > > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, > > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > > >>>>> > + ODP_AUTH_ALG_SNOW, > > >>>>> > + ODP_AUTH_ALG_KASUMI, > > >>>>> > + ... > > >>>>> > +}; > > >>>>> > + > > >>>>> > +typedef union odp_crypto_alg_t { > > >>>>> > + enum odp_cipher_alg cipher; > > >>>>> > + enum odp_auth_alg auth; > > >>>>> > +}odp_crypto_alg_t; > > >>>>> > +@endcode > > >>>>> > +@subsection parameter_structures Parameter Structures > > >>>>> > +@subsubsection crypto_sessions Crypto Sessions > > >>>>> > +The following structure describes a crypto session. All packets > / > > >>>>> raw data buffers processed in a session share the data that > defines the > > >>>>> session. A crypto session is defined by: > > >>>>> > + > > >>>>> > +- Operation type : encode or decode\n\n > > >>>>> > + > > >>>>> > +- Algorithms specifications, keys and , if required, > initialization > > >>>>> vectors. When initialization vectors are not provided and they > should be > > >>>>> provided automatically by the crypto engine.\n\n > > >>>>> > + > > >>>>> > +- The operation mode: synchronous or asynchronous. Synchronous > > >>>>> operation blocks the caller until an operation status and result > are > > >>>>> available. In synchronous mode there is at most only one > outstanding crypto > > >>>>> operation in the calling thread. In asynchronous mode, the caller > starts > > >>>>> the crypto operation and later it may receive the status and the > result > > >>>>> together with a request context. The operation status and result > may also > > >>>>> be received by a different thread.\n\n > > >>>>> > + > > >>>>> > +- Operation mode parameters: For asynchronous operation a > > >>>>> completion event containing the status, the result and the request > context > > >>>>> is enqueued to a completion queue. In case the queue is under the > scheduler > > >>>>> control, the scheduler determines who will receive the completion > event and > > >>>>> when. When the completion queue is not scheduled, the thread which > is > > >>>>> supposed to get the operation output has to explicitly poll the > completion > > >>>>> queue. > > >>>>> > + > > >>>>> > +Note that this is an abstract data type and its structure is > > >>>>> implementation-specific. The layout shown here is for illustrative > purposes > > >>>>> and the actual layout will vary from one implementation to the > next to most > > >>>>> closely align with the structures needed by the underlying SoC > platform. > > >>>>> Applications set and reference fields in the session structure via > accessor > > >>>>> functions that hide the actual layout. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +typedef enum odp_crypto_op_t { > > >>>>> > + ODP_CRYPTO_OP_ENCODE, > > >>>>> > + ODP_CRYPTO_OP_DECODE > > >>>>> > +}odp_crypto_op_t; > > >>>>> > + > > >>>>> > +typedef struct odp_key_t { > > >>>>> > +}odp_key_t; > > >>>>> > + > > >>>>> > +typedef struct odp_crypto_session_t { > > >>>>> > + odp_crypto_op_t op; > > >>>>> > + struct { > > >>>>> > + enum odp_cipher_alg cipher_alg; > > >>>>> > + odp_key_t *key; > > >>>>> > + uint8_t *iv; > > >>>>> > + size_t iv_len; > > >>>>> > + } cipher; > > >>>>> > + > > >>>>> > + struct { > > >>>>> > + enum odp_auth_alg auth_alg; > > >>>>> > + enum odp_auth_len auth_len; > > >>>>> > + odp_key_t *key; > > >>>>> > + } auth; > > >>>>> > + > > >>>>> > + enum odp_crypto_op_mode { > > >>>>> > + ODP_CRYPTO_SYNC, > > >>>>> > + ODP_CRYPTO_ASYNC, > > >>>>> > + } op_mode; > > >>>>> > + > > >>>>> > + struct { > > >>>>> > + uint32_t timeout; > > >>>>> > + struct { > > >>>>> > + odp_queue_t completion_queue; > > >>>>> > + } async; > > >>>>> > + } op_mode_params; > > >>>>> > + > > >>>>> > + odp_session_proc_info_t session_proc_info; > > >>>>> > +} odp_crxsypto_session_t; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +The completion queue contained in the session structure is an > > >>>>> in/out parameter. If provided, then the queue specified is > associated with > > >>>>> the session and is used to ensure order preservation on that > session. If > > >>>>> not provided, one is created and returned to the caller. Note that > this > > >>>>> completion queue is used to order operations performed on this > crypto > > >>>>> session. It should not be confused with the completion queue > specified on > > >>>>> the odp_crypto_session_create() call (see below) that is used to > control > > >>>>> whether that call is itself processed in a synchronous vs. > asynchronous > > >>>>> manner. > > >>>>> > + > > >>>>> > +The following structure comprises processing information. This > is > > >>>>> logically divided in two parts: > > >>>>> > + > > >>>>> > +- Processing input info - When crypto engine provides support > for > > >>>>> protocol processing, this information is provided in a higher > level common > > >>>>> protocol terminology form and a particular implementation should > be able to > > >>>>> derive everything it needs from this definition. In addition, for > crypto > > >>>>> engines able to automate tasks like memory allocation for the > output a > > >>>>> buffer pool id may be specified.\n\n > > >>>>> > + > > >>>>> > +- Processing output information - statistics about processed > > >>>>> bytes/packets. These are useful when a session expiration is based > on > > >>>>> traffic volume. These statistics may be updated by the software or > by the > > >>>>> hardware crypto engine. > > >>>>> > + > > >>>>> > +Again, this is an abstract type whose specific layout will vary > > >>>>> based on implementation considerations. Access to fields contained > in the > > >>>>> structure is only via accessor functions. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +typedef struct { > > >>>>> > + uint64_t pkts_processed; > > >>>>> > + uint64_t bytes_processed; > > >>>>> > + uint64_t pkts_errored; > > >>>>> > + uint64_t bytes_errored; > > >>>>> > + > > >>>>> > + odp_buffer_pool_t out_pool; > > >>>>> > + > > >>>>> > +} odp_session_proc_info_t; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +This enumeration defines which operations are applied and the > order. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +enum odp_crypto_combination { > > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, > > >>>>> > + ODP_CRYPTO_AUTH_ONLY, > > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +This structure defines a contiguous segment in the input data > which > > >>>>> starts at offset offset and is len bytes long. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +struct odp_data_range { > > >>>>> > + unsigned offset:16; > > >>>>> > + unsigned len:16; > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +@subsection api_functions API Functions > > >>>>> > + > > >>>>> > +@subsubfunction Session Creation > > >>>>> > + > > >>>>> > +This function is used to create a crypto session. The required > > >>>>> parameters are : > > >>>>> > + > > >>>>> > +- Operation : encode/decode > > >>>>> > +- Processing info : cipher/auth/both > > >>>>> > +- Preferred mode : sync or async. > > >>>>> > +- Algorithms suites, keys and optional IV > > >>>>> > + > > >>>>> > +Session creation can be synchronous or asynchronous. Completion > > >>>>> event argument is used to return the status and the session > handle. When > > >>>>> completion queue is not provided (synchronous call), the > completion event > > >>>>> is available upon function call return. When completion queue is > provided > > >>>>> (asynchronous call), the completion event is placed on the > completion queue. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +typedef uint64_t odp_crypto_session_t; > > >>>>> > + > > >>>>> > +struct odp_session_params { > > >>>>> > + enum odp_crypto_operation op; > > >>>>> > + odp_session_proc_info_t proc_info; > > >>>>> > + enum odp_crypto_op_mode pref_mode; > > >>>>> > + enum odp_cipher_alg cipher_alg; > > >>>>> > + odp_key_t *cipher_key; > > >>>>> > + uint8_t *iv; > > >>>>> > + size_t iv_len; > > >>>>> > + enum odp_auth_alg auth_alg; > > >>>>> > + odp_key_t *auth_key; > > >>>>> > +}; > > >>>>> > + > > >>>>> > +enum odp_crypto_ses_create_err { > > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, > > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, > > >>>>> > + /* Session creation error codes */ > > >>>>> > +}; > > >>>>> > + > > >>>>> > +void > > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t > > >>>>> completion_event, enum odp_crypto_ses_create_err *status); > > >>>>> > + > > >>>>> > +void > > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t > > >>>>> completion_event, odp_crypto_session_t *handle); > > >>>>> > + > > >>>>> > +int odp_crypto_session_create( > > >>>>> > + struct odp_session_params *params, > > >>>>> > + odp_buffer_t completion_event, > > >>>>> > + odp_queue_t completion_queue); > > >>>>> > +@endcode > > >>>>> > +@subsection crypto_operation Crypto Operation > > >>>>> > + > > >>>>> > +Crypto operations are described by a parameter structure: > > >>>>> > +@code > > >>>>> > +struct odp_crypto_op_params { > > >>>>> > + odp_crypto_session_t session; > > >>>>> > + odp_packet_t pkt; > > >>>>> > + odp_packet_t out_pkt; > > >>>>> > + uint8_t *override_iv_ptr; > > >>>>> > + unsigned hash_result_offset; > > >>>>> > + struct odp_data_range cipher_range; > > >>>>> > + struct odp_data_range auth_range; > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +<table> > > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> > > >>>>> > +<tr><td>session</td><td>Session to perform the > operation</td></tr> > > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> > > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to > be > > >>>>> returned as the result of the operation. There are three different > ways > > >>>>> this parameter is used, depending on the mode of operation > requested by the > > >>>>> caller and the capabilities of the underlying implementation:\n\n > > >>>>> > + > > >>>>> > +-# If out_pkt is the same as pkt this indicates that the > operation > > >>>>> should be performed in place.\n\n > > >>>>> > +-# If out_pkt is different from pkt this indicates that output > > >>>>> should be placed in the buffer supplied by the caller.\n\n > > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied on > input) > > >>>>> this indicates that an output buffer should be allocated by the > operation > > >>>>> and returned as part of the completion event associated with the > > >>>>> operation.\n\n > > >>>>> > + > > >>>>> > +Note that not every implementation will support all of these > modes > > >>>>> and MAY require that one mode be used in preference to others. Any > such > > >>>>> implementation restrictions are communicated as output from session > > >>>>> creation.</td></tr> > > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this > > >>>>> request</td></tr> > > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the output packet > > >>>>> where the hash result should be stored.</td></tr> > > >>>>> > +<tr><td>cipher_range</td><td>The byte range (offset:length) of > the > > >>>>> data to be processed for ciphering.</td></tr> > > >>>>> > +<tr><td>auth_range</td><td>The byte range (offset:length) of the > > >>>>> data to be processed for authentication.</td></tr> > > >>>>> > +</table> > > >>>>> > + > > >>>>> > +The crypto operation is initiated with a single call that passes > > >>>>> the parameters for the operation and an event (for asynchronous > completion). > > >>>>> > +@code > > >>>>> > +int odp_crypto_operation( > > >>>>> > + struct odp_crypto_op_params *params, > > >>>>> > + odp_buffer_t completion_event); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Parameter | Meaning > > >>>>> > +----------|-------- > > >>>>> > +params | The parameter structure describing the crypto > operation > > >>>>> to be performed. > > >>>>> > +completion_event | The event delivered on completion. It > provides > > >>>>> information about the status of the operation, result and request > context. > > >>>>> In synchronous mode the event is available upon function call > return. In > > >>>>> asynchronous mode, the event is placed on the session / operation > > >>>>> completion queue when the operation finished. > > >>>>> > + > > >>>>> > +Upon return the return code indicates whether the operation was > > >>>>> synchronous or asynchronous, or if an error occurred that > prevented the > > >>>>> operation from being performed. > > >>>>> > + > > >>>>> > +Get session operation : > > >>>>> > +@code > > >>>>> > +odp_crypto_op_t > > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Get session cipher information : > > >>>>> > +@code > > >>>>> > +odp_cipher_alg > > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Get session authentication information : > > >>>>> > +@code > > >>>>> > +odp_auth_alg > > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Change session IV : > > >>>>> > +@code > > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t > > >>>>> *iv); > > >>>>> > +@emdcode > > >>>>> > + > > >>>>> > +Change cipher or/and hash keys: > > >>>>> > +@code > > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, > odp_key_t > > >>>>> *key); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Destroy crypto session. All pending operations are cancelled. > > >>>>> > +@code > > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Get completion event information - algorithm error, output and > > >>>>> context. Note that implementations MAY define their own specific > error > > >>>>> codes that have meaning in that context. For application > portability it is > > >>>>> sufficient to know whether an operation completed successfully or > > >>>>> experienced an error of some sort. > > >>>>> > +@code > > >>>>> > +enum crypto_alg_err { > > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > > >>>>> > +}; > > >>>>> > + > > >>>>> > +enum crypto_hw_err { > > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, > > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, > > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > > >>>>> > +}; > > >>>>> > + > > >>>>> > +struct odp_crypto_compl_status { > > >>>>> > + odp_crypto_alg_t alg; > > >>>>> > + enum crypto_alg_err alg_err; > > >>>>> > + enum crypto_hw_err hw_err; > > >>>>> > +}; > > >>>>> > + > > >>>>> > +void > > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > > >>>>> > + struct odp_crypto_compl_status *auth, > > >>>>> > + struct odp_crypto_compl_status > *cipher); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Returns the output packet handle associated with the completion > > >>>>> event : > > >>>>> > +@code > > >>>>> > +odp_packet_t > > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Sets a context handle to be returned with the completion event : > > >>>>> > +@code > > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, > > >>>>> odp_compl_ctx_t *ctx); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Returns the context associated with the completion event : > > >>>>> > +@code > > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t > > >>>>> completion_event); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +This section describes the API/Interface being defined at a > > >>>>> functional level in technical detail. Sub-sections include header > file > > >>>>> names, where implementation files are expected to reside in the > ODP git > > >>>>> tree, as well as the name, parameters, abstract data types, > functionality, > > >>>>> return codes, and exception conditions of each function call > defined by the > > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be used > to allow > > >>>>> the programmer tasked with implementing the API/Interface to > understand the > > >>>>> function to be implemented as well as error conditions, corner > cases, > > >>>>> performance requirements, etc. needed to implement the described > > >>>>> API/Interface in a functionally correct and efficient manner. > > >>>>> > + > > >>>>> > +@subsubsection random_number_functions Random Number Functions > > >>>>> > +As noted earlier, random number support consists of two > functions: > > >>>>> > +@code > > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool > > >>>>> use_entropy); > > >>>>> > + > > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +The difference is that the first provides access to hardware > random > > >>>>> number functions that return true random data. This is typically > used for > > >>>>> seed values. The second provides a deterministic random bit > generator > > >>>>> conforming to NIST standards and is used by various crypto > protocols and > > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get is used > to > > >>>>> disable any hardware pre-processing normally provided by the > function and > > >>>>> is mainly intended to be used for testing/validation purposes. > > >>>>> > + > > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > > >>>>> > +To support zeroization a buffer may be allocated with an > > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer should > be > > >>>>> zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is > added to > > >>>>> odp_buffer_pool_create() that specifies that all buffers allocated > from > > >>>>> this pool must be zeroized upon free. Essentially, the buffer > security > > >>>>> attribute is set by default from the attributes of the buffer pool > that it > > >>>>> is allocated from. > > >>>>> > + > > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > > >>>>> > +To enable applications to determine crypto capabilities. > > >>>>> > +@code > > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Inquires whether the specified crypto and auth algorithms are > > >>>>> supported. Responses include: > > >>>>> > +- ODP_HW_SYNC_SUPPORT > > >>>>> > +- ODP_HW_ASYNC_SUPPORT > > >>>>> > +- ODP_SW_SYNC_SUPPORT > > >>>>> > +- ODP_SW_ASYNC_SUPPORT > > >>>>> > +- ODP_NO_SUPPORT > > >>>>> > + > > >>>>> > +HW support means the combination is supported in hardware, SW > > >>>>> support means the combination is supported in software by the > > >>>>> implementation. No support means the combination is not supported > by the > > >>>>> implementation. The SYNC and ASYNC return options can help the > application > > >>>>> decide how to invoke these functions, or it can just check whether > or not > > >>>>> the response is ODP_NO_SUPPORT. > > >>>>> > + > > >>>>> > +@section implementation_considerations Implementation > Considerations > > >>>>> > +One of the main purposes for the ODP crypto APIs is to provide > > >>>>> portable access across different SoCs whose hardware crypto > capabilities > > >>>>> largely overlap but vary in terms of their implementation details. > As a > > >>>>> result, implementations need not provide software fill-ins for > specific > > >>>>> cryptographic features that are not available as hardware features > on that > > >>>>> platform. Presumably applications needing specific features will > select > > >>>>> platforms on which these features are present. Therefore, while > all APIs > > >>>>> specified here MUST exist in each conforming ODP implementation, > it is > > >>>>> acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in > response > > >>>>> to calls requesting crypto features not present on that platform. > > >>>>> > + > > >>>>> > +For example, the linux-generic ODP implementation may only > > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and return a > feature > > >>>>> not present error code for any other cipher. This indication will > also be > > >>>>> returned on that platform in response to odp_crypto_inquire calls > for > > >>>>> non-null cipher algorithms. > > >>>>> > + > > >>>>> > +@section verification Verification/Testing > > >>>>> > +This section describes the verification/test cases needed to > ensure > > >>>>> that the defined functionality is implemented correctly and > performs > > >>>>> adequately. This should be at a level of detail such that the > programmer > > >>>>> tasked with writing test scripts/programs to verify the > implementation(s) > > >>>>> of the defined functions can be written to ensure that all relevant > > >>>>> functional variants and error/exception cases are properly tested. > > >>>>> > + > > >>>>> > +This section needs to be completed before API testing begins. > > >>>>> > + > > >>>>> > +*/ > > >>>>> > \ No newline at end of file > > >>>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png > > >>>>> > new file mode 100644 > > >>>>> > index > > >>>>> > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > > >>>>> > GIT binary patch > > >>>>> > literal 17179 > > >>>>> > zcmch;XH?Tcv@Z > $>iXhSqNDxrER8c~aDjh?WUL(Et-Vx~th$xXJz4smxnsljBLkDS* > > >>>>> > > z-U&T7c+PqEth3g=pWb`(A^(+`Ju`dSo?U(urKTcJLIfnj!NDO>RFHXxgM;UcgM-UP > > >>>>> > zco&=V+&Rz%2S;jIQRa=N_smYZm=g1R%A)G;H}~-I@ > #)CiCI2J+roi>GZf!`WZf2C^ > > >>>>> > z)RvpX$JcFtiQ5qoYL6FkUycg*4Vd+@ > &4{rjkG>nkclWe8rfD1Kcc1XHC~lIRaY%yb > > >>>>> > z&#AzVI)|_y#V9pZhT`)S%d?B?+??Iw*B&jKn(0AesGPJrSZ@CB2 > `0NB4)JL96L+p} > > >>>>> > > z2EA*#7UJYgNNv7slHc$~o1KpsjkR7Barezu`JrcdID~L;+5)WX%*UJQ&Yi``U%4(X > > >>>>> > > zh-E}#FgHFdGdD9&|LPB(lF}u>&RE{s?M=6MF^#D=F|5EA<NV{oCcMa<zn~Mk<T(Ze > > >>>>> > > z&0HR0nL<AyH)RZQ<XDn1{1sHSG^Y=gE!Bz}JL8mgNokN{HQQR8?0sLmM}k+*VtSKU > > >>>>> > > z0(G5xjIBkg*mgar8dl?2>(#mwgCLf6u_Q?2KQ*N}ioKasK+MwbOk$c3&Z~KIZ=mPa > > >>>>> > > zLC?i`823#_G-G7OIGO%Zt?-*4ASFD1bOllAd=>Z=)0y0vs(aX((aGyG^fp5mz!EEf > > >>>>> > > zF>d?iB8)~$oLa4x=o~?8D}fg;$+MVIVN%ak%xZb5y40sy{T31f2D7)Al2jElI=#fN > > >>>>> > zx)0-4Uf!(2BHt@6HeOe~;Bhg-@ > +!)V3ysYAsLS76mS&4ywdoKN<Xkcj8vRSH?CpA^ > > >>>>> > > zZ9jN`nyu1e6#Y_3nzMKf^V7svbi+ln5P6Btmp3WERhY<Khny?~P8Zpg?wVm3cV*HP > > >>>>> > > zF7irVsHEod?fy`fjUhz9{Io}Ph2yS$vZyi)rbl*X|6+P8NG4lr_T`IRUN`;zBs<+} > > >>>>> > zT&;Tegh9lXEM8H#WzrQ4k0`6-rOIZab@5GnK > @r4wCG}xiH?WAEvh^2e8oA|8_7(DV > > >>>>> > z5#{zDv#r_|AZFJ|X*X!oF;&=4Fo&EnWes7Xf5LE1ZL%z@ > !1el5uR?cCfVh?NTYPzB > > >>>>> > > zBcJE;-j0G%Ppbn+w^1fHs*r*cspp$f(G$WC(1olV7+1;iP|5mP^(0==$z0aQYE_N1 > > >>>>> > > zFJ;$W95c_yL552$#QpDU9PXBRRb|F>CNv1JuK7MGSR~?}M)kid{}5SM^TJ#tde-1^ > > >>>>> > zqHAH7)P6A@4 > ^IsHUVRggU`~aL0v88o>F0e|d~9In=Gaqy9!h71JGknx1kk5a>{LRn > > >>>>> > > zJ7WiSU7d^tmr_kniLBtPMh%Gv_z#>Ks~I~B1j#>TDETJt+oLT^>%d$VrsQ^(^G805 > > >>>>> > zKs`qV`Q@O > }XIF0R3S5rE1tG5KaRey<eev{=NU2n>D%~0XZj&qBhgXJ-OXdPjX%P#o > > >>>>> > z=imy!?b@^Bdbyh91U3fS1-8WVR+)p~rF@V > <{4{`?m9{iM{V>%%rk<_FJQmO&;nng$ > > >>>>> > zrTh`()rUt!GGJ4Hs6_n$G;B|fguqa@K59S3 > =7BW#S1Y_73S6kJOv%g%BFORd1>Wru > > >>>>> > > z!u2w4OV|4}Q}I>YDXg!02-Nv(Wm^-*Y!s7WMx3ro>HuA`z}u}pb7Wlla_sN$xCfeh > > >>>>> > z-W5g#<HDupfx1pwl$br>rF8z`UH#Tx?|Sq_6f-@ > -8m^0-NE}>f=?0ZSkg?(OfT*s& > > >>>>> > zb{*dZs*0x%Ty1n#a>?cGHq3Fy=zNod!EhM~!B6L4R*B;U-8PoMFD@Qd > *}L}J^ON5Q > > >>>>> > > z3}1fu1ADd?Xm4aDO1ti>l2Ox^PN%VDw89)IJsE-(Op<Ns5)e4989DV%{7NE$`Jm+0 > > >>>>> > z(K4#==OJ^AIAuaz@ > =bhu!^+GR4DM`H(~oaRaYLLQS(zSQ!MLA~$1{y#A$MTpS)qZ& > > >>>>> > z*0}KkoEc%u(+GK>9QVU9&yPO_e*?h!qR&iJt;nIH)t~yf8;2sQj@A- > &iD=n^v7>7X > > >>>>> > > zc;w7TG_d4bWf^7^5ZGMr?sur<9VshcD!Ne3bXi7tV9IfIr74>H=iHEynQ_Er1O;1W > > >>>>> > > zk>I$rnyotFAW|IyP#dhiq{>i+Ye7KUVEDs=;cp-67Si*Csi1BoR2<J!o$-Q|gS5|L > > >>>>> > > z4+g%AHrzW;vt^H{v=5sKp*aU1il;Y*r$;Ia^Y}#fbHM2rGIS}|nrc>1Ne1U9ee<(e > > >>>>> > z{&18JjB@`B48?@mEPm@A`T+R6^(hEDWx-U@F > $ouS;wIldeGtiCDpz<px&I1cf~^od > > >>>>> > > zN%W~-ywM^`V#T5x`m;+xXUl^t?Y1c#oPFl|)POywWv3Ue1Rf=pkRD22iI#s?!(zJg > > >>>>> > zALmv^$p~`W5H3@mm}crh;p#o{<J!5r$k%+Po@tx- > *!o`2m(0u5XnMFxfV~6WdcQKs > > >>>>> > z2!&cJ<gb+rKfCzGl@h > )vL4`g#`Ci)o8TsPEJtNcvs`179wMRyppjGD=u9aiOl~V{M > > >>>>> > z1?O`1{aMD1Zx%(YC&-OGQ@OP2irm@5yet7qtA^*i<cO_=*_S2{{+@r- > <imD)W{g)( > > >>>>> > > z(I^dg!5C6}u}FmN5KJ(h+IyatbISifm}l$LOkVzs))VbdpHqIr*fe_s_)-392h0bK > > >>>>> > > z#q7l;k(AFoiVxgvb^SK2^sWs$7pVbI7Uhnl=+@%!=@OIUzb+6J<47Lc*8x6?Gup>j > > >>>>> > > zfdKa#|H%{VV1xHqm!f}G#o(t=TSQ#U=4JOAti>7GRvj)oi$!`#5kRe^uSsCFF}1s+ > > >>>>> > zJO;GkMoocZc}bvxWu8aQ29|!{E@UXVi7X > )9f{Brr!dd(}=7S_1aVRHtJd)rk(t1@V > > >>>>> > > z_N8K;I_(qqxGySwr|%Ibvg84-6||UwIHlq5w^uTndMghI=He7JUg7GHT&bqI`+i_= > > >>>>> > ztxz_uU|I?dAsW3?e0v4f0-c^yxG<XaH`Rel6-;HfoS|M>4}l*v)G!R1y-@ > _VPa|sz > > >>>>> > > zd)68tM(n|97s8&g+Lg$ZdS#~UhlVpA!Z{m#C2DhxGHrvl-+h$*8loFiH0};{B3IsR > > >>>>> > zWdodZ^gZc(9iidRH=J@ > (u!2C6lbpPcsxgI#ol`*OfkRPcvZng7?3Y)UO(3N-jH71- > > >>>>> > zQHldV@tK9 > #seT88b5Y(PlZhTUoe=gMVBsb=MPj4-5$>dNbTpF=S<eNJ?Nr?$LGwl_ > > >>>>> > zP;RJ-)L(7#hWzES#oUo1T?6DX)v>>#Mi|Gf{-k=J+&17tFy}ii>>nI7^tUSt%8z@ > - > > >>>>> > z+R0@A > &uhTt>pE=^DwFjfJ$F;C=1~{aBE?cUaxj~R#~ufOThGm7I-oRst+i^U3XrR~ > > >>>>> > > zoAQOFs|mk%yPn;YSh}`v<itr_FRbtRUSM8|$lmqp8=#i3(7$WxS;THPc1;O4vZjdO > > >>>>> > z!eRfY2z63FTji(wvXH%-So=!}$Y*f5xAH6VU29)mZo^_O;_=zmi2r@M3rtx5j > }K#c > > >>>>> > zF0&`TcR`K_)q%B_)*f8F^6JAG&ZRX+h3woDZo})g*I)5*_LV}k8JD@X5O > $2?4>kQG > > >>>>> > zEgbtJ3*baF<V>?13RfJ+KUU)K6GL)IHtt8xfhpb*(}HE~TMDw1h52p@D > ?H|eLY&## > > >>>>> > zwR@C > <v&4gAAJz}Tc1gQt6X+r8f7sf0VxwUWO!%b7t&w%Zz=m8i$k_9m2xARy25Jee > > >>>>> > z>p3Ii!e(CH?Hd^ztnl+@B > ^lnk5pAlxr2g97Au9vchAyYrrSbR|XZP|rvM+DsfOQHM > > >>>>> > > zyimv<J<kon1<#jpi<)icJmY%GNUOv+F{ZxPC#^;g4wwl`l7o*vf;oZtq!^9QKlGp~ > > >>>>> > > z(tM+hyL2fSOBOpxD^mnh&2NdfO5uIt;sy5!gmL>yjSUhMntY}K6W(>=TA9MA`@ > > >>>>> > z3mUA+4I9pd?s=^yKf2!-gq^UX@ydJNsxb38gCvD > &hO!d|7zyHf8zoz9Ii6N{R#Z}` > > >>>>> > > z=adl4nY<HHRqVrNldic1Vc(R(6&#mo)8n+54;7=zwNjVW{l1s>ynyL?zQ4DpR1p<w > > >>>>> > > zmYy!(v;VG{ta;<c=WK1aR+N41k75yyVNI2O;Wcj72;6G4CTu3->Qxkl&-Ya=d!^zt > > >>>>> > zpc*b;86HysqgiW|_ZK(6;~*U}&tIUxoHAu@pGAGW > >h3nWdmFt)S|z0i^eJvlAij!a > > >>>>> > z8?A<h6hc@wxHSsJZL7yPHC(?lTFDyQW-zkCFhPOL!GQJGJ;Z*v4JZX@ > _If84{-LQR > > >>>>> > > zRm6YNMuI<gb;;WiQ)lru`(&8e8x|?4r$b(qKPwENt9I(hqr7AJNsYo>y<Pc)I*@oM > > >>>>> > > zUZSQHAGH{o{2*b>Vf2p#(`bQIaWP|G#;dX$a|139C&QVr4TPUGI4g374q!V*W0L|} > > >>>>> > > zV>7MHT+>F1HV~LP&4YNDUS?f-DFK(NTCN$Fa2%Z%$8T)B1JUu=&5HAM35Wi70Mp04 > > >>>>> > > z<Tv+ma0rEh?|CjNP(RJXiUmR;oLyS%X#z6-`({4FTWa~!f-U&ZjQ{##3;s6&w)h|6 > > >>>>> > > zKeF>${R7~eKD4{v3FhlfAKUa<IgcSVCiXAl{iM-;nLYj!9Gp2TTsD%aKcJ6>nj>s! > > >>>>> > zkJTIGY&t**PW-Bnj@BmYuLh4AIz > ^&_@8ASSurGx(qG#+IWXm5ls>~-16Q0PHLokAr > > >>>>> > z&h7W!(v~X@ > =1ng0lm*>chn4v)cQZEFY+89e-96l_(1`!l;^|R6Z+GQobA=rgj<++O > > >>>>> > z<FxKGBA%*lZo3ZF*^&eUmnaX1OA1^z)Un#KGl_T##>3+sMC2I#ZL-G!V4_u)<3@8 > * > > >>>>> > zQOwK0I1|UzutGtcF+L$y)<JQjnRrHywF&p%<EK5L9mkBa3v3N>eDAKto*5GMHZ9@ > % > > >>>>> > z_;a6cc#G9IQ!oT&kO@|l0j}5TyO@JeqBjM+k41i-6Wq>$s5x$fV`y@ZfkY > <}ng;h? > > >>>>> > z1J_dY1!QyNUYXrOoso3g#Nf?+u|<m~iAN&;di#x^M)+zmjKc`L@NT4tWSwok9 > >cpS > > >>>>> > > zwUgKR2k39lxb#}H&4*Kefe=CB7U%wrsy2{*0jr2D?B6aPOaoWPWrO*y4Sv^5{oWVH > > >>>>> > zd;x&><&5=iiNuB_-2}$(jaga_wwZ03k<)IFeuuGjddUVKYSbkqP;@ > <)sF~X%02mJN > > >>>>> > z$>E^`{<dl7xO+m4dk<@{$+gX!(<E@2uRkTBH-tX-YPOKk > |5a<3_B;4?>FzNt;a9o4 > > >>>>> > > z2bl4j-Z#0+VMv{<2ltkD;kEmZ<@k)%b74-{dpVpi_!4_J{MXky66fE4?Dw`9=Rd#L > > >>>>> > z;{O}@k~kBC=3czvFBS&#Ai_C)vp3TCZ2@ > <1oEH<EXz67f#auag&ebj(B4H0nQ1!x% > > >>>>> > > z-{h=K&}gjm`dG*}lWBW<B5-y&OUe&crhKmHq75OdmP~?VjoAmUiWyZ;p^Sp4QPP@W > > >>>>> > znOz}QN??*Mx*HVtfz{?QaXXp1aGr}7ZO}DPMfK@YA2c-RMDDMJ > !@=~`t^|~NK~)We > > >>>>> > > zQ~mruuL<lf3`VT<60(8CTxSzfHTh2U(J>0XIU&2_ER*%>*Sy(|ugRPb)gW<m?^jQ? > > >>>>> > z?Db@F%eD?=0si+mE;te{GhI$>VT@dYvB9aMN3 > !;lEn1ziTobeX#B~@}l1Ey1GKFui > > >>>>> > > z12Iv^tWUk#rOs_{d&5z7wdH!as4|GdCU1dhQ8sFu2E$nV7T#KZdC0LX%DB*8u1IdN > > >>>>> > > zV~K!t9F`Wcr)gBJ^V1o(MNOru|Ag%V%c2BLy-m=(xqR(^oT(9q{b-Sd$jjHFt(TB~ > > >>>>> > zVuZwj5CP6v;P}f@Q > {y&06CJHTo~3wwM4$rgMzuB%Sa<o*n-glH-ll0D0!Alwf|+dn > > >>>>> > > zJ3BtcIB^?3d90?7aP$YTB75JyMVle8QN&2U81<YS%W{8V^wW)y?RQ`u`S4&$7v}lo > > >>>>> > > z7EZ0W02f85WdTv~!}*{>Z4kMy{3csPyS->6CRTsykmL93Pg<4I9h)QWljA_45*zYK > > >>>>> > z%_U)Fc{b>yCC`Lsch|yZ$l6J8mK@26 > =aOFYR$6LF>WRa1W5$SuHl)5Ol8Ka$M5Fsy > > >>>>> > zR!}oqj~olnQu-nhOJB-W@0%&1No@7&Pg<>1I%vj@g > #qp*970HtICfX!sAYNB*T<As > > >>>>> > z5#O4GIJ-2Xu{LG)rbcE(B)9+ne@ou{_OZ2y1|}`^ZiCUm>0Z#bms3Us<owD@A > }QxZ > > >>>>> > > z(sKnYC*CPd0piqAMTwnSaXCB6Xawrct*lY^hvY22W9<E*+BvI3<;)c0;)|6OI6v}( > > >>>>> > > zX^Z4`Ur=cnFy)M3%6hMTOBf&Co_C!6LA>(7dL!PoabUw_<=(v0rRmQTK?wjJ-y}Wa > > >>>>> > > z0<vy4(r_)^GtGCviRx{n==LC(JGJ(*OuLo7SeuXr7fP7h-0M&{1^g5j^cJBj9~c`5 > > >>>>> > z;g2ptrB(q{Wxj_(w-@7Xf > <~?n{T>lFmk`2k{Zr9qY;iiHjHp>Yr~juJHcH|J?Z7CR > > >>>>> > zQTHZp?Ygprh4CN@7Aoyn(@neMOOE<#AL6t~(W<`trf*_o(}-I8@za > #7y+vHfh#Q%e > > >>>>> > > z0}fo0w{OK04h~kF!uo7pa=M!{U0gpQe$Cq=CF8DF1&Ar?bCIUDp^DOSI<Up#sfQ^G > > >>>>> > > z<ZF}$ebc)Y+BlM?A4H;L)wct=1S9#XLZUo&N-z0$SxN8>e-ore*8cPk8oj>IDszVt > > >>>>> > > z!#efRTC!`3Iey|{|2pgi-my|Fb-i~G8Y1KWjR)Y2bv9APh*f3#fPb7dMhAmg)gyyx > > >>>>> > z5l@x > >bEHPjSJI-pJNAgf<#)I!g5-wPu0)D#=kkRxUvGgZynjpLY=n#U2W{N_Mi9hl > > >>>>> > zH-d?W62W9L0~9R_v@KU?3P)LdEpT;cqS@Z > {rnvv&LQcSlk*fKUZP;~gOO)$wG8#8} > > >>>>> > > zuFbze6l)bOp7FN3P}X#asYY{Aj6uT7crI37FREww*S3085AVaYPbCKKLDyzho5)a_ > > >>>>> > > z0<dLAHzcaCJJ3QYJ$8)80uMVe|2^#&7R|YyRja`sVE+0suYn#licVlf{F2L4DcKeW > > >>>>> > z|3{4<dzBZTellJ49XLhpectV7<)FK31Lt|iS}k<81RCaC9NRKPZrz%w@xdp > (=T7%g > > >>>>> > zc({xiEu7zX(ui8>-(zG}sRlg}H|r;94{L@AFtg > +F1(`Rz6fupGZENm924uUkHm4ix > > >>>>> > zhU)vZ7KE8iyZwUXN#{$texK`yi2Gib__y!d2a3Gvo9H$<8oR;Y@ > _7aed>41Ee5JB^ > > >>>>> > z@T_dMofuuq{k{1@3cE > |tp~K2RR&q~~gxOIDIeA|1&X#zUb5xxQ)xpBp&V*zq*JjmV > > >>>>> > zZ-8?Vs6RSNc1)q~B2J4WNI;rP@re_ > ^n0TDyJY-_=Et$OHSY??_24C!PT>ehZMGeVW > > >>>>> > > z5k0M%I-=rycC0oMlae%c4?sBD8#Ge;0N;mmBQT?$P7KmH9=)!2*h;nPH<YJ6qLcrL > > >>>>> > > z4RrO8#7TN=-D+D$Su`MD)Ux(L2JjD9Ze%=5Esbl_qY71uA97v}E3vcM+6zUrSO9Tw > > >>>>> > > z^p&)A%rl~ihx4Pqe<8xl0?WS9Ua=-fgZ%YV=u&xwi>zSG*MqZuf<6Dfk_xPM`WpWd > > >>>>> > > zKTXw5-g(X-JMLv)TmHe+82}dqJo^@4MzhhP&=#B0^yItSL!%smYNTNdoF09?J0WBl > > >>>>> > z+bgD(rA{KFXmsremy1DZP&+%wUHKh|d~=Cg)R_#3;TXMcUaF8zI?=u2E@ > ?w+?~2b0 > > >>>>> > > zK5i2A24}RgB^lWQg0grGWAYv2N-}<Z+L|eG8Q#F8g(FONlheXEO^)$>PX08cUd-lr > > >>>>> > > z*ns1GBslX$vD-;xpJnBz1i5ZV6Im5wr;&Oai1I~NFeUoUwPx&8jm`JINV7$dXY6&# > > >>>>> > zv!!Ah)UOsKM@uo35LUrzq > ~)NCs3kv&#dLxQ3`e#l?zfX7gyQ+dt6CyistjcFh9dwt > > >>>>> > zen3xHYq^xmVbtW2C7#OWO>OkmJ7<y|;mPGK2vHMkTIYl2Lu3D@ > $k*eqU*(~6PF{cW > > >>>>> > > zzyyYWmzcZ|F2r1pr`ulba6CqW;y_S+D~BHvoBdMI=vvup$QZ0^m{VCNNRIB|UQWnO > > >>>>> > z`FBw#>+dY|1vog1@hRjqDzs6 > !Ohah`+IO(LuGta7QpB&)qrcoI2||6j>pjSytw#lO > > >>>>> > z9D8icx^xN}vRuiOA~qBf->D;)F8L7LPYdp@uKHnqAC > ^sSHt3z#?jY4MJszOaflkU1 > > >>>>> > zV0v4PZ&=Yi5fg0pSIR+Kz8XKRRlZ4$7KHu`Q+?Cq_A@4edS2S > {Qj*|zEx0WIPmJVb > > >>>>> > zpdAg5`8bo4L(L83?@e*OgX9WBUvE&&W$yygI5TN}tacj@XO6 > ~*!?MZG0+<XJP_fI; > > >>>>> > > zG8iUvHdgZqVo+N7#<Ij(%QvkK?u13T$;%oEQI#swMstg`I046)>hPWb-*_em`{hVk > > >>>>> > > zkEJ&(hcT99yPO?+*nLFxtm=_p=?~MrjNPmU_n^Z}{K(gPsvIm0nSOQXh!tpHF8LJb > > >>>>> > zQUWtb7eR<0&z4@ > -{S<RWn~5UP=9>M;<kx=AcW|L&uDg>vF5H)2;FYv4>arT_OWSqH > > >>>>> > zt{dJXLl4M7vodYz-?yelWZJ@ > #4xS}yGw8%84cg7$c$46wy7ujmLikvj)<U^M<Mew6 > > >>>>> > zY5jM0?!<DVPViuHm*)q|wEd*@0no*d?=ShtYtLW8!bl;z@rbcWX42E9IL > `c{720wL > > >>>>> > zE^%*|dtormIFyQ<DNqXB8oj^ENeHt6aLSU@6t > )+EEBx4(?i$&e(0bTV+dgM<sFSoG > > >>>>> > > zEXFWF^_5kX4YzpcNE?=cWe$3Hjz&jmNa~D`^Bu1uf-8kFHto7$8azi8$m?j|z=9iz > > >>>>> > > zT&ypr&0&T6?!rtDV?%rfee)!v4C|eQ=IwVSd(q^cf!c0U0Ar6Li?ZD1!p&;x??2pa > > >>>>> > zpm`YzzX4~{_eYuW91VwSc&P&+>av(>Fk5LTUdtkghuHkOqR@GJthOSV > |0MMVq_C9- > > >>>>> > zsy|P(88q{C1MVjpV|;sm8b(8qmE2^``!XA9fB@Q > +C)HG)S5#McF|ud}BSNo1jtQ(I > > >>>>> > zyFAMMjSBu{K6_F@ > )OWeO;dxc3JtvnlQ;u)R0%e=7l^TDo9G_}h?J71Nb>rj2hmXD! > > >>>>> > > zL)({6sw(36Gu+jzJ#TRq39d)x*$Jo5=kQedpX<FhHKNskvivq*Oo)bQ2PnM;pPA=L > > >>>>> > > zpT^qKHxZ~^EX8|doYC^%_!+L~gRgng8`l=S!&7p9LBCxmnNFuOAk=;bG`|tQ^2VhS > > >>>>> > z$W_1NU3pb`?1sj=1{lJrZ2@mTTG7n$l<-`djWhnf()3Cm-7R3g1bnkHd@bfH > )iE_h > > >>>>> > > zD3AXYA_mve2$#mS8soDV<;%NdHG;cdC_P<D3CNb`3U|^Zi-x^cdsDwV6jW{XyK_&% > > >>>>> > zfN}Dt4y)s$*!7z+mYyK>R#$t~u0Kf#e@ > |M`Ho3AUHNT(?VBKN+u4>28UWt%l|9t<< > > >>>>> > zaK}+yg?fO*nX=}vH=byVm7Y)0DN~*cT66xq#T^AimQ@koOvHXG > %AIBLD4_Xc-*}w( > > >>>>> > > zgsmK8HmSnD04M6Xc}mClW!p4Nz(E!XTe5zI>$Ul=WVJN9>We-(X~=QYeJ;1154~Ss > > >>>>> > > zK(-n^cb>L-4yAOfzx(OMoyD0QEVpuVtLI}L3)&tbB%pgR^_Yd+qYh#OLi8qc;sNgj > > >>>>> > z@i3KbQ1m9UHGWG > ^6TNq3VNrBi;d8fcUrzwjgN~A1ysj}cv%Q`-X%%}M&CFYWDEC?S > > >>>>> > > z=d0qRock+Wt~XZDI2{qsvU4u5^#@LiT&9BTe&TUe<RfQ+I2~J`BNOPyv#xhG1=7@a > > >>>>> > > z5_AMm6_%?Vsw1a=poK~C73wjer;8-5bLlOlu`~PqSaU+*?|O)K%j4BP;<{(Eg^R?v > > >>>>> > > z4QiKnbPDqD0){2}*%J_XVD2|95Ciy~d*j9YHe3pN4BwI<2q`a^bslD^%t|s$yM(~7 > > >>>>> > > z!0t*$VdU)S)q9D1%Y6pOdad^!e{Z;O*^E+XKS<V;e)oTve1tH%h)Qv(GrTwmXB-XW > > >>>>> > > zqY~%cuBO7^1M9T&*%-uvG2rvH%hq_AxraK0j&(m<N%3~qE-{z(MW?)tz_OsEpJFf` > > >>>>> > z4s)5bvZAHug^?vC-bc%Szu9fyJuzF$eWp7=CLs2+g&VyC{?_zsN@s > +B%KcNS=yXIR > > >>>>> > > zW;K3Q5$<(uWwCDf+Qx*5a4`rj*Jr~oG`T)HeCYjbU8krV(aq;p!(rN$fq9^4++e3K > > >>>>> > z&Qi=AJHxHd6mA;x{%g2*oAAdke-emcf1q_A|D4ZDxPoq@X > #%!~R1RZH4Y>4W!7CO7 > > >>>>> > zI5_kgIo;oa3p9~FdRXlctLl2tVQuem>+xW?iV;@ > %2ZDg0%pdAVT%2Gzl3+OYX!G0h > > >>>>> > z+e#W0lw)N<EHD<RhAi5`s>eBZCI5qb6ldIH^ED36@4 > }HnT#xkssDaJHN)BvG<r@E5 > > >>>>> > > zij^ZN+`7%nRKJsX+tTm<P5a+k|Hllr-~Xb`QNOeK`ac-NDa7`Q<>g<?nd<+o<d$_T > > >>>>> > > zoBx}m|IzLLvD#Ak=JY?yw0siNwt3;b>T2ot()E1F`zFNgvYhP3WHsOEbN$a=z(D<1 > > >>>>> > > z2c1<oli>SPv`o2qeauhK-r{fq9CX^Q!9$4((ofDJ1*BA}u$`Cn3<RxuQ*>P16SMTr > > >>>>> > zIdVpgucZ_0?9_E@61KcE@pfAu@ > ^0_Sort5c-NliMyrXX21bO%xsq!?Q-kigcovJ&u > > >>>>> > zKYmU~MsmwJN_FXo?Ke2pL$xA}L54W6f;6nA%@Xi5boTHm#vCZ<^Y;qa=y_Br3X@ > -} > > >>>>> > zohc5MOWNES{VtZec<tleQh$v@TZbs > *EFdi`*EKHD$_0$y`QT^gQM-1sZLt#sMJ-|w > > >>>>> > > zd)f)vejNUMa1*19cP6WvPbQRwV<Zibn4AQ^oRd1_8MTW5Wh1ZefPOb?t+A7BdeTL6 > > >>>>> > > z_N*IE-4(apYh$bucAsJJnsIrjcaFDuKKXzVGI0U7X+J?{#)1#k)LXw`Lda{yug&<& > > >>>>> > > za28eD)=t(l_yt=;GxL>m)cH^(z#yZ|3fEY<>5V(Xt%E~0`f`IE4#FLMjJshz)?ZI> > > >>>>> > zZD@ZPC > +@x(`%A6l>!;k(bAmf<LN7zPIl~Xha7VCEeLlR}ZH)oeVRVeWC0u%v5+a^1 > > >>>>> > zIlj~JtxGsW@>y-VLyet+%C1lL9sp}MGCw@ > &E3^Zg=)5?wpBb-sR%S*pFPM9RToe&@ > > >>>>> > z*k%Q#XH9Whd*6|3TT^Ogc!6GFqm(o5x9Xn1v$eV}wX@fPj_D > %>OL+CiynE!eM!V?? > > >>>>> > ztuk&NITRn=(eb5g3bq@ > &ct?t_9YIu_ZCBe}Z#Q+vw^^W$J~{(bhEjoOufHtMq1KMs > > >>>>> > > z+>~o`ur}hfg+pw_5`{=#9s1;Y6hdSz6o<toA&m^;)&Xg17%_dpfJR4KVFhE`I7i*v > > >>>>> > > zIF|9&pir^kdf~!%>HI&UzbfxOI{EM-*9pQ&6I;C(&Q2hB73xz`x^>5r+glgDL~^9r > > >>>>> > z@plrI1lpAzQ=qrIXn0AVFK&#{ZZ0Doj22gN+w^+d@ > %JIVVU~wBY(`=}?8E`PQ`{yC > > >>>>> > zH}=FRoOQ}LS9A(F@A > (=}=qhjO^X4DxGZbe61xYmHchTD6A>j?SoBHaq$dp~$ad>rs > > >>>>> > z4Fl<J;unGC8sJbkJwzt~lyzW$3q`_3vrztgyezMPdkNjNL@ > @Ph$jD{=4iB&WxrGA{ > > >>>>> > > z{mcF4`Ti8$#?~ZiTfYuo%o&5z_p24jvu(TdDZ#bPu+wZGl^Ls{Ux3o$f}g|+gSunY > > >>>>> > zg(=VnnCcaRIoM>fV%g$?zV0t?Ichw0)YvtnH{Z<fqn)D~>mOB+lt@J > !m<4V_Hi`L9 > > >>>>> > > z-G{b64IoLusS`(UeTQ7+a{R3ww~KAQ63^hQ4R-8LHIc8s1X_qpp~pp=1dg-nvPtPN > > >>>>> > zr~cS*gtfo;C$RwM@ > ~w`F9K{6#^KVnvF$nANK4Jtz_T8Nzaf8C^XB3~${aBYA^>qy8 > > >>>>> > > zjFS12;z;usP9NJ%=L`1;diUo)oQ4ZL=Kq>_fv3i=jaX?rd`~bJPHrhK22#$LN2TOC > > >>>>> > > z4R=nIo3yytcxma%izp{kWz2k3?uN>tr!q1IkvFm9M^4^)K4rtgLDxwh2r9xITy9h< > > >>>>> > > z5lnSG8Cl`6mF;%x2>yM!96JdPYHjjF^)vuNQ1zr<FUkCzj_F|vZGhN*5u7s~JRa02 > > >>>>> > zjk@#)S#!P><=+zCR9gFI<;7W_<Qjc{o_-LJoRoTLOP^H!>rS7<3)WAZ#j@s > %D}TPQ > > >>>>> > zEJb&>n;?|jW`Zvr!wkrsy(TNU$8Suqk(OgIN+)CyCue@SX1SWq > ;rhk&-5QF}JqX$4 > > >>>>> > > z%hG$T=Hnm+x%npDV_RQ=SNMjYm6np?46Ybi?>JIB&907IeM+{Mn}195P1^J3->crO > > >>>>> > > zvX|$5F3nxMa;S7^-`ALHYS$gPLD_ujCKowt71!{WikHkemE+;Ho7Xliep<sLeG~05 > > >>>>> > > zEAONUjO5lB%x+uiThmvM)}RlztV;s?*Yhc-Dk(a_drV8)Z3aP<7ka^gcPH-6?~dHl > > >>>>> > zRd?ET2w-1*Nv{S4_4Qx8fBceU_#V{rjS=(G>8G~M@ne > <E)NIlcN3Kt99KY-NOPj=h > > >>>>> > zzmDx1O6vL={)hWTW6!>}4>XarMZL|aq1@hX > <#ocdLjQDOb>h%H#;uY4g}*2Cns#!7 > > >>>>> > z<8>jEIrJxER$MMS%J^ola2qN-CcTgmRJEktGpEAdioa~6B}{fz8G@9zTo8 > >;e=Ju| > > >>>>> > zrbkSSJyC`$&e6DKZqoVUNy?4rje~t)JffCXU~g2B@ > >JHlSP|a$(}TOQn?CUkG>-D5 > > >>>>> > zCsmo}@3 > ^RPu>?kGd*pZ^<?0mX-Yb>*%gGqx-+Uq>KY<G~5*Uy+)u1g8S?Dy_yckTi > > >>>>> > zR;K+ddnB1UdDouP`~6vJz<P*-#AJs`WMSj>FT9m}@ > {_<t>n1HTF~2erR2sQ6!AV2e > > >>>>> > > zpR<U#z2d3yqqH9lMHXWwrxWu#yokfEHWo&D<6Dhpo3&(~vCs+C!SVUDixNAdVY`p@ > > >>>>> > zSsuN}81*tX1AXj;;mH!oI{=>0mCe@-rGp)roo^4w^D@Gft_ > }Inp=g6qXJ$IRj$0Sx > > >>>>> > zE(oi((o=}iN!jfL$dsD3_|?pV%7w8Wq<!-QIhQ0;?=O)S4oe?$-IR@z > `)}jQ|1<rN > > >>>>> > z5Z1xuxJjr}VCz_)8K5}S@91 > >>p|84RNVtRqdG0!h8Lg22&szUq|NntEE8z|+OQ1p5 > > >>>>> > zzudZ6FOXVqDNA^_D(3{E!@~5)y7;`aG8(>7@6N > }s`9bo(#4k!zi1u9^o}Syfm-)i5 > > >>>>> > zz(X8IFj+J0w6l}^!*MMplM%m`H*xWFEP<TT@I7|d2&>E0xdx__S-@Rr > =QF88hc)U3 > > >>>>> > > zv6=K|9P8O;BI-BMXz5k|h(kCS7kzrpDu~4!NN&+i7b!^k#}Z5-P?S|`n>z~JuB`&P > > >>>>> > z;WrmOLsN@bXR > ^fXKfkg#=jrapU`o5p$iC0FUfCH83zZk+Dw%Ub%s6q8ylEa*fecOp > > >>>>> > > zRd&HX1PE4tf3_`<W0qlb&3n|nhrHYW%^ezknR1`vK8mpfY0)F=@AJ&LF?e=(U<`p; > > >>>>> > z8S!DrS>YVni`aJm>RP4S{G2+S)8w)oReJbE)G@Xe > @=k6i*`=?M`k94SLPqW-;=231 > > >>>>> > z9$9dppC<Q5#kB^zTWX_WA}*`_$qF@*dCHy1?lG+Gs1g?l;|Kl#M@SMZ8u7 > }E@2uqF > > >>>>> > z@=1KM2&I;3SIIVh58Iur^VecLfo7PKd@06ycFRveG2Ai3IukF > )t(BEJyX{TWV`L(P > > >>>>> > > z6jMW)TntQD*S_VtX>upFc4K58vHF}niZS4vTNYKAIyi{8GCRv{T8Q12?U_`f(OhvG > > >>>>> > zb(g>7G;>K4;C`p#qCZ^zrtHnrzWT2xhy(|*n=Rpfv$WQ}s{1RMBiR@JVxF > ;U-tJT? > > >>>>> > zhE%QrD@ > _4$!%oKtfPoiwOqmvVj<4#qK{cn$MkQla>|b15tGQbjmJ=hR-LdyqjI73^ > > >>>>> > > zh)?pA>J(mMzz-}^-8~6}>1(<VyzSIS%Pzs&5>;y4CBJ*AoQ=Js&xp8{qJD3RQ9ffV > > >>>>> > > z28NpZ8)xK~2-Xwkn>ut8_Kno=`}UigPSZx0sYSiNcucsa>N3L|@6uR=^R{oxj%#Vv > > >>>>> > > zaHBr1D{rIaG+XUdQ4gHbRQdHV;YFT*-t3gI>hm0#tHEv)whe`TIo8MC>TD+6fu=53 > > >>>>> > > z2TJ2?8zpzMw^s++X<~YHKeJ9EoTcPUcSM&hu`0fGa&Qdo88MvE3>QVax#g9`n$1Y= > > >>>>> > > zoyDRgqe8U-gJ&NgT#UU16unIEU;36KUQ|5}6k;oG%Ht$|1sP_w;*b7Z7tZHls^x3o > > >>>>> > > zGp5Ev62kdo;9$c2JTNj$$&*IsRjGCaiBX#i{D&&R`E=aaNF^_o2ezJ5CsOe3WimVU > > >>>>> > > z0Xy>e9G3Lc);^%0BZ#*Wi;_Ed+}CF_R=#2$e)wDv8~c_liIkP3Bu?9lKAuk&BzIm& > > >>>>> > zc@$lgD{?SJ_@nBTI_rkbBWE > ^Lca0JM-64asA>zCa-2nwy6s;(7B1JbQFt(%qvRO-2 > > >>>>> > > z#@N*7s!NwFpz&);5|}ZCm50pv#I5}`*3iAOT%*WmdBCOwP7)H|Lz&`2zxKp=inR(i > > >>>>> > > z*eke-1+M*@BtX>rU-WlS1aW(=O;N!jHG~8oXIEUbIG!ZxRc5S&8<$G7luQx{Z3r}1 > > >>>>> > > z2agHu=vKbk(to6#bLncSXh-(OG&ve!z^1H6*R!F}eJ4K&Q9=Z>ymRivvovII($qB; > > >>>>> > > zzk^U}v(P(u$2mWNZ<y0NAKgD5Ep)(kbG!Lu&wgILlq=36hq^$jShinuz}-A>y#&Nd > > >>>>> > zUs4f<CcZi#*Z<Hob!fuM$OI6Ive@4b;Tc~z0;lpPd!)GUU4Ic4(Fjck@cbHOW_ > !(! > > >>>>> > > z(UNO4WL|nWqz4~06MW=c)pfY<AIONicI1Wy8Fo_!+V-~Y-JGnf%Gmca$H*m|vA88U > > >>>>> > > zx!%}(tmCVy-*x+Uz`u0P9D}I1UaD|aeSgwLQe{Ml&hL+8o`rmw{_NtV&;4-LptmWK > > >>>>> > > zECH(95C<ek(;ugJwlCE+tEhnsRiZdsvrp6c5+08#^$vl|s+5{7Lu8WNFIhLP#$W6X > > >>>>> > > zT#{H-7|XVu>ot9e5aJ=vdtGycg&<aWUjvC7r+jH34ZI{aElO=H#Pk{6H_S$XO)2Rf > > >>>>> > > zn~0xzKbThtCAuwEIskmM#OCCI2e5VsZD&oSgoxg4&_X{nGItgHz~lPu&%?%(zGa%| > > >>>>> > > zgsIB;tY5)s+l~tp#)sRV2EEsd_^;r{5riMYS%hVryGVk>RHW_S#Nda<%CoXY{w1d- > > >>>>> > zE@f{Ph;z&4H|8-H13a(Rlz+hq0z8hX@>aBbU!JC1*}HkDL?z@ > {yQ;X*v0u~Ig?gqp > > >>>>> > zgS}LBb&aC{b^_nSQqlvH`L+n&+tWNqQn}xuh<|w@jGMwW_D > ;1=$gFf>dU=SEDo4nS > > >>>>> > zuiT}JN@If > }erqVTdriX>yvrMZs$qg1#_zXpimCV!Niz*!+^++h1R>7egv^tO;bb!| > > >>>>> > > z>^{K(c4^z63p;G|Y>$=CF%tO8wjYFGvvH`2%NI}64Mvw!I~6P<Ri%s&1KlkfM}{~J > > >>>>> > > zs=PMX^5DzJPr~1#m|yD2QT?X(Yqv;19`4UYusD{dgnQol2ljgteo4MOupGB<^=@BN > > >>>>> > > zk2XB{KqQoWF81ad_OAE7>dj64#@b_^e;x<sa;u(%1UWZBx>UGb55){5Lf>nlWA;Cr > > >>>>> > > z5FMU329QWog`aK_mH%ylU(_5plziX*9Y7J05!+lISp3HK^@->KXGR9+<_-6W-}|A2 > > >>>>> > > z`$~2|OiQ$O6nIiabmB#mw{ITGamz=12PD>-d%0k}ApH|mcC)3ga-E-M3oK~x^-O)K > > >>>>> > > zM}nWm<-u=Jo~nw7+%rD$DqXvEjmAGF=MQ{2T<TcyIE&x1Qy;eEs)$x>$Z?+!cxh4& > > >>>>> > z%yQ3O9*Fr&L*gWluG=^O0sK@5Ceor4L6lYz(V3+*s}3nt1ug@RaaWP0qMBKPmYs > &F > > >>>>> > > z7dBqgR6>}tbvkAA`_-%V*&SfM#>h8|W<&mLTgfo!aEwNl9_ca}TnU)3rQn;O^U4PE > > >>>>> > ze)%UJ)^)RwPv)}9ZAAc}Tv&EneaD%!4-O9|?ov@lfBPgf{VFj0_$-v@A=ro@3zM > $# > > >>>>> > zp}MF&f0*!FfLCCtu`$7Ncz2`q=-Tve{xH*ma+{&PL;!*X0B7@6nU5 > ^;RWs(1)?HKj > > >>>>> > z{^dpx=qSb{9<Pfpky6PPau!d9#mC^N#zaSF8HQU|O=gCW6KS_O08LzrTeaKjQm@ > -< > > >>>>> > > ziAbtSr_05KTO4HcBXx7)u<^Y79v*g{`Iv>bplO*lEiJ;qLdoMNcDg#`&MT}x)Pe;l > > >>>>> > > zofm-YMqQ(HcHB|IOiSjFg6EVO;cuY&A`ynRxU~a~wJ`u}xAelC9Pe{yHM(PbVx~V6 > > >>>>> > z5jh<cn-jt`0F)r8XR|&oTa&g+y{U|jF{X9YOq%1JzkkJ@DrS > {Zt$E;LHBpxTXL?0c > > >>>>> > > z>5Vb-5>W~Y0LUtlWB&m=S{b%)nE_qtq{MY$-S}qExI9{<d(iJ%$H%yWS%KQe`cwQ0 > > >>>>> > > zLUwZd=Vt->_fF>Yiuti2*0D_KE=8xr>#$F5Z#it?ACF$+nXp8z**u-fKn8SuI)e|k > > >>>>> > zh$F3&xB3YC>9@Q > #V4_*C2qmaH7Zb_loD$sv(u89RhC_9nr_GN1k(L?Yp1S)EDaiUv > > >>>>> > z{{VW|H$c~)n7~9GRVT9B$h>5J@W > &Vvdu+H5XO6a$Xk3oZFgl%%7#qKQuqb;gk(?dO > > >>>>> > > zAA}Cb0Gq=a#P2(0cm3%LHWp#Ifv*U5??wTh+Wiw-!Qcd0W(%q>N?EPeVJA-H1{p?n > > >>>>> > zJ#PGz;(;$}09JungDN%LH9zkj2QB2qm=O`IR1AV1`air!6ww>J@ > <X!ep*f+F#FFrU > > >>>>> > > ze7s!?GoGm0Tky$TO{2cVITj40{S0p{vH#|K6(Omf+eRJv)0Ykq?e`Fks%NPFugAq; > > >>>>> > > z9cj`8kF3sRErbOw8>4cmOAUvDg`EBf%h+{S1?EX?E=Cg_k65=8`XyYge-Xa!(H&X` > > >>>>> > > zeYU({?Q<@x664!Kxa`36smBPO)^;y3UdMO0_##5S^VUBjfwj#|ytA|$d2KERM;S1# > > >>>>> > > z-Ywdk!+VYohg&PUcP$*$=W3vcS8HKt%BT{O>lkR=sMEUbomRb>=h3u!#SIbXv_BTF > > >>>>> > > z&&AhBahCXAEsfTNay4_jgipj1#x{YGtP~>}FBl8w^A=faA1R%=8e0()r0qxzmi&EQ > > >>>>> > > z;+!%_=IxoFf;b(O#T%-KWi}nGu;p>=2gMm}X^&WwKRazt3n~sl20FROt!(^0JovMR > > >>>>> > > z*sjY;VI)E6F?~X0>{{%g6kY_xmQMuwn4k+p>QmNa)n*)chr&^wmok-6M~seG`}-@k > > >>>>> > zmpc6<zbftUx}C>)?5V>ylxKY6)z0o)Z&71h9LEFU1#F0`#0@ > #_TlaTV^)DgBeK9+n > > >>>>> > z(lb$|#Es|r#~%m1rK@bHxR^A@W3RdM > ;Z;Mew(~0mp$z4zm=A3njYlPE5yXk~@NU(I > > >>>>> > z)BeXBfwX}iHqX5u8y8bEnjBe?OENmj;LO|j8t<x*@-|^~jf=0RimzltoK@Rpn > {aXF > > >>>>> > > z#2MMe8;|Bc#C!-YDbeCFO#Pc!1q95WM-fGIzt#5IxR>T6-4+FM{%wyM&)9?4YBxGS > > >>>>> > > zdEmlJqZ9r2QV4~3w`Y{6l0xXw8L*9aKjBZFpe;7aytaU<2zn<w3USfZhTJ?~75KBV > > >>>>> > z%0@S=>wlKvN5!?*#%WXR6*eZeqoIY%v@8 > #o?z&)|tY-oU=g4`7Wy{HoeTo*`XsJ!a > > >>>>> > z%@y > (BmHvHF|8($6{>FO<w3`jjrYEnY4(yeyOC~rV{3XH+P$VqIb7PDcXM7&G<4u1a > > >>>>> > > zl-biTf9~?p4Va&6q7c7l4ZD;xd^;WZTS!Mag%xy_LjHAMq0tW43o?p5bAoII?GDOa > > >>>>> > > z->FSl<{KVw*Wi^Z59{ghnJ>0o8k$jOYnXJ{gCyIYEn!J<$ejOyK5iZF*z|Pi_V@pd > > >>>>> > > zyiUr0&q;9pfklFYrEj4h*yjI<=Uc2NHsL?{Pm+j#D3yQckpD*V9~}J;lK*1*wmzZI > > >>>>> > > zf05jFvae|!V<=DDz7cD<ku*9*-`Ln2yLFoDNX?{k-d))b9P*-8?Es&&-wK9*jh1(~ > > >>>>> > zubwhB&^00#A5UU&9UlYIxyf|fZLt76Bwb@m > @5G4?{z^mi=S^;+;q_vdKi3iuu@GlN > > >>>>> > zEL`m0Ae`yMWqB$vN0vd*=oEo@M-4vKOX > (Q(hTVP&XN`o}s5!|cNV}uu$=3Kvx}~3d > > >>>>> > > zmnEMoCkNd3CBC7K+!P(Wf-SNDGUm#L=jh#X8g$bo<*?z`#U{m9d-`vP^sFGPRyi}+ > > >>>>> > zLY*+HdEk-RBeV2G-f@s > +60UW^ne6~+kibH>$q6Ii5*4im2?mq<QtDbG`&1_lr7jG% > > >>>>> > zx&X1(au)+!!JKow@ybihCWqp > )*_gS)3nS#U>+S{?OCL6mxoR$Ry2b5X+h?6d{0Y-% > > >>>>> > > zQIsxg=f+O!{yv$@>08->&|MLiD3+4K5C<iKp?vy1wKr>;OMnxMW_WN79vFYFr+4ks > > >>>>> > z88N~k-q6-(OJig$?ESB_hVSGz@=$&99{!yl0%A@ > ^n2Z#6`-QMz&eqbwu9c;h20y(^ > > >>>>> > > zY&hT)MBx-feZN<<0oz|27A`(z1#pLGKJ|f4X!)21y3w?AfZG6CnLc;t&kyX_-lW7; > > >>>>> > zurCq)Y^)9fcUdZT8EU16BAl)k6sb3jo+h%&z;2@q4PH > +dh<NIb>o+`yK>9&WQnU?w > > >>>>> > z&6zt1M#Px8Ew9)P@GfvecFNPnsa- > ?f_!#m0u6OitO2l5#O?2<(=(VuNAikkd*!N0o > > >>>>> > > zQ2#<p;k;6%?hjS&tjFtpUaAJ%qfGtQ>|n}HJXD#Nt0Ak{r{tBJR#kb#I(q*(q0mM- > > >>>>> > zH}813qdIJ@ZlHwY`wpzf1u*F5doBCD)dg)v@s`Ir(`(>Vnv%I>_o^~<Pj-@cPMT > `| > > >>>>> > z@KfT > #{SB70CH+?#t$-(6HJn}_FIV{(hm)SAxOzw1Z`^qUm%8>Y#09(?{XB8}lSRtD > > >>>>> > zD@ > {ibZ%5&}%$%^g>0*8i6Zpx%s7sG$rOa!%)2ZtRLokHz;27a9y6|~jx_!ZU<B%Oh > > >>>>> > zvQ_u1BQ)R7pi53d>rZMzwW0QbMCOU@Q > )%<q<Sl0gd_#88yZYbj_mqd}qI0$gVTtz` > > >>>>> > zv2b8aESTGvAV59YrRW4!c$t5kyl&O+SGAc@ > _R&}AD(U2$e+yV<LkB!n3b+1hHOI!i > > >>>>> > > z^^nA`FAvNitUN~COm)3(F_oe7+x^VSPG{eq+vdATOS`YuZ_&8B2j~)$_bQOWJW*DV > > >>>>> > > zn6|Y=n9;kSoHswH2gMe0OfH{E1avQ{ja+*1c_+|}1yKHsVZj2%<mr<lXq>ufFZ_yo > > >>>>> > z3bdwtw!#65^Bj0+!`Iq;6&Sls_<(ft?&y8)tYFR*Gh@wT > +mBU6Qj3D7;$lupW;^`N > > >>>>> > z1;Fml0);<fGvCmTHtoRVI1f3YDpMQ3h3qzaqSIv)Gaf1<!!H8zV&6y5S0vxvt@ > |Np > > >>>>> > > zW$aGmD`sr-IPm3X-W58rg56OMK>B?ry)jfzfv2sI2Y0Ff)6`Xrc09SW!)B`nMrV-N > > >>>>> > > zAT=5dG0Zu+X(58)LRFSF$1nbJp8^IE6`Xf`jb`rf8SwKqX^F{i_TM|gNDia_kfuP5 > > >>>>> > zz!hLNqq>cA<F8MERYJukY1Y0MgFZXuKJncN#v&P{8Rag}(_A5@dhueM > )ZbTUaR1!P > > >>>>> > z*PwC><@gMRBpnIBiD0gWJ9ujpzKiBPZkEFjQX3I4Sw6x@ > *ck$jzP!k?`8yU6AX<)# > > >>>>> > zHJbE6IaNhgy1!C9J}@LVShns > $79#5v1B5QS>omIh)Wd^Ik}Cyj57;+4S~G2ColJ#a > > >>>>> > z|57kW1+y)=H@dsV > )`?F{Kr#gURnX0&{<TG9`(~K>x~%62_YgJpBMY|4rcpVkzR2FD > > >>>>> > zb*I_f;T|1+pB?vDGgU#*o-j0ymqa#(T1zCQKBQ{0v;@ > =<k&Fy)0r$Vx8>R&zM`Akl > > >>>>> > zp!!1$(FBglN9R)LZznUVg_pUP4O%i@=Ho@CiI > <tSeKYzIr^;sxuS%WSy5FHk&gys{ > > >>>>> > z23{G@ > >vr2G3nCa)m5hL6m+S*20B2guSygKT{<Sqtp&9CQW$qrqH{PinyKIJV&94<! > > >>>>> > > z7SPklC-~YToJ-;<`=`fO!Ws-)`8-%PQT(Z3NWh(LDVIb=_6f-+yRZ^fsq?P9MD5L# > > >>>>> > > zmM{JEJw5<jRM^sI0m4KYyrJ*|yQhWzKK4L~mQ*`FrY6e78#;%|Xj=;(2bra~@M-9? > > >>>>> > > zrRqa?`I_)&6Fw5!bJ;;Vm9QKLg>^e9j=RpnnSy`71ImM}SsN`siWm=@*&U_XHPc^b > > >>>>> > > zS!v1)%*t*=0rAQoMSgylxL;GQt}Y8ZnaxMqcSORsh=lya7Qa{C!@}gs?p(^X`Mmi? > > >>>>> > zEHjZg`Elga#R~G`_~1P1z7bCyzeqFvt96TkZZC@Q=4@lASgcoqJP1dU > $*9~#u3E!x > > >>>>> > > zU>iVSXt19zUQD|4EMR{<cJU$96Db63e(=dC6R!8s%?MZU?<mi&(+3CD_N68TG<fBL > > >>>>> > > zm2=$1FH%8ktHPdx_Xgu>`cp~K9RTdJGJ!zPfp_c=UAuh+iefiypYm68v9~-pHJq{7 > > >>>>> > zLg?^PM5B$`gzGw^$o{&=YL5pp4K+)iYEL+nu~k$&Tk@ahx > %)?u6T!r^aH*V3Y7Hb+ > > >>>>> > zrdI*^x6-4E9g(SoFdnhiOw_UEoN56uC_@ > -Y#NoupY4_Mz*E8jCXQX!6R`2`|-h9ek > > >>>>> > > z3BT))3kJ>WYk6oQyxnhA+u!C-*n+Un9DH-%6xv9m^%-t<bRIbm>82U~ZM^vzSQz5i > > >>>>> > ze>OjIrhSq{M+B1vc#4<r63Yw*S8+{Ww<ILLB)z8e3gr4cJXQqmnc}v@K1 > ^&b&Hk%E > > >>>>> > zTg>B-W^8@odvaDEE > >f_Op(fG4IV|YQYd9l|eYbkFvbpISJM*&hXHxeb_mf1p(_Efe > > >>>>> > > z>fxrBHf;}|#-#D8`$pg*i;!9Q*pKxRG(8dp&<OG~oVngAQ<&wcOXESfb7f~Vwl0sZ > > >>>>> > > ziTfkbx!?$VrN^8aT_BYo2Y*ySjl-qA#hV}_fsjBASyZVH`S<b5{QkU^C4VnV7AE^t > > >>>>> > > zouF%JT+~XH_R`z;Wt?z1aCJ}2TrrqUWWdJwD&Th>FVSpDQq$yY%KiRstFgVKmeRlo > > >>>>> > z&G)=Vg?Dj;;u#D@A2n@wrgm2@0j&nk<+ut^v50OLj%yBlqHd?uU0P=wL1@4Ad > )7}D > > >>>>> > > z?cHm5TiuyptKO4)f!m*8B+zRI2(K|mxl6v0)BF1acHU-hQeuE|5HfTqx!8`c<8)+b > > >>>>> > z*3(jYXdJk|Z!3Y^fs+RBC-1Ttx#7oWg9ZiDi&;q97b|ejWQ-V%NA`OzmHij@Ar > !lu > > >>>>> > z_w>=x9Q*4q_gh<D03dWuj6WxBJ#aNJCFT`~J5I^-$}qt+5t@AYeMqlaqUVWGA > (k+% > > >>>>> > > z$*yG?0l8Rt_LQosg;lCHqW^*FlPcpF3m<qFS~>!3b^P!d^Q|7L&sJ^z{X>RL%X~X^ > > >>>>> > z%@ > ;5<Ga>77#dAk&Nw8B-g#-;_2iw)^Gemc~?#7kQD|}4A9>6OwMC}&{!}Cvbog+(D > > >>>>> > zOgqWDE3u**ip(c>foSgk`c0Hv$^6P8k66GiT?XsB#cQA=e1j8Qa?miOb@NE > <y)#UH > > >>>>> > > z`}AgePC~vFQ?y{-_ywzTS$N+B0FaCg`#nLAjlD6qk2lu$M;-U>`19`~jyz<$i>E;x > > >>>>> > > z*P|REM!DW9VabrROJ?b|bJc=#RigSaAa*3VmS3fq7j7O!HDJ^v7QYcRwEe@6WSycr > > >>>>> > > zc<nG%wVFYN{T=q^y4_N^D2aRPcnJciQG)6&09FeHRi1t;6vhr&vE=*ZY+*u~)o^u~ > > >>>>> > > z!BYzR#zQFw_KSeO77IDqN^s$>(fWL;fuQx0p1eiEhXiSu7S{^+&j;A{5?TNBOHJ!8 > > >>>>> > > zVcWpb59X5MPU26FTx#8aD%BsfSz>>sat{?9)H-A;l%zuS^K`ysZ1)eB$gNM{|CrFx > > >>>>> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > >>>>> > > > >>>>> > literal 0 > > >>>>> > HcmV?d00001 > > >>>>> > > > >>>>> > -- > > >>>>> > 1.8.3.2 > > >>>>> > > > >>>>> > > > >>>>> > _______________________________________________ > > >>>>> > lng-odp mailing list > > >>>>> > lng-odp@lists.linaro.org > > >>>>> > http://lists.linaro.org/mailman/listinfo/lng-odp > > >>>>> > > >>>> > > >>>> > > >>>> _______________________________________________ > > >>>> lng-odp mailing list > > >>>> lng-odp@lists.linaro.org > > >>>> http://lists.linaro.org/mailman/listinfo/lng-odp > > >>>> > > >>>> > > >>> > > >>> > > >>> -- > > >>> *Mike Holmes* > > >>> Linaro Technical Manager / Lead > > >>> LNG - ODP > > >>> > > >> > > >> > > > > > > > > > -- > > > *Mike Holmes* > > > Linaro Technical Manager / Lead > > > LNG - ODP > > > >
We should decide who is the main user/consumer of this arch document, because they have different needs. - current developers (we) who are contributing/reviewing the document will most probably prefer patches, because it is easier to follow what is changing without need to read through a whole updated document. - New developers will read a whole document anyway so they don't care much about history. - SC need to get rendered document, maybe with highlighted changes. On 07/03/2014 07:04 PM, Mike Holmes wrote: > Can everyone please weigh in with their thoughts, we need consensus on > this before we can make progress with the Arch doc. > > Thanks BIll / Mike > > > On 3 July 2014 11:25, Anders Roxell <anders.roxell@linaro.org > <mailto:anders.roxell@linaro.org>> wrote: > > On 2014-07-03 10:01, Bill Fischofer wrote: > > The people who review and approve these docs want to see docs > with things > > like change bars, not patches. The patch mechanism is simply > inappropriate > > for this activity and we shouldn't try to force-fit it for > something it's > > not designed to address. > > > > Again, the primary users of the odp-architecture git repository > are those > > who want access to complete docs, not those who are creating, > reviewing, > > and approving them. That's why we have a separate repository > from the main > > odp git repository so that "patches" can be handled differently > between > > them. > > That is why we use doxygen so that people reviewing for approval can > look > at the end result... However, isn't it better if anyone on the list can > review the patch and send patches when that is needed? > > SC approval should only be required for major revisions. > Possibly only a final read through review for every ODP release. > > > > > My preference would be to grant push rights to those adding items > to this > > repository rather than going through the artifice of patches. It > would be > > more straightforward and consistent with the actual workflow. > Git would > > still be doing version tracking so it would be possible to see > the complete > > change history for any given doc easily. > > We should use git as a revision control system as it is, to allow us to > make small changes when we discover them. > > > Cheers, > Anders > > > > > > > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes > <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: > > > > > I agree we need approval, but approval can be of a review of > the patch to > > > the text. > > > > > > I hope we don't need wholesale changes that need a complete re > write and > > > thus approval of a whole new document. For example a new patch > which may > > > add a new function to an API but we would hopefully not change > any of the > > > existing text in the main. > > > > > > Thus we can then make changes in manageable chunks, I agree > that large > > > new additions will come in via a pre approved hugue patch, > created from a > > > sequence of sprints just have we have done so far. > > > > > > I would argue that these small changes are likely given the > additions > > > already discovered by starting the validation testing work and > the feedback > > > it is generating with the need to be more specific in > architectural areas. > > > > > > Mike > > > > > > > > > On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org > <mailto:bill.fischofer@linaro.org>> wrote: > > > > > >> Design documents require approval by those who aren't going to be > > >> reviewing patches. This is different from code. My > understanding of the > > >> purpose of the odp-architecture repository is to provide a > convenient means > > >> of distributing documentation and making it available in > various forms > > >> (Doxygen, PDF) for access through the ODP web site as well as > being > > >> downloaded. > > >> > > >> So in this sense we're just using Git as a publication > mechanism for docs. > > >> > > >> > > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes > <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> > > >> wrote: > > >> > > >>> I am confused git is a change control mechanism, and I really > hope they > > >>> do get patched, how will we improve the content ? > > >>> > > >>> > > >>> On 3 July 2014 10:03, Bill Fischofer > <bill.fischofer@linaro.org <mailto:bill.fischofer@linaro.org>> wrote: > > >>> > > >>>> Git is a publication mechanism for docs, not a change control > > >>>> mechanism. Docs will not be 'patched'. New versions will > replace old ones > > >>>> as they are approved. > > >>>> > > >>>> > > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell > <anders.roxell@linaro.org <mailto:anders.roxell@linaro.org> > > >>>> > wrote: > > >>>> > > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: > > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org > <mailto:bill.fischofer@linaro.org>> > > >>>>> > --- > > >>>>> > crypto_design.dox | 455 > > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ > > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes > > >>>>> > 2 files changed, 455 insertions(+) > > >>>>> > create mode 100644 crypto_design.dox > > >>>>> > create mode 100644 images/syncmodels.png > > >>>>> > > > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox > > >>>>> > new file mode 100644 > > >>>>> > index 0000000..1ad2ac6 > > >>>>> > --- /dev/null > > >>>>> > +++ b/crypto_design.dox > > >>>>> > @@ -0,0 +1,455 @@ > > >>>>> > +/* Copyright (c) 2043, Linaro Limited > > >>>>> > + * All rights reserved > > >>>>> > + * > > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause > > >>>>> > + */ > > >>>>> > + > > >>>>> > +/** > > >>>>> > +@page crypto_design ODP Design - Crypto API > > >>>>> > +For the implimentation of the ODP crypto API please see @ref > > >>>>> odp_crypto.h > > >>>>> > + > > >>>>> > +@tableofcontents > > >>>>> > + > > >>>>> > +@section revision_history Revision History > > >>>>> > +Revision | Issue Data | Description | Author > > >>>>> > +---------|------------|-------------|-------- > > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic > Functions | > > >>>>> Bill, Alexandru > > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, > started use > > >>>>> cases, miscellaneous formatting, API comments | Bill > > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to > include results > > >>>>> of design discussions held during ODP team calls | Bill > > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto > > >>>>> sprint--action to resolve | Bill > > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review > > >>>>> comments--ready for final review | Bill > > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC > approval | Bill > > >>>>> > + > > >>>>> > +@section introduction Introduction > > >>>>> > +This document describes the ODP v1.0 Crypto API. > Cryptography is an > > >>>>> important part of data plane processing as many > communication protocols > > >>>>> make use of cryptographic functions. Moreover, many SoCs > incorporate > > >>>>> cryptographic hardware that can significantly accelerate > these operations > > >>>>> compared to their software equivalents as well as provide > validated > > >>>>> hardware functional correctness and security boundaries > necessary for > > >>>>> system-level security certifications such as FIPS-140 Level > 2 and above. > > >>>>> > +@section requirements Requirements > > >>>>> > +@subsection use_of_terms Use of Terms > > >>>>> > +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 [RFC 2119]( > > >>>>> https://tools.ietf.org/html/rfc2119). > > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography > > >>>>> > +Crypto functions cover a range of uses and capabilities > designed to > > >>>>> support data security, integrity, authentication, and > non-repudiation. > > >>>>> > +@subsubsection data_security Data Security > > >>>>> > +Cryptography supports data security by making use of complex > > >>>>> mathematical transformations that are not feasibly > reversible without > > >>>>> possession of the secret key used to encrypt message data. > > >>>>> > +@subsubsection data_integrity Data Integrity > > >>>>> > +Cryptography supports data integrity through the use of > > >>>>> cryptographic checksums (also known as secure hashes) that > ensure the > > >>>>> recipient that message data has not been altered either > accidentally or > > >>>>> maliciously while in transit. > > >>>>> > +@subsubsection data_authentication Data Authentication > > >>>>> > +Cryptography supports data authentication through the > uses of > > >>>>> Message Authentication Codes (MACs) that enable the > recipient to verify > > >>>>> that a message was sent from an authorized counterparty, > and hence was not > > >>>>> forged. > > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation > > >>>>> > +Cryptography supports data non-repudiation through the > use of > > >>>>> digital signatures that enable a recipient or third party > to verify the > > >>>>> identity of the sending party and prevents the sending > party from later > > >>>>> denying that they originated a signed message. > > >>>>> > +@subsection scope Scope > > >>>>> > +ODP v1.0 crypto support is designed to provide a > portable framework > > >>>>> for accessing SoC-specific cryptographic functions of most > use to the data > > >>>>> plane. This is predominantly symmetric crypto operations > used to support > > >>>>> the encryption and decryption of data at line rate using > hardware > > >>>>> acceleration and offload. Specifically excluded in this > support are public > > >>>>> key operations and other crypto functions mainly used in > the control plane. > > >>>>> > +@subsection cryptographic_operations_in_the_data_plane > > >>>>> Cryptographic Operations in the Data Plane > > >>>>> > +ODP v1.0 crypto APIs cover the following areas: > > >>>>> > +@subsubsection ciphering Ciphering > > >>>>> > +Ciphering refers to mathematical transformations that > use a secret > > >>>>> key to encipher data, transforming the original data > (referred to as > > >>>>> plaintext) into ciphertext, thereby making it > unintelligible to anyone not > > >>>>> in possession of the key. Similarly, ciphering is also used > to decipher > > >>>>> data, allowing someone in possession of the correct key to > transform > > >>>>> received ciphertext back into plaintext. Approved block > ciphers are listed > > >>>>> > [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and > > >>>>> SHOULD be supported by each ODP implementation. > > >>>>> > +@subsubsection hasing Hashing > > >>>>> > +A hash is a cryptographic digest of a message that can > be used to > > >>>>> represent it for comparison or integrity checking. Hash > functions are > > >>>>> designed so that any alteration of a message will alter the > hash and that > > >>>>> it is computationally infeasible to craft a message that > generates the same > > >>>>> hash value as another message. Secure hash functions > approved for > > >>>>> cryptographic use are listed by NIST [here]( > > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and > > >>>>> SHOULD be supported by each ODP implementation. > > >>>>> > +@subsubsection zeroization Zeroization > > >>>>> > +To preserve the security of data, certain transient data > held in > > >>>>> data buffers MUST be cleared to zeros upon buffer free. > Such capability is > > >>>>> referred to as zeroization. ODP supports zeroization as a > buffer pool > > >>>>> attribute. > > >>>>> > +@subsubsection random_number_generation Random Number > Generation > > >>>>> > +Because cryptography relies heavily on “unguessable” keys of > > >>>>> various sorts, random number generation (RNG) is an > integral part of > > >>>>> cryptographic processing. Random numbers are used in key > generation, > > >>>>> initialization vectors (IVs), various types of padding > bytes, and various > > >>>>> other uses collectively referred to as nonces, that serve > to “harden” > > >>>>> cryptographic processing. > > >>>>> > + > > >>>>> > +There are two types of random number support of > interest. Hardware > > >>>>> random data, also known as entropy, that is the result of > inherently random > > >>>>> physical processes, and deterministic random bit generation > (DRBG) that is > > >>>>> used in certain certified cryptographic operations. > Approved DRBG > > >>>>> algorithms are listed in [NIST SP 800-90A]( > > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not > > >>>>> specify which algorithms are available on a given > implementation. As such > > >>>>> ODP implementations MAY use any approved DRGB algorithm but > SHOULD support > > >>>>> at least one of them. Additionally, ODP implementations > MUST NOT represent > > >>>>> non-approved algorithms as DRBG implementations. Validated > algorithms are > > >>>>> listed in the [NIST DRBG Validation List]( > > >>>>> > http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > > >>>>> > + > > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > > >>>>> > +To enable applications to adapt to the implementation models > > >>>>> offered across different SoC platforms, ODP provides APIs > to allow > > >>>>> applications to inquire about underlying crypto > capabilities. A given ODP > > >>>>> implementation may offer crypto as hardware features, > software features, or > > >>>>> not available on a given platform. > > >>>>> > +@subsection cryptographic_algorithms Cryptographic > Algorithms and > > >>>>> Protocols > > >>>>> > +A cryptographic algorithm is a mathematical transform > that provides > > >>>>> one of the cryptographic operations described above. They > in turn are used > > >>>>> as building blocks in creating cryptographic protocols. > These are complete > > >>>>> sets of rules for how to exchange data securely using > cryptography. Both > > >>>>> cryptographic algorithm and protocol design are highly > specialized > > >>>>> disciplines that involve high levels of public scrutiny and > validation. As > > >>>>> a result, applications simply make use of approved > cryptographic algorithms > > >>>>> and protocols. > > >>>>> > +@subsection cryptographic_operations Cryptographic > Operations > > >>>>> > +Cryptographic operations may be initiated by software or > directly > > >>>>> by hardware as part of the RX or TX packet path processing. > For ODP v1.0 > > >>>>> software-initiated cryptographic operations are the primary > use case. ODP > > >>>>> provides APIs for performing data ciphering, hashing, > random number > > >>>>> generation, and capability inquiry. > > >>>>> > +@subsection performance_expectations Performance > Expectations > > >>>>> > +In the data plane, the total processing budget for a > packet may > > >>>>> only be a few hundred cycles, so function invocation > overhead MUST be kept > > >>>>> to a minimum. This has several implications. > > >>>>> > + > > >>>>> > +-# When work is dispatched to a thread, all information > needed by > > >>>>> the thread to process the work request SHOULD be > immediately at hand. > > >>>>> Ideally any context or variables needed for the operation > have been > > >>>>> pre-warmed in the cache to avoid the latency hits > associated with cache > > >>>>> misses. SoCs having hardware schedulers generally do this > pre-staging of > > >>>>> data to minimize such latencies, and ODP implementations > are expected to > > >>>>> exploit such platform capabilities whenever possible.\n\n > > >>>>> > + > > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive > amounts of > > >>>>> parameter passing and (depending on the implementation) > SHOULD be inlined > > >>>>> as much as possible to avoid call overhead. One technique > that has proven > > >>>>> useful is to allow for parameters to be passed as an > explicit thread-local > > >>>>> static structure. Such use of “templating” means that a > single function can > > >>>>> support a rich set of options but the caller can configure > a template > > >>>>> matched to specific use and only vary the one or two > parameters that differ > > >>>>> from call to call.\n\n > > >>>>> > + > > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any > > >>>>> non-exception path function processing. Kernel calls and > such are > > >>>>> acceptable only during one-time initialization logic or > certain types of > > >>>>> unusual error recovery operations. Often the best way to > handle the latter > > >>>>> is to pass the work to a dedicated recovery thread (or back > to the control > > >>>>> plane) rather than attempting to handle the condition > inline. For example, > > >>>>> a link-down condition will trigger various recovery actions > that might best > > >>>>> be handled in this manner. > > >>>>> > + > > >>>>> > +@subsection use_by_existing_code Use by Existing Code > > >>>>> > +Most applications wishing to make use of ODP represent > substantial > > >>>>> existing investment that must be preserved. Insofar as > possible, ODP > > >>>>> functions need to be orthogonal to existing application > environments and > > >>>>> structures to permit easy intermixing with pre-existing code. > > >>>>> > +@subsection data_references Data References > > >>>>> > +Packet data is inherently of variable length however it > is often > > >>>>> more efficient to organize memory into fixed-sized buffers > that can be > > >>>>> chained together on demand to contain packets. The > application SHOULD > > >>>>> normally not need to be aware of such lower-level > segmentation and should > > >>>>> be able to treat a packet as a single object. Alternately, > especially when > > >>>>> dealing with existing code, data segmentation MUST be > explicitly > > >>>>> specifiable via scatter/gather lists. For example, data > encryption or > > >>>>> decryption may be invoked on a list of data segments as > part of a single > > >>>>> function call. > > >>>>> > > >>>>> Every time you add a full stop for a sentence, you have to > press return > > >>>>> and start typing the next sentence. > > >>>>> This means that diffs of future changes will be per sentence. > > >>>>> Doxygen will still concatenate this as a paragraph with no > visual > > >>>>> difference in the result. > > >>>>> I think the above line will look like this: > > >>>>> > > >>>>> Packet data is inherently of variable length however it is > often more > > >>>>> efficient to organize memory into fixed-sized buffers that > can be chained > > >>>>> together on demand to contain packets. > > >>>>> The application SHOULD normally not need to be aware of such > > >>>>> lower-level segmentation and should be able to treat a > packet as a single > > >>>>> object. > > >>>>> Alternately, especially when dealing with existing code, data > > >>>>> segmentation MUST be explicitly specifiable via > scatter/gather lists. > > >>>>> For example, data encryption or decryption may be invoked > on a list of > > >>>>> data segments as part of a single function call. > > >>>>> > > >>>>> > > >>>>> Cheers, > > >>>>> Anders > > >>>>> > > >>>>> > +@subsection chained_operations Chained Operations > > >>>>> > +Crypto operations such as hashing and encryption, or > decryption and > > >>>>> verification, are very commonly used in combination. For > ODP, it is > > >>>>> sufficient to support one cipher and one > hash/authentication operation in a > > >>>>> single call and this combination MUST be supported to avoid > the call and > > >>>>> dispatch overhead of separate invocations. > > >>>>> > +@subsection key_management Key Management and Session Data > > >>>>> > +Keying is an area of particular sensitivity in crypto > processing > > >>>>> since keys are highly confidential and may be subject to > legal requirements > > >>>>> for safeguarding within special hardware enclosures. > > >>>>> > + > > >>>>> > +A session is the security context used to represent an > active set > > >>>>> of crypto operations that need to be applied to a flow on a > > >>>>> packet-by-packet basis. Generally a session is established > upon detection > > >>>>> of a flow requiring crypto processing and retained for the > life of that > > >>>>> flow. It has been noted that this can involve cooperative > processing > > >>>>> between the control and data planes so several requirements > stem from this: > > >>>>> > + > > >>>>> > +-# Session creation MAY need to be handled in an > asynchronous > > >>>>> manner. This is to allow these to be created in batches by > thread(s) that > > >>>>> specialize in this activity.\n\n > > >>>>> > + > > >>>>> > +-# Sessions MAY need to reference keying material > indirectly via > > >>>>> key handling modules.\n\n > > >>>>> > + > > >>>>> > +-# Session creation MAY be performed by non-ODP code and > > >>>>> communicated to data plane routines that make use of ODP > crypto functions > > >>>>> that need to reference the session information. > > >>>>> > + > > >>>>> > +ODP session APIs and data structures SHOULD be > represented by > > >>>>> abstract data types that encapsulate implementation details > for both > > >>>>> platform efficiency and to accommodate these needs. > > >>>>> > +Use Cases > > >>>>> > +For ODP v1.0 the major use cases of interest involve > cryptographic > > >>>>> algorithm acceleration. Cryptographic protocol acceleration > is reserved for > > >>>>> future ODP releases. > > >>>>> > +Buffers and Data Blocks > > >>>>> > +Cryptographic operations may be performed directly on data > > >>>>> contained in ODP packet buffers, or it may be performed on > “raw” data > > >>>>> blocks operating entirely under application control. Note > that when using > > >>>>> raw data blocks not managed by ODP, the application must > perform any needed > > >>>>> zeroization using either its own or ODP-supplied buffer > zeroization > > >>>>> functions. ODP automatic support for zeroization is limited > to ODP-managed > > >>>>> buffers. ODP buffers allocated from buffer pools designated > for crypto use > > >>>>> will also have whatever alignment and/or addressability > attributes needed > > >>>>> by the implementation to support crypto API calls. > > >>>>> > + > > >>>>> > +Note: Some implementations may have difficulty dealing with > > >>>>> application buffer addresses, as these may be virtual > addresses that are > > >>>>> mapped discontiguously into physical memory. For such > implementations, > > >>>>> memory SHOULD be allocated contiguously and MAY need to be > “registered” to > > >>>>> have proper addressability for crypto operations. This area > of the design > > >>>>> will be updated based on experience in dealing with > different crypto > > >>>>> implementations that have such requirements. > > >>>>> > +Synchronization > > >>>>> > +ODP operations fall into one of three categories: > > >>>>> > + > > >>>>> > +-# Inline (Synchronous): Upon return from a call the > operation is > > >>>>> complete. Operation is thus completely synchronous to the > caller. Inline > > >>>>> is the appropriate model when the invoked function takes > relatively few > > >>>>> cycles or when the caller cannot feasibly progress without > the results of > > >>>>> the invoked function.\n\n > > >>>>> > + > > >>>>> > +-# Parallel: Upon return from a call the operation has been > > >>>>> initiated, but is expected to complete shortly. The caller > continues to > > >>>>> execute until it needs the result at which point it waits > to complete the > > >>>>> parallel operation. The effect is as if the operation were > inline except > > >>>>> that the caller was able to execute in parallel with the > operation for some > > >>>>> application-determined period of time. Parallel is the > appropriate model > > >>>>> when the operation being performed is relatively short (a > few dozen up to > > >>>>> perhaps 100 or 200 cycles) and the caller can usefully > accomplish other > > >>>>> processing on the same unit of work while the parallel > operation is in > > >>>>> progress, but not enough to justify the overhead of a > formal queued work > > >>>>> dispatch.\n\n > > >>>>> > + > > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call the > > >>>>> operation has been queued for execution. A completion event > will be queued > > >>>>> back to the scheduler when the event is completed. Offload > is the > > >>>>> appropriate model when the invoked function will take a > substantial amount > > >>>>> of cycles (thousands to tens of thousands) allowing the > invoking > > >>>>> thread/core to service other work until the operation > completes. For > > >>>>> offloaded work, completion is indicated by a completion > event being posted > > >>>>> back to an application-designated completion queue. Upon > receipt the unit > > >>>>> of work that initiated the offloaded operation continues > processing with > > >>>>> the results of the call. > > >>>>> > + > > >>>>> > +The synchronization models of interest are summarized in > Figure 1: > > >>>>> > + > > >>>>> > + > > >>>>> > + > > >>>>> > +Note: Because few implementations are expected to offer the > > >>>>> Parallel mode of operation as described above, this mode > is reserved for > > >>>>> potential future use. For ODP v1.0 only synchronous and > asynchronous crypto > > >>>>> operations are defined. > > >>>>> > +@section functional_definition Functional Definition > > >>>>> > +@subsection abstract_data_types Abstract data types > > >>>>> > +The following enumerations define various algorithms > used for > > >>>>> ciphering and hashing. These are the basic operations > applied to input data. > > >>>>> > + > > >>>>> > +A particular ODP implementation should map these values > to the > > >>>>> actual information to be passed to the crypto engine. As > such, the actual > > >>>>> values of these enums is implementation-defined. > > >>>>> > + > > >>>>> > +Cipher algorithm encoding specifies the algorithm and > cipher mode > > >>>>> employed (as per security relevant RFCs - [4305]( > > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > > >>>>> http://tools.ietf.org/html/rfc4494)). > > >>>>> > + > > >>>>> > +@code > > >>>>> > +enum odp_cipher_alg { > > >>>>> > + ODP_CIPHER_ALG_NULL, > > >>>>> > + ODP_CIPHER_ALG_DES, > > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, > > >>>>> > + ODP_CIPHER_ALG_AES_CBC, > > >>>>> > + ODP_CIPHER_ALG_AES_GCM, > > >>>>> > + ODP_CIPHER_ALG_AES_CTR, > > >>>>> > + ODP_CIPHER_ALG_KASUMI, > > >>>>> > + ODP_CIPHER_ALG_SNOW, > > >>>>> > + ... > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Authorization algorithm encoding specifies the algorithm > and the > > >>>>> length of the authorization used (as per security relevant > RFCs - [4305]( > > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > > >>>>> http://tools.ietf.org/html/rfc4494)): > > >>>>> > + > > >>>>> > +@code > > >>>>> > +enum odp_auth_alg { > > >>>>> > + ODP_AUTH_ALG_NULL, > > >>>>> > + ODP_AUTH_MD5_96, > > >>>>> > + ODP_AUTH_ALG_SHA1_96, > > >>>>> > + ODP_AUTH_ALG_SHA1_160 > > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, > > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, > > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, > > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, > > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > > >>>>> > + ODP_AUTH_ALG_SNOW, > > >>>>> > + ODP_AUTH_ALG_KASUMI, > > >>>>> > + ... > > >>>>> > +}; > > >>>>> > + > > >>>>> > +typedef union odp_crypto_alg_t { > > >>>>> > + enum odp_cipher_alg cipher; > > >>>>> > + enum odp_auth_alg auth; > > >>>>> > +}odp_crypto_alg_t; > > >>>>> > +@endcode > > >>>>> > +@subsection parameter_structures Parameter Structures > > >>>>> > +@subsubsection crypto_sessions Crypto Sessions > > >>>>> > +The following structure describes a crypto session. All > packets / > > >>>>> raw data buffers processed in a session share the data that > defines the > > >>>>> session. A crypto session is defined by: > > >>>>> > + > > >>>>> > +- Operation type : encode or decode\n\n > > >>>>> > + > > >>>>> > +- Algorithms specifications, keys and , if required, > initialization > > >>>>> vectors. When initialization vectors are not provided and > they should be > > >>>>> provided automatically by the crypto engine.\n\n > > >>>>> > + > > >>>>> > +- The operation mode: synchronous or asynchronous. > Synchronous > > >>>>> operation blocks the caller until an operation status and > result are > > >>>>> available. In synchronous mode there is at most only one > outstanding crypto > > >>>>> operation in the calling thread. In asynchronous mode, the > caller starts > > >>>>> the crypto operation and later it may receive the status > and the result > > >>>>> together with a request context. The operation status and > result may also > > >>>>> be received by a different thread.\n\n > > >>>>> > + > > >>>>> > +- Operation mode parameters: For asynchronous operation a > > >>>>> completion event containing the status, the result and the > request context > > >>>>> is enqueued to a completion queue. In case the queue is > under the scheduler > > >>>>> control, the scheduler determines who will receive the > completion event and > > >>>>> when. When the completion queue is not scheduled, the > thread which is > > >>>>> supposed to get the operation output has to explicitly poll > the completion > > >>>>> queue. > > >>>>> > + > > >>>>> > +Note that this is an abstract data type and its structure is > > >>>>> implementation-specific. The layout shown here is for > illustrative purposes > > >>>>> and the actual layout will vary from one implementation to > the next to most > > >>>>> closely align with the structures needed by the underlying > SoC platform. > > >>>>> Applications set and reference fields in the session > structure via accessor > > >>>>> functions that hide the actual layout. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +typedef enum odp_crypto_op_t { > > >>>>> > + ODP_CRYPTO_OP_ENCODE, > > >>>>> > + ODP_CRYPTO_OP_DECODE > > >>>>> > +}odp_crypto_op_t; > > >>>>> > + > > >>>>> > +typedef struct odp_key_t { > > >>>>> > +}odp_key_t; > > >>>>> > + > > >>>>> > +typedef struct odp_crypto_session_t { > > >>>>> > + odp_crypto_op_t op; > > >>>>> > + struct { > > >>>>> > + enum odp_cipher_alg cipher_alg; > > >>>>> > + odp_key_t *key; > > >>>>> > + uint8_t *iv; > > >>>>> > + size_t iv_len; > > >>>>> > + } cipher; > > >>>>> > + > > >>>>> > + struct { > > >>>>> > + enum odp_auth_alg auth_alg; > > >>>>> > + enum odp_auth_len auth_len; > > >>>>> > + odp_key_t *key; > > >>>>> > + } auth; > > >>>>> > + > > >>>>> > + enum odp_crypto_op_mode { > > >>>>> > + ODP_CRYPTO_SYNC, > > >>>>> > + ODP_CRYPTO_ASYNC, > > >>>>> > + } op_mode; > > >>>>> > + > > >>>>> > + struct { > > >>>>> > + uint32_t timeout; > > >>>>> > + struct { > > >>>>> > + odp_queue_t completion_queue; > > >>>>> > + } async; > > >>>>> > + } op_mode_params; > > >>>>> > + > > >>>>> > + odp_session_proc_info_t session_proc_info; > > >>>>> > +} odp_crxsypto_session_t; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +The completion queue contained in the session structure > is an > > >>>>> in/out parameter. If provided, then the queue specified is > associated with > > >>>>> the session and is used to ensure order preservation on > that session. If > > >>>>> not provided, one is created and returned to the caller. > Note that this > > >>>>> completion queue is used to order operations performed on > this crypto > > >>>>> session. It should not be confused with the completion > queue specified on > > >>>>> the odp_crypto_session_create() call (see below) that is > used to control > > >>>>> whether that call is itself processed in a synchronous vs. > asynchronous > > >>>>> manner. > > >>>>> > + > > >>>>> > +The following structure comprises processing > information. This is > > >>>>> logically divided in two parts: > > >>>>> > + > > >>>>> > +- Processing input info - When crypto engine provides > support for > > >>>>> protocol processing, this information is provided in a > higher level common > > >>>>> protocol terminology form and a particular implementation > should be able to > > >>>>> derive everything it needs from this definition. In > addition, for crypto > > >>>>> engines able to automate tasks like memory allocation for > the output a > > >>>>> buffer pool id may be specified.\n\n > > >>>>> > + > > >>>>> > +- Processing output information - statistics about processed > > >>>>> bytes/packets. These are useful when a session expiration > is based on > > >>>>> traffic volume. These statistics may be updated by the > software or by the > > >>>>> hardware crypto engine. > > >>>>> > + > > >>>>> > +Again, this is an abstract type whose specific layout > will vary > > >>>>> based on implementation considerations. Access to fields > contained in the > > >>>>> structure is only via accessor functions. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +typedef struct { > > >>>>> > + uint64_t pkts_processed; > > >>>>> > + uint64_t bytes_processed; > > >>>>> > + uint64_t pkts_errored; > > >>>>> > + uint64_t bytes_errored; > > >>>>> > + > > >>>>> > + odp_buffer_pool_t out_pool; > > >>>>> > + > > >>>>> > +} odp_session_proc_info_t; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +This enumeration defines which operations are applied > and the order. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +enum odp_crypto_combination { > > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, > > >>>>> > + ODP_CRYPTO_AUTH_ONLY, > > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +This structure defines a contiguous segment in the input > data which > > >>>>> starts at offset offset and is len bytes long. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +struct odp_data_range { > > >>>>> > + unsigned offset:16; > > >>>>> > + unsigned len:16; > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +@subsection api_functions API Functions > > >>>>> > + > > >>>>> > +@subsubfunction Session Creation > > >>>>> > + > > >>>>> > +This function is used to create a crypto session. The > required > > >>>>> parameters are : > > >>>>> > + > > >>>>> > +- Operation : encode/decode > > >>>>> > +- Processing info : cipher/auth/both > > >>>>> > +- Preferred mode : sync or async. > > >>>>> > +- Algorithms suites, keys and optional IV > > >>>>> > + > > >>>>> > +Session creation can be synchronous or asynchronous. > Completion > > >>>>> event argument is used to return the status and the session > handle. When > > >>>>> completion queue is not provided (synchronous call), the > completion event > > >>>>> is available upon function call return. When completion > queue is provided > > >>>>> (asynchronous call), the completion event is placed on the > completion queue. > > >>>>> > + > > >>>>> > +@code > > >>>>> > +typedef uint64_t odp_crypto_session_t; > > >>>>> > + > > >>>>> > +struct odp_session_params { > > >>>>> > + enum odp_crypto_operation op; > > >>>>> > + odp_session_proc_info_t proc_info; > > >>>>> > + enum odp_crypto_op_mode pref_mode; > > >>>>> > + enum odp_cipher_alg cipher_alg; > > >>>>> > + odp_key_t *cipher_key; > > >>>>> > + uint8_t *iv; > > >>>>> > + size_t iv_len; > > >>>>> > + enum odp_auth_alg auth_alg; > > >>>>> > + odp_key_t *auth_key; > > >>>>> > +}; > > >>>>> > + > > >>>>> > +enum odp_crypto_ses_create_err { > > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, > > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, > > >>>>> > + /* Session creation error codes */ > > >>>>> > +}; > > >>>>> > + > > >>>>> > +void > > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t > > >>>>> completion_event, enum odp_crypto_ses_create_err *status); > > >>>>> > + > > >>>>> > +void > > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t > > >>>>> completion_event, odp_crypto_session_t *handle); > > >>>>> > + > > >>>>> > +int odp_crypto_session_create( > > >>>>> > + struct odp_session_params *params, > > >>>>> > + odp_buffer_t completion_event, > > >>>>> > + odp_queue_t completion_queue); > > >>>>> > +@endcode > > >>>>> > +@subsection crypto_operation Crypto Operation > > >>>>> > + > > >>>>> > +Crypto operations are described by a parameter structure: > > >>>>> > +@code > > >>>>> > +struct odp_crypto_op_params { > > >>>>> > + odp_crypto_session_t session; > > >>>>> > + odp_packet_t pkt; > > >>>>> > + odp_packet_t out_pkt; > > >>>>> > + uint8_t *override_iv_ptr; > > >>>>> > + unsigned hash_result_offset; > > >>>>> > + struct odp_data_range cipher_range; > > >>>>> > + struct odp_data_range auth_range; > > >>>>> > +}; > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +<table> > > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> > > >>>>> > +<tr><td>session</td><td>Session to perform the > operation</td></tr> > > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be > processed</td></tr> > > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / > buffer to be > > >>>>> returned as the result of the operation. There are three > different ways > > >>>>> this parameter is used, depending on the mode of operation > requested by the > > >>>>> caller and the capabilities of the underlying > implementation:\n\n > > >>>>> > + > > >>>>> > +-# If out_pkt is the same as pkt this indicates that the > operation > > >>>>> should be performed in place.\n\n > > >>>>> > +-# If out_pkt is different from pkt this indicates that > output > > >>>>> should be placed in the buffer supplied by the caller.\n\n > > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied > on input) > > >>>>> this indicates that an output buffer should be allocated by > the operation > > >>>>> and returned as part of the completion event associated > with the > > >>>>> operation.\n\n > > >>>>> > + > > >>>>> > +Note that not every implementation will support all of > these modes > > >>>>> and MAY require that one mode be used in preference to > others. Any such > > >>>>> implementation restrictions are communicated as output from > session > > >>>>> creation.</td></tr> > > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for this > > >>>>> request</td></tr> > > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the > output packet > > >>>>> where the hash result should be stored.</td></tr> > > >>>>> > +<tr><td>cipher_range</td><td>The byte range > (offset:length) of the > > >>>>> data to be processed for ciphering.</td></tr> > > >>>>> > +<tr><td>auth_range</td><td>The byte range > (offset:length) of the > > >>>>> data to be processed for authentication.</td></tr> > > >>>>> > +</table> > > >>>>> > + > > >>>>> > +The crypto operation is initiated with a single call > that passes > > >>>>> the parameters for the operation and an event (for > asynchronous completion). > > >>>>> > +@code > > >>>>> > +int odp_crypto_operation( > > >>>>> > + struct odp_crypto_op_params *params, > > >>>>> > + odp_buffer_t completion_event); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Parameter | Meaning > > >>>>> > +----------|-------- > > >>>>> > +params | The parameter structure describing the > crypto operation > > >>>>> to be performed. > > >>>>> > +completion_event | The event delivered on completion. It > provides > > >>>>> information about the status of the operation, result and > request context. > > >>>>> In synchronous mode the event is available upon function > call return. In > > >>>>> asynchronous mode, the event is placed on the session / > operation > > >>>>> completion queue when the operation finished. > > >>>>> > + > > >>>>> > +Upon return the return code indicates whether the > operation was > > >>>>> synchronous or asynchronous, or if an error occurred that > prevented the > > >>>>> operation from being performed. > > >>>>> > + > > >>>>> > +Get session operation : > > >>>>> > +@code > > >>>>> > +odp_crypto_op_t > > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Get session cipher information : > > >>>>> > +@code > > >>>>> > +odp_cipher_alg > > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Get session authentication information : > > >>>>> > +@code > > >>>>> > +odp_auth_alg > > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Change session IV : > > >>>>> > +@code > > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, > uint8_t > > >>>>> *iv); > > >>>>> > +@emdcode > > >>>>> > + > > >>>>> > +Change cipher or/and hash keys: > > >>>>> > +@code > > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, > odp_key_t > > >>>>> *key); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Destroy crypto session. All pending operations are > cancelled. > > >>>>> > +@code > > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Get completion event information - algorithm error, > output and > > >>>>> context. Note that implementations MAY define their own > specific error > > >>>>> codes that have meaning in that context. For application > portability it is > > >>>>> sufficient to know whether an operation completed > successfully or > > >>>>> experienced an error of some sort. > > >>>>> > +@code > > >>>>> > +enum crypto_alg_err { > > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > > >>>>> > +}; > > >>>>> > + > > >>>>> > +enum crypto_hw_err { > > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, > > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, > > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > > >>>>> > +}; > > >>>>> > + > > >>>>> > +struct odp_crypto_compl_status { > > >>>>> > + odp_crypto_alg_t alg; > > >>>>> > + enum crypto_alg_err alg_err; > > >>>>> > + enum crypto_hw_err hw_err; > > >>>>> > +}; > > >>>>> > + > > >>>>> > +void > > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, > > >>>>> > + struct odp_crypto_compl_status > *auth, > > >>>>> > + struct odp_crypto_compl_status > *cipher); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Returns the output packet handle associated with the > completion > > >>>>> event : > > >>>>> > +@code > > >>>>> > +odp_packet_t > > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Sets a context handle to be returned with the completion > event : > > >>>>> > +@code > > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, > > >>>>> odp_compl_ctx_t *ctx); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Returns the context associated with the completion event : > > >>>>> > +@code > > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t > > >>>>> completion_event); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +This section describes the API/Interface being defined at a > > >>>>> functional level in technical detail. Sub-sections include > header file > > >>>>> names, where implementation files are expected to reside in > the ODP git > > >>>>> tree, as well as the name, parameters, abstract data types, > functionality, > > >>>>> return codes, and exception conditions of each function > call defined by the > > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be > used to allow > > >>>>> the programmer tasked with implementing the API/Interface > to understand the > > >>>>> function to be implemented as well as error conditions, > corner cases, > > >>>>> performance requirements, etc. needed to implement the > described > > >>>>> API/Interface in a functionally correct and efficient manner. > > >>>>> > + > > >>>>> > +@subsubsection random_number_functions Random Number > Functions > > >>>>> > +As noted earlier, random number support consists of two > functions: > > >>>>> > +@code > > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool > > >>>>> use_entropy); > > >>>>> > + > > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +The difference is that the first provides access to > hardware random > > >>>>> number functions that return true random data. This is > typically used for > > >>>>> seed values. The second provides a deterministic random bit > generator > > >>>>> conforming to NIST standards and is used by various crypto > protocols and > > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get > is used to > > >>>>> disable any hardware pre-processing normally provided by > the function and > > >>>>> is mainly intended to be used for testing/validation purposes. > > >>>>> > + > > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool Extensions > > >>>>> > +To support zeroization a buffer may be allocated with an > > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer > should be > > >>>>> zeroized upon free. Alternately, a new type > (ODP_CLEAR_ON_FREE) is added to > > >>>>> odp_buffer_pool_create() that specifies that all buffers > allocated from > > >>>>> this pool must be zeroized upon free. Essentially, the > buffer security > > >>>>> attribute is set by default from the attributes of the > buffer pool that it > > >>>>> is allocated from. > > >>>>> > + > > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > > >>>>> > +To enable applications to determine crypto capabilities. > > >>>>> > +@code > > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum > odp_auth_alg); > > >>>>> > +@endcode > > >>>>> > + > > >>>>> > +Inquires whether the specified crypto and auth > algorithms are > > >>>>> supported. Responses include: > > >>>>> > +- ODP_HW_SYNC_SUPPORT > > >>>>> > +- ODP_HW_ASYNC_SUPPORT > > >>>>> > +- ODP_SW_SYNC_SUPPORT > > >>>>> > +- ODP_SW_ASYNC_SUPPORT > > >>>>> > +- ODP_NO_SUPPORT > > >>>>> > + > > >>>>> > +HW support means the combination is supported in > hardware, SW > > >>>>> support means the combination is supported in software by the > > >>>>> implementation. No support means the combination is not > supported by the > > >>>>> implementation. The SYNC and ASYNC return options can help > the application > > >>>>> decide how to invoke these functions, or it can just check > whether or not > > >>>>> the response is ODP_NO_SUPPORT. > > >>>>> > + > > >>>>> > +@section implementation_considerations Implementation > Considerations > > >>>>> > +One of the main purposes for the ODP crypto APIs is to > provide > > >>>>> portable access across different SoCs whose hardware crypto > capabilities > > >>>>> largely overlap but vary in terms of their implementation > details. As a > > >>>>> result, implementations need not provide software fill-ins > for specific > > >>>>> cryptographic features that are not available as hardware > features on that > > >>>>> platform. Presumably applications needing specific features > will select > > >>>>> platforms on which these features are present. Therefore, > while all APIs > > >>>>> specified here MUST exist in each conforming ODP > implementation, it is > > >>>>> acceptable for these APIs to return > ODP_RC_FEATURE_NOT_PRESENT in response > > >>>>> to calls requesting crypto features not present on that > platform. > > >>>>> > + > > >>>>> > +For example, the linux-generic ODP implementation may only > > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and > return a feature > > >>>>> not present error code for any other cipher. This > indication will also be > > >>>>> returned on that platform in response to odp_crypto_inquire > calls for > > >>>>> non-null cipher algorithms. > > >>>>> > + > > >>>>> > +@section verification Verification/Testing > > >>>>> > +This section describes the verification/test cases > needed to ensure > > >>>>> that the defined functionality is implemented correctly and > performs > > >>>>> adequately. This should be at a level of detail such that > the programmer > > >>>>> tasked with writing test scripts/programs to verify the > implementation(s) > > >>>>> of the defined functions can be written to ensure that all > relevant > > >>>>> functional variants and error/exception cases are properly > tested. > > >>>>> > + > > >>>>> > +This section needs to be completed before API testing > begins. > > >>>>> > + > > >>>>> > +*/ > > >>>>> > \ No newline at end of file > > >>>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png > > >>>>> > new file mode 100644 > > >>>>> > index > > >>>>> > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > > >>>>> > GIT binary patch > > >>>>> > literal 17179 > > >>>>> > > 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 > > >>>>> > Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b > > >>>>> > > > >>>>> > literal 0 > > >>>>> > HcmV?d00001 > > >>>>> > > > >>>>> > -- > > >>>>> > 1.8.3.2 > > >>>>> > > > >>>>> > > > >>>>> > _______________________________________________ > > >>>>> > lng-odp mailing list > > >>>>> > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > >>>>> > http://lists.linaro.org/mailman/listinfo/lng-odp > > >>>>> > > >>>> > > >>>> > > >>>> _______________________________________________ > > >>>> lng-odp mailing list > > >>>> lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > > >>>> http://lists.linaro.org/mailman/listinfo/lng-odp > > >>>> > > >>>> > > >>> > > >>> > > >>> -- > > >>> *Mike Holmes* > > >>> Linaro Technical Manager / Lead > > >>> LNG - ODP > > >>> > > >> > > >> > > > > > > > > > -- > > > *Mike Holmes* > > > Linaro Technical Manager / Lead > > > LNG - ODP > > > > > > > > -- > *Mike Holmes* > Linaro Technical Manager / Lead > LNG - ODP > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
I agree with opinion that architecture document should evolve along with ODP APIs reference. The architecture document should tie things together. I think we need to keep updating it along as we update public header files. And we would have periodic approval reviews among bigger group of SC members, how would not have time to follow incremental updates. I feel lack of good architecture document somewhat now, as I try to write my own ODP application. Example around are good and API descriptions help but I wish we would have something that explain bigger picture. As format goes, I would not mind that it would be like IETF RFC, plain text with ASCII art is fine with me. I would suggest normative language similar to RFCs as well. So it along with APIs description it would be normative document. Thanks, Victor On 3 July 2014 09:20, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > We should decide who is the main user/consumer of this arch document, > because they have different needs. > > - current developers (we) who are contributing/reviewing the document > will most probably prefer patches, because it is easier to follow > what is changing without need to read through a whole updated > document. > - New developers will read a whole document anyway so they don't care > much about history. > - SC need to get rendered document, maybe with highlighted changes. > > On 07/03/2014 07:04 PM, Mike Holmes wrote: >> >> Can everyone please weigh in with their thoughts, we need consensus on >> this before we can make progress with the Arch doc. >> >> Thanks BIll / Mike >> >> >> On 3 July 2014 11:25, Anders Roxell <anders.roxell@linaro.org >> <mailto:anders.roxell@linaro.org>> wrote: >> >> On 2014-07-03 10:01, Bill Fischofer wrote: >> > The people who review and approve these docs want to see docs >> with things >> > like change bars, not patches. The patch mechanism is simply >> inappropriate >> > for this activity and we shouldn't try to force-fit it for >> something it's >> > not designed to address. >> > >> > Again, the primary users of the odp-architecture git repository >> are those >> > who want access to complete docs, not those who are creating, >> reviewing, >> > and approving them. That's why we have a separate repository >> from the main >> > odp git repository so that "patches" can be handled differently >> between >> > them. >> >> That is why we use doxygen so that people reviewing for approval can >> look >> at the end result... However, isn't it better if anyone on the list >> can >> review the patch and send patches when that is needed? >> >> SC approval should only be required for major revisions. >> Possibly only a final read through review for every ODP release. >> >> > >> > My preference would be to grant push rights to those adding items >> to this >> > repository rather than going through the artifice of patches. It >> would be >> > more straightforward and consistent with the actual workflow. >> Git would >> > still be doing version tracking so it would be possible to see >> the complete >> > change history for any given doc easily. >> >> We should use git as a revision control system as it is, to allow us >> to >> make small changes when we discover them. >> >> >> Cheers, >> Anders >> >> > >> > >> > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: >> > >> > > I agree we need approval, but approval can be of a review of >> the patch to >> > > the text. >> > > >> > > I hope we don't need wholesale changes that need a complete re >> write and >> > > thus approval of a whole new document. For example a new patch >> which may >> > > add a new function to an API but we would hopefully not change >> any of the >> > > existing text in the main. >> > > >> > > Thus we can then make changes in manageable chunks, I agree >> that large >> > > new additions will come in via a pre approved hugue patch, >> created from a >> > > sequence of sprints just have we have done so far. >> > > >> > > I would argue that these small changes are likely given the >> additions >> > > already discovered by starting the validation testing work and >> the feedback >> > > it is generating with the need to be more specific in >> architectural areas. >> > > >> > > Mike >> > > >> > > >> > > On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org >> <mailto:bill.fischofer@linaro.org>> wrote: >> > > >> > >> Design documents require approval by those who aren't going to >> be >> > >> reviewing patches. This is different from code. My >> understanding of the >> > >> purpose of the odp-architecture repository is to provide a >> convenient means >> > >> of distributing documentation and making it available in >> various forms >> > >> (Doxygen, PDF) for access through the ODP web site as well as >> being >> > >> downloaded. >> > >> >> > >> So in this sense we're just using Git as a publication >> mechanism for docs. >> > >> >> > >> >> > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> >> > >> wrote: >> > >> >> > >>> I am confused git is a change control mechanism, and I really >> hope they >> > >>> do get patched, how will we improve the content ? >> > >>> >> > >>> >> > >>> On 3 July 2014 10:03, Bill Fischofer >> <bill.fischofer@linaro.org <mailto:bill.fischofer@linaro.org>> wrote: >> > >>> >> > >>>> Git is a publication mechanism for docs, not a change control >> > >>>> mechanism. Docs will not be 'patched'. New versions will >> replace old ones >> > >>>> as they are approved. >> > >>>> >> > >>>> >> > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell >> <anders.roxell@linaro.org <mailto:anders.roxell@linaro.org> >> > >>>> > wrote: >> > >>>> >> > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: >> > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org >> <mailto:bill.fischofer@linaro.org>> >> > >>>>> > --- >> > >>>>> > crypto_design.dox | 455 >> > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ >> > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes >> > >>>>> > 2 files changed, 455 insertions(+) >> > >>>>> > create mode 100644 crypto_design.dox >> > >>>>> > create mode 100644 images/syncmodels.png >> > >>>>> > >> > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox >> > >>>>> > new file mode 100644 >> > >>>>> > index 0000000..1ad2ac6 >> > >>>>> > --- /dev/null >> > >>>>> > +++ b/crypto_design.dox >> > >>>>> > @@ -0,0 +1,455 @@ >> > >>>>> > +/* Copyright (c) 2043, Linaro Limited >> > >>>>> > + * All rights reserved >> > >>>>> > + * >> > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause >> > >>>>> > + */ >> > >>>>> > + >> > >>>>> > +/** >> > >>>>> > +@page crypto_design ODP Design - Crypto API >> > >>>>> > +For the implimentation of the ODP crypto API please see >> @ref >> > >>>>> odp_crypto.h >> > >>>>> > + >> > >>>>> > +@tableofcontents >> > >>>>> > + >> > >>>>> > +@section revision_history Revision History >> > >>>>> > +Revision | Issue Data | Description | Author >> > >>>>> > +---------|------------|-------------|-------- >> > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic >> Functions | >> > >>>>> Bill, Alexandru >> > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, >> started use >> > >>>>> cases, miscellaneous formatting, API comments | Bill >> > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to >> include results >> > >>>>> of design discussions held during ODP team calls | Bill >> > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto >> > >>>>> sprint--action to resolve | Bill >> > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review >> > >>>>> comments--ready for final review | Bill >> > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC >> approval | Bill >> > >>>>> > + >> > >>>>> > +@section introduction Introduction >> > >>>>> > +This document describes the ODP v1.0 Crypto API. >> Cryptography is an >> > >>>>> important part of data plane processing as many >> communication protocols >> > >>>>> make use of cryptographic functions. Moreover, many SoCs >> incorporate >> > >>>>> cryptographic hardware that can significantly accelerate >> these operations >> > >>>>> compared to their software equivalents as well as provide >> validated >> > >>>>> hardware functional correctness and security boundaries >> necessary for >> > >>>>> system-level security certifications such as FIPS-140 Level >> 2 and above. >> > >>>>> > +@section requirements Requirements >> > >>>>> > +@subsection use_of_terms Use of Terms >> > >>>>> > +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 [RFC 2119]( >> > >>>>> https://tools.ietf.org/html/rfc2119). >> > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography >> > >>>>> > +Crypto functions cover a range of uses and capabilities >> designed to >> > >>>>> support data security, integrity, authentication, and >> non-repudiation. >> > >>>>> > +@subsubsection data_security Data Security >> > >>>>> > +Cryptography supports data security by making use of >> complex >> > >>>>> mathematical transformations that are not feasibly >> reversible without >> > >>>>> possession of the secret key used to encrypt message data. >> > >>>>> > +@subsubsection data_integrity Data Integrity >> > >>>>> > +Cryptography supports data integrity through the use of >> > >>>>> cryptographic checksums (also known as secure hashes) that >> ensure the >> > >>>>> recipient that message data has not been altered either >> accidentally or >> > >>>>> maliciously while in transit. >> > >>>>> > +@subsubsection data_authentication Data Authentication >> > >>>>> > +Cryptography supports data authentication through the >> uses of >> > >>>>> Message Authentication Codes (MACs) that enable the >> recipient to verify >> > >>>>> that a message was sent from an authorized counterparty, >> and hence was not >> > >>>>> forged. >> > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation >> > >>>>> > +Cryptography supports data non-repudiation through the >> use of >> > >>>>> digital signatures that enable a recipient or third party >> to verify the >> > >>>>> identity of the sending party and prevents the sending >> party from later >> > >>>>> denying that they originated a signed message. >> > >>>>> > +@subsection scope Scope >> > >>>>> > +ODP v1.0 crypto support is designed to provide a >> portable framework >> > >>>>> for accessing SoC-specific cryptographic functions of most >> use to the data >> > >>>>> plane. This is predominantly symmetric crypto operations >> used to support >> > >>>>> the encryption and decryption of data at line rate using >> hardware >> > >>>>> acceleration and offload. Specifically excluded in this >> support are public >> > >>>>> key operations and other crypto functions mainly used in >> the control plane. >> > >>>>> > +@subsection cryptographic_operations_in_the_data_plane >> > >>>>> Cryptographic Operations in the Data Plane >> > >>>>> > +ODP v1.0 crypto APIs cover the following areas: >> > >>>>> > +@subsubsection ciphering Ciphering >> > >>>>> > +Ciphering refers to mathematical transformations that >> use a secret >> > >>>>> key to encipher data, transforming the original data >> (referred to as >> > >>>>> plaintext) into ciphertext, thereby making it >> unintelligible to anyone not >> > >>>>> in possession of the key. Similarly, ciphering is also used >> to decipher >> > >>>>> data, allowing someone in possession of the correct key to >> transform >> > >>>>> received ciphertext back into plaintext. Approved block >> ciphers are listed >> > >>>>> >> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and >> > >>>>> SHOULD be supported by each ODP implementation. >> > >>>>> > +@subsubsection hasing Hashing >> > >>>>> > +A hash is a cryptographic digest of a message that can >> be used to >> > >>>>> represent it for comparison or integrity checking. Hash >> functions are >> > >>>>> designed so that any alteration of a message will alter the >> hash and that >> > >>>>> it is computationally infeasible to craft a message that >> generates the same >> > >>>>> hash value as another message. Secure hash functions >> approved for >> > >>>>> cryptographic use are listed by NIST [here]( >> > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) >> and >> > >>>>> SHOULD be supported by each ODP implementation. >> > >>>>> > +@subsubsection zeroization Zeroization >> > >>>>> > +To preserve the security of data, certain transient data >> held in >> > >>>>> data buffers MUST be cleared to zeros upon buffer free. >> Such capability is >> > >>>>> referred to as zeroization. ODP supports zeroization as a >> buffer pool >> > >>>>> attribute. >> > >>>>> > +@subsubsection random_number_generation Random Number >> Generation >> > >>>>> > +Because cryptography relies heavily on “unguessable” keys >> of >> > >>>>> various sorts, random number generation (RNG) is an >> integral part of >> > >>>>> cryptographic processing. Random numbers are used in key >> generation, >> > >>>>> initialization vectors (IVs), various types of padding >> bytes, and various >> > >>>>> other uses collectively referred to as nonces, that serve >> to “harden” >> > >>>>> cryptographic processing. >> > >>>>> > + >> > >>>>> > +There are two types of random number support of >> interest. Hardware >> > >>>>> random data, also known as entropy, that is the result of >> inherently random >> > >>>>> physical processes, and deterministic random bit generation >> (DRBG) that is >> > >>>>> used in certain certified cryptographic operations. >> Approved DRBG >> > >>>>> algorithms are listed in [NIST SP 800-90A]( >> > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does >> not >> > >>>>> specify which algorithms are available on a given >> implementation. As such >> > >>>>> ODP implementations MAY use any approved DRGB algorithm but >> SHOULD support >> > >>>>> at least one of them. Additionally, ODP implementations >> MUST NOT represent >> > >>>>> non-approved algorithms as DRBG implementations. Validated >> algorithms are >> > >>>>> listed in the [NIST DRBG Validation List]( >> > >>>>> >> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >> > >>>>> > + >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry >> > >>>>> > +To enable applications to adapt to the implementation >> models >> > >>>>> offered across different SoC platforms, ODP provides APIs >> to allow >> > >>>>> applications to inquire about underlying crypto >> capabilities. A given ODP >> > >>>>> implementation may offer crypto as hardware features, >> software features, or >> > >>>>> not available on a given platform. >> > >>>>> > +@subsection cryptographic_algorithms Cryptographic >> Algorithms and >> > >>>>> Protocols >> > >>>>> > +A cryptographic algorithm is a mathematical transform >> that provides >> > >>>>> one of the cryptographic operations described above. They >> in turn are used >> > >>>>> as building blocks in creating cryptographic protocols. >> These are complete >> > >>>>> sets of rules for how to exchange data securely using >> cryptography. Both >> > >>>>> cryptographic algorithm and protocol design are highly >> specialized >> > >>>>> disciplines that involve high levels of public scrutiny and >> validation. As >> > >>>>> a result, applications simply make use of approved >> cryptographic algorithms >> > >>>>> and protocols. >> > >>>>> > +@subsection cryptographic_operations Cryptographic >> Operations >> > >>>>> > +Cryptographic operations may be initiated by software or >> directly >> > >>>>> by hardware as part of the RX or TX packet path processing. >> For ODP v1.0 >> > >>>>> software-initiated cryptographic operations are the primary >> use case. ODP >> > >>>>> provides APIs for performing data ciphering, hashing, >> random number >> > >>>>> generation, and capability inquiry. >> > >>>>> > +@subsection performance_expectations Performance >> Expectations >> > >>>>> > +In the data plane, the total processing budget for a >> packet may >> > >>>>> only be a few hundred cycles, so function invocation >> overhead MUST be kept >> > >>>>> to a minimum. This has several implications. >> > >>>>> > + >> > >>>>> > +-# When work is dispatched to a thread, all information >> needed by >> > >>>>> the thread to process the work request SHOULD be >> immediately at hand. >> > >>>>> Ideally any context or variables needed for the operation >> have been >> > >>>>> pre-warmed in the cache to avoid the latency hits >> associated with cache >> > >>>>> misses. SoCs having hardware schedulers generally do this >> pre-staging of >> > >>>>> data to minimize such latencies, and ODP implementations >> are expected to >> > >>>>> exploit such platform capabilities whenever possible.\n\n >> > >>>>> > + >> > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive >> amounts of >> > >>>>> parameter passing and (depending on the implementation) >> SHOULD be inlined >> > >>>>> as much as possible to avoid call overhead. One technique >> that has proven >> > >>>>> useful is to allow for parameters to be passed as an >> explicit thread-local >> > >>>>> static structure. Such use of “templating” means that a >> single function can >> > >>>>> support a rich set of options but the caller can configure >> a template >> > >>>>> matched to specific use and only vary the one or two >> parameters that differ >> > >>>>> from call to call.\n\n >> > >>>>> > + >> > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any >> > >>>>> non-exception path function processing. Kernel calls and >> such are >> > >>>>> acceptable only during one-time initialization logic or >> certain types of >> > >>>>> unusual error recovery operations. Often the best way to >> handle the latter >> > >>>>> is to pass the work to a dedicated recovery thread (or back >> to the control >> > >>>>> plane) rather than attempting to handle the condition >> inline. For example, >> > >>>>> a link-down condition will trigger various recovery actions >> that might best >> > >>>>> be handled in this manner. >> > >>>>> > + >> > >>>>> > +@subsection use_by_existing_code Use by Existing Code >> > >>>>> > +Most applications wishing to make use of ODP represent >> substantial >> > >>>>> existing investment that must be preserved. Insofar as >> possible, ODP >> > >>>>> functions need to be orthogonal to existing application >> environments and >> > >>>>> structures to permit easy intermixing with pre-existing code. >> > >>>>> > +@subsection data_references Data References >> > >>>>> > +Packet data is inherently of variable length however it >> is often >> > >>>>> more efficient to organize memory into fixed-sized buffers >> that can be >> > >>>>> chained together on demand to contain packets. The >> application SHOULD >> > >>>>> normally not need to be aware of such lower-level >> segmentation and should >> > >>>>> be able to treat a packet as a single object. Alternately, >> especially when >> > >>>>> dealing with existing code, data segmentation MUST be >> explicitly >> > >>>>> specifiable via scatter/gather lists. For example, data >> encryption or >> > >>>>> decryption may be invoked on a list of data segments as >> part of a single >> > >>>>> function call. >> > >>>>> >> > >>>>> Every time you add a full stop for a sentence, you have to >> press return >> > >>>>> and start typing the next sentence. >> > >>>>> This means that diffs of future changes will be per sentence. >> > >>>>> Doxygen will still concatenate this as a paragraph with no >> visual >> > >>>>> difference in the result. >> > >>>>> I think the above line will look like this: >> > >>>>> >> > >>>>> Packet data is inherently of variable length however it is >> often more >> > >>>>> efficient to organize memory into fixed-sized buffers that >> can be chained >> > >>>>> together on demand to contain packets. >> > >>>>> The application SHOULD normally not need to be aware of such >> > >>>>> lower-level segmentation and should be able to treat a >> packet as a single >> > >>>>> object. >> > >>>>> Alternately, especially when dealing with existing code, data >> > >>>>> segmentation MUST be explicitly specifiable via >> scatter/gather lists. >> > >>>>> For example, data encryption or decryption may be invoked >> on a list of >> > >>>>> data segments as part of a single function call. >> > >>>>> >> > >>>>> >> > >>>>> Cheers, >> > >>>>> Anders >> > >>>>> >> > >>>>> > +@subsection chained_operations Chained Operations >> > >>>>> > +Crypto operations such as hashing and encryption, or >> decryption and >> > >>>>> verification, are very commonly used in combination. For >> ODP, it is >> > >>>>> sufficient to support one cipher and one >> hash/authentication operation in a >> > >>>>> single call and this combination MUST be supported to avoid >> the call and >> > >>>>> dispatch overhead of separate invocations. >> > >>>>> > +@subsection key_management Key Management and Session Data >> > >>>>> > +Keying is an area of particular sensitivity in crypto >> processing >> > >>>>> since keys are highly confidential and may be subject to >> legal requirements >> > >>>>> for safeguarding within special hardware enclosures. >> > >>>>> > + >> > >>>>> > +A session is the security context used to represent an >> active set >> > >>>>> of crypto operations that need to be applied to a flow on a >> > >>>>> packet-by-packet basis. Generally a session is established >> upon detection >> > >>>>> of a flow requiring crypto processing and retained for the >> life of that >> > >>>>> flow. It has been noted that this can involve cooperative >> processing >> > >>>>> between the control and data planes so several requirements >> stem from this: >> > >>>>> > + >> > >>>>> > +-# Session creation MAY need to be handled in an >> asynchronous >> > >>>>> manner. This is to allow these to be created in batches by >> thread(s) that >> > >>>>> specialize in this activity.\n\n >> > >>>>> > + >> > >>>>> > +-# Sessions MAY need to reference keying material >> indirectly via >> > >>>>> key handling modules.\n\n >> > >>>>> > + >> > >>>>> > +-# Session creation MAY be performed by non-ODP code and >> > >>>>> communicated to data plane routines that make use of ODP >> crypto functions >> > >>>>> that need to reference the session information. >> > >>>>> > + >> > >>>>> > +ODP session APIs and data structures SHOULD be >> represented by >> > >>>>> abstract data types that encapsulate implementation details >> for both >> > >>>>> platform efficiency and to accommodate these needs. >> > >>>>> > +Use Cases >> > >>>>> > +For ODP v1.0 the major use cases of interest involve >> cryptographic >> > >>>>> algorithm acceleration. Cryptographic protocol acceleration >> is reserved for >> > >>>>> future ODP releases. >> > >>>>> > +Buffers and Data Blocks >> > >>>>> > +Cryptographic operations may be performed directly on data >> > >>>>> contained in ODP packet buffers, or it may be performed on >> “raw” data >> > >>>>> blocks operating entirely under application control. Note >> that when using >> > >>>>> raw data blocks not managed by ODP, the application must >> perform any needed >> > >>>>> zeroization using either its own or ODP-supplied buffer >> zeroization >> > >>>>> functions. ODP automatic support for zeroization is limited >> to ODP-managed >> > >>>>> buffers. ODP buffers allocated from buffer pools designated >> for crypto use >> > >>>>> will also have whatever alignment and/or addressability >> attributes needed >> > >>>>> by the implementation to support crypto API calls. >> > >>>>> > + >> > >>>>> > +Note: Some implementations may have difficulty dealing >> with >> > >>>>> application buffer addresses, as these may be virtual >> addresses that are >> > >>>>> mapped discontiguously into physical memory. For such >> implementations, >> > >>>>> memory SHOULD be allocated contiguously and MAY need to be >> “registered” to >> > >>>>> have proper addressability for crypto operations. This area >> of the design >> > >>>>> will be updated based on experience in dealing with >> different crypto >> > >>>>> implementations that have such requirements. >> > >>>>> > +Synchronization >> > >>>>> > +ODP operations fall into one of three categories: >> > >>>>> > + >> > >>>>> > +-# Inline (Synchronous): Upon return from a call the >> operation is >> > >>>>> complete. Operation is thus completely synchronous to the >> caller. Inline >> > >>>>> is the appropriate model when the invoked function takes >> relatively few >> > >>>>> cycles or when the caller cannot feasibly progress without >> the results of >> > >>>>> the invoked function.\n\n >> > >>>>> > + >> > >>>>> > +-# Parallel: Upon return from a call the operation has >> been >> > >>>>> initiated, but is expected to complete shortly. The caller >> continues to >> > >>>>> execute until it needs the result at which point it waits >> to complete the >> > >>>>> parallel operation. The effect is as if the operation were >> inline except >> > >>>>> that the caller was able to execute in parallel with the >> operation for some >> > >>>>> application-determined period of time. Parallel is the >> appropriate model >> > >>>>> when the operation being performed is relatively short (a >> few dozen up to >> > >>>>> perhaps 100 or 200 cycles) and the caller can usefully >> accomplish other >> > >>>>> processing on the same unit of work while the parallel >> operation is in >> > >>>>> progress, but not enough to justify the overhead of a >> formal queued work >> > >>>>> dispatch.\n\n >> > >>>>> > + >> > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call the >> > >>>>> operation has been queued for execution. A completion event >> will be queued >> > >>>>> back to the scheduler when the event is completed. Offload >> is the >> > >>>>> appropriate model when the invoked function will take a >> substantial amount >> > >>>>> of cycles (thousands to tens of thousands) allowing the >> invoking >> > >>>>> thread/core to service other work until the operation >> completes. For >> > >>>>> offloaded work, completion is indicated by a completion >> event being posted >> > >>>>> back to an application-designated completion queue. Upon >> receipt the unit >> > >>>>> of work that initiated the offloaded operation continues >> processing with >> > >>>>> the results of the call. >> > >>>>> > + >> > >>>>> > +The synchronization models of interest are summarized in >> Figure 1: >> > >>>>> > + >> > >>>>> > + >> > >>>>> > + >> > >>>>> > +Note: Because few implementations are expected to offer >> the >> > >>>>> Parallel mode of operation as described above, this mode >> is reserved for >> > >>>>> potential future use. For ODP v1.0 only synchronous and >> asynchronous crypto >> > >>>>> operations are defined. >> > >>>>> > +@section functional_definition Functional Definition >> > >>>>> > +@subsection abstract_data_types Abstract data types >> > >>>>> > +The following enumerations define various algorithms >> used for >> > >>>>> ciphering and hashing. These are the basic operations >> applied to input data. >> > >>>>> > + >> > >>>>> > +A particular ODP implementation should map these values >> to the >> > >>>>> actual information to be passed to the crypto engine. As >> such, the actual >> > >>>>> values of these enums is implementation-defined. >> > >>>>> > + >> > >>>>> > +Cipher algorithm encoding specifies the algorithm and >> cipher mode >> > >>>>> employed (as per security relevant RFCs - [4305]( >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( >> > >>>>> http://tools.ietf.org/html/rfc4494)). >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +enum odp_cipher_alg { >> > >>>>> > + ODP_CIPHER_ALG_NULL, >> > >>>>> > + ODP_CIPHER_ALG_DES, >> > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, >> > >>>>> > + ODP_CIPHER_ALG_AES_CBC, >> > >>>>> > + ODP_CIPHER_ALG_AES_GCM, >> > >>>>> > + ODP_CIPHER_ALG_AES_CTR, >> > >>>>> > + ODP_CIPHER_ALG_KASUMI, >> > >>>>> > + ODP_CIPHER_ALG_SNOW, >> > >>>>> > + ... >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Authorization algorithm encoding specifies the algorithm >> and the >> > >>>>> length of the authorization used (as per security relevant >> RFCs - [4305]( >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( >> > >>>>> http://tools.ietf.org/html/rfc4494)): >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +enum odp_auth_alg { >> > >>>>> > + ODP_AUTH_ALG_NULL, >> > >>>>> > + ODP_AUTH_MD5_96, >> > >>>>> > + ODP_AUTH_ALG_SHA1_96, >> > >>>>> > + ODP_AUTH_ALG_SHA1_160 >> > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, >> > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, >> > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, >> > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, >> > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, >> > >>>>> > + ODP_AUTH_ALG_SNOW, >> > >>>>> > + ODP_AUTH_ALG_KASUMI, >> > >>>>> > + ... >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +typedef union odp_crypto_alg_t { >> > >>>>> > + enum odp_cipher_alg cipher; >> > >>>>> > + enum odp_auth_alg auth; >> > >>>>> > +}odp_crypto_alg_t; >> > >>>>> > +@endcode >> > >>>>> > +@subsection parameter_structures Parameter Structures >> > >>>>> > +@subsubsection crypto_sessions Crypto Sessions >> > >>>>> > +The following structure describes a crypto session. All >> packets / >> > >>>>> raw data buffers processed in a session share the data that >> defines the >> > >>>>> session. A crypto session is defined by: >> > >>>>> > + >> > >>>>> > +- Operation type : encode or decode\n\n >> > >>>>> > + >> > >>>>> > +- Algorithms specifications, keys and , if required, >> initialization >> > >>>>> vectors. When initialization vectors are not provided and >> they should be >> > >>>>> provided automatically by the crypto engine.\n\n >> > >>>>> > + >> > >>>>> > +- The operation mode: synchronous or asynchronous. >> Synchronous >> > >>>>> operation blocks the caller until an operation status and >> result are >> > >>>>> available. In synchronous mode there is at most only one >> outstanding crypto >> > >>>>> operation in the calling thread. In asynchronous mode, the >> caller starts >> > >>>>> the crypto operation and later it may receive the status >> and the result >> > >>>>> together with a request context. The operation status and >> result may also >> > >>>>> be received by a different thread.\n\n >> > >>>>> > + >> > >>>>> > +- Operation mode parameters: For asynchronous operation a >> > >>>>> completion event containing the status, the result and the >> request context >> > >>>>> is enqueued to a completion queue. In case the queue is >> under the scheduler >> > >>>>> control, the scheduler determines who will receive the >> completion event and >> > >>>>> when. When the completion queue is not scheduled, the >> thread which is >> > >>>>> supposed to get the operation output has to explicitly poll >> the completion >> > >>>>> queue. >> > >>>>> > + >> > >>>>> > +Note that this is an abstract data type and its structure >> is >> > >>>>> implementation-specific. The layout shown here is for >> illustrative purposes >> > >>>>> and the actual layout will vary from one implementation to >> the next to most >> > >>>>> closely align with the structures needed by the underlying >> SoC platform. >> > >>>>> Applications set and reference fields in the session >> structure via accessor >> > >>>>> functions that hide the actual layout. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +typedef enum odp_crypto_op_t { >> > >>>>> > + ODP_CRYPTO_OP_ENCODE, >> > >>>>> > + ODP_CRYPTO_OP_DECODE >> > >>>>> > +}odp_crypto_op_t; >> > >>>>> > + >> > >>>>> > +typedef struct odp_key_t { >> > >>>>> > +}odp_key_t; >> > >>>>> > + >> > >>>>> > +typedef struct odp_crypto_session_t { >> > >>>>> > + odp_crypto_op_t op; >> > >>>>> > + struct { >> > >>>>> > + enum odp_cipher_alg cipher_alg; >> > >>>>> > + odp_key_t *key; >> > >>>>> > + uint8_t *iv; >> > >>>>> > + size_t iv_len; >> > >>>>> > + } cipher; >> > >>>>> > + >> > >>>>> > + struct { >> > >>>>> > + enum odp_auth_alg auth_alg; >> > >>>>> > + enum odp_auth_len auth_len; >> > >>>>> > + odp_key_t *key; >> > >>>>> > + } auth; >> > >>>>> > + >> > >>>>> > + enum odp_crypto_op_mode { >> > >>>>> > + ODP_CRYPTO_SYNC, >> > >>>>> > + ODP_CRYPTO_ASYNC, >> > >>>>> > + } op_mode; >> > >>>>> > + >> > >>>>> > + struct { >> > >>>>> > + uint32_t timeout; >> > >>>>> > + struct { >> > >>>>> > + odp_queue_t completion_queue; >> > >>>>> > + } async; >> > >>>>> > + } op_mode_params; >> > >>>>> > + >> > >>>>> > + odp_session_proc_info_t session_proc_info; >> > >>>>> > +} odp_crxsypto_session_t; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +The completion queue contained in the session structure >> is an >> > >>>>> in/out parameter. If provided, then the queue specified is >> associated with >> > >>>>> the session and is used to ensure order preservation on >> that session. If >> > >>>>> not provided, one is created and returned to the caller. >> Note that this >> > >>>>> completion queue is used to order operations performed on >> this crypto >> > >>>>> session. It should not be confused with the completion >> queue specified on >> > >>>>> the odp_crypto_session_create() call (see below) that is >> used to control >> > >>>>> whether that call is itself processed in a synchronous vs. >> asynchronous >> > >>>>> manner. >> > >>>>> > + >> > >>>>> > +The following structure comprises processing >> information. This is >> > >>>>> logically divided in two parts: >> > >>>>> > + >> > >>>>> > +- Processing input info - When crypto engine provides >> support for >> > >>>>> protocol processing, this information is provided in a >> higher level common >> > >>>>> protocol terminology form and a particular implementation >> should be able to >> > >>>>> derive everything it needs from this definition. In >> addition, for crypto >> > >>>>> engines able to automate tasks like memory allocation for >> the output a >> > >>>>> buffer pool id may be specified.\n\n >> > >>>>> > + >> > >>>>> > +- Processing output information - statistics about >> processed >> > >>>>> bytes/packets. These are useful when a session expiration >> is based on >> > >>>>> traffic volume. These statistics may be updated by the >> software or by the >> > >>>>> hardware crypto engine. >> > >>>>> > + >> > >>>>> > +Again, this is an abstract type whose specific layout >> will vary >> > >>>>> based on implementation considerations. Access to fields >> contained in the >> > >>>>> structure is only via accessor functions. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +typedef struct { >> > >>>>> > + uint64_t pkts_processed; >> > >>>>> > + uint64_t bytes_processed; >> > >>>>> > + uint64_t pkts_errored; >> > >>>>> > + uint64_t bytes_errored; >> > >>>>> > + >> > >>>>> > + odp_buffer_pool_t out_pool; >> > >>>>> > + >> > >>>>> > +} odp_session_proc_info_t; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +This enumeration defines which operations are applied >> and the order. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +enum odp_crypto_combination { >> > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, >> > >>>>> > + ODP_CRYPTO_AUTH_ONLY, >> > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +This structure defines a contiguous segment in the input >> data which >> > >>>>> starts at offset offset and is len bytes long. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +struct odp_data_range { >> > >>>>> > + unsigned offset:16; >> > >>>>> > + unsigned len:16; >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +@subsection api_functions API Functions >> > >>>>> > + >> > >>>>> > +@subsubfunction Session Creation >> > >>>>> > + >> > >>>>> > +This function is used to create a crypto session. The >> required >> > >>>>> parameters are : >> > >>>>> > + >> > >>>>> > +- Operation : encode/decode >> > >>>>> > +- Processing info : cipher/auth/both >> > >>>>> > +- Preferred mode : sync or async. >> > >>>>> > +- Algorithms suites, keys and optional IV >> > >>>>> > + >> > >>>>> > +Session creation can be synchronous or asynchronous. >> Completion >> > >>>>> event argument is used to return the status and the session >> handle. When >> > >>>>> completion queue is not provided (synchronous call), the >> completion event >> > >>>>> is available upon function call return. When completion >> queue is provided >> > >>>>> (asynchronous call), the completion event is placed on the >> completion queue. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +typedef uint64_t odp_crypto_session_t; >> > >>>>> > + >> > >>>>> > +struct odp_session_params { >> > >>>>> > + enum odp_crypto_operation op; >> > >>>>> > + odp_session_proc_info_t proc_info; >> > >>>>> > + enum odp_crypto_op_mode pref_mode; >> > >>>>> > + enum odp_cipher_alg cipher_alg; >> > >>>>> > + odp_key_t *cipher_key; >> > >>>>> > + uint8_t *iv; >> > >>>>> > + size_t iv_len; >> > >>>>> > + enum odp_auth_alg auth_alg; >> > >>>>> > + odp_key_t *auth_key; >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +enum odp_crypto_ses_create_err { >> > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, >> > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, >> > >>>>> > + /* Session creation error codes */ >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +void >> > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t >> > >>>>> completion_event, enum odp_crypto_ses_create_err *status); >> > >>>>> > + >> > >>>>> > +void >> > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t >> > >>>>> completion_event, odp_crypto_session_t *handle); >> > >>>>> > + >> > >>>>> > +int odp_crypto_session_create( >> > >>>>> > + struct odp_session_params *params, >> > >>>>> > + odp_buffer_t completion_event, >> > >>>>> > + odp_queue_t completion_queue); >> > >>>>> > +@endcode >> > >>>>> > +@subsection crypto_operation Crypto Operation >> > >>>>> > + >> > >>>>> > +Crypto operations are described by a parameter structure: >> > >>>>> > +@code >> > >>>>> > +struct odp_crypto_op_params { >> > >>>>> > + odp_crypto_session_t session; >> > >>>>> > + odp_packet_t pkt; >> > >>>>> > + odp_packet_t out_pkt; >> > >>>>> > + uint8_t *override_iv_ptr; >> > >>>>> > + unsigned hash_result_offset; >> > >>>>> > + struct odp_data_range cipher_range; >> > >>>>> > + struct odp_data_range auth_range; >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +<table> >> > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> >> > >>>>> > +<tr><td>session</td><td>Session to perform the >> operation</td></tr> >> > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be >> processed</td></tr> >> > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / >> buffer to be >> > >>>>> returned as the result of the operation. There are three >> different ways >> > >>>>> this parameter is used, depending on the mode of operation >> requested by the >> > >>>>> caller and the capabilities of the underlying >> implementation:\n\n >> > >>>>> > + >> > >>>>> > +-# If out_pkt is the same as pkt this indicates that the >> operation >> > >>>>> should be performed in place.\n\n >> > >>>>> > +-# If out_pkt is different from pkt this indicates that >> output >> > >>>>> should be placed in the buffer supplied by the caller.\n\n >> > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied >> on input) >> > >>>>> this indicates that an output buffer should be allocated by >> the operation >> > >>>>> and returned as part of the completion event associated >> with the >> > >>>>> operation.\n\n >> > >>>>> > + >> > >>>>> > +Note that not every implementation will support all of >> these modes >> > >>>>> and MAY require that one mode be used in preference to >> others. Any such >> > >>>>> implementation restrictions are communicated as output from >> session >> > >>>>> creation.</td></tr> >> > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for >> this >> > >>>>> request</td></tr> >> > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the >> output packet >> > >>>>> where the hash result should be stored.</td></tr> >> > >>>>> > +<tr><td>cipher_range</td><td>The byte range >> (offset:length) of the >> > >>>>> data to be processed for ciphering.</td></tr> >> > >>>>> > +<tr><td>auth_range</td><td>The byte range >> (offset:length) of the >> > >>>>> data to be processed for authentication.</td></tr> >> > >>>>> > +</table> >> > >>>>> > + >> > >>>>> > +The crypto operation is initiated with a single call >> that passes >> > >>>>> the parameters for the operation and an event (for >> asynchronous completion). >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_operation( >> > >>>>> > + struct odp_crypto_op_params *params, >> > >>>>> > + odp_buffer_t completion_event); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Parameter | Meaning >> > >>>>> > +----------|-------- >> > >>>>> > +params | The parameter structure describing the >> crypto operation >> > >>>>> to be performed. >> > >>>>> > +completion_event | The event delivered on completion. It >> provides >> > >>>>> information about the status of the operation, result and >> request context. >> > >>>>> In synchronous mode the event is available upon function >> call return. In >> > >>>>> asynchronous mode, the event is placed on the session / >> operation >> > >>>>> completion queue when the operation finished. >> > >>>>> > + >> > >>>>> > +Upon return the return code indicates whether the >> operation was >> > >>>>> synchronous or asynchronous, or if an error occurred that >> prevented the >> > >>>>> operation from being performed. >> > >>>>> > + >> > >>>>> > +Get session operation : >> > >>>>> > +@code >> > >>>>> > +odp_crypto_op_t >> > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Get session cipher information : >> > >>>>> > +@code >> > >>>>> > +odp_cipher_alg >> > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t >> ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Get session authentication information : >> > >>>>> > +@code >> > >>>>> > +odp_auth_alg >> > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Change session IV : >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, >> uint8_t >> > >>>>> *iv); >> > >>>>> > +@emdcode >> > >>>>> > + >> > >>>>> > +Change cipher or/and hash keys: >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, >> odp_key_t >> > >>>>> *key); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Destroy crypto session. All pending operations are >> cancelled. >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Get completion event information - algorithm error, >> output and >> > >>>>> context. Note that implementations MAY define their own >> specific error >> > >>>>> codes that have meaning in that context. For application >> portability it is >> > >>>>> sufficient to know whether an operation completed >> successfully or >> > >>>>> experienced an error of some sort. >> > >>>>> > +@code >> > >>>>> > +enum crypto_alg_err { >> > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +enum crypto_hw_err { >> > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, >> > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, >> > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +struct odp_crypto_compl_status { >> > >>>>> > + odp_crypto_alg_t alg; >> > >>>>> > + enum crypto_alg_err alg_err; >> > >>>>> > + enum crypto_hw_err hw_err; >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +void >> > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, >> > >>>>> > + struct odp_crypto_compl_status >> *auth, >> > >>>>> > + struct odp_crypto_compl_status >> *cipher); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Returns the output packet handle associated with the >> completion >> > >>>>> event : >> > >>>>> > +@code >> > >>>>> > +odp_packet_t >> > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Sets a context handle to be returned with the completion >> event : >> > >>>>> > +@code >> > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t >> completion_event, >> > >>>>> odp_compl_ctx_t *ctx); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Returns the context associated with the completion event : >> > >>>>> > +@code >> > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t >> > >>>>> completion_event); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +This section describes the API/Interface being defined at >> a >> > >>>>> functional level in technical detail. Sub-sections include >> header file >> > >>>>> names, where implementation files are expected to reside in >> the ODP git >> > >>>>> tree, as well as the name, parameters, abstract data types, >> functionality, >> > >>>>> return codes, and exception conditions of each function >> call defined by the >> > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be >> used to allow >> > >>>>> the programmer tasked with implementing the API/Interface >> to understand the >> > >>>>> function to be implemented as well as error conditions, >> corner cases, >> > >>>>> performance requirements, etc. needed to implement the >> described >> > >>>>> API/Interface in a functionally correct and efficient manner. >> > >>>>> > + >> > >>>>> > +@subsubsection random_number_functions Random Number >> Functions >> > >>>>> > +As noted earlier, random number support consists of two >> functions: >> > >>>>> > +@code >> > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool >> > >>>>> use_entropy); >> > >>>>> > + >> > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +The difference is that the first provides access to >> hardware random >> > >>>>> number functions that return true random data. This is >> typically used for >> > >>>>> seed values. The second provides a deterministic random bit >> generator >> > >>>>> conforming to NIST standards and is used by various crypto >> protocols and >> > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get >> is used to >> > >>>>> disable any hardware pre-processing normally provided by >> the function and >> > >>>>> is mainly intended to be used for testing/validation >> purposes. >> > >>>>> > + >> > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool >> Extensions >> > >>>>> > +To support zeroization a buffer may be allocated with an >> > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer >> should be >> > >>>>> zeroized upon free. Alternately, a new type >> (ODP_CLEAR_ON_FREE) is added to >> > >>>>> odp_buffer_pool_create() that specifies that all buffers >> allocated from >> > >>>>> this pool must be zeroized upon free. Essentially, the >> buffer security >> > >>>>> attribute is set by default from the attributes of the >> buffer pool that it >> > >>>>> is allocated from. >> > >>>>> > + >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry >> > >>>>> > +To enable applications to determine crypto capabilities. >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum >> odp_auth_alg); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Inquires whether the specified crypto and auth >> algorithms are >> > >>>>> supported. Responses include: >> > >>>>> > +- ODP_HW_SYNC_SUPPORT >> > >>>>> > +- ODP_HW_ASYNC_SUPPORT >> > >>>>> > +- ODP_SW_SYNC_SUPPORT >> > >>>>> > +- ODP_SW_ASYNC_SUPPORT >> > >>>>> > +- ODP_NO_SUPPORT >> > >>>>> > + >> > >>>>> > +HW support means the combination is supported in >> hardware, SW >> > >>>>> support means the combination is supported in software by the >> > >>>>> implementation. No support means the combination is not >> supported by the >> > >>>>> implementation. The SYNC and ASYNC return options can help >> the application >> > >>>>> decide how to invoke these functions, or it can just check >> whether or not >> > >>>>> the response is ODP_NO_SUPPORT. >> > >>>>> > + >> > >>>>> > +@section implementation_considerations Implementation >> Considerations >> > >>>>> > +One of the main purposes for the ODP crypto APIs is to >> provide >> > >>>>> portable access across different SoCs whose hardware crypto >> capabilities >> > >>>>> largely overlap but vary in terms of their implementation >> details. As a >> > >>>>> result, implementations need not provide software fill-ins >> for specific >> > >>>>> cryptographic features that are not available as hardware >> features on that >> > >>>>> platform. Presumably applications needing specific features >> will select >> > >>>>> platforms on which these features are present. Therefore, >> while all APIs >> > >>>>> specified here MUST exist in each conforming ODP >> implementation, it is >> > >>>>> acceptable for these APIs to return >> ODP_RC_FEATURE_NOT_PRESENT in response >> > >>>>> to calls requesting crypto features not present on that >> platform. >> > >>>>> > + >> > >>>>> > +For example, the linux-generic ODP implementation may only >> > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and >> return a feature >> > >>>>> not present error code for any other cipher. This >> indication will also be >> > >>>>> returned on that platform in response to odp_crypto_inquire >> calls for >> > >>>>> non-null cipher algorithms. >> > >>>>> > + >> > >>>>> > +@section verification Verification/Testing >> > >>>>> > +This section describes the verification/test cases >> needed to ensure >> > >>>>> that the defined functionality is implemented correctly and >> performs >> > >>>>> adequately. This should be at a level of detail such that >> the programmer >> > >>>>> tasked with writing test scripts/programs to verify the >> implementation(s) >> > >>>>> of the defined functions can be written to ensure that all >> relevant >> > >>>>> functional variants and error/exception cases are properly >> tested. >> > >>>>> > + >> > >>>>> > +This section needs to be completed before API testing >> begins. >> > >>>>> > + >> > >>>>> > +*/ >> > >>>>> > \ No newline at end of file >> > >>>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png >> > >>>>> > new file mode 100644 >> > >>>>> > index >> > >>>>> >> >> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >> > >>>>> > GIT binary patch >> > >>>>> > literal 17179 >> > >>>>> > >> zcmch;XH?Tcv@Z$>iXhSqNDxrER8c~aDjh?WUL(Et-Vx~th$xXJz4smxnsljBLkDS* >> > >>>>> > >> z-U&T7c+PqEth3g=pWb`(A^(+`Ju`dSo?U(urKTcJLIfnj!NDO>RFHXxgM;UcgM-UP >> > >>>>> > >> zco&=V+&Rz%2S;jIQRa=N_smYZm=g1R%A)G;H}~-I@#)CiCI2J+roi>GZf!`WZf2C^ >> > >>>>> > >> z)RvpX$JcFtiQ5qoYL6FkUycg*4Vd+@&4{rjkG>nkclWe8rfD1Kcc1XHC~lIRaY%yb >> > >>>>> > >> z&#AzVI)|_y#V9pZhT`)S%d?B?+??Iw*B&jKn(0AesGPJrSZ@CB2`0NB4)JL96L+p} >> > >>>>> > >> z2EA*#7UJYgNNv7slHc$~o1KpsjkR7Barezu`JrcdID~L;+5)WX%*UJQ&Yi``U%4(X >> > >>>>> > >> zh-E}#FgHFdGdD9&|LPB(lF}u>&RE{s?M=6MF^#D=F|5EA<NV{oCcMa<zn~Mk<T(Ze >> > >>>>> > >> z&0HR0nL<AyH)RZQ<XDn1{1sHSG^Y=gE!Bz}JL8mgNokN{HQQR8?0sLmM}k+*VtSKU >> > >>>>> > >> z0(G5xjIBkg*mgar8dl?2>(#mwgCLf6u_Q?2KQ*N}ioKasK+MwbOk$c3&Z~KIZ=mPa >> > >>>>> > >> zLC?i`823#_G-G7OIGO%Zt?-*4ASFD1bOllAd=>Z=)0y0vs(aX((aGyG^fp5mz!EEf >> > >>>>> > >> zF>d?iB8)~$oLa4x=o~?8D}fg;$+MVIVN%ak%xZb5y40sy{T31f2D7)Al2jElI=#fN >> > >>>>> > >> zx)0-4Uf!(2BHt@6HeOe~;Bhg-@+!)V3ysYAsLS76mS&4ywdoKN<Xkcj8vRSH?CpA^ >> > >>>>> > >> zZ9jN`nyu1e6#Y_3nzMKf^V7svbi+ln5P6Btmp3WERhY<Khny?~P8Zpg?wVm3cV*HP >> > >>>>> > >> zF7irVsHEod?fy`fjUhz9{Io}Ph2yS$vZyi)rbl*X|6+P8NG4lr_T`IRUN`;zBs<+} >> > >>>>> > >> zT&;Tegh9lXEM8H#WzrQ4k0`6-rOIZab@5GnK@r4wCG}xiH?WAEvh^2e8oA|8_7(DV >> > >>>>> > >> z5#{zDv#r_|AZFJ|X*X!oF;&=4Fo&EnWes7Xf5LE1ZL%z@!1el5uR?cCfVh?NTYPzB >> > >>>>> > >> zBcJE;-j0G%Ppbn+w^1fHs*r*cspp$f(G$WC(1olV7+1;iP|5mP^(0==$z0aQYE_N1 >> > >>>>> > >> zFJ;$W95c_yL552$#QpDU9PXBRRb|F>CNv1JuK7MGSR~?}M)kid{}5SM^TJ#tde-1^ >> > >>>>> > >> zqHAH7)P6A@4^IsHUVRggU`~aL0v88o>F0e|d~9In=Gaqy9!h71JGknx1kk5a>{LRn >> > >>>>> > >> zJ7WiSU7d^tmr_kniLBtPMh%Gv_z#>Ks~I~B1j#>TDETJt+oLT^>%d$VrsQ^(^G805 >> > >>>>> > >> zKs`qV`Q@O}XIF0R3S5rE1tG5KaRey<eev{=NU2n>D%~0XZj&qBhgXJ-OXdPjX%P#o >> > >>>>> > >> z=imy!?b@^Bdbyh91U3fS1-8WVR+)p~rF@V<{4{`?m9{iM{V>%%rk<_FJQmO&;nng$ >> > >>>>> > >> zrTh`()rUt!GGJ4Hs6_n$G;B|fguqa@K59S3=7BW#S1Y_73S6kJOv%g%BFORd1>Wru >> > >>>>> > >> z!u2w4OV|4}Q}I>YDXg!02-Nv(Wm^-*Y!s7WMx3ro>HuA`z}u}pb7Wlla_sN$xCfeh >> > >>>>> > >> z-W5g#<HDupfx1pwl$br>rF8z`UH#Tx?|Sq_6f-@-8m^0-NE}>f=?0ZSkg?(OfT*s& >> > >>>>> > >> zb{*dZs*0x%Ty1n#a>?cGHq3Fy=zNod!EhM~!B6L4R*B;U-8PoMFD@Qd*}L}J^ON5Q >> > >>>>> > >> z3}1fu1ADd?Xm4aDO1ti>l2Ox^PN%VDw89)IJsE-(Op<Ns5)e4989DV%{7NE$`Jm+0 >> > >>>>> > >> z(K4#==OJ^AIAuaz@=bhu!^+GR4DM`H(~oaRaYLLQS(zSQ!MLA~$1{y#A$MTpS)qZ& >> > >>>>> > >> z*0}KkoEc%u(+GK>9QVU9&yPO_e*?h!qR&iJt;nIH)t~yf8;2sQj@A-&iD=n^v7>7X >> > >>>>> > >> zc;w7TG_d4bWf^7^5ZGMr?sur<9VshcD!Ne3bXi7tV9IfIr74>H=iHEynQ_Er1O;1W >> > >>>>> > >> zk>I$rnyotFAW|IyP#dhiq{>i+Ye7KUVEDs=;cp-67Si*Csi1BoR2<J!o$-Q|gS5|L >> > >>>>> > >> z4+g%AHrzW;vt^H{v=5sKp*aU1il;Y*r$;Ia^Y}#fbHM2rGIS}|nrc>1Ne1U9ee<(e >> > >>>>> > >> z{&18JjB@`B48?@mEPm@A`T+R6^(hEDWx-U@F$ouS;wIldeGtiCDpz<px&I1cf~^od >> > >>>>> > >> zN%W~-ywM^`V#T5x`m;+xXUl^t?Y1c#oPFl|)POywWv3Ue1Rf=pkRD22iI#s?!(zJg >> > >>>>> > >> zALmv^$p~`W5H3@mm}crh;p#o{<J!5r$k%+Po@tx-*!o`2m(0u5XnMFxfV~6WdcQKs >> > >>>>> > >> z2!&cJ<gb+rKfCzGl@h)vL4`g#`Ci)o8TsPEJtNcvs`179wMRyppjGD=u9aiOl~V{M >> > >>>>> > >> z1?O`1{aMD1Zx%(YC&-OGQ@OP2irm@5yet7qtA^*i<cO_=*_S2{{+@r-<imD)W{g)( >> > >>>>> > >> z(I^dg!5C6}u}FmN5KJ(h+IyatbISifm}l$LOkVzs))VbdpHqIr*fe_s_)-392h0bK >> > >>>>> > >> z#q7l;k(AFoiVxgvb^SK2^sWs$7pVbI7Uhnl=+@%!=@OIUzb+6J<47Lc*8x6?Gup>j >> > >>>>> > >> zfdKa#|H%{VV1xHqm!f}G#o(t=TSQ#U=4JOAti>7GRvj)oi$!`#5kRe^uSsCFF}1s+ >> > >>>>> > >> zJO;GkMoocZc}bvxWu8aQ29|!{E@UXVi7X)9f{Brr!dd(}=7S_1aVRHtJd)rk(t1@V >> > >>>>> > On 3 July 2014 09:20, Taras Kondratiuk <taras.kondratiuk@linaro.org> wrote: > We should decide who is the main user/consumer of this arch document, > because they have different needs. > > - current developers (we) who are contributing/reviewing the document > will most probably prefer patches, because it is easier to follow > what is changing without need to read through a whole updated > document. > - New developers will read a whole document anyway so they don't care > much about history. > - SC need to get rendered document, maybe with highlighted changes. > > > On 07/03/2014 07:04 PM, Mike Holmes wrote: >> >> Can everyone please weigh in with their thoughts, we need consensus on >> this before we can make progress with the Arch doc. >> >> Thanks BIll / Mike >> >> >> On 3 July 2014 11:25, Anders Roxell <anders.roxell@linaro.org >> <mailto:anders.roxell@linaro.org>> wrote: >> >> On 2014-07-03 10:01, Bill Fischofer wrote: >> > The people who review and approve these docs want to see docs >> with things >> > like change bars, not patches. The patch mechanism is simply >> inappropriate >> > for this activity and we shouldn't try to force-fit it for >> something it's >> > not designed to address. >> > >> > Again, the primary users of the odp-architecture git repository >> are those >> > who want access to complete docs, not those who are creating, >> reviewing, >> > and approving them. That's why we have a separate repository >> from the main >> > odp git repository so that "patches" can be handled differently >> between >> > them. >> >> That is why we use doxygen so that people reviewing for approval can >> look >> at the end result... However, isn't it better if anyone on the list >> can >> review the patch and send patches when that is needed? >> >> SC approval should only be required for major revisions. >> Possibly only a final read through review for every ODP release. >> >> > >> > My preference would be to grant push rights to those adding items >> to this >> > repository rather than going through the artifice of patches. It >> would be >> > more straightforward and consistent with the actual workflow. >> Git would >> > still be doing version tracking so it would be possible to see >> the complete >> > change history for any given doc easily. >> >> We should use git as a revision control system as it is, to allow us >> to >> make small changes when we discover them. >> >> >> Cheers, >> Anders >> >> > >> > >> > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: >> > >> > > I agree we need approval, but approval can be of a review of >> the patch to >> > > the text. >> > > >> > > I hope we don't need wholesale changes that need a complete re >> write and >> > > thus approval of a whole new document. For example a new patch >> which may >> > > add a new function to an API but we would hopefully not change >> any of the >> > > existing text in the main. >> > > >> > > Thus we can then make changes in manageable chunks, I agree >> that large >> > > new additions will come in via a pre approved hugue patch, >> created from a >> > > sequence of sprints just have we have done so far. >> > > >> > > I would argue that these small changes are likely given the >> additions >> > > already discovered by starting the validation testing work and >> the feedback >> > > it is generating with the need to be more specific in >> architectural areas. >> > > >> > > Mike >> > > >> > > >> > > On 3 July 2014 10:44, Bill Fischofer <bill.fischofer@linaro.org >> <mailto:bill.fischofer@linaro.org>> wrote: >> > > >> > >> Design documents require approval by those who aren't going to >> be >> > >> reviewing patches. This is different from code. My >> understanding of the >> > >> purpose of the odp-architecture repository is to provide a >> convenient means >> > >> of distributing documentation and making it available in >> various forms >> > >> (Doxygen, PDF) for access through the ODP web site as well as >> being >> > >> downloaded. >> > >> >> > >> So in this sense we're just using Git as a publication >> mechanism for docs. >> > >> >> > >> >> > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> >> >> > >> wrote: >> > >> >> > >>> I am confused git is a change control mechanism, and I really >> hope they >> > >>> do get patched, how will we improve the content ? >> > >>> >> > >>> >> > >>> On 3 July 2014 10:03, Bill Fischofer >> <bill.fischofer@linaro.org <mailto:bill.fischofer@linaro.org>> wrote: >> > >>> >> > >>>> Git is a publication mechanism for docs, not a change control >> > >>>> mechanism. Docs will not be 'patched'. New versions will >> replace old ones >> > >>>> as they are approved. >> > >>>> >> > >>>> >> > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell >> <anders.roxell@linaro.org <mailto:anders.roxell@linaro.org> >> >> > >>>> > wrote: >> > >>>> >> > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: >> > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org >> <mailto:bill.fischofer@linaro.org>> >> >> > >>>>> > --- >> > >>>>> > crypto_design.dox | 455 >> > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ >> > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes >> > >>>>> > 2 files changed, 455 insertions(+) >> > >>>>> > create mode 100644 crypto_design.dox >> > >>>>> > create mode 100644 images/syncmodels.png >> > >>>>> > >> > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox >> > >>>>> > new file mode 100644 >> > >>>>> > index 0000000..1ad2ac6 >> > >>>>> > --- /dev/null >> > >>>>> > +++ b/crypto_design.dox >> > >>>>> > @@ -0,0 +1,455 @@ >> > >>>>> > +/* Copyright (c) 2043, Linaro Limited >> > >>>>> > + * All rights reserved >> > >>>>> > + * >> > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause >> > >>>>> > + */ >> > >>>>> > + >> > >>>>> > +/** >> > >>>>> > +@page crypto_design ODP Design - Crypto API >> > >>>>> > +For the implimentation of the ODP crypto API please see >> @ref >> > >>>>> odp_crypto.h >> > >>>>> > + >> > >>>>> > +@tableofcontents >> > >>>>> > + >> > >>>>> > +@section revision_history Revision History >> > >>>>> > +Revision | Issue Data | Description | Author >> > >>>>> > +---------|------------|-------------|-------- >> > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic >> Functions | >> > >>>>> Bill, Alexandru >> > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, >> started use >> > >>>>> cases, miscellaneous formatting, API comments | Bill >> > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to >> include results >> > >>>>> of design discussions held during ODP team calls | Bill >> > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto >> > >>>>> sprint--action to resolve | Bill >> > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review >> > >>>>> comments--ready for final review | Bill >> > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC >> approval | Bill >> > >>>>> > + >> > >>>>> > +@section introduction Introduction >> > >>>>> > +This document describes the ODP v1.0 Crypto API. >> Cryptography is an >> > >>>>> important part of data plane processing as many >> communication protocols >> > >>>>> make use of cryptographic functions. Moreover, many SoCs >> incorporate >> > >>>>> cryptographic hardware that can significantly accelerate >> these operations >> > >>>>> compared to their software equivalents as well as provide >> validated >> > >>>>> hardware functional correctness and security boundaries >> necessary for >> > >>>>> system-level security certifications such as FIPS-140 Level >> 2 and above. >> > >>>>> > +@section requirements Requirements >> > >>>>> > +@subsection use_of_terms Use of Terms >> > >>>>> > +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 [RFC 2119]( >> > >>>>> https://tools.ietf.org/html/rfc2119). >> > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography >> > >>>>> > +Crypto functions cover a range of uses and capabilities >> designed to >> > >>>>> support data security, integrity, authentication, and >> non-repudiation. >> > >>>>> > +@subsubsection data_security Data Security >> > >>>>> > +Cryptography supports data security by making use of >> complex >> > >>>>> mathematical transformations that are not feasibly >> reversible without >> > >>>>> possession of the secret key used to encrypt message data. >> > >>>>> > +@subsubsection data_integrity Data Integrity >> > >>>>> > +Cryptography supports data integrity through the use of >> > >>>>> cryptographic checksums (also known as secure hashes) that >> ensure the >> > >>>>> recipient that message data has not been altered either >> accidentally or >> > >>>>> maliciously while in transit. >> > >>>>> > +@subsubsection data_authentication Data Authentication >> > >>>>> > +Cryptography supports data authentication through the >> uses of >> > >>>>> Message Authentication Codes (MACs) that enable the >> recipient to verify >> > >>>>> that a message was sent from an authorized counterparty, >> and hence was not >> > >>>>> forged. >> > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation >> > >>>>> > +Cryptography supports data non-repudiation through the >> use of >> > >>>>> digital signatures that enable a recipient or third party >> to verify the >> > >>>>> identity of the sending party and prevents the sending >> party from later >> > >>>>> denying that they originated a signed message. >> > >>>>> > +@subsection scope Scope >> > >>>>> > +ODP v1.0 crypto support is designed to provide a >> portable framework >> > >>>>> for accessing SoC-specific cryptographic functions of most >> use to the data >> > >>>>> plane. This is predominantly symmetric crypto operations >> used to support >> > >>>>> the encryption and decryption of data at line rate using >> hardware >> > >>>>> acceleration and offload. Specifically excluded in this >> support are public >> > >>>>> key operations and other crypto functions mainly used in >> the control plane. >> > >>>>> > +@subsection cryptographic_operations_in_the_data_plane >> > >>>>> Cryptographic Operations in the Data Plane >> > >>>>> > +ODP v1.0 crypto APIs cover the following areas: >> > >>>>> > +@subsubsection ciphering Ciphering >> > >>>>> > +Ciphering refers to mathematical transformations that >> use a secret >> > >>>>> key to encipher data, transforming the original data >> (referred to as >> > >>>>> plaintext) into ciphertext, thereby making it >> unintelligible to anyone not >> > >>>>> in possession of the key. Similarly, ciphering is also used >> to decipher >> > >>>>> data, allowing someone in possession of the correct key to >> transform >> > >>>>> received ciphertext back into plaintext. Approved block >> ciphers are listed >> > >>>>> >> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and >> > >>>>> SHOULD be supported by each ODP implementation. >> > >>>>> > +@subsubsection hasing Hashing >> > >>>>> > +A hash is a cryptographic digest of a message that can >> be used to >> > >>>>> represent it for comparison or integrity checking. Hash >> functions are >> > >>>>> designed so that any alteration of a message will alter the >> hash and that >> > >>>>> it is computationally infeasible to craft a message that >> generates the same >> > >>>>> hash value as another message. Secure hash functions >> approved for >> > >>>>> cryptographic use are listed by NIST [here]( >> > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) >> and >> > >>>>> SHOULD be supported by each ODP implementation. >> > >>>>> > +@subsubsection zeroization Zeroization >> > >>>>> > +To preserve the security of data, certain transient data >> held in >> > >>>>> data buffers MUST be cleared to zeros upon buffer free. >> Such capability is >> > >>>>> referred to as zeroization. ODP supports zeroization as a >> buffer pool >> > >>>>> attribute. >> > >>>>> > +@subsubsection random_number_generation Random Number >> Generation >> > >>>>> > +Because cryptography relies heavily on “unguessable” keys >> of >> > >>>>> various sorts, random number generation (RNG) is an >> integral part of >> > >>>>> cryptographic processing. Random numbers are used in key >> generation, >> > >>>>> initialization vectors (IVs), various types of padding >> bytes, and various >> > >>>>> other uses collectively referred to as nonces, that serve >> to “harden” >> > >>>>> cryptographic processing. >> > >>>>> > + >> > >>>>> > +There are two types of random number support of >> interest. Hardware >> > >>>>> random data, also known as entropy, that is the result of >> inherently random >> > >>>>> physical processes, and deterministic random bit generation >> (DRBG) that is >> > >>>>> used in certain certified cryptographic operations. >> Approved DRBG >> > >>>>> algorithms are listed in [NIST SP 800-90A]( >> > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does >> not >> > >>>>> specify which algorithms are available on a given >> implementation. As such >> > >>>>> ODP implementations MAY use any approved DRGB algorithm but >> SHOULD support >> > >>>>> at least one of them. Additionally, ODP implementations >> MUST NOT represent >> > >>>>> non-approved algorithms as DRBG implementations. Validated >> algorithms are >> > >>>>> listed in the [NIST DRBG Validation List]( >> > >>>>> >> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). >> > >>>>> > + >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry >> > >>>>> > +To enable applications to adapt to the implementation >> models >> > >>>>> offered across different SoC platforms, ODP provides APIs >> to allow >> > >>>>> applications to inquire about underlying crypto >> capabilities. A given ODP >> > >>>>> implementation may offer crypto as hardware features, >> software features, or >> > >>>>> not available on a given platform. >> > >>>>> > +@subsection cryptographic_algorithms Cryptographic >> Algorithms and >> > >>>>> Protocols >> > >>>>> > +A cryptographic algorithm is a mathematical transform >> that provides >> > >>>>> one of the cryptographic operations described above. They >> in turn are used >> > >>>>> as building blocks in creating cryptographic protocols. >> These are complete >> > >>>>> sets of rules for how to exchange data securely using >> cryptography. Both >> > >>>>> cryptographic algorithm and protocol design are highly >> specialized >> > >>>>> disciplines that involve high levels of public scrutiny and >> validation. As >> > >>>>> a result, applications simply make use of approved >> cryptographic algorithms >> > >>>>> and protocols. >> > >>>>> > +@subsection cryptographic_operations Cryptographic >> Operations >> > >>>>> > +Cryptographic operations may be initiated by software or >> directly >> > >>>>> by hardware as part of the RX or TX packet path processing. >> For ODP v1.0 >> > >>>>> software-initiated cryptographic operations are the primary >> use case. ODP >> > >>>>> provides APIs for performing data ciphering, hashing, >> random number >> > >>>>> generation, and capability inquiry. >> > >>>>> > +@subsection performance_expectations Performance >> Expectations >> > >>>>> > +In the data plane, the total processing budget for a >> packet may >> > >>>>> only be a few hundred cycles, so function invocation >> overhead MUST be kept >> > >>>>> to a minimum. This has several implications. >> > >>>>> > + >> > >>>>> > +-# When work is dispatched to a thread, all information >> needed by >> > >>>>> the thread to process the work request SHOULD be >> immediately at hand. >> > >>>>> Ideally any context or variables needed for the operation >> have been >> > >>>>> pre-warmed in the cache to avoid the latency hits >> associated with cache >> > >>>>> misses. SoCs having hardware schedulers generally do this >> pre-staging of >> > >>>>> data to minimize such latencies, and ODP implementations >> are expected to >> > >>>>> exploit such platform capabilities whenever possible.\n\n >> > >>>>> > + >> > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive >> amounts of >> > >>>>> parameter passing and (depending on the implementation) >> SHOULD be inlined >> > >>>>> as much as possible to avoid call overhead. One technique >> that has proven >> > >>>>> useful is to allow for parameters to be passed as an >> explicit thread-local >> > >>>>> static structure. Such use of “templating” means that a >> single function can >> > >>>>> support a rich set of options but the caller can configure >> a template >> > >>>>> matched to specific use and only vary the one or two >> parameters that differ >> > >>>>> from call to call.\n\n >> > >>>>> > + >> > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any >> > >>>>> non-exception path function processing. Kernel calls and >> such are >> > >>>>> acceptable only during one-time initialization logic or >> certain types of >> > >>>>> unusual error recovery operations. Often the best way to >> handle the latter >> > >>>>> is to pass the work to a dedicated recovery thread (or back >> to the control >> > >>>>> plane) rather than attempting to handle the condition >> inline. For example, >> > >>>>> a link-down condition will trigger various recovery actions >> that might best >> > >>>>> be handled in this manner. >> > >>>>> > + >> > >>>>> > +@subsection use_by_existing_code Use by Existing Code >> > >>>>> > +Most applications wishing to make use of ODP represent >> substantial >> > >>>>> existing investment that must be preserved. Insofar as >> possible, ODP >> > >>>>> functions need to be orthogonal to existing application >> environments and >> > >>>>> structures to permit easy intermixing with pre-existing code. >> > >>>>> > +@subsection data_references Data References >> > >>>>> > +Packet data is inherently of variable length however it >> is often >> > >>>>> more efficient to organize memory into fixed-sized buffers >> that can be >> > >>>>> chained together on demand to contain packets. The >> application SHOULD >> > >>>>> normally not need to be aware of such lower-level >> segmentation and should >> > >>>>> be able to treat a packet as a single object. Alternately, >> especially when >> > >>>>> dealing with existing code, data segmentation MUST be >> explicitly >> > >>>>> specifiable via scatter/gather lists. For example, data >> encryption or >> > >>>>> decryption may be invoked on a list of data segments as >> part of a single >> > >>>>> function call. >> > >>>>> >> > >>>>> Every time you add a full stop for a sentence, you have to >> press return >> > >>>>> and start typing the next sentence. >> > >>>>> This means that diffs of future changes will be per sentence. >> > >>>>> Doxygen will still concatenate this as a paragraph with no >> visual >> > >>>>> difference in the result. >> > >>>>> I think the above line will look like this: >> > >>>>> >> > >>>>> Packet data is inherently of variable length however it is >> often more >> > >>>>> efficient to organize memory into fixed-sized buffers that >> can be chained >> > >>>>> together on demand to contain packets. >> > >>>>> The application SHOULD normally not need to be aware of such >> > >>>>> lower-level segmentation and should be able to treat a >> packet as a single >> > >>>>> object. >> > >>>>> Alternately, especially when dealing with existing code, data >> > >>>>> segmentation MUST be explicitly specifiable via >> scatter/gather lists. >> > >>>>> For example, data encryption or decryption may be invoked >> on a list of >> > >>>>> data segments as part of a single function call. >> > >>>>> >> > >>>>> >> > >>>>> Cheers, >> > >>>>> Anders >> > >>>>> >> > >>>>> > +@subsection chained_operations Chained Operations >> > >>>>> > +Crypto operations such as hashing and encryption, or >> decryption and >> > >>>>> verification, are very commonly used in combination. For >> ODP, it is >> > >>>>> sufficient to support one cipher and one >> hash/authentication operation in a >> > >>>>> single call and this combination MUST be supported to avoid >> the call and >> > >>>>> dispatch overhead of separate invocations. >> > >>>>> > +@subsection key_management Key Management and Session Data >> > >>>>> > +Keying is an area of particular sensitivity in crypto >> processing >> > >>>>> since keys are highly confidential and may be subject to >> legal requirements >> > >>>>> for safeguarding within special hardware enclosures. >> > >>>>> > + >> > >>>>> > +A session is the security context used to represent an >> active set >> > >>>>> of crypto operations that need to be applied to a flow on a >> > >>>>> packet-by-packet basis. Generally a session is established >> upon detection >> > >>>>> of a flow requiring crypto processing and retained for the >> life of that >> > >>>>> flow. It has been noted that this can involve cooperative >> processing >> > >>>>> between the control and data planes so several requirements >> stem from this: >> > >>>>> > + >> > >>>>> > +-# Session creation MAY need to be handled in an >> asynchronous >> > >>>>> manner. This is to allow these to be created in batches by >> thread(s) that >> > >>>>> specialize in this activity.\n\n >> > >>>>> > + >> > >>>>> > +-# Sessions MAY need to reference keying material >> indirectly via >> > >>>>> key handling modules.\n\n >> > >>>>> > + >> > >>>>> > +-# Session creation MAY be performed by non-ODP code and >> > >>>>> communicated to data plane routines that make use of ODP >> crypto functions >> > >>>>> that need to reference the session information. >> > >>>>> > + >> > >>>>> > +ODP session APIs and data structures SHOULD be >> represented by >> > >>>>> abstract data types that encapsulate implementation details >> for both >> > >>>>> platform efficiency and to accommodate these needs. >> > >>>>> > +Use Cases >> > >>>>> > +For ODP v1.0 the major use cases of interest involve >> cryptographic >> > >>>>> algorithm acceleration. Cryptographic protocol acceleration >> is reserved for >> > >>>>> future ODP releases. >> > >>>>> > +Buffers and Data Blocks >> > >>>>> > +Cryptographic operations may be performed directly on data >> > >>>>> contained in ODP packet buffers, or it may be performed on >> “raw” data >> > >>>>> blocks operating entirely under application control. Note >> that when using >> > >>>>> raw data blocks not managed by ODP, the application must >> perform any needed >> > >>>>> zeroization using either its own or ODP-supplied buffer >> zeroization >> > >>>>> functions. ODP automatic support for zeroization is limited >> to ODP-managed >> > >>>>> buffers. ODP buffers allocated from buffer pools designated >> for crypto use >> > >>>>> will also have whatever alignment and/or addressability >> attributes needed >> > >>>>> by the implementation to support crypto API calls. >> > >>>>> > + >> > >>>>> > +Note: Some implementations may have difficulty dealing >> with >> > >>>>> application buffer addresses, as these may be virtual >> addresses that are >> > >>>>> mapped discontiguously into physical memory. For such >> implementations, >> > >>>>> memory SHOULD be allocated contiguously and MAY need to be >> “registered” to >> > >>>>> have proper addressability for crypto operations. This area >> of the design >> > >>>>> will be updated based on experience in dealing with >> different crypto >> > >>>>> implementations that have such requirements. >> > >>>>> > +Synchronization >> > >>>>> > +ODP operations fall into one of three categories: >> > >>>>> > + >> > >>>>> > +-# Inline (Synchronous): Upon return from a call the >> operation is >> > >>>>> complete. Operation is thus completely synchronous to the >> caller. Inline >> > >>>>> is the appropriate model when the invoked function takes >> relatively few >> > >>>>> cycles or when the caller cannot feasibly progress without >> the results of >> > >>>>> the invoked function.\n\n >> > >>>>> > + >> > >>>>> > +-# Parallel: Upon return from a call the operation has >> been >> > >>>>> initiated, but is expected to complete shortly. The caller >> continues to >> > >>>>> execute until it needs the result at which point it waits >> to complete the >> > >>>>> parallel operation. The effect is as if the operation were >> inline except >> > >>>>> that the caller was able to execute in parallel with the >> operation for some >> > >>>>> application-determined period of time. Parallel is the >> appropriate model >> > >>>>> when the operation being performed is relatively short (a >> few dozen up to >> > >>>>> perhaps 100 or 200 cycles) and the caller can usefully >> accomplish other >> > >>>>> processing on the same unit of work while the parallel >> operation is in >> > >>>>> progress, but not enough to justify the overhead of a >> formal queued work >> > >>>>> dispatch.\n\n >> > >>>>> > + >> > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call the >> > >>>>> operation has been queued for execution. A completion event >> will be queued >> > >>>>> back to the scheduler when the event is completed. Offload >> is the >> > >>>>> appropriate model when the invoked function will take a >> substantial amount >> > >>>>> of cycles (thousands to tens of thousands) allowing the >> invoking >> > >>>>> thread/core to service other work until the operation >> completes. For >> > >>>>> offloaded work, completion is indicated by a completion >> event being posted >> > >>>>> back to an application-designated completion queue. Upon >> receipt the unit >> > >>>>> of work that initiated the offloaded operation continues >> processing with >> > >>>>> the results of the call. >> > >>>>> > + >> > >>>>> > +The synchronization models of interest are summarized in >> Figure 1: >> > >>>>> > + >> > >>>>> > + >> > >>>>> > + >> > >>>>> > +Note: Because few implementations are expected to offer >> the >> > >>>>> Parallel mode of operation as described above, this mode >> is reserved for >> > >>>>> potential future use. For ODP v1.0 only synchronous and >> asynchronous crypto >> > >>>>> operations are defined. >> > >>>>> > +@section functional_definition Functional Definition >> > >>>>> > +@subsection abstract_data_types Abstract data types >> > >>>>> > +The following enumerations define various algorithms >> used for >> > >>>>> ciphering and hashing. These are the basic operations >> applied to input data. >> > >>>>> > + >> > >>>>> > +A particular ODP implementation should map these values >> to the >> > >>>>> actual information to be passed to the crypto engine. As >> such, the actual >> > >>>>> values of these enums is implementation-defined. >> > >>>>> > + >> > >>>>> > +Cipher algorithm encoding specifies the algorithm and >> cipher mode >> > >>>>> employed (as per security relevant RFCs - [4305]( >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( >> > >>>>> http://tools.ietf.org/html/rfc4494)). >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +enum odp_cipher_alg { >> > >>>>> > + ODP_CIPHER_ALG_NULL, >> > >>>>> > + ODP_CIPHER_ALG_DES, >> > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, >> > >>>>> > + ODP_CIPHER_ALG_AES_CBC, >> > >>>>> > + ODP_CIPHER_ALG_AES_GCM, >> > >>>>> > + ODP_CIPHER_ALG_AES_CTR, >> > >>>>> > + ODP_CIPHER_ALG_KASUMI, >> > >>>>> > + ODP_CIPHER_ALG_SNOW, >> > >>>>> > + ... >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Authorization algorithm encoding specifies the algorithm >> and the >> > >>>>> length of the authorization used (as per security relevant >> RFCs - [4305]( >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( >> > >>>>> http://tools.ietf.org/html/rfc4494)): >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +enum odp_auth_alg { >> > >>>>> > + ODP_AUTH_ALG_NULL, >> > >>>>> > + ODP_AUTH_MD5_96, >> > >>>>> > + ODP_AUTH_ALG_SHA1_96, >> > >>>>> > + ODP_AUTH_ALG_SHA1_160 >> > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, >> > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, >> > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, >> > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, >> > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, >> > >>>>> > + ODP_AUTH_ALG_SNOW, >> > >>>>> > + ODP_AUTH_ALG_KASUMI, >> > >>>>> > + ... >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +typedef union odp_crypto_alg_t { >> > >>>>> > + enum odp_cipher_alg cipher; >> > >>>>> > + enum odp_auth_alg auth; >> > >>>>> > +}odp_crypto_alg_t; >> > >>>>> > +@endcode >> > >>>>> > +@subsection parameter_structures Parameter Structures >> > >>>>> > +@subsubsection crypto_sessions Crypto Sessions >> > >>>>> > +The following structure describes a crypto session. All >> packets / >> > >>>>> raw data buffers processed in a session share the data that >> defines the >> > >>>>> session. A crypto session is defined by: >> > >>>>> > + >> > >>>>> > +- Operation type : encode or decode\n\n >> > >>>>> > + >> > >>>>> > +- Algorithms specifications, keys and , if required, >> initialization >> > >>>>> vectors. When initialization vectors are not provided and >> they should be >> > >>>>> provided automatically by the crypto engine.\n\n >> > >>>>> > + >> > >>>>> > +- The operation mode: synchronous or asynchronous. >> Synchronous >> > >>>>> operation blocks the caller until an operation status and >> result are >> > >>>>> available. In synchronous mode there is at most only one >> outstanding crypto >> > >>>>> operation in the calling thread. In asynchronous mode, the >> caller starts >> > >>>>> the crypto operation and later it may receive the status >> and the result >> > >>>>> together with a request context. The operation status and >> result may also >> > >>>>> be received by a different thread.\n\n >> > >>>>> > + >> > >>>>> > +- Operation mode parameters: For asynchronous operation a >> > >>>>> completion event containing the status, the result and the >> request context >> > >>>>> is enqueued to a completion queue. In case the queue is >> under the scheduler >> > >>>>> control, the scheduler determines who will receive the >> completion event and >> > >>>>> when. When the completion queue is not scheduled, the >> thread which is >> > >>>>> supposed to get the operation output has to explicitly poll >> the completion >> > >>>>> queue. >> > >>>>> > + >> > >>>>> > +Note that this is an abstract data type and its structure >> is >> > >>>>> implementation-specific. The layout shown here is for >> illustrative purposes >> > >>>>> and the actual layout will vary from one implementation to >> the next to most >> > >>>>> closely align with the structures needed by the underlying >> SoC platform. >> > >>>>> Applications set and reference fields in the session >> structure via accessor >> > >>>>> functions that hide the actual layout. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +typedef enum odp_crypto_op_t { >> > >>>>> > + ODP_CRYPTO_OP_ENCODE, >> > >>>>> > + ODP_CRYPTO_OP_DECODE >> > >>>>> > +}odp_crypto_op_t; >> > >>>>> > + >> > >>>>> > +typedef struct odp_key_t { >> > >>>>> > +}odp_key_t; >> > >>>>> > + >> > >>>>> > +typedef struct odp_crypto_session_t { >> > >>>>> > + odp_crypto_op_t op; >> > >>>>> > + struct { >> > >>>>> > + enum odp_cipher_alg cipher_alg; >> > >>>>> > + odp_key_t *key; >> > >>>>> > + uint8_t *iv; >> > >>>>> > + size_t iv_len; >> > >>>>> > + } cipher; >> > >>>>> > + >> > >>>>> > + struct { >> > >>>>> > + enum odp_auth_alg auth_alg; >> > >>>>> > + enum odp_auth_len auth_len; >> > >>>>> > + odp_key_t *key; >> > >>>>> > + } auth; >> > >>>>> > + >> > >>>>> > + enum odp_crypto_op_mode { >> > >>>>> > + ODP_CRYPTO_SYNC, >> > >>>>> > + ODP_CRYPTO_ASYNC, >> > >>>>> > + } op_mode; >> > >>>>> > + >> > >>>>> > + struct { >> > >>>>> > + uint32_t timeout; >> > >>>>> > + struct { >> > >>>>> > + odp_queue_t completion_queue; >> > >>>>> > + } async; >> > >>>>> > + } op_mode_params; >> > >>>>> > + >> > >>>>> > + odp_session_proc_info_t session_proc_info; >> > >>>>> > +} odp_crxsypto_session_t; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +The completion queue contained in the session structure >> is an >> > >>>>> in/out parameter. If provided, then the queue specified is >> associated with >> > >>>>> the session and is used to ensure order preservation on >> that session. If >> > >>>>> not provided, one is created and returned to the caller. >> Note that this >> > >>>>> completion queue is used to order operations performed on >> this crypto >> > >>>>> session. It should not be confused with the completion >> queue specified on >> > >>>>> the odp_crypto_session_create() call (see below) that is >> used to control >> > >>>>> whether that call is itself processed in a synchronous vs. >> asynchronous >> > >>>>> manner. >> > >>>>> > + >> > >>>>> > +The following structure comprises processing >> information. This is >> > >>>>> logically divided in two parts: >> > >>>>> > + >> > >>>>> > +- Processing input info - When crypto engine provides >> support for >> > >>>>> protocol processing, this information is provided in a >> higher level common >> > >>>>> protocol terminology form and a particular implementation >> should be able to >> > >>>>> derive everything it needs from this definition. In >> addition, for crypto >> > >>>>> engines able to automate tasks like memory allocation for >> the output a >> > >>>>> buffer pool id may be specified.\n\n >> > >>>>> > + >> > >>>>> > +- Processing output information - statistics about >> processed >> > >>>>> bytes/packets. These are useful when a session expiration >> is based on >> > >>>>> traffic volume. These statistics may be updated by the >> software or by the >> > >>>>> hardware crypto engine. >> > >>>>> > + >> > >>>>> > +Again, this is an abstract type whose specific layout >> will vary >> > >>>>> based on implementation considerations. Access to fields >> contained in the >> > >>>>> structure is only via accessor functions. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +typedef struct { >> > >>>>> > + uint64_t pkts_processed; >> > >>>>> > + uint64_t bytes_processed; >> > >>>>> > + uint64_t pkts_errored; >> > >>>>> > + uint64_t bytes_errored; >> > >>>>> > + >> > >>>>> > + odp_buffer_pool_t out_pool; >> > >>>>> > + >> > >>>>> > +} odp_session_proc_info_t; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +This enumeration defines which operations are applied >> and the order. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +enum odp_crypto_combination { >> > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, >> > >>>>> > + ODP_CRYPTO_AUTH_ONLY, >> > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +This structure defines a contiguous segment in the input >> data which >> > >>>>> starts at offset offset and is len bytes long. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +struct odp_data_range { >> > >>>>> > + unsigned offset:16; >> > >>>>> > + unsigned len:16; >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +@subsection api_functions API Functions >> > >>>>> > + >> > >>>>> > +@subsubfunction Session Creation >> > >>>>> > + >> > >>>>> > +This function is used to create a crypto session. The >> required >> > >>>>> parameters are : >> > >>>>> > + >> > >>>>> > +- Operation : encode/decode >> > >>>>> > +- Processing info : cipher/auth/both >> > >>>>> > +- Preferred mode : sync or async. >> > >>>>> > +- Algorithms suites, keys and optional IV >> > >>>>> > + >> > >>>>> > +Session creation can be synchronous or asynchronous. >> Completion >> > >>>>> event argument is used to return the status and the session >> handle. When >> > >>>>> completion queue is not provided (synchronous call), the >> completion event >> > >>>>> is available upon function call return. When completion >> queue is provided >> > >>>>> (asynchronous call), the completion event is placed on the >> completion queue. >> > >>>>> > + >> > >>>>> > +@code >> > >>>>> > +typedef uint64_t odp_crypto_session_t; >> > >>>>> > + >> > >>>>> > +struct odp_session_params { >> > >>>>> > + enum odp_crypto_operation op; >> > >>>>> > + odp_session_proc_info_t proc_info; >> > >>>>> > + enum odp_crypto_op_mode pref_mode; >> > >>>>> > + enum odp_cipher_alg cipher_alg; >> > >>>>> > + odp_key_t *cipher_key; >> > >>>>> > + uint8_t *iv; >> > >>>>> > + size_t iv_len; >> > >>>>> > + enum odp_auth_alg auth_alg; >> > >>>>> > + odp_key_t *auth_key; >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +enum odp_crypto_ses_create_err { >> > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, >> > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, >> > >>>>> > + /* Session creation error codes */ >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +void >> > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t >> > >>>>> completion_event, enum odp_crypto_ses_create_err *status); >> > >>>>> > + >> > >>>>> > +void >> > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t >> > >>>>> completion_event, odp_crypto_session_t *handle); >> > >>>>> > + >> > >>>>> > +int odp_crypto_session_create( >> > >>>>> > + struct odp_session_params *params, >> > >>>>> > + odp_buffer_t completion_event, >> > >>>>> > + odp_queue_t completion_queue); >> > >>>>> > +@endcode >> > >>>>> > +@subsection crypto_operation Crypto Operation >> > >>>>> > + >> > >>>>> > +Crypto operations are described by a parameter structure: >> > >>>>> > +@code >> > >>>>> > +struct odp_crypto_op_params { >> > >>>>> > + odp_crypto_session_t session; >> > >>>>> > + odp_packet_t pkt; >> > >>>>> > + odp_packet_t out_pkt; >> > >>>>> > + uint8_t *override_iv_ptr; >> > >>>>> > + unsigned hash_result_offset; >> > >>>>> > + struct odp_data_range cipher_range; >> > >>>>> > + struct odp_data_range auth_range; >> > >>>>> > +}; >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +<table> >> > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> >> > >>>>> > +<tr><td>session</td><td>Session to perform the >> operation</td></tr> >> > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be >> processed</td></tr> >> > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / >> buffer to be >> > >>>>> returned as the result of the operation. There are three >> different ways >> > >>>>> this parameter is used, depending on the mode of operation >> requested by the >> > >>>>> caller and the capabilities of the underlying >> implementation:\n\n >> > >>>>> > + >> > >>>>> > +-# If out_pkt is the same as pkt this indicates that the >> operation >> > >>>>> should be performed in place.\n\n >> > >>>>> > +-# If out_pkt is different from pkt this indicates that >> output >> > >>>>> should be placed in the buffer supplied by the caller.\n\n >> > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied >> on input) >> > >>>>> this indicates that an output buffer should be allocated by >> the operation >> > >>>>> and returned as part of the completion event associated >> with the >> > >>>>> operation.\n\n >> > >>>>> > + >> > >>>>> > +Note that not every implementation will support all of >> these modes >> > >>>>> and MAY require that one mode be used in preference to >> others. Any such >> > >>>>> implementation restrictions are communicated as output from >> session >> > >>>>> creation.</td></tr> >> > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for >> this >> > >>>>> request</td></tr> >> > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the >> output packet >> > >>>>> where the hash result should be stored.</td></tr> >> > >>>>> > +<tr><td>cipher_range</td><td>The byte range >> (offset:length) of the >> > >>>>> data to be processed for ciphering.</td></tr> >> > >>>>> > +<tr><td>auth_range</td><td>The byte range >> (offset:length) of the >> > >>>>> data to be processed for authentication.</td></tr> >> > >>>>> > +</table> >> > >>>>> > + >> > >>>>> > +The crypto operation is initiated with a single call >> that passes >> > >>>>> the parameters for the operation and an event (for >> asynchronous completion). >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_operation( >> > >>>>> > + struct odp_crypto_op_params *params, >> > >>>>> > + odp_buffer_t completion_event); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Parameter | Meaning >> > >>>>> > +----------|-------- >> > >>>>> > +params | The parameter structure describing the >> crypto operation >> > >>>>> to be performed. >> > >>>>> > +completion_event | The event delivered on completion. It >> provides >> > >>>>> information about the status of the operation, result and >> request context. >> > >>>>> In synchronous mode the event is available upon function >> call return. In >> > >>>>> asynchronous mode, the event is placed on the session / >> operation >> > >>>>> completion queue when the operation finished. >> > >>>>> > + >> > >>>>> > +Upon return the return code indicates whether the >> operation was >> > >>>>> synchronous or asynchronous, or if an error occurred that >> prevented the >> > >>>>> operation from being performed. >> > >>>>> > + >> > >>>>> > +Get session operation : >> > >>>>> > +@code >> > >>>>> > +odp_crypto_op_t >> > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Get session cipher information : >> > >>>>> > +@code >> > >>>>> > +odp_cipher_alg >> > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t >> ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Get session authentication information : >> > >>>>> > +@code >> > >>>>> > +odp_auth_alg >> > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Change session IV : >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, >> uint8_t >> > >>>>> *iv); >> > >>>>> > +@emdcode >> > >>>>> > + >> > >>>>> > +Change cipher or/and hash keys: >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, >> odp_key_t >> > >>>>> *key); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Destroy crypto session. All pending operations are >> cancelled. >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t ses); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Get completion event information - algorithm error, >> output and >> > >>>>> context. Note that implementations MAY define their own >> specific error >> > >>>>> codes that have meaning in that context. For application >> portability it is >> > >>>>> sufficient to know whether an operation completed >> successfully or >> > >>>>> experienced an error of some sort. >> > >>>>> > +@code >> > >>>>> > +enum crypto_alg_err { >> > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, >> > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +enum crypto_hw_err { >> > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, >> > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, >> > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +struct odp_crypto_compl_status { >> > >>>>> > + odp_crypto_alg_t alg; >> > >>>>> > + enum crypto_alg_err alg_err; >> > >>>>> > + enum crypto_hw_err hw_err; >> > >>>>> > +}; >> > >>>>> > + >> > >>>>> > +void >> > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t completion_event, >> > >>>>> > + struct odp_crypto_compl_status >> *auth, >> > >>>>> > + struct odp_crypto_compl_status >> *cipher); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Returns the output packet handle associated with the >> completion >> > >>>>> event : >> > >>>>> > +@code >> > >>>>> > +odp_packet_t >> > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Sets a context handle to be returned with the completion >> event : >> > >>>>> > +@code >> > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t >> completion_event, >> > >>>>> odp_compl_ctx_t *ctx); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Returns the context associated with the completion event : >> > >>>>> > +@code >> > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t >> > >>>>> completion_event); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +This section describes the API/Interface being defined at >> a >> > >>>>> functional level in technical detail. Sub-sections include >> header file >> > >>>>> names, where implementation files are expected to reside in >> the ODP git >> > >>>>> tree, as well as the name, parameters, abstract data types, >> functionality, >> > >>>>> return codes, and exception conditions of each function >> call defined by the >> > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be >> used to allow >> > >>>>> the programmer tasked with implementing the API/Interface >> to understand the >> > >>>>> function to be implemented as well as error conditions, >> corner cases, >> > >>>>> performance requirements, etc. needed to implement the >> described >> > >>>>> API/Interface in a functionally correct and efficient manner. >> > >>>>> > + >> > >>>>> > +@subsubsection random_number_functions Random Number >> Functions >> > >>>>> > +As noted earlier, random number support consists of two >> functions: >> > >>>>> > +@code >> > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool >> > >>>>> use_entropy); >> > >>>>> > + >> > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +The difference is that the first provides access to >> hardware random >> > >>>>> number functions that return true random data. This is >> typically used for >> > >>>>> seed values. The second provides a deterministic random bit >> generator >> > >>>>> conforming to NIST standards and is used by various crypto >> protocols and >> > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get >> is used to >> > >>>>> disable any hardware pre-processing normally provided by >> the function and >> > >>>>> is mainly intended to be used for testing/validation >> purposes. >> > >>>>> > + >> > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool >> Extensions >> > >>>>> > +To support zeroization a buffer may be allocated with an >> > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer >> should be >> > >>>>> zeroized upon free. Alternately, a new type >> (ODP_CLEAR_ON_FREE) is added to >> > >>>>> odp_buffer_pool_create() that specifies that all buffers >> allocated from >> > >>>>> this pool must be zeroized upon free. Essentially, the >> buffer security >> > >>>>> attribute is set by default from the attributes of the >> buffer pool that it >> > >>>>> is allocated from. >> > >>>>> > + >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry >> > >>>>> > +To enable applications to determine crypto capabilities. >> > >>>>> > +@code >> > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum >> odp_auth_alg); >> > >>>>> > +@endcode >> > >>>>> > + >> > >>>>> > +Inquires whether the specified crypto and auth >> algorithms are >> > >>>>> supported. Responses include: >> > >>>>> > +- ODP_HW_SYNC_SUPPORT >> > >>>>> > +- ODP_HW_ASYNC_SUPPORT >> > >>>>> > +- ODP_SW_SYNC_SUPPORT >> > >>>>> > +- ODP_SW_ASYNC_SUPPORT >> > >>>>> > +- ODP_NO_SUPPORT >> > >>>>> > + >> > >>>>> > +HW support means the combination is supported in >> hardware, SW >> > >>>>> support means the combination is supported in software by the >> > >>>>> implementation. No support means the combination is not >> supported by the >> > >>>>> implementation. The SYNC and ASYNC return options can help >> the application >> > >>>>> decide how to invoke these functions, or it can just check >> whether or not >> > >>>>> the response is ODP_NO_SUPPORT. >> > >>>>> > + >> > >>>>> > +@section implementation_considerations Implementation >> Considerations >> > >>>>> > +One of the main purposes for the ODP crypto APIs is to >> provide >> > >>>>> portable access across different SoCs whose hardware crypto >> capabilities >> > >>>>> largely overlap but vary in terms of their implementation >> details. As a >> > >>>>> result, implementations need not provide software fill-ins >> for specific >> > >>>>> cryptographic features that are not available as hardware >> features on that >> > >>>>> platform. Presumably applications needing specific features >> will select >> > >>>>> platforms on which these features are present. Therefore, >> while all APIs >> > >>>>> specified here MUST exist in each conforming ODP >> implementation, it is >> > >>>>> acceptable for these APIs to return >> ODP_RC_FEATURE_NOT_PRESENT in response >> > >>>>> to calls requesting crypto features not present on that >> platform. >> > >>>>> > + >> > >>>>> > +For example, the linux-generic ODP implementation may only >> > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and >> return a feature >> > >>>>> not present error code for any other cipher. This >> indication will also be >> > >>>>> returned on that platform in response to odp_crypto_inquire >> calls for >> > >>>>> non-null cipher algorithms. >> > >>>>> > + >> > >>>>> > +@section verification Verification/Testing >> > >>>>> > +This section describes the verification/test cases >> needed to ensure >> > >>>>> that the defined functionality is implemented correctly and >> performs >> > >>>>> adequately. This should be at a level of detail such that >> the programmer >> > >>>>> tasked with writing test scripts/programs to verify the >> implementation(s) >> > >>>>> of the defined functions can be written to ensure that all >> relevant >> > >>>>> functional variants and error/exception cases are properly >> tested. >> > >>>>> > + >> > >>>>> > +This section needs to be completed before API testing >> begins. >> > >>>>> > + >> > >>>>> > +*/ >> > >>>>> > \ No newline at end of file >> > >>>>> > diff --git a/images/syncmodels.png b/images/syncmodels.png >> > >>>>> > new file mode 100644 >> > >>>>> > index >> > >>>>> >> >> 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 >> > >>>>> > GIT binary patch >> > >>>>> > literal 17179 >> > >>>>> > >> zcmch;XH?Tcv@Z$>iXhSqNDxrER8c~aDjh?WUL(Et-Vx~th$xXJz4smxnsljBLkDS* >> > >>>>> > >> z-U&T7c+PqEth3g=pWb`(A^(+`Ju`dSo?U(urKTcJLIfnj!NDO>RFHXxgM;UcgM-UP >> > >>>>> > >> zco&=V+&Rz%2S;jIQRa=N_smYZm=g1R%A)G;H}~-I@#)CiCI2J+roi>GZf!`WZf2C^ >> > >>>>> > >> z)RvpX$JcFtiQ5qoYL6FkUycg*4Vd+@&4{rjkG>nkclWe8rfD1Kcc1XHC~lIRaY%yb >> > >>>>> > >> z&#AzVI)|_y#V9pZhT`)S%d?B?+??Iw*B&jKn(0AesGPJrSZ@CB2`0NB4)JL96L+p} >> > >>>>> > >> z2EA*#7UJYgNNv7slHc$~o1KpsjkR7Barezu`JrcdID~L;+5)WX%*UJQ&Yi``U%4(X >> > >>>>> > >> zh-E}#FgHFdGdD9&|LPB(lF}u>&RE{s?M=6MF^#D=F|5EA<NV{oCcMa<zn~Mk<T(Ze >> > >>>>> > >> z&0HR0nL<AyH)RZQ<XDn1{1sHSG^Y=gE!Bz}JL8mgNokN{HQQR8?0sLmM}k+*VtSKU >> > >>>>> > >> z0(G5xjIBkg*mgar8dl?2>(#mwgCLf6u_Q?2KQ*N}ioKasK+MwbOk$c3&Z~KIZ=mPa >> > >>>>> > >> zLC?i`823#_G-G7OIGO%Zt?-*4ASFD1bOllAd=>Z=)0y0vs(aX((aGyG^fp5mz!EEf >> > >>>>> > >> zF>d?iB8)~$oLa4x=o~?8D}fg;$+MVIVN%ak%xZb5y40sy{T31f2D7)Al2jElI=#fN >> > >>>>> > >> zx)0-4Uf!(2BHt@6HeOe~;Bhg-@+!)V3ysYAsLS76mS&4ywdoKN<Xkcj8vRSH?CpA^ >> > >>>>> > >> zZ9jN`nyu1e6#Y_3nzMKf^V7svbi+ln5P6Btmp3WERhY<Khny?~P8Zpg?wVm3cV*HP >> > >>>>> > >> zF7irVsHEod?fy`fjUhz9{Io}Ph2yS$vZyi)rbl*X|6+P8NG4lr_T`IRUN`;zBs<+} >> > >>>>> > >> zT&;Tegh9lXEM8H#WzrQ4k0`6-rOIZab@5GnK@r4wCG}xiH?WAEvh^2e8oA|8_7(DV >> > >>>>> > >> z5#{zDv#r_|AZFJ|X*X!oF;&=4Fo&EnWes7Xf5LE1ZL%z@!1el5uR?cCfVh?NTYPzB >> > >>>>> > >> zBcJE;-j0G%Ppbn+w^1fHs*r*cspp$f(G$WC(1olV7+1;iP|5mP^(0==$z0aQYE_N1 >> > >>>>> > >> zFJ;$W95c_yL552$#QpDU9PXBRRb|F>CNv1JuK7MGSR~?}M)kid{}5SM^TJ#tde-1^ >> > >>>>> > >> zqHAH7)P6A@4^IsHUVRggU`~aL0v88o>F0e|d~9In=Gaqy9!h71JGknx1kk5a>{LRn >> > >>>>> > >> zJ7WiSU7d^tmr_kniLBtPMh%Gv_z#>Ks~I~B1j#>TDETJt+oLT^>%d$VrsQ^(^G805 >> > >>>>> > >> zKs`qV`Q@O}XIF0R3S5rE1tG5KaRey<eev{=NU2n>D%~0XZj&qBhgXJ-OXdPjX%P#o >> > >>>>> > >> z=imy!?b@^Bdbyh91U3fS1-8WVR+)p~rF@V<{4{`?m9{iM{V>%%rk<_FJQmO&;nng$ >> > >>>>> > >> zrTh`()rUt!GGJ4Hs6_n$G;B|fguqa@K59S3=7BW#S1Y_73S6kJOv%g%BFORd1>Wru >> > >>>>> > >> z!u2w4OV|4}Q}I>YDXg!02-Nv(Wm^-*Y!s7WMx3ro>HuA`z}u}pb7Wlla_sN$xCfeh >> > >>>>> > >> z-W5g#<HDupfx1pwl$br>rF8z`UH#Tx?|Sq_6f-@-8m^0-NE}>f=?0ZSkg?(OfT*s& >> > >>>>> > >> zb{*dZs*0x%Ty1n#a>?cGHq3Fy=zNod!EhM~!B6L4R*B;U-8PoMFD@Qd*}L}J^ON5Q >> > >>>>> > >> z3}1fu1ADd?Xm4aDO1ti>l2Ox^PN%VDw89)IJsE-(Op<Ns5)e4989DV%{7NE$`Jm+0 >> > >>>>> > >> z(K4#==OJ^AIAuaz@=bhu!^+GR4DM`H(~oaRaYLLQS(zSQ!MLA~$1{y#A$MTpS)qZ& >> > >>>>> > >> z*0}KkoEc%u(+GK>9QVU9&yPO_e*?h!qR&iJt;nIH)t~yf8;2sQj@A-&iD=n^v7>7X >> > >>>>> > >> zc;w7TG_d4bWf^7^5ZGMr?sur<9VshcD!Ne3bXi7tV9IfIr74>H=iHEynQ_Er1O;1W >> > >>>>> > >> zk>I$rnyotFAW|IyP#dhiq{>i+Ye7KUVEDs=;cp-67Si*Csi1BoR2<J!o$-Q|gS5|L >> > >>>>> > >> z4+g%AHrzW;vt^H{v=5sKp*aU1il;Y*r$;Ia^Y}#fbHM2rGIS}|nrc>1Ne1U9ee<(e >> > >>>>> > >> z{&18JjB@`B48?@mEPm@A`T+R6^(hEDWx-U@F$ouS;wIldeGtiCDpz<px&I1cf~^od >> > >>>>> > >> zN%W~-ywM^`V#T5x`m;+xXUl^t?Y1c#oPFl|)POywWv3Ue1Rf=pkRD22iI#s?!(zJg >> > >>>>> > >> zALmv^$p~`W5H3@mm}crh;p# > > ... > > [Message clipped]
All, I think the consensus from those commenting so far is that we should proceed this way. 1. Large new API sections are added as big patches that have already been reviewed - aka crypto, classification etc to date. 2. The doxygen version of the architecture doc that is versioned in git for the world to consume is formatted so that incremental changes can be easily made as we find things. The things I envisage are things such as the need arising today to state C99 compiance. This allows small changes to be reviewed on the list and there is no disincentive to fixing what you find. This supports our agile continuous improvement. 3. Official doc versions 1.0, 1.1 etc can be made by having a regular document review periodically as needed, they may be very short if the list of changes is small. With clean patches simple diffs will show the changes, including the addition of large new sections. Obviously the pdf could be created and read if it is to be an offline review Does anyone still have a strong opinion that has not been raised yet ? On 7 July 2014 16:13, Victor Kamensky <victor.kamensky@linaro.org> wrote: > I agree with opinion that architecture document should evolve > along with ODP APIs reference. The architecture document > should tie things together. I think we need to keep updating it > along as we update public header files. And we would have > periodic approval reviews among bigger group of SC members, > how would not have time to follow incremental updates. > > I feel lack of good architecture document somewhat now, as I try > to write my own ODP application. Example around are good > and API descriptions help but I wish we would have something > that explain bigger picture. > > As format goes, I would not mind that it would be like IETF RFC, > plain text with ASCII art is fine with me. I would suggest > normative language similar to RFCs as well. So it along with > APIs description it would be normative document. > > Thanks, > Victor > > On 3 July 2014 09:20, Taras Kondratiuk <taras.kondratiuk@linaro.org> > wrote: > > We should decide who is the main user/consumer of this arch document, > > because they have different needs. > > > > - current developers (we) who are contributing/reviewing the document > > will most probably prefer patches, because it is easier to follow > > what is changing without need to read through a whole updated > > document. > > - New developers will read a whole document anyway so they don't care > > much about history. > > - SC need to get rendered document, maybe with highlighted changes. > > > > On 07/03/2014 07:04 PM, Mike Holmes wrote: > >> > >> Can everyone please weigh in with their thoughts, we need consensus on > >> this before we can make progress with the Arch doc. > >> > >> Thanks BIll / Mike > >> > >> > >> On 3 July 2014 11:25, Anders Roxell <anders.roxell@linaro.org > >> <mailto:anders.roxell@linaro.org>> wrote: > >> > >> On 2014-07-03 10:01, Bill Fischofer wrote: > >> > The people who review and approve these docs want to see docs > >> with things > >> > like change bars, not patches. The patch mechanism is simply > >> inappropriate > >> > for this activity and we shouldn't try to force-fit it for > >> something it's > >> > not designed to address. > >> > > >> > Again, the primary users of the odp-architecture git repository > >> are those > >> > who want access to complete docs, not those who are creating, > >> reviewing, > >> > and approving them. That's why we have a separate repository > >> from the main > >> > odp git repository so that "patches" can be handled differently > >> between > >> > them. > >> > >> That is why we use doxygen so that people reviewing for approval can > >> look > >> at the end result... However, isn't it better if anyone on the list > >> can > >> review the patch and send patches when that is needed? > >> > >> SC approval should only be required for major revisions. > >> Possibly only a final read through review for every ODP release. > >> > >> > > >> > My preference would be to grant push rights to those adding items > >> to this > >> > repository rather than going through the artifice of patches. It > >> would be > >> > more straightforward and consistent with the actual workflow. > >> Git would > >> > still be doing version tracking so it would be possible to see > >> the complete > >> > change history for any given doc easily. > >> > >> We should use git as a revision control system as it is, to allow us > >> to > >> make small changes when we discover them. > >> > >> > >> Cheers, > >> Anders > >> > >> > > >> > > >> > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes > >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: > >> > > >> > > I agree we need approval, but approval can be of a review of > >> the patch to > >> > > the text. > >> > > > >> > > I hope we don't need wholesale changes that need a complete re > >> write and > >> > > thus approval of a whole new document. For example a new patch > >> which may > >> > > add a new function to an API but we would hopefully not change > >> any of the > >> > > existing text in the main. > >> > > > >> > > Thus we can then make changes in manageable chunks, I agree > >> that large > >> > > new additions will come in via a pre approved hugue patch, > >> created from a > >> > > sequence of sprints just have we have done so far. > >> > > > >> > > I would argue that these small changes are likely given the > >> additions > >> > > already discovered by starting the validation testing work and > >> the feedback > >> > > it is generating with the need to be more specific in > >> architectural areas. > >> > > > >> > > Mike > >> > > > >> > > > >> > > On 3 July 2014 10:44, Bill Fischofer < > bill.fischofer@linaro.org > >> <mailto:bill.fischofer@linaro.org>> wrote: > >> > > > >> > >> Design documents require approval by those who aren't going to > >> be > >> > >> reviewing patches. This is different from code. My > >> understanding of the > >> > >> purpose of the odp-architecture repository is to provide a > >> convenient means > >> > >> of distributing documentation and making it available in > >> various forms > >> > >> (Doxygen, PDF) for access through the ODP web site as well as > >> being > >> > >> downloaded. > >> > >> > >> > >> So in this sense we're just using Git as a publication > >> mechanism for docs. > >> > >> > >> > >> > >> > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes > >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> > >> > >> wrote: > >> > >> > >> > >>> I am confused git is a change control mechanism, and I really > >> hope they > >> > >>> do get patched, how will we improve the content ? > >> > >>> > >> > >>> > >> > >>> On 3 July 2014 10:03, Bill Fischofer > >> <bill.fischofer@linaro.org <mailto:bill.fischofer@linaro.org>> > wrote: > >> > >>> > >> > >>>> Git is a publication mechanism for docs, not a change > control > >> > >>>> mechanism. Docs will not be 'patched'. New versions will > >> replace old ones > >> > >>>> as they are approved. > >> > >>>> > >> > >>>> > >> > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell > >> <anders.roxell@linaro.org <mailto:anders.roxell@linaro.org> > >> > >>>> > wrote: > >> > >>>> > >> > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: > >> > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org > >> <mailto:bill.fischofer@linaro.org>> > >> > >>>>> > --- > >> > >>>>> > crypto_design.dox | 455 > >> > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ > >> > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes > >> > >>>>> > 2 files changed, 455 insertions(+) > >> > >>>>> > create mode 100644 crypto_design.dox > >> > >>>>> > create mode 100644 images/syncmodels.png > >> > >>>>> > > >> > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox > >> > >>>>> > new file mode 100644 > >> > >>>>> > index 0000000..1ad2ac6 > >> > >>>>> > --- /dev/null > >> > >>>>> > +++ b/crypto_design.dox > >> > >>>>> > @@ -0,0 +1,455 @@ > >> > >>>>> > +/* Copyright (c) 2043, Linaro Limited > >> > >>>>> > + * All rights reserved > >> > >>>>> > + * > >> > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause > >> > >>>>> > + */ > >> > >>>>> > + > >> > >>>>> > +/** > >> > >>>>> > +@page crypto_design ODP Design - Crypto API > >> > >>>>> > +For the implimentation of the ODP crypto API please see > >> @ref > >> > >>>>> odp_crypto.h > >> > >>>>> > + > >> > >>>>> > +@tableofcontents > >> > >>>>> > + > >> > >>>>> > +@section revision_history Revision History > >> > >>>>> > +Revision | Issue Data | Description | Author > >> > >>>>> > +---------|------------|-------------|-------- > >> > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic > >> Functions | > >> > >>>>> Bill, Alexandru > >> > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, > >> started use > >> > >>>>> cases, miscellaneous formatting, API comments | Bill > >> > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to > >> include results > >> > >>>>> of design discussions held during ODP team calls | Bill > >> > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto > >> > >>>>> sprint--action to resolve | Bill > >> > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review > >> > >>>>> comments--ready for final review | Bill > >> > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC > >> approval | Bill > >> > >>>>> > + > >> > >>>>> > +@section introduction Introduction > >> > >>>>> > +This document describes the ODP v1.0 Crypto API. > >> Cryptography is an > >> > >>>>> important part of data plane processing as many > >> communication protocols > >> > >>>>> make use of cryptographic functions. Moreover, many SoCs > >> incorporate > >> > >>>>> cryptographic hardware that can significantly accelerate > >> these operations > >> > >>>>> compared to their software equivalents as well as provide > >> validated > >> > >>>>> hardware functional correctness and security boundaries > >> necessary for > >> > >>>>> system-level security certifications such as FIPS-140 Level > >> 2 and above. > >> > >>>>> > +@section requirements Requirements > >> > >>>>> > +@subsection use_of_terms Use of Terms > >> > >>>>> > +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 [RFC 2119]( > >> > >>>>> https://tools.ietf.org/html/rfc2119). > >> > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography > >> > >>>>> > +Crypto functions cover a range of uses and capabilities > >> designed to > >> > >>>>> support data security, integrity, authentication, and > >> non-repudiation. > >> > >>>>> > +@subsubsection data_security Data Security > >> > >>>>> > +Cryptography supports data security by making use of > >> complex > >> > >>>>> mathematical transformations that are not feasibly > >> reversible without > >> > >>>>> possession of the secret key used to encrypt message data. > >> > >>>>> > +@subsubsection data_integrity Data Integrity > >> > >>>>> > +Cryptography supports data integrity through the use of > >> > >>>>> cryptographic checksums (also known as secure hashes) that > >> ensure the > >> > >>>>> recipient that message data has not been altered either > >> accidentally or > >> > >>>>> maliciously while in transit. > >> > >>>>> > +@subsubsection data_authentication Data Authentication > >> > >>>>> > +Cryptography supports data authentication through the > >> uses of > >> > >>>>> Message Authentication Codes (MACs) that enable the > >> recipient to verify > >> > >>>>> that a message was sent from an authorized counterparty, > >> and hence was not > >> > >>>>> forged. > >> > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation > >> > >>>>> > +Cryptography supports data non-repudiation through the > >> use of > >> > >>>>> digital signatures that enable a recipient or third party > >> to verify the > >> > >>>>> identity of the sending party and prevents the sending > >> party from later > >> > >>>>> denying that they originated a signed message. > >> > >>>>> > +@subsection scope Scope > >> > >>>>> > +ODP v1.0 crypto support is designed to provide a > >> portable framework > >> > >>>>> for accessing SoC-specific cryptographic functions of most > >> use to the data > >> > >>>>> plane. This is predominantly symmetric crypto operations > >> used to support > >> > >>>>> the encryption and decryption of data at line rate using > >> hardware > >> > >>>>> acceleration and offload. Specifically excluded in this > >> support are public > >> > >>>>> key operations and other crypto functions mainly used in > >> the control plane. > >> > >>>>> > +@subsection cryptographic_operations_in_the_data_plane > >> > >>>>> Cryptographic Operations in the Data Plane > >> > >>>>> > +ODP v1.0 crypto APIs cover the following areas: > >> > >>>>> > +@subsubsection ciphering Ciphering > >> > >>>>> > +Ciphering refers to mathematical transformations that > >> use a secret > >> > >>>>> key to encipher data, transforming the original data > >> (referred to as > >> > >>>>> plaintext) into ciphertext, thereby making it > >> unintelligible to anyone not > >> > >>>>> in possession of the key. Similarly, ciphering is also used > >> to decipher > >> > >>>>> data, allowing someone in possession of the correct key to > >> transform > >> > >>>>> received ciphertext back into plaintext. Approved block > >> ciphers are listed > >> > >>>>> > >> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) > and > >> > >>>>> SHOULD be supported by each ODP implementation. > >> > >>>>> > +@subsubsection hasing Hashing > >> > >>>>> > +A hash is a cryptographic digest of a message that can > >> be used to > >> > >>>>> represent it for comparison or integrity checking. Hash > >> functions are > >> > >>>>> designed so that any alteration of a message will alter the > >> hash and that > >> > >>>>> it is computationally infeasible to craft a message that > >> generates the same > >> > >>>>> hash value as another message. Secure hash functions > >> approved for > >> > >>>>> cryptographic use are listed by NIST [here]( > >> > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html > ) > >> and > >> > >>>>> SHOULD be supported by each ODP implementation. > >> > >>>>> > +@subsubsection zeroization Zeroization > >> > >>>>> > +To preserve the security of data, certain transient data > >> held in > >> > >>>>> data buffers MUST be cleared to zeros upon buffer free. > >> Such capability is > >> > >>>>> referred to as zeroization. ODP supports zeroization as a > >> buffer pool > >> > >>>>> attribute. > >> > >>>>> > +@subsubsection random_number_generation Random Number > >> Generation > >> > >>>>> > +Because cryptography relies heavily on “unguessable” > keys > >> of > >> > >>>>> various sorts, random number generation (RNG) is an > >> integral part of > >> > >>>>> cryptographic processing. Random numbers are used in key > >> generation, > >> > >>>>> initialization vectors (IVs), various types of padding > >> bytes, and various > >> > >>>>> other uses collectively referred to as nonces, that serve > >> to “harden” > >> > >>>>> cryptographic processing. > >> > >>>>> > + > >> > >>>>> > +There are two types of random number support of > >> interest. Hardware > >> > >>>>> random data, also known as entropy, that is the result of > >> inherently random > >> > >>>>> physical processes, and deterministic random bit generation > >> (DRBG) that is > >> > >>>>> used in certain certified cryptographic operations. > >> Approved DRBG > >> > >>>>> algorithms are listed in [NIST SP 800-90A]( > >> > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does > >> not > >> > >>>>> specify which algorithms are available on a given > >> implementation. As such > >> > >>>>> ODP implementations MAY use any approved DRGB algorithm but > >> SHOULD support > >> > >>>>> at least one of them. Additionally, ODP implementations > >> MUST NOT represent > >> > >>>>> non-approved algorithms as DRBG implementations. Validated > >> algorithms are > >> > >>>>> listed in the [NIST DRBG Validation List]( > >> > >>>>> > >> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > >> > >>>>> > + > >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > >> > >>>>> > +To enable applications to adapt to the implementation > >> models > >> > >>>>> offered across different SoC platforms, ODP provides APIs > >> to allow > >> > >>>>> applications to inquire about underlying crypto > >> capabilities. A given ODP > >> > >>>>> implementation may offer crypto as hardware features, > >> software features, or > >> > >>>>> not available on a given platform. > >> > >>>>> > +@subsection cryptographic_algorithms Cryptographic > >> Algorithms and > >> > >>>>> Protocols > >> > >>>>> > +A cryptographic algorithm is a mathematical transform > >> that provides > >> > >>>>> one of the cryptographic operations described above. They > >> in turn are used > >> > >>>>> as building blocks in creating cryptographic protocols. > >> These are complete > >> > >>>>> sets of rules for how to exchange data securely using > >> cryptography. Both > >> > >>>>> cryptographic algorithm and protocol design are highly > >> specialized > >> > >>>>> disciplines that involve high levels of public scrutiny and > >> validation. As > >> > >>>>> a result, applications simply make use of approved > >> cryptographic algorithms > >> > >>>>> and protocols. > >> > >>>>> > +@subsection cryptographic_operations Cryptographic > >> Operations > >> > >>>>> > +Cryptographic operations may be initiated by software or > >> directly > >> > >>>>> by hardware as part of the RX or TX packet path processing. > >> For ODP v1.0 > >> > >>>>> software-initiated cryptographic operations are the primary > >> use case. ODP > >> > >>>>> provides APIs for performing data ciphering, hashing, > >> random number > >> > >>>>> generation, and capability inquiry. > >> > >>>>> > +@subsection performance_expectations Performance > >> Expectations > >> > >>>>> > +In the data plane, the total processing budget for a > >> packet may > >> > >>>>> only be a few hundred cycles, so function invocation > >> overhead MUST be kept > >> > >>>>> to a minimum. This has several implications. > >> > >>>>> > + > >> > >>>>> > +-# When work is dispatched to a thread, all information > >> needed by > >> > >>>>> the thread to process the work request SHOULD be > >> immediately at hand. > >> > >>>>> Ideally any context or variables needed for the operation > >> have been > >> > >>>>> pre-warmed in the cache to avoid the latency hits > >> associated with cache > >> > >>>>> misses. SoCs having hardware schedulers generally do this > >> pre-staging of > >> > >>>>> data to minimize such latencies, and ODP implementations > >> are expected to > >> > >>>>> exploit such platform capabilities whenever possible.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive > >> amounts of > >> > >>>>> parameter passing and (depending on the implementation) > >> SHOULD be inlined > >> > >>>>> as much as possible to avoid call overhead. One technique > >> that has proven > >> > >>>>> useful is to allow for parameters to be passed as an > >> explicit thread-local > >> > >>>>> static structure. Such use of “templating” means that a > >> single function can > >> > >>>>> support a rich set of options but the caller can configure > >> a template > >> > >>>>> matched to specific use and only vary the one or two > >> parameters that differ > >> > >>>>> from call to call.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any > >> > >>>>> non-exception path function processing. Kernel calls and > >> such are > >> > >>>>> acceptable only during one-time initialization logic or > >> certain types of > >> > >>>>> unusual error recovery operations. Often the best way to > >> handle the latter > >> > >>>>> is to pass the work to a dedicated recovery thread (or back > >> to the control > >> > >>>>> plane) rather than attempting to handle the condition > >> inline. For example, > >> > >>>>> a link-down condition will trigger various recovery actions > >> that might best > >> > >>>>> be handled in this manner. > >> > >>>>> > + > >> > >>>>> > +@subsection use_by_existing_code Use by Existing Code > >> > >>>>> > +Most applications wishing to make use of ODP represent > >> substantial > >> > >>>>> existing investment that must be preserved. Insofar as > >> possible, ODP > >> > >>>>> functions need to be orthogonal to existing application > >> environments and > >> > >>>>> structures to permit easy intermixing with pre-existing > code. > >> > >>>>> > +@subsection data_references Data References > >> > >>>>> > +Packet data is inherently of variable length however it > >> is often > >> > >>>>> more efficient to organize memory into fixed-sized buffers > >> that can be > >> > >>>>> chained together on demand to contain packets. The > >> application SHOULD > >> > >>>>> normally not need to be aware of such lower-level > >> segmentation and should > >> > >>>>> be able to treat a packet as a single object. Alternately, > >> especially when > >> > >>>>> dealing with existing code, data segmentation MUST be > >> explicitly > >> > >>>>> specifiable via scatter/gather lists. For example, data > >> encryption or > >> > >>>>> decryption may be invoked on a list of data segments as > >> part of a single > >> > >>>>> function call. > >> > >>>>> > >> > >>>>> Every time you add a full stop for a sentence, you have to > >> press return > >> > >>>>> and start typing the next sentence. > >> > >>>>> This means that diffs of future changes will be per > sentence. > >> > >>>>> Doxygen will still concatenate this as a paragraph with no > >> visual > >> > >>>>> difference in the result. > >> > >>>>> I think the above line will look like this: > >> > >>>>> > >> > >>>>> Packet data is inherently of variable length however it is > >> often more > >> > >>>>> efficient to organize memory into fixed-sized buffers that > >> can be chained > >> > >>>>> together on demand to contain packets. > >> > >>>>> The application SHOULD normally not need to be aware of > such > >> > >>>>> lower-level segmentation and should be able to treat a > >> packet as a single > >> > >>>>> object. > >> > >>>>> Alternately, especially when dealing with existing code, > data > >> > >>>>> segmentation MUST be explicitly specifiable via > >> scatter/gather lists. > >> > >>>>> For example, data encryption or decryption may be invoked > >> on a list of > >> > >>>>> data segments as part of a single function call. > >> > >>>>> > >> > >>>>> > >> > >>>>> Cheers, > >> > >>>>> Anders > >> > >>>>> > >> > >>>>> > +@subsection chained_operations Chained Operations > >> > >>>>> > +Crypto operations such as hashing and encryption, or > >> decryption and > >> > >>>>> verification, are very commonly used in combination. For > >> ODP, it is > >> > >>>>> sufficient to support one cipher and one > >> hash/authentication operation in a > >> > >>>>> single call and this combination MUST be supported to avoid > >> the call and > >> > >>>>> dispatch overhead of separate invocations. > >> > >>>>> > +@subsection key_management Key Management and Session > Data > >> > >>>>> > +Keying is an area of particular sensitivity in crypto > >> processing > >> > >>>>> since keys are highly confidential and may be subject to > >> legal requirements > >> > >>>>> for safeguarding within special hardware enclosures. > >> > >>>>> > + > >> > >>>>> > +A session is the security context used to represent an > >> active set > >> > >>>>> of crypto operations that need to be applied to a flow on a > >> > >>>>> packet-by-packet basis. Generally a session is established > >> upon detection > >> > >>>>> of a flow requiring crypto processing and retained for the > >> life of that > >> > >>>>> flow. It has been noted that this can involve cooperative > >> processing > >> > >>>>> between the control and data planes so several requirements > >> stem from this: > >> > >>>>> > + > >> > >>>>> > +-# Session creation MAY need to be handled in an > >> asynchronous > >> > >>>>> manner. This is to allow these to be created in batches by > >> thread(s) that > >> > >>>>> specialize in this activity.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Sessions MAY need to reference keying material > >> indirectly via > >> > >>>>> key handling modules.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Session creation MAY be performed by non-ODP code and > >> > >>>>> communicated to data plane routines that make use of ODP > >> crypto functions > >> > >>>>> that need to reference the session information. > >> > >>>>> > + > >> > >>>>> > +ODP session APIs and data structures SHOULD be > >> represented by > >> > >>>>> abstract data types that encapsulate implementation details > >> for both > >> > >>>>> platform efficiency and to accommodate these needs. > >> > >>>>> > +Use Cases > >> > >>>>> > +For ODP v1.0 the major use cases of interest involve > >> cryptographic > >> > >>>>> algorithm acceleration. Cryptographic protocol acceleration > >> is reserved for > >> > >>>>> future ODP releases. > >> > >>>>> > +Buffers and Data Blocks > >> > >>>>> > +Cryptographic operations may be performed directly on > data > >> > >>>>> contained in ODP packet buffers, or it may be performed on > >> “raw” data > >> > >>>>> blocks operating entirely under application control. Note > >> that when using > >> > >>>>> raw data blocks not managed by ODP, the application must > >> perform any needed > >> > >>>>> zeroization using either its own or ODP-supplied buffer > >> zeroization > >> > >>>>> functions. ODP automatic support for zeroization is limited > >> to ODP-managed > >> > >>>>> buffers. ODP buffers allocated from buffer pools designated > >> for crypto use > >> > >>>>> will also have whatever alignment and/or addressability > >> attributes needed > >> > >>>>> by the implementation to support crypto API calls. > >> > >>>>> > + > >> > >>>>> > +Note: Some implementations may have difficulty dealing > >> with > >> > >>>>> application buffer addresses, as these may be virtual > >> addresses that are > >> > >>>>> mapped discontiguously into physical memory. For such > >> implementations, > >> > >>>>> memory SHOULD be allocated contiguously and MAY need to be > >> “registered” to > >> > >>>>> have proper addressability for crypto operations. This area > >> of the design > >> > >>>>> will be updated based on experience in dealing with > >> different crypto > >> > >>>>> implementations that have such requirements. > >> > >>>>> > +Synchronization > >> > >>>>> > +ODP operations fall into one of three categories: > >> > >>>>> > + > >> > >>>>> > +-# Inline (Synchronous): Upon return from a call the > >> operation is > >> > >>>>> complete. Operation is thus completely synchronous to the > >> caller. Inline > >> > >>>>> is the appropriate model when the invoked function takes > >> relatively few > >> > >>>>> cycles or when the caller cannot feasibly progress without > >> the results of > >> > >>>>> the invoked function.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Parallel: Upon return from a call the operation has > >> been > >> > >>>>> initiated, but is expected to complete shortly. The caller > >> continues to > >> > >>>>> execute until it needs the result at which point it waits > >> to complete the > >> > >>>>> parallel operation. The effect is as if the operation were > >> inline except > >> > >>>>> that the caller was able to execute in parallel with the > >> operation for some > >> > >>>>> application-determined period of time. Parallel is the > >> appropriate model > >> > >>>>> when the operation being performed is relatively short (a > >> few dozen up to > >> > >>>>> perhaps 100 or 200 cycles) and the caller can usefully > >> accomplish other > >> > >>>>> processing on the same unit of work while the parallel > >> operation is in > >> > >>>>> progress, but not enough to justify the overhead of a > >> formal queued work > >> > >>>>> dispatch.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call > the > >> > >>>>> operation has been queued for execution. A completion event > >> will be queued > >> > >>>>> back to the scheduler when the event is completed. Offload > >> is the > >> > >>>>> appropriate model when the invoked function will take a > >> substantial amount > >> > >>>>> of cycles (thousands to tens of thousands) allowing the > >> invoking > >> > >>>>> thread/core to service other work until the operation > >> completes. For > >> > >>>>> offloaded work, completion is indicated by a completion > >> event being posted > >> > >>>>> back to an application-designated completion queue. Upon > >> receipt the unit > >> > >>>>> of work that initiated the offloaded operation continues > >> processing with > >> > >>>>> the results of the call. > >> > >>>>> > + > >> > >>>>> > +The synchronization models of interest are summarized in > >> Figure 1: > >> > >>>>> > + > >> > >>>>> > + > >> > >>>>> > + > >> > >>>>> > +Note: Because few implementations are expected to offer > >> the > >> > >>>>> Parallel mode of operation as described above, this mode > >> is reserved for > >> > >>>>> potential future use. For ODP v1.0 only synchronous and > >> asynchronous crypto > >> > >>>>> operations are defined. > >> > >>>>> > +@section functional_definition Functional Definition > >> > >>>>> > +@subsection abstract_data_types Abstract data types > >> > >>>>> > +The following enumerations define various algorithms > >> used for > >> > >>>>> ciphering and hashing. These are the basic operations > >> applied to input data. > >> > >>>>> > + > >> > >>>>> > +A particular ODP implementation should map these values > >> to the > >> > >>>>> actual information to be passed to the crypto engine. As > >> such, the actual > >> > >>>>> values of these enums is implementation-defined. > >> > >>>>> > + > >> > >>>>> > +Cipher algorithm encoding specifies the algorithm and > >> cipher mode > >> > >>>>> employed (as per security relevant RFCs - [4305]( > >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > >> > >>>>> http://tools.ietf.org/html/rfc4494)). > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +enum odp_cipher_alg { > >> > >>>>> > + ODP_CIPHER_ALG_NULL, > >> > >>>>> > + ODP_CIPHER_ALG_DES, > >> > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, > >> > >>>>> > + ODP_CIPHER_ALG_AES_CBC, > >> > >>>>> > + ODP_CIPHER_ALG_AES_GCM, > >> > >>>>> > + ODP_CIPHER_ALG_AES_CTR, > >> > >>>>> > + ODP_CIPHER_ALG_KASUMI, > >> > >>>>> > + ODP_CIPHER_ALG_SNOW, > >> > >>>>> > + ... > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Authorization algorithm encoding specifies the algorithm > >> and the > >> > >>>>> length of the authorization used (as per security relevant > >> RFCs - [4305]( > >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > >> > >>>>> http://tools.ietf.org/html/rfc4494)): > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +enum odp_auth_alg { > >> > >>>>> > + ODP_AUTH_ALG_NULL, > >> > >>>>> > + ODP_AUTH_MD5_96, > >> > >>>>> > + ODP_AUTH_ALG_SHA1_96, > >> > >>>>> > + ODP_AUTH_ALG_SHA1_160 > >> > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, > >> > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, > >> > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, > >> > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, > >> > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > >> > >>>>> > + ODP_AUTH_ALG_SNOW, > >> > >>>>> > + ODP_AUTH_ALG_KASUMI, > >> > >>>>> > + ... > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +typedef union odp_crypto_alg_t { > >> > >>>>> > + enum odp_cipher_alg cipher; > >> > >>>>> > + enum odp_auth_alg auth; > >> > >>>>> > +}odp_crypto_alg_t; > >> > >>>>> > +@endcode > >> > >>>>> > +@subsection parameter_structures Parameter Structures > >> > >>>>> > +@subsubsection crypto_sessions Crypto Sessions > >> > >>>>> > +The following structure describes a crypto session. All > >> packets / > >> > >>>>> raw data buffers processed in a session share the data that > >> defines the > >> > >>>>> session. A crypto session is defined by: > >> > >>>>> > + > >> > >>>>> > +- Operation type : encode or decode\n\n > >> > >>>>> > + > >> > >>>>> > +- Algorithms specifications, keys and , if required, > >> initialization > >> > >>>>> vectors. When initialization vectors are not provided and > >> they should be > >> > >>>>> provided automatically by the crypto engine.\n\n > >> > >>>>> > + > >> > >>>>> > +- The operation mode: synchronous or asynchronous. > >> Synchronous > >> > >>>>> operation blocks the caller until an operation status and > >> result are > >> > >>>>> available. In synchronous mode there is at most only one > >> outstanding crypto > >> > >>>>> operation in the calling thread. In asynchronous mode, the > >> caller starts > >> > >>>>> the crypto operation and later it may receive the status > >> and the result > >> > >>>>> together with a request context. The operation status and > >> result may also > >> > >>>>> be received by a different thread.\n\n > >> > >>>>> > + > >> > >>>>> > +- Operation mode parameters: For asynchronous operation > a > >> > >>>>> completion event containing the status, the result and the > >> request context > >> > >>>>> is enqueued to a completion queue. In case the queue is > >> under the scheduler > >> > >>>>> control, the scheduler determines who will receive the > >> completion event and > >> > >>>>> when. When the completion queue is not scheduled, the > >> thread which is > >> > >>>>> supposed to get the operation output has to explicitly poll > >> the completion > >> > >>>>> queue. > >> > >>>>> > + > >> > >>>>> > +Note that this is an abstract data type and its > structure > >> is > >> > >>>>> implementation-specific. The layout shown here is for > >> illustrative purposes > >> > >>>>> and the actual layout will vary from one implementation to > >> the next to most > >> > >>>>> closely align with the structures needed by the underlying > >> SoC platform. > >> > >>>>> Applications set and reference fields in the session > >> structure via accessor > >> > >>>>> functions that hide the actual layout. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +typedef enum odp_crypto_op_t { > >> > >>>>> > + ODP_CRYPTO_OP_ENCODE, > >> > >>>>> > + ODP_CRYPTO_OP_DECODE > >> > >>>>> > +}odp_crypto_op_t; > >> > >>>>> > + > >> > >>>>> > +typedef struct odp_key_t { > >> > >>>>> > +}odp_key_t; > >> > >>>>> > + > >> > >>>>> > +typedef struct odp_crypto_session_t { > >> > >>>>> > + odp_crypto_op_t op; > >> > >>>>> > + struct { > >> > >>>>> > + enum odp_cipher_alg cipher_alg; > >> > >>>>> > + odp_key_t *key; > >> > >>>>> > + uint8_t *iv; > >> > >>>>> > + size_t iv_len; > >> > >>>>> > + } cipher; > >> > >>>>> > + > >> > >>>>> > + struct { > >> > >>>>> > + enum odp_auth_alg auth_alg; > >> > >>>>> > + enum odp_auth_len auth_len; > >> > >>>>> > + odp_key_t *key; > >> > >>>>> > + } auth; > >> > >>>>> > + > >> > >>>>> > + enum odp_crypto_op_mode { > >> > >>>>> > + ODP_CRYPTO_SYNC, > >> > >>>>> > + ODP_CRYPTO_ASYNC, > >> > >>>>> > + } op_mode; > >> > >>>>> > + > >> > >>>>> > + struct { > >> > >>>>> > + uint32_t timeout; > >> > >>>>> > + struct { > >> > >>>>> > + odp_queue_t completion_queue; > >> > >>>>> > + } async; > >> > >>>>> > + } op_mode_params; > >> > >>>>> > + > >> > >>>>> > + odp_session_proc_info_t session_proc_info; > >> > >>>>> > +} odp_crxsypto_session_t; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +The completion queue contained in the session structure > >> is an > >> > >>>>> in/out parameter. If provided, then the queue specified is > >> associated with > >> > >>>>> the session and is used to ensure order preservation on > >> that session. If > >> > >>>>> not provided, one is created and returned to the caller. > >> Note that this > >> > >>>>> completion queue is used to order operations performed on > >> this crypto > >> > >>>>> session. It should not be confused with the completion > >> queue specified on > >> > >>>>> the odp_crypto_session_create() call (see below) that is > >> used to control > >> > >>>>> whether that call is itself processed in a synchronous vs. > >> asynchronous > >> > >>>>> manner. > >> > >>>>> > + > >> > >>>>> > +The following structure comprises processing > >> information. This is > >> > >>>>> logically divided in two parts: > >> > >>>>> > + > >> > >>>>> > +- Processing input info - When crypto engine provides > >> support for > >> > >>>>> protocol processing, this information is provided in a > >> higher level common > >> > >>>>> protocol terminology form and a particular implementation > >> should be able to > >> > >>>>> derive everything it needs from this definition. In > >> addition, for crypto > >> > >>>>> engines able to automate tasks like memory allocation for > >> the output a > >> > >>>>> buffer pool id may be specified.\n\n > >> > >>>>> > + > >> > >>>>> > +- Processing output information - statistics about > >> processed > >> > >>>>> bytes/packets. These are useful when a session expiration > >> is based on > >> > >>>>> traffic volume. These statistics may be updated by the > >> software or by the > >> > >>>>> hardware crypto engine. > >> > >>>>> > + > >> > >>>>> > +Again, this is an abstract type whose specific layout > >> will vary > >> > >>>>> based on implementation considerations. Access to fields > >> contained in the > >> > >>>>> structure is only via accessor functions. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +typedef struct { > >> > >>>>> > + uint64_t pkts_processed; > >> > >>>>> > + uint64_t bytes_processed; > >> > >>>>> > + uint64_t pkts_errored; > >> > >>>>> > + uint64_t bytes_errored; > >> > >>>>> > + > >> > >>>>> > + odp_buffer_pool_t out_pool; > >> > >>>>> > + > >> > >>>>> > +} odp_session_proc_info_t; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +This enumeration defines which operations are applied > >> and the order. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +enum odp_crypto_combination { > >> > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, > >> > >>>>> > + ODP_CRYPTO_AUTH_ONLY, > >> > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +This structure defines a contiguous segment in the input > >> data which > >> > >>>>> starts at offset offset and is len bytes long. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +struct odp_data_range { > >> > >>>>> > + unsigned offset:16; > >> > >>>>> > + unsigned len:16; > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +@subsection api_functions API Functions > >> > >>>>> > + > >> > >>>>> > +@subsubfunction Session Creation > >> > >>>>> > + > >> > >>>>> > +This function is used to create a crypto session. The > >> required > >> > >>>>> parameters are : > >> > >>>>> > + > >> > >>>>> > +- Operation : encode/decode > >> > >>>>> > +- Processing info : cipher/auth/both > >> > >>>>> > +- Preferred mode : sync or async. > >> > >>>>> > +- Algorithms suites, keys and optional IV > >> > >>>>> > + > >> > >>>>> > +Session creation can be synchronous or asynchronous. > >> Completion > >> > >>>>> event argument is used to return the status and the session > >> handle. When > >> > >>>>> completion queue is not provided (synchronous call), the > >> completion event > >> > >>>>> is available upon function call return. When completion > >> queue is provided > >> > >>>>> (asynchronous call), the completion event is placed on the > >> completion queue. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +typedef uint64_t odp_crypto_session_t; > >> > >>>>> > + > >> > >>>>> > +struct odp_session_params { > >> > >>>>> > + enum odp_crypto_operation op; > >> > >>>>> > + odp_session_proc_info_t proc_info; > >> > >>>>> > + enum odp_crypto_op_mode pref_mode; > >> > >>>>> > + enum odp_cipher_alg cipher_alg; > >> > >>>>> > + odp_key_t *cipher_key; > >> > >>>>> > + uint8_t *iv; > >> > >>>>> > + size_t iv_len; > >> > >>>>> > + enum odp_auth_alg auth_alg; > >> > >>>>> > + odp_key_t *auth_key; > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +enum odp_crypto_ses_create_err { > >> > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, > >> > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, > >> > >>>>> > + /* Session creation error codes */ > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +void > >> > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t > >> > >>>>> completion_event, enum odp_crypto_ses_create_err *status); > >> > >>>>> > + > >> > >>>>> > +void > >> > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t > >> > >>>>> completion_event, odp_crypto_session_t *handle); > >> > >>>>> > + > >> > >>>>> > +int odp_crypto_session_create( > >> > >>>>> > + struct odp_session_params *params, > >> > >>>>> > + odp_buffer_t completion_event, > >> > >>>>> > + odp_queue_t completion_queue); > >> > >>>>> > +@endcode > >> > >>>>> > +@subsection crypto_operation Crypto Operation > >> > >>>>> > + > >> > >>>>> > +Crypto operations are described by a parameter > structure: > >> > >>>>> > +@code > >> > >>>>> > +struct odp_crypto_op_params { > >> > >>>>> > + odp_crypto_session_t session; > >> > >>>>> > + odp_packet_t pkt; > >> > >>>>> > + odp_packet_t out_pkt; > >> > >>>>> > + uint8_t *override_iv_ptr; > >> > >>>>> > + unsigned hash_result_offset; > >> > >>>>> > + struct odp_data_range cipher_range; > >> > >>>>> > + struct odp_data_range auth_range; > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +<table> > >> > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> > >> > >>>>> > +<tr><td>session</td><td>Session to perform the > >> operation</td></tr> > >> > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be > >> processed</td></tr> > >> > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / > >> buffer to be > >> > >>>>> returned as the result of the operation. There are three > >> different ways > >> > >>>>> this parameter is used, depending on the mode of operation > >> requested by the > >> > >>>>> caller and the capabilities of the underlying > >> implementation:\n\n > >> > >>>>> > + > >> > >>>>> > +-# If out_pkt is the same as pkt this indicates that the > >> operation > >> > >>>>> should be performed in place.\n\n > >> > >>>>> > +-# If out_pkt is different from pkt this indicates that > >> output > >> > >>>>> should be placed in the buffer supplied by the caller.\n\n > >> > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied > >> on input) > >> > >>>>> this indicates that an output buffer should be allocated by > >> the operation > >> > >>>>> and returned as part of the completion event associated > >> with the > >> > >>>>> operation.\n\n > >> > >>>>> > + > >> > >>>>> > +Note that not every implementation will support all of > >> these modes > >> > >>>>> and MAY require that one mode be used in preference to > >> others. Any such > >> > >>>>> implementation restrictions are communicated as output from > >> session > >> > >>>>> creation.</td></tr> > >> > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for > >> this > >> > >>>>> request</td></tr> > >> > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the > >> output packet > >> > >>>>> where the hash result should be stored.</td></tr> > >> > >>>>> > +<tr><td>cipher_range</td><td>The byte range > >> (offset:length) of the > >> > >>>>> data to be processed for ciphering.</td></tr> > >> > >>>>> > +<tr><td>auth_range</td><td>The byte range > >> (offset:length) of the > >> > >>>>> data to be processed for authentication.</td></tr> > >> > >>>>> > +</table> > >> > >>>>> > + > >> > >>>>> > +The crypto operation is initiated with a single call > >> that passes > >> > >>>>> the parameters for the operation and an event (for > >> asynchronous completion). > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_operation( > >> > >>>>> > + struct odp_crypto_op_params *params, > >> > >>>>> > + odp_buffer_t completion_event); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Parameter | Meaning > >> > >>>>> > +----------|-------- > >> > >>>>> > +params | The parameter structure describing the > >> crypto operation > >> > >>>>> to be performed. > >> > >>>>> > +completion_event | The event delivered on completion. It > >> provides > >> > >>>>> information about the status of the operation, result and > >> request context. > >> > >>>>> In synchronous mode the event is available upon function > >> call return. In > >> > >>>>> asynchronous mode, the event is placed on the session / > >> operation > >> > >>>>> completion queue when the operation finished. > >> > >>>>> > + > >> > >>>>> > +Upon return the return code indicates whether the > >> operation was > >> > >>>>> synchronous or asynchronous, or if an error occurred that > >> prevented the > >> > >>>>> operation from being performed. > >> > >>>>> > + > >> > >>>>> > +Get session operation : > >> > >>>>> > +@code > >> > >>>>> > +odp_crypto_op_t > >> > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Get session cipher information : > >> > >>>>> > +@code > >> > >>>>> > +odp_cipher_alg > >> > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t > >> ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Get session authentication information : > >> > >>>>> > +@code > >> > >>>>> > +odp_auth_alg > >> > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t > ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Change session IV : > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, > >> uint8_t > >> > >>>>> *iv); > >> > >>>>> > +@emdcode > >> > >>>>> > + > >> > >>>>> > +Change cipher or/and hash keys: > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, > >> odp_key_t > >> > >>>>> *key); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Destroy crypto session. All pending operations are > >> cancelled. > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t > ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Get completion event information - algorithm error, > >> output and > >> > >>>>> context. Note that implementations MAY define their own > >> specific error > >> > >>>>> codes that have meaning in that context. For application > >> portability it is > >> > >>>>> sufficient to know whether an operation completed > >> successfully or > >> > >>>>> experienced an error of some sort. > >> > >>>>> > +@code > >> > >>>>> > +enum crypto_alg_err { > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +enum crypto_hw_err { > >> > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, > >> > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, > >> > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +struct odp_crypto_compl_status { > >> > >>>>> > + odp_crypto_alg_t alg; > >> > >>>>> > + enum crypto_alg_err alg_err; > >> > >>>>> > + enum crypto_hw_err hw_err; > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +void > >> > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t > completion_event, > >> > >>>>> > + struct odp_crypto_compl_status > >> *auth, > >> > >>>>> > + struct odp_crypto_compl_status > >> *cipher); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Returns the output packet handle associated with the > >> completion > >> > >>>>> event : > >> > >>>>> > +@code > >> > >>>>> > +odp_packet_t > >> > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Sets a context handle to be returned with the completion > >> event : > >> > >>>>> > +@code > >> > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t > >> completion_event, > >> > >>>>> odp_compl_ctx_t *ctx); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Returns the context associated with the completion > event : > >> > >>>>> > +@code > >> > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t > >> > >>>>> completion_event); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +This section describes the API/Interface being defined > at > >> a > >> > >>>>> functional level in technical detail. Sub-sections include > >> header file > >> > >>>>> names, where implementation files are expected to reside in > >> the ODP git > >> > >>>>> tree, as well as the name, parameters, abstract data types, > >> functionality, > >> > >>>>> return codes, and exception conditions of each function > >> call defined by the > >> > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be > >> used to allow > >> > >>>>> the programmer tasked with implementing the API/Interface > >> to understand the > >> > >>>>> function to be implemented as well as error conditions, > >> corner cases, > >> > >>>>> performance requirements, etc. needed to implement the > >> described > >> > >>>>> API/Interface in a functionally correct and efficient > manner. > >> > >>>>> > + > >> > >>>>> > +@subsubsection random_number_functions Random Number > >> Functions > >> > >>>>> > +As noted earlier, random number support consists of two > >> functions: > >> > >>>>> > +@code > >> > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool > >> > >>>>> use_entropy); > >> > >>>>> > + > >> > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +The difference is that the first provides access to > >> hardware random > >> > >>>>> number functions that return true random data. This is > >> typically used for > >> > >>>>> seed values. The second provides a deterministic random bit > >> generator > >> > >>>>> conforming to NIST standards and is used by various crypto > >> protocols and > >> > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get > >> is used to > >> > >>>>> disable any hardware pre-processing normally provided by > >> the function and > >> > >>>>> is mainly intended to be used for testing/validation > >> purposes. > >> > >>>>> > + > >> > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool > >> Extensions > >> > >>>>> > +To support zeroization a buffer may be allocated with an > >> > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer > >> should be > >> > >>>>> zeroized upon free. Alternately, a new type > >> (ODP_CLEAR_ON_FREE) is added to > >> > >>>>> odp_buffer_pool_create() that specifies that all buffers > >> allocated from > >> > >>>>> this pool must be zeroized upon free. Essentially, the > >> buffer security > >> > >>>>> attribute is set by default from the attributes of the > >> buffer pool that it > >> > >>>>> is allocated from. > >> > >>>>> > + > >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > >> > >>>>> > +To enable applications to determine crypto capabilities. > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum > >> odp_auth_alg); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Inquires whether the specified crypto and auth > >> algorithms are > >> > >>>>> supported. Responses include: > >> > >>>>> > +- ODP_HW_SYNC_SUPPORT > >> > >>>>> > +- ODP_HW_ASYNC_SUPPORT > >> > >>>>> > +- ODP_SW_SYNC_SUPPORT > >> > >>>>> > +- ODP_SW_ASYNC_SUPPORT > >> > >>>>> > +- ODP_NO_SUPPORT > >> > >>>>> > + > >> > >>>>> > +HW support means the combination is supported in > >> hardware, SW > >> > >>>>> support means the combination is supported in software by > the > >> > >>>>> implementation. No support means the combination is not > >> supported by the > >> > >>>>> implementation. The SYNC and ASYNC return options can help > >> the application > >> > >>>>> decide how to invoke these functions, or it can just check > >> whether or not > >> > >>>>> the response is ODP_NO_SUPPORT. > >> > >>>>> > + > >> > >>>>> > +@section implementation_considerations Implementation > >> Considerations > >> > >>>>> > +One of the main purposes for the ODP crypto APIs is to > >> provide > >> > >>>>> portable access across different SoCs whose hardware crypto > >> capabilities > >> > >>>>> largely overlap but vary in terms of their implementation > >> details. As a > >> > >>>>> result, implementations need not provide software fill-ins > >> for specific > >> > >>>>> cryptographic features that are not available as hardware > >> features on that > >> > >>>>> platform. Presumably applications needing specific features > >> will select > >> > >>>>> platforms on which these features are present. Therefore, > >> while all APIs > >> > >>>>> specified here MUST exist in each conforming ODP > >> implementation, it is > >> > >>>>> acceptable for these APIs to return > >> ODP_RC_FEATURE_NOT_PRESENT in response > >> > >>>>> to calls requesting crypto features not present on that > >> platform. > >> > >>>>> > + > >> > >>>>> > +For example, the linux-generic ODP implementation may > only > >> > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and > >> return a feature > >> > >>>>> not present error code for any other cipher. This > >> indication will also be > >> > >>>>> returned on that platform in response to odp_crypto_inquire > >> calls for > >> > >>>>> non-null cipher algorithms. > >> > >>>>> > + > >> > >>>>> > +@section verification Verification/Testing > >> > >>>>> > +This section describes the verification/test cases > >> needed to ensure > >> > >>>>> that the defined functionality is implemented correctly and > >> performs > >> > >>>>> adequately. This should be at a level of detail such that > >> the programmer > >> > >>>>> tasked with writing test scripts/programs to verify the > >> implementation(s) > >> > >>>>> of the defined functions can be written to ensure that all > >> relevant > >> > >>>>> functional variants and error/exception cases are properly > >> tested. > >> > >>>>> > + > >> > >>>>> > +This section needs to be completed before API testing > >> begins. > >> > >>>>> > + > >> > >>>>> > +*/ > >> > >>>>> > \ No newline at end of file > >> > >>>>> > diff --git a/images/syncmodels.png > b/images/syncmodels.png > >> > >>>>> > new file mode 100644 > >> > >>>>> > index > >> > >>>>> > >> > >> > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > >> > >>>>> > GIT binary patch > >> > >>>>> > literal 17179 > >> > >>>>> > > >> zcmch;XH?Tcv@Z$>iXhSqNDxrER8c~aDjh?WUL(Et-Vx~th$xXJz4smxnsljBLkDS* > >> > >>>>> > > >> z-U&T7c+PqEth3g=pWb`(A^(+`Ju`dSo?U(urKTcJLIfnj!NDO>RFHXxgM;UcgM-UP > >> > >>>>> > > >> zco&=V+&Rz%2S;jIQRa=N_smYZm=g1R%A)G;H}~-I@#)CiCI2J+roi>GZf!`WZf2C^ > >> > >>>>> > > >> z)RvpX$JcFtiQ5qoYL6FkUycg*4Vd+@&4{rjkG>nkclWe8rfD1Kcc1XHC~lIRaY%yb > >> > >>>>> > > >> z&#AzVI)|_y#V9pZhT`)S%d?B?+??Iw*B&jKn(0AesGPJrSZ@CB2`0NB4)JL96L+p} > >> > >>>>> > > >> z2EA*#7UJYgNNv7slHc$~o1KpsjkR7Barezu`JrcdID~L;+5)WX%*UJQ&Yi``U%4(X > >> > >>>>> > > >> zh-E}#FgHFdGdD9&|LPB(lF}u>&RE{s?M=6MF^#D=F|5EA<NV{oCcMa<zn~Mk<T(Ze > >> > >>>>> > > >> z&0HR0nL<AyH)RZQ<XDn1{1sHSG^Y=gE!Bz}JL8mgNokN{HQQR8?0sLmM}k+*VtSKU > >> > >>>>> > > >> z0(G5xjIBkg*mgar8dl?2>(#mwgCLf6u_Q?2KQ*N}ioKasK+MwbOk$c3&Z~KIZ=mPa > >> > >>>>> > > >> zLC?i`823#_G-G7OIGO%Zt?-*4ASFD1bOllAd=>Z=)0y0vs(aX((aGyG^fp5mz!EEf > >> > >>>>> > > >> zF>d?iB8)~$oLa4x=o~?8D}fg;$+MVIVN%ak%xZb5y40sy{T31f2D7)Al2jElI=#fN > >> > >>>>> > > >> zx)0-4Uf!(2BHt@6HeOe~;Bhg-@+!)V3ysYAsLS76mS&4ywdoKN<Xkcj8vRSH?CpA^ > >> > >>>>> > > >> zZ9jN`nyu1e6#Y_3nzMKf^V7svbi+ln5P6Btmp3WERhY<Khny?~P8Zpg?wVm3cV*HP > >> > >>>>> > > >> zF7irVsHEod?fy`fjUhz9{Io}Ph2yS$vZyi)rbl*X|6+P8NG4lr_T`IRUN`;zBs<+} > >> > >>>>> > > >> zT&;Tegh9lXEM8H#WzrQ4k0`6-rOIZab@5GnK@r4wCG}xiH?WAEvh^2e8oA|8_7(DV > >> > >>>>> > > >> z5#{zDv#r_|AZFJ|X*X!oF;&=4Fo&EnWes7Xf5LE1ZL%z@!1el5uR?cCfVh?NTYPzB > >> > >>>>> > > >> zBcJE;-j0G%Ppbn+w^1fHs*r*cspp$f(G$WC(1olV7+1;iP|5mP^(0==$z0aQYE_N1 > >> > >>>>> > > >> zFJ;$W95c_yL552$#QpDU9PXBRRb|F>CNv1JuK7MGSR~?}M)kid{}5SM^TJ#tde-1^ > >> > >>>>> > > >> zqHAH7)P6A@4^IsHUVRggU`~aL0v88o>F0e|d~9In=Gaqy9!h71JGknx1kk5a>{LRn > >> > >>>>> > > >> zJ7WiSU7d^tmr_kniLBtPMh%Gv_z#>Ks~I~B1j#>TDETJt+oLT^>%d$VrsQ^(^G805 > >> > >>>>> > > >> zKs`qV`Q@O}XIF0R3S5rE1tG5KaRey<eev{=NU2n>D%~0XZj&qBhgXJ-OXdPjX%P#o > >> > >>>>> > > >> z=imy!?b@^Bdbyh91U3fS1-8WVR+)p~rF@V<{4{`?m9{iM{V>%%rk<_FJQmO&;nng$ > >> > >>>>> > > >> zrTh`()rUt!GGJ4Hs6_n$G;B|fguqa@K59S3=7BW#S1Y_73S6kJOv%g%BFORd1>Wru > >> > >>>>> > > >> z!u2w4OV|4}Q}I>YDXg!02-Nv(Wm^-*Y!s7WMx3ro>HuA`z}u}pb7Wlla_sN$xCfeh > >> > >>>>> > > >> z-W5g#<HDupfx1pwl$br>rF8z`UH#Tx?|Sq_6f-@-8m^0-NE}>f=?0ZSkg?(OfT*s& > >> > >>>>> > > >> zb{*dZs*0x%Ty1n#a>?cGHq3Fy=zNod!EhM~!B6L4R*B;U-8PoMFD@Qd*}L}J^ON5Q > >> > >>>>> > > >> z3}1fu1ADd?Xm4aDO1ti>l2Ox^PN%VDw89)IJsE-(Op<Ns5)e4989DV%{7NE$`Jm+0 > >> > >>>>> > > >> z(K4#==OJ^AIAuaz@=bhu!^+GR4DM`H(~oaRaYLLQS(zSQ!MLA~$1{y#A$MTpS)qZ& > >> > >>>>> > > >> z*0}KkoEc%u(+GK>9QVU9&yPO_e*?h!qR&iJt;nIH)t~yf8;2sQj@A-&iD=n^v7>7X > >> > >>>>> > > >> zc;w7TG_d4bWf^7^5ZGMr?sur<9VshcD!Ne3bXi7tV9IfIr74>H=iHEynQ_Er1O;1W > >> > >>>>> > > >> zk>I$rnyotFAW|IyP#dhiq{>i+Ye7KUVEDs=;cp-67Si*Csi1BoR2<J!o$-Q|gS5|L > >> > >>>>> > > >> z4+g%AHrzW;vt^H{v=5sKp*aU1il;Y*r$;Ia^Y}#fbHM2rGIS}|nrc>1Ne1U9ee<(e > >> > >>>>> > > >> z{&18JjB@`B48?@mEPm@A`T+R6^(hEDWx-U@F$ouS;wIldeGtiCDpz<px&I1cf~^od > >> > >>>>> > > >> zN%W~-ywM^`V#T5x`m;+xXUl^t?Y1c#oPFl|)POywWv3Ue1Rf=pkRD22iI#s?!(zJg > >> > >>>>> > > >> zALmv^$p~`W5H3@mm}crh;p#o{<J!5r$k%+Po@tx-*!o`2m(0u5XnMFxfV~6WdcQKs > >> > >>>>> > > >> z2!&cJ<gb+rKfCzGl@h)vL4`g#`Ci)o8TsPEJtNcvs`179wMRyppjGD=u9aiOl~V{M > >> > >>>>> > > >> z1?O`1{aMD1Zx%(YC&-OGQ@OP2irm@5yet7qtA^*i<cO_=*_S2{{+@r-<imD)W{g)( > >> > >>>>> > > >> z(I^dg!5C6}u}FmN5KJ(h+IyatbISifm}l$LOkVzs))VbdpHqIr*fe_s_)-392h0bK > >> > >>>>> > > >> z#q7l;k(AFoiVxgvb^SK2^sWs$7pVbI7Uhnl=+@%!=@OIUzb+6J<47Lc*8x6?Gup>j > >> > >>>>> > > >> zfdKa#|H%{VV1xHqm!f}G#o(t=TSQ#U=4JOAti>7GRvj)oi$!`#5kRe^uSsCFF}1s+ > >> > >>>>> > > >> zJO;GkMoocZc}bvxWu8aQ29|!{E@UXVi7X)9f{Brr!dd(}=7S_1aVRHtJd)rk(t1@V > >> > >>>>> > > > > On 3 July 2014 09:20, Taras Kondratiuk <taras.kondratiuk@linaro.org> > wrote: > > We should decide who is the main user/consumer of this arch document, > > because they have different needs. > > > > - current developers (we) who are contributing/reviewing the document > > will most probably prefer patches, because it is easier to follow > > what is changing without need to read through a whole updated > > document. > > - New developers will read a whole document anyway so they don't care > > much about history. > > - SC need to get rendered document, maybe with highlighted changes. > > > > > > On 07/03/2014 07:04 PM, Mike Holmes wrote: > >> > >> Can everyone please weigh in with their thoughts, we need consensus on > >> this before we can make progress with the Arch doc. > >> > >> Thanks BIll / Mike > >> > >> > >> On 3 July 2014 11:25, Anders Roxell <anders.roxell@linaro.org > >> <mailto:anders.roxell@linaro.org>> wrote: > >> > >> On 2014-07-03 10:01, Bill Fischofer wrote: > >> > The people who review and approve these docs want to see docs > >> with things > >> > like change bars, not patches. The patch mechanism is simply > >> inappropriate > >> > for this activity and we shouldn't try to force-fit it for > >> something it's > >> > not designed to address. > >> > > >> > Again, the primary users of the odp-architecture git repository > >> are those > >> > who want access to complete docs, not those who are creating, > >> reviewing, > >> > and approving them. That's why we have a separate repository > >> from the main > >> > odp git repository so that "patches" can be handled differently > >> between > >> > them. > >> > >> That is why we use doxygen so that people reviewing for approval can > >> look > >> at the end result... However, isn't it better if anyone on the list > >> can > >> review the patch and send patches when that is needed? > >> > >> SC approval should only be required for major revisions. > >> Possibly only a final read through review for every ODP release. > >> > >> > > >> > My preference would be to grant push rights to those adding items > >> to this > >> > repository rather than going through the artifice of patches. It > >> would be > >> > more straightforward and consistent with the actual workflow. > >> Git would > >> > still be doing version tracking so it would be possible to see > >> the complete > >> > change history for any given doc easily. > >> > >> We should use git as a revision control system as it is, to allow us > >> to > >> make small changes when we discover them. > >> > >> > >> Cheers, > >> Anders > >> > >> > > >> > > >> > On Thu, Jul 3, 2014 at 9:52 AM, Mike Holmes > >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> wrote: > >> > > >> > > I agree we need approval, but approval can be of a review of > >> the patch to > >> > > the text. > >> > > > >> > > I hope we don't need wholesale changes that need a complete re > >> write and > >> > > thus approval of a whole new document. For example a new patch > >> which may > >> > > add a new function to an API but we would hopefully not change > >> any of the > >> > > existing text in the main. > >> > > > >> > > Thus we can then make changes in manageable chunks, I agree > >> that large > >> > > new additions will come in via a pre approved hugue patch, > >> created from a > >> > > sequence of sprints just have we have done so far. > >> > > > >> > > I would argue that these small changes are likely given the > >> additions > >> > > already discovered by starting the validation testing work and > >> the feedback > >> > > it is generating with the need to be more specific in > >> architectural areas. > >> > > > >> > > Mike > >> > > > >> > > > >> > > On 3 July 2014 10:44, Bill Fischofer < > bill.fischofer@linaro.org > >> <mailto:bill.fischofer@linaro.org>> wrote: > >> > > > >> > >> Design documents require approval by those who aren't going to > >> be > >> > >> reviewing patches. This is different from code. My > >> understanding of the > >> > >> purpose of the odp-architecture repository is to provide a > >> convenient means > >> > >> of distributing documentation and making it available in > >> various forms > >> > >> (Doxygen, PDF) for access through the ODP web site as well as > >> being > >> > >> downloaded. > >> > >> > >> > >> So in this sense we're just using Git as a publication > >> mechanism for docs. > >> > >> > >> > >> > >> > >> On Thu, Jul 3, 2014 at 9:37 AM, Mike Holmes > >> <mike.holmes@linaro.org <mailto:mike.holmes@linaro.org>> > >> > >> > >> wrote: > >> > >> > >> > >>> I am confused git is a change control mechanism, and I really > >> hope they > >> > >>> do get patched, how will we improve the content ? > >> > >>> > >> > >>> > >> > >>> On 3 July 2014 10:03, Bill Fischofer > >> <bill.fischofer@linaro.org <mailto:bill.fischofer@linaro.org>> > wrote: > >> > >>> > >> > >>>> Git is a publication mechanism for docs, not a change > control > >> > >>>> mechanism. Docs will not be 'patched'. New versions will > >> replace old ones > >> > >>>> as they are approved. > >> > >>>> > >> > >>>> > >> > >>>> On Thu, Jul 3, 2014 at 8:52 AM, Anders Roxell > >> <anders.roxell@linaro.org <mailto:anders.roxell@linaro.org> > >> > >> > >>>> > wrote: > >> > >>>> > >> > >>>>> On 2014-07-02 12:46, Bill Fischofer wrote: > >> > >>>>> > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org > >> <mailto:bill.fischofer@linaro.org>> > >> > >> > >>>>> > --- > >> > >>>>> > crypto_design.dox | 455 > >> > >>>>> ++++++++++++++++++++++++++++++++++++++++++++++++++ > >> > >>>>> > images/syncmodels.png | Bin 0 -> 17179 bytes > >> > >>>>> > 2 files changed, 455 insertions(+) > >> > >>>>> > create mode 100644 crypto_design.dox > >> > >>>>> > create mode 100644 images/syncmodels.png > >> > >>>>> > > >> > >>>>> > diff --git a/crypto_design.dox b/crypto_design.dox > >> > >>>>> > new file mode 100644 > >> > >>>>> > index 0000000..1ad2ac6 > >> > >>>>> > --- /dev/null > >> > >>>>> > +++ b/crypto_design.dox > >> > >>>>> > @@ -0,0 +1,455 @@ > >> > >>>>> > +/* Copyright (c) 2043, Linaro Limited > >> > >>>>> > + * All rights reserved > >> > >>>>> > + * > >> > >>>>> > + * SPDX-License-Identifier: BSD-3-Clause > >> > >>>>> > + */ > >> > >>>>> > + > >> > >>>>> > +/** > >> > >>>>> > +@page crypto_design ODP Design - Crypto API > >> > >>>>> > +For the implimentation of the ODP crypto API please see > >> @ref > >> > >>>>> odp_crypto.h > >> > >>>>> > + > >> > >>>>> > +@tableofcontents > >> > >>>>> > + > >> > >>>>> > +@section revision_history Revision History > >> > >>>>> > +Revision | Issue Data | Description | Author > >> > >>>>> > +---------|------------|-------------|-------- > >> > >>>>> > +0.1 | 4/9/2014 | Introduction started, Basic > >> Functions | > >> > >>>>> Bill, Alexandru > >> > >>>>> > +0.2 | 4/15/2014 | Completed intro, added TOC, > >> started use > >> > >>>>> cases, miscellaneous formatting, API comments | Bill > >> > >>>>> > +0.3 | 4/22/2014 | Added Use Case section to > >> include results > >> > >>>>> of design discussions held during ODP team calls | Bill > >> > >>>>> > +0.4 | 4/30/2014 | Design review from ODP crypto > >> > >>>>> sprint--action to resolve | Bill > >> > >>>>> > +0.5 | 5/5/2014 | Rewrite incorporating review > >> > >>>>> comments--ready for final review | Bill > >> > >>>>> > +1.0 | 5/30/2014 | Final version for LNG-SC > >> approval | Bill > >> > >>>>> > + > >> > >>>>> > +@section introduction Introduction > >> > >>>>> > +This document describes the ODP v1.0 Crypto API. > >> Cryptography is an > >> > >>>>> important part of data plane processing as many > >> communication protocols > >> > >>>>> make use of cryptographic functions. Moreover, many SoCs > >> incorporate > >> > >>>>> cryptographic hardware that can significantly accelerate > >> these operations > >> > >>>>> compared to their software equivalents as well as provide > >> validated > >> > >>>>> hardware functional correctness and security boundaries > >> necessary for > >> > >>>>> system-level security certifications such as FIPS-140 Level > >> 2 and above. > >> > >>>>> > +@section requirements Requirements > >> > >>>>> > +@subsection use_of_terms Use of Terms > >> > >>>>> > +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 [RFC 2119]( > >> > >>>>> https://tools.ietf.org/html/rfc2119). > >> > >>>>> > +@subsection uses_of_cryptography Uses of Cryptography > >> > >>>>> > +Crypto functions cover a range of uses and capabilities > >> designed to > >> > >>>>> support data security, integrity, authentication, and > >> non-repudiation. > >> > >>>>> > +@subsubsection data_security Data Security > >> > >>>>> > +Cryptography supports data security by making use of > >> complex > >> > >>>>> mathematical transformations that are not feasibly > >> reversible without > >> > >>>>> possession of the secret key used to encrypt message data. > >> > >>>>> > +@subsubsection data_integrity Data Integrity > >> > >>>>> > +Cryptography supports data integrity through the use of > >> > >>>>> cryptographic checksums (also known as secure hashes) that > >> ensure the > >> > >>>>> recipient that message data has not been altered either > >> accidentally or > >> > >>>>> maliciously while in transit. > >> > >>>>> > +@subsubsection data_authentication Data Authentication > >> > >>>>> > +Cryptography supports data authentication through the > >> uses of > >> > >>>>> Message Authentication Codes (MACs) that enable the > >> recipient to verify > >> > >>>>> that a message was sent from an authorized counterparty, > >> and hence was not > >> > >>>>> forged. > >> > >>>>> > +@subsubsection data_non_repudiation Data Non-Repudiation > >> > >>>>> > +Cryptography supports data non-repudiation through the > >> use of > >> > >>>>> digital signatures that enable a recipient or third party > >> to verify the > >> > >>>>> identity of the sending party and prevents the sending > >> party from later > >> > >>>>> denying that they originated a signed message. > >> > >>>>> > +@subsection scope Scope > >> > >>>>> > +ODP v1.0 crypto support is designed to provide a > >> portable framework > >> > >>>>> for accessing SoC-specific cryptographic functions of most > >> use to the data > >> > >>>>> plane. This is predominantly symmetric crypto operations > >> used to support > >> > >>>>> the encryption and decryption of data at line rate using > >> hardware > >> > >>>>> acceleration and offload. Specifically excluded in this > >> support are public > >> > >>>>> key operations and other crypto functions mainly used in > >> the control plane. > >> > >>>>> > +@subsection cryptographic_operations_in_the_data_plane > >> > >>>>> Cryptographic Operations in the Data Plane > >> > >>>>> > +ODP v1.0 crypto APIs cover the following areas: > >> > >>>>> > +@subsubsection ciphering Ciphering > >> > >>>>> > +Ciphering refers to mathematical transformations that > >> use a secret > >> > >>>>> key to encipher data, transforming the original data > >> (referred to as > >> > >>>>> plaintext) into ciphertext, thereby making it > >> unintelligible to anyone not > >> > >>>>> in possession of the key. Similarly, ciphering is also used > >> to decipher > >> > >>>>> data, allowing someone in possession of the correct key to > >> transform > >> > >>>>> received ciphertext back into plaintext. Approved block > >> ciphers are listed > >> > >>>>> > >> [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) > and > >> > >>>>> SHOULD be supported by each ODP implementation. > >> > >>>>> > +@subsubsection hasing Hashing > >> > >>>>> > +A hash is a cryptographic digest of a message that can > >> be used to > >> > >>>>> represent it for comparison or integrity checking. Hash > >> functions are > >> > >>>>> designed so that any alteration of a message will alter the > >> hash and that > >> > >>>>> it is computationally infeasible to craft a message that > >> generates the same > >> > >>>>> hash value as another message. Secure hash functions > >> approved for > >> > >>>>> cryptographic use are listed by NIST [here]( > >> > >>>>> http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html > ) > >> and > >> > >>>>> SHOULD be supported by each ODP implementation. > >> > >>>>> > +@subsubsection zeroization Zeroization > >> > >>>>> > +To preserve the security of data, certain transient data > >> held in > >> > >>>>> data buffers MUST be cleared to zeros upon buffer free. > >> Such capability is > >> > >>>>> referred to as zeroization. ODP supports zeroization as a > >> buffer pool > >> > >>>>> attribute. > >> > >>>>> > +@subsubsection random_number_generation Random Number > >> Generation > >> > >>>>> > +Because cryptography relies heavily on “unguessable” > keys > >> of > >> > >>>>> various sorts, random number generation (RNG) is an > >> integral part of > >> > >>>>> cryptographic processing. Random numbers are used in key > >> generation, > >> > >>>>> initialization vectors (IVs), various types of padding > >> bytes, and various > >> > >>>>> other uses collectively referred to as nonces, that serve > >> to “harden” > >> > >>>>> cryptographic processing. > >> > >>>>> > + > >> > >>>>> > +There are two types of random number support of > >> interest. Hardware > >> > >>>>> random data, also known as entropy, that is the result of > >> inherently random > >> > >>>>> physical processes, and deterministic random bit generation > >> (DRBG) that is > >> > >>>>> used in certain certified cryptographic operations. > >> Approved DRBG > >> > >>>>> algorithms are listed in [NIST SP 800-90A]( > >> > >>>>> http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does > >> not > >> > >>>>> specify which algorithms are available on a given > >> implementation. As such > >> > >>>>> ODP implementations MAY use any approved DRGB algorithm but > >> SHOULD support > >> > >>>>> at least one of them. Additionally, ODP implementations > >> MUST NOT represent > >> > >>>>> non-approved algorithms as DRBG implementations. Validated > >> algorithms are > >> > >>>>> listed in the [NIST DRBG Validation List]( > >> > >>>>> > >> http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). > >> > >>>>> > + > >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > >> > >>>>> > +To enable applications to adapt to the implementation > >> models > >> > >>>>> offered across different SoC platforms, ODP provides APIs > >> to allow > >> > >>>>> applications to inquire about underlying crypto > >> capabilities. A given ODP > >> > >>>>> implementation may offer crypto as hardware features, > >> software features, or > >> > >>>>> not available on a given platform. > >> > >>>>> > +@subsection cryptographic_algorithms Cryptographic > >> Algorithms and > >> > >>>>> Protocols > >> > >>>>> > +A cryptographic algorithm is a mathematical transform > >> that provides > >> > >>>>> one of the cryptographic operations described above. They > >> in turn are used > >> > >>>>> as building blocks in creating cryptographic protocols. > >> These are complete > >> > >>>>> sets of rules for how to exchange data securely using > >> cryptography. Both > >> > >>>>> cryptographic algorithm and protocol design are highly > >> specialized > >> > >>>>> disciplines that involve high levels of public scrutiny and > >> validation. As > >> > >>>>> a result, applications simply make use of approved > >> cryptographic algorithms > >> > >>>>> and protocols. > >> > >>>>> > +@subsection cryptographic_operations Cryptographic > >> Operations > >> > >>>>> > +Cryptographic operations may be initiated by software or > >> directly > >> > >>>>> by hardware as part of the RX or TX packet path processing. > >> For ODP v1.0 > >> > >>>>> software-initiated cryptographic operations are the primary > >> use case. ODP > >> > >>>>> provides APIs for performing data ciphering, hashing, > >> random number > >> > >>>>> generation, and capability inquiry. > >> > >>>>> > +@subsection performance_expectations Performance > >> Expectations > >> > >>>>> > +In the data plane, the total processing budget for a > >> packet may > >> > >>>>> only be a few hundred cycles, so function invocation > >> overhead MUST be kept > >> > >>>>> to a minimum. This has several implications. > >> > >>>>> > + > >> > >>>>> > +-# When work is dispatched to a thread, all information > >> needed by > >> > >>>>> the thread to process the work request SHOULD be > >> immediately at hand. > >> > >>>>> Ideally any context or variables needed for the operation > >> have been > >> > >>>>> pre-warmed in the cache to avoid the latency hits > >> associated with cache > >> > >>>>> misses. SoCs having hardware schedulers generally do this > >> pre-staging of > >> > >>>>> data to minimize such latencies, and ODP implementations > >> are expected to > >> > >>>>> exploit such platform capabilities whenever possible.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Calls to ODP functions SHOULD NOT involve excessive > >> amounts of > >> > >>>>> parameter passing and (depending on the implementation) > >> SHOULD be inlined > >> > >>>>> as much as possible to avoid call overhead. One technique > >> that has proven > >> > >>>>> useful is to allow for parameters to be passed as an > >> explicit thread-local > >> > >>>>> static structure. Such use of “templating” means that a > >> single function can > >> > >>>>> support a rich set of options but the caller can configure > >> a template > >> > >>>>> matched to specific use and only vary the one or two > >> parameters that differ > >> > >>>>> from call to call.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Kernel traps or interrupts SHOULD NOT be part of any > >> > >>>>> non-exception path function processing. Kernel calls and > >> such are > >> > >>>>> acceptable only during one-time initialization logic or > >> certain types of > >> > >>>>> unusual error recovery operations. Often the best way to > >> handle the latter > >> > >>>>> is to pass the work to a dedicated recovery thread (or back > >> to the control > >> > >>>>> plane) rather than attempting to handle the condition > >> inline. For example, > >> > >>>>> a link-down condition will trigger various recovery actions > >> that might best > >> > >>>>> be handled in this manner. > >> > >>>>> > + > >> > >>>>> > +@subsection use_by_existing_code Use by Existing Code > >> > >>>>> > +Most applications wishing to make use of ODP represent > >> substantial > >> > >>>>> existing investment that must be preserved. Insofar as > >> possible, ODP > >> > >>>>> functions need to be orthogonal to existing application > >> environments and > >> > >>>>> structures to permit easy intermixing with pre-existing > code. > >> > >>>>> > +@subsection data_references Data References > >> > >>>>> > +Packet data is inherently of variable length however it > >> is often > >> > >>>>> more efficient to organize memory into fixed-sized buffers > >> that can be > >> > >>>>> chained together on demand to contain packets. The > >> application SHOULD > >> > >>>>> normally not need to be aware of such lower-level > >> segmentation and should > >> > >>>>> be able to treat a packet as a single object. Alternately, > >> especially when > >> > >>>>> dealing with existing code, data segmentation MUST be > >> explicitly > >> > >>>>> specifiable via scatter/gather lists. For example, data > >> encryption or > >> > >>>>> decryption may be invoked on a list of data segments as > >> part of a single > >> > >>>>> function call. > >> > >>>>> > >> > >>>>> Every time you add a full stop for a sentence, you have to > >> press return > >> > >>>>> and start typing the next sentence. > >> > >>>>> This means that diffs of future changes will be per > sentence. > >> > >>>>> Doxygen will still concatenate this as a paragraph with no > >> visual > >> > >>>>> difference in the result. > >> > >>>>> I think the above line will look like this: > >> > >>>>> > >> > >>>>> Packet data is inherently of variable length however it is > >> often more > >> > >>>>> efficient to organize memory into fixed-sized buffers that > >> can be chained > >> > >>>>> together on demand to contain packets. > >> > >>>>> The application SHOULD normally not need to be aware of > such > >> > >>>>> lower-level segmentation and should be able to treat a > >> packet as a single > >> > >>>>> object. > >> > >>>>> Alternately, especially when dealing with existing code, > data > >> > >>>>> segmentation MUST be explicitly specifiable via > >> scatter/gather lists. > >> > >>>>> For example, data encryption or decryption may be invoked > >> on a list of > >> > >>>>> data segments as part of a single function call. > >> > >>>>> > >> > >>>>> > >> > >>>>> Cheers, > >> > >>>>> Anders > >> > >>>>> > >> > >>>>> > +@subsection chained_operations Chained Operations > >> > >>>>> > +Crypto operations such as hashing and encryption, or > >> decryption and > >> > >>>>> verification, are very commonly used in combination. For > >> ODP, it is > >> > >>>>> sufficient to support one cipher and one > >> hash/authentication operation in a > >> > >>>>> single call and this combination MUST be supported to avoid > >> the call and > >> > >>>>> dispatch overhead of separate invocations. > >> > >>>>> > +@subsection key_management Key Management and Session > Data > >> > >>>>> > +Keying is an area of particular sensitivity in crypto > >> processing > >> > >>>>> since keys are highly confidential and may be subject to > >> legal requirements > >> > >>>>> for safeguarding within special hardware enclosures. > >> > >>>>> > + > >> > >>>>> > +A session is the security context used to represent an > >> active set > >> > >>>>> of crypto operations that need to be applied to a flow on a > >> > >>>>> packet-by-packet basis. Generally a session is established > >> upon detection > >> > >>>>> of a flow requiring crypto processing and retained for the > >> life of that > >> > >>>>> flow. It has been noted that this can involve cooperative > >> processing > >> > >>>>> between the control and data planes so several requirements > >> stem from this: > >> > >>>>> > + > >> > >>>>> > +-# Session creation MAY need to be handled in an > >> asynchronous > >> > >>>>> manner. This is to allow these to be created in batches by > >> thread(s) that > >> > >>>>> specialize in this activity.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Sessions MAY need to reference keying material > >> indirectly via > >> > >>>>> key handling modules.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Session creation MAY be performed by non-ODP code and > >> > >>>>> communicated to data plane routines that make use of ODP > >> crypto functions > >> > >>>>> that need to reference the session information. > >> > >>>>> > + > >> > >>>>> > +ODP session APIs and data structures SHOULD be > >> represented by > >> > >>>>> abstract data types that encapsulate implementation details > >> for both > >> > >>>>> platform efficiency and to accommodate these needs. > >> > >>>>> > +Use Cases > >> > >>>>> > +For ODP v1.0 the major use cases of interest involve > >> cryptographic > >> > >>>>> algorithm acceleration. Cryptographic protocol acceleration > >> is reserved for > >> > >>>>> future ODP releases. > >> > >>>>> > +Buffers and Data Blocks > >> > >>>>> > +Cryptographic operations may be performed directly on > data > >> > >>>>> contained in ODP packet buffers, or it may be performed on > >> “raw” data > >> > >>>>> blocks operating entirely under application control. Note > >> that when using > >> > >>>>> raw data blocks not managed by ODP, the application must > >> perform any needed > >> > >>>>> zeroization using either its own or ODP-supplied buffer > >> zeroization > >> > >>>>> functions. ODP automatic support for zeroization is limited > >> to ODP-managed > >> > >>>>> buffers. ODP buffers allocated from buffer pools designated > >> for crypto use > >> > >>>>> will also have whatever alignment and/or addressability > >> attributes needed > >> > >>>>> by the implementation to support crypto API calls. > >> > >>>>> > + > >> > >>>>> > +Note: Some implementations may have difficulty dealing > >> with > >> > >>>>> application buffer addresses, as these may be virtual > >> addresses that are > >> > >>>>> mapped discontiguously into physical memory. For such > >> implementations, > >> > >>>>> memory SHOULD be allocated contiguously and MAY need to be > >> “registered” to > >> > >>>>> have proper addressability for crypto operations. This area > >> of the design > >> > >>>>> will be updated based on experience in dealing with > >> different crypto > >> > >>>>> implementations that have such requirements. > >> > >>>>> > +Synchronization > >> > >>>>> > +ODP operations fall into one of three categories: > >> > >>>>> > + > >> > >>>>> > +-# Inline (Synchronous): Upon return from a call the > >> operation is > >> > >>>>> complete. Operation is thus completely synchronous to the > >> caller. Inline > >> > >>>>> is the appropriate model when the invoked function takes > >> relatively few > >> > >>>>> cycles or when the caller cannot feasibly progress without > >> the results of > >> > >>>>> the invoked function.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Parallel: Upon return from a call the operation has > >> been > >> > >>>>> initiated, but is expected to complete shortly. The caller > >> continues to > >> > >>>>> execute until it needs the result at which point it waits > >> to complete the > >> > >>>>> parallel operation. The effect is as if the operation were > >> inline except > >> > >>>>> that the caller was able to execute in parallel with the > >> operation for some > >> > >>>>> application-determined period of time. Parallel is the > >> appropriate model > >> > >>>>> when the operation being performed is relatively short (a > >> few dozen up to > >> > >>>>> perhaps 100 or 200 cycles) and the caller can usefully > >> accomplish other > >> > >>>>> processing on the same unit of work while the parallel > >> operation is in > >> > >>>>> progress, but not enough to justify the overhead of a > >> formal queued work > >> > >>>>> dispatch.\n\n > >> > >>>>> > + > >> > >>>>> > +-# Offloaded (Asynchronous): Upon return from the call > the > >> > >>>>> operation has been queued for execution. A completion event > >> will be queued > >> > >>>>> back to the scheduler when the event is completed. Offload > >> is the > >> > >>>>> appropriate model when the invoked function will take a > >> substantial amount > >> > >>>>> of cycles (thousands to tens of thousands) allowing the > >> invoking > >> > >>>>> thread/core to service other work until the operation > >> completes. For > >> > >>>>> offloaded work, completion is indicated by a completion > >> event being posted > >> > >>>>> back to an application-designated completion queue. Upon > >> receipt the unit > >> > >>>>> of work that initiated the offloaded operation continues > >> processing with > >> > >>>>> the results of the call. > >> > >>>>> > + > >> > >>>>> > +The synchronization models of interest are summarized in > >> Figure 1: > >> > >>>>> > + > >> > >>>>> > + > >> > >>>>> > + > >> > >>>>> > +Note: Because few implementations are expected to offer > >> the > >> > >>>>> Parallel mode of operation as described above, this mode > >> is reserved for > >> > >>>>> potential future use. For ODP v1.0 only synchronous and > >> asynchronous crypto > >> > >>>>> operations are defined. > >> > >>>>> > +@section functional_definition Functional Definition > >> > >>>>> > +@subsection abstract_data_types Abstract data types > >> > >>>>> > +The following enumerations define various algorithms > >> used for > >> > >>>>> ciphering and hashing. These are the basic operations > >> applied to input data. > >> > >>>>> > + > >> > >>>>> > +A particular ODP implementation should map these values > >> to the > >> > >>>>> actual information to be passed to the crypto engine. As > >> such, the actual > >> > >>>>> values of these enums is implementation-defined. > >> > >>>>> > + > >> > >>>>> > +Cipher algorithm encoding specifies the algorithm and > >> cipher mode > >> > >>>>> employed (as per security relevant RFCs - [4305]( > >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > >> > >>>>> http://tools.ietf.org/html/rfc4494)). > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +enum odp_cipher_alg { > >> > >>>>> > + ODP_CIPHER_ALG_NULL, > >> > >>>>> > + ODP_CIPHER_ALG_DES, > >> > >>>>> > + ODP_CIPHER_ALG_3DES_CBC, > >> > >>>>> > + ODP_CIPHER_ALG_AES_CBC, > >> > >>>>> > + ODP_CIPHER_ALG_AES_GCM, > >> > >>>>> > + ODP_CIPHER_ALG_AES_CTR, > >> > >>>>> > + ODP_CIPHER_ALG_KASUMI, > >> > >>>>> > + ODP_CIPHER_ALG_SNOW, > >> > >>>>> > + ... > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Authorization algorithm encoding specifies the algorithm > >> and the > >> > >>>>> length of the authorization used (as per security relevant > >> RFCs - [4305]( > >> > >>>>> http://tools.ietf.org/html/rfc4305), [4868]( > >> > >>>>> http://tools.ietf.org/html/rfc4868), [4494]( > >> > >>>>> http://tools.ietf.org/html/rfc4494)): > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +enum odp_auth_alg { > >> > >>>>> > + ODP_AUTH_ALG_NULL, > >> > >>>>> > + ODP_AUTH_MD5_96, > >> > >>>>> > + ODP_AUTH_ALG_SHA1_96, > >> > >>>>> > + ODP_AUTH_ALG_SHA1_160 > >> > >>>>> > + ODP_AUTH_ALG_SHA2_256_128, > >> > >>>>> > + ODP_AUTH_ALG_SHA2_384_192, > >> > >>>>> > + ODP_AUTH_ALG_SHA2_512_256, > >> > >>>>> > + ODP_AUTH_ALG_AES_CMAC_96, > >> > >>>>> > + ODP_AUTH_ALG_AES_XCBC_MAC_96, > >> > >>>>> > + ODP_AUTH_ALG_SNOW, > >> > >>>>> > + ODP_AUTH_ALG_KASUMI, > >> > >>>>> > + ... > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +typedef union odp_crypto_alg_t { > >> > >>>>> > + enum odp_cipher_alg cipher; > >> > >>>>> > + enum odp_auth_alg auth; > >> > >>>>> > +}odp_crypto_alg_t; > >> > >>>>> > +@endcode > >> > >>>>> > +@subsection parameter_structures Parameter Structures > >> > >>>>> > +@subsubsection crypto_sessions Crypto Sessions > >> > >>>>> > +The following structure describes a crypto session. All > >> packets / > >> > >>>>> raw data buffers processed in a session share the data that > >> defines the > >> > >>>>> session. A crypto session is defined by: > >> > >>>>> > + > >> > >>>>> > +- Operation type : encode or decode\n\n > >> > >>>>> > + > >> > >>>>> > +- Algorithms specifications, keys and , if required, > >> initialization > >> > >>>>> vectors. When initialization vectors are not provided and > >> they should be > >> > >>>>> provided automatically by the crypto engine.\n\n > >> > >>>>> > + > >> > >>>>> > +- The operation mode: synchronous or asynchronous. > >> Synchronous > >> > >>>>> operation blocks the caller until an operation status and > >> result are > >> > >>>>> available. In synchronous mode there is at most only one > >> outstanding crypto > >> > >>>>> operation in the calling thread. In asynchronous mode, the > >> caller starts > >> > >>>>> the crypto operation and later it may receive the status > >> and the result > >> > >>>>> together with a request context. The operation status and > >> result may also > >> > >>>>> be received by a different thread.\n\n > >> > >>>>> > + > >> > >>>>> > +- Operation mode parameters: For asynchronous operation > a > >> > >>>>> completion event containing the status, the result and the > >> request context > >> > >>>>> is enqueued to a completion queue. In case the queue is > >> under the scheduler > >> > >>>>> control, the scheduler determines who will receive the > >> completion event and > >> > >>>>> when. When the completion queue is not scheduled, the > >> thread which is > >> > >>>>> supposed to get the operation output has to explicitly poll > >> the completion > >> > >>>>> queue. > >> > >>>>> > + > >> > >>>>> > +Note that this is an abstract data type and its > structure > >> is > >> > >>>>> implementation-specific. The layout shown here is for > >> illustrative purposes > >> > >>>>> and the actual layout will vary from one implementation to > >> the next to most > >> > >>>>> closely align with the structures needed by the underlying > >> SoC platform. > >> > >>>>> Applications set and reference fields in the session > >> structure via accessor > >> > >>>>> functions that hide the actual layout. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +typedef enum odp_crypto_op_t { > >> > >>>>> > + ODP_CRYPTO_OP_ENCODE, > >> > >>>>> > + ODP_CRYPTO_OP_DECODE > >> > >>>>> > +}odp_crypto_op_t; > >> > >>>>> > + > >> > >>>>> > +typedef struct odp_key_t { > >> > >>>>> > +}odp_key_t; > >> > >>>>> > + > >> > >>>>> > +typedef struct odp_crypto_session_t { > >> > >>>>> > + odp_crypto_op_t op; > >> > >>>>> > + struct { > >> > >>>>> > + enum odp_cipher_alg cipher_alg; > >> > >>>>> > + odp_key_t *key; > >> > >>>>> > + uint8_t *iv; > >> > >>>>> > + size_t iv_len; > >> > >>>>> > + } cipher; > >> > >>>>> > + > >> > >>>>> > + struct { > >> > >>>>> > + enum odp_auth_alg auth_alg; > >> > >>>>> > + enum odp_auth_len auth_len; > >> > >>>>> > + odp_key_t *key; > >> > >>>>> > + } auth; > >> > >>>>> > + > >> > >>>>> > + enum odp_crypto_op_mode { > >> > >>>>> > + ODP_CRYPTO_SYNC, > >> > >>>>> > + ODP_CRYPTO_ASYNC, > >> > >>>>> > + } op_mode; > >> > >>>>> > + > >> > >>>>> > + struct { > >> > >>>>> > + uint32_t timeout; > >> > >>>>> > + struct { > >> > >>>>> > + odp_queue_t completion_queue; > >> > >>>>> > + } async; > >> > >>>>> > + } op_mode_params; > >> > >>>>> > + > >> > >>>>> > + odp_session_proc_info_t session_proc_info; > >> > >>>>> > +} odp_crxsypto_session_t; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +The completion queue contained in the session structure > >> is an > >> > >>>>> in/out parameter. If provided, then the queue specified is > >> associated with > >> > >>>>> the session and is used to ensure order preservation on > >> that session. If > >> > >>>>> not provided, one is created and returned to the caller. > >> Note that this > >> > >>>>> completion queue is used to order operations performed on > >> this crypto > >> > >>>>> session. It should not be confused with the completion > >> queue specified on > >> > >>>>> the odp_crypto_session_create() call (see below) that is > >> used to control > >> > >>>>> whether that call is itself processed in a synchronous vs. > >> asynchronous > >> > >>>>> manner. > >> > >>>>> > + > >> > >>>>> > +The following structure comprises processing > >> information. This is > >> > >>>>> logically divided in two parts: > >> > >>>>> > + > >> > >>>>> > +- Processing input info - When crypto engine provides > >> support for > >> > >>>>> protocol processing, this information is provided in a > >> higher level common > >> > >>>>> protocol terminology form and a particular implementation > >> should be able to > >> > >>>>> derive everything it needs from this definition. In > >> addition, for crypto > >> > >>>>> engines able to automate tasks like memory allocation for > >> the output a > >> > >>>>> buffer pool id may be specified.\n\n > >> > >>>>> > + > >> > >>>>> > +- Processing output information - statistics about > >> processed > >> > >>>>> bytes/packets. These are useful when a session expiration > >> is based on > >> > >>>>> traffic volume. These statistics may be updated by the > >> software or by the > >> > >>>>> hardware crypto engine. > >> > >>>>> > + > >> > >>>>> > +Again, this is an abstract type whose specific layout > >> will vary > >> > >>>>> based on implementation considerations. Access to fields > >> contained in the > >> > >>>>> structure is only via accessor functions. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +typedef struct { > >> > >>>>> > + uint64_t pkts_processed; > >> > >>>>> > + uint64_t bytes_processed; > >> > >>>>> > + uint64_t pkts_errored; > >> > >>>>> > + uint64_t bytes_errored; > >> > >>>>> > + > >> > >>>>> > + odp_buffer_pool_t out_pool; > >> > >>>>> > + > >> > >>>>> > +} odp_session_proc_info_t; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +This enumeration defines which operations are applied > >> and the order. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +enum odp_crypto_combination { > >> > >>>>> > +ODP_CRYPTO_CIPHER_ONLY, > >> > >>>>> > + ODP_CRYPTO_AUTH_ONLY, > >> > >>>>> > + ODP_CRYPTO_AUTH_CIPHERTEXT > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +This structure defines a contiguous segment in the input > >> data which > >> > >>>>> starts at offset offset and is len bytes long. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +struct odp_data_range { > >> > >>>>> > + unsigned offset:16; > >> > >>>>> > + unsigned len:16; > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +@subsection api_functions API Functions > >> > >>>>> > + > >> > >>>>> > +@subsubfunction Session Creation > >> > >>>>> > + > >> > >>>>> > +This function is used to create a crypto session. The > >> required > >> > >>>>> parameters are : > >> > >>>>> > + > >> > >>>>> > +- Operation : encode/decode > >> > >>>>> > +- Processing info : cipher/auth/both > >> > >>>>> > +- Preferred mode : sync or async. > >> > >>>>> > +- Algorithms suites, keys and optional IV > >> > >>>>> > + > >> > >>>>> > +Session creation can be synchronous or asynchronous. > >> Completion > >> > >>>>> event argument is used to return the status and the session > >> handle. When > >> > >>>>> completion queue is not provided (synchronous call), the > >> completion event > >> > >>>>> is available upon function call return. When completion > >> queue is provided > >> > >>>>> (asynchronous call), the completion event is placed on the > >> completion queue. > >> > >>>>> > + > >> > >>>>> > +@code > >> > >>>>> > +typedef uint64_t odp_crypto_session_t; > >> > >>>>> > + > >> > >>>>> > +struct odp_session_params { > >> > >>>>> > + enum odp_crypto_operation op; > >> > >>>>> > + odp_session_proc_info_t proc_info; > >> > >>>>> > + enum odp_crypto_op_mode pref_mode; > >> > >>>>> > + enum odp_cipher_alg cipher_alg; > >> > >>>>> > + odp_key_t *cipher_key; > >> > >>>>> > + uint8_t *iv; > >> > >>>>> > + size_t iv_len; > >> > >>>>> > + enum odp_auth_alg auth_alg; > >> > >>>>> > + odp_key_t *auth_key; > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +enum odp_crypto_ses_create_err { > >> > >>>>> > + ODP_CRYPTO_SES_CREATE_NONE, > >> > >>>>> > + ODP_CRYPTO_SES_CREATE_ENOMEM, > >> > >>>>> > + /* Session creation error codes */ > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +void > >> > >>>>> > +odp_crypto_get_ses_create_compl_status(odp_buffer_t > >> > >>>>> completion_event, enum odp_crypto_ses_create_err *status); > >> > >>>>> > + > >> > >>>>> > +void > >> > >>>>> > +odp_crypto_get_ses_create_compl_handle(odp_buffer_t > >> > >>>>> completion_event, odp_crypto_session_t *handle); > >> > >>>>> > + > >> > >>>>> > +int odp_crypto_session_create( > >> > >>>>> > + struct odp_session_params *params, > >> > >>>>> > + odp_buffer_t completion_event, > >> > >>>>> > + odp_queue_t completion_queue); > >> > >>>>> > +@endcode > >> > >>>>> > +@subsection crypto_operation Crypto Operation > >> > >>>>> > + > >> > >>>>> > +Crypto operations are described by a parameter > structure: > >> > >>>>> > +@code > >> > >>>>> > +struct odp_crypto_op_params { > >> > >>>>> > + odp_crypto_session_t session; > >> > >>>>> > + odp_packet_t pkt; > >> > >>>>> > + odp_packet_t out_pkt; > >> > >>>>> > + uint8_t *override_iv_ptr; > >> > >>>>> > + unsigned hash_result_offset; > >> > >>>>> > + struct odp_data_range cipher_range; > >> > >>>>> > + struct odp_data_range auth_range; > >> > >>>>> > +}; > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +<table> > >> > >>>>> > +<tr><th>Parameter</th><th>Meaning</th></tr> > >> > >>>>> > +<tr><td>session</td><td>Session to perform the > >> operation</td></tr> > >> > >>>>> > +<tr><td>pkt</td><td>Packet / buffer to be > >> processed</td></tr> > >> > >>>>> > +<tr><td>out_pkt</td><td>Handle of an output packet / > >> buffer to be > >> > >>>>> returned as the result of the operation. There are three > >> different ways > >> > >>>>> this parameter is used, depending on the mode of operation > >> requested by the > >> > >>>>> caller and the capabilities of the underlying > >> implementation:\n\n > >> > >>>>> > + > >> > >>>>> > +-# If out_pkt is the same as pkt this indicates that the > >> operation > >> > >>>>> should be performed in place.\n\n > >> > >>>>> > +-# If out_pkt is different from pkt this indicates that > >> output > >> > >>>>> should be placed in the buffer supplied by the caller.\n\n > >> > >>>>> > +-# If out_pkt is omitted (a null/invalid value supplied > >> on input) > >> > >>>>> this indicates that an output buffer should be allocated by > >> the operation > >> > >>>>> and returned as part of the completion event associated > >> with the > >> > >>>>> operation.\n\n > >> > >>>>> > + > >> > >>>>> > +Note that not every implementation will support all of > >> these modes > >> > >>>>> and MAY require that one mode be used in preference to > >> others. Any such > >> > >>>>> implementation restrictions are communicated as output from > >> session > >> > >>>>> creation.</td></tr> > >> > >>>>> > +<tr><td>override_iv_ptr</td><td>Optional IV to use for > >> this > >> > >>>>> request</td></tr> > >> > >>>>> > +<tr><td>hash_result_offset</td><td>Offset into the > >> output packet > >> > >>>>> where the hash result should be stored.</td></tr> > >> > >>>>> > +<tr><td>cipher_range</td><td>The byte range > >> (offset:length) of the > >> > >>>>> data to be processed for ciphering.</td></tr> > >> > >>>>> > +<tr><td>auth_range</td><td>The byte range > >> (offset:length) of the > >> > >>>>> data to be processed for authentication.</td></tr> > >> > >>>>> > +</table> > >> > >>>>> > + > >> > >>>>> > +The crypto operation is initiated with a single call > >> that passes > >> > >>>>> the parameters for the operation and an event (for > >> asynchronous completion). > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_operation( > >> > >>>>> > + struct odp_crypto_op_params *params, > >> > >>>>> > + odp_buffer_t completion_event); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Parameter | Meaning > >> > >>>>> > +----------|-------- > >> > >>>>> > +params | The parameter structure describing the > >> crypto operation > >> > >>>>> to be performed. > >> > >>>>> > +completion_event | The event delivered on completion. It > >> provides > >> > >>>>> information about the status of the operation, result and > >> request context. > >> > >>>>> In synchronous mode the event is available upon function > >> call return. In > >> > >>>>> asynchronous mode, the event is placed on the session / > >> operation > >> > >>>>> completion queue when the operation finished. > >> > >>>>> > + > >> > >>>>> > +Upon return the return code indicates whether the > >> operation was > >> > >>>>> synchronous or asynchronous, or if an error occurred that > >> prevented the > >> > >>>>> operation from being performed. > >> > >>>>> > + > >> > >>>>> > +Get session operation : > >> > >>>>> > +@code > >> > >>>>> > +odp_crypto_op_t > >> > >>>>> > +odp_crypto_session_get_op(odp_crypto_session_t ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Get session cipher information : > >> > >>>>> > +@code > >> > >>>>> > +odp_cipher_alg > >> > >>>>> > +odp_cipher_session_get_cipher_alg(odp_crypto_session_t > >> ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Get session authentication information : > >> > >>>>> > +@code > >> > >>>>> > +odp_auth_alg > >> > >>>>> > +odp_crypto_session_get_auth_alg(odp_crypto_session_t > ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Change session IV : > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_session_iv_set(odp_crypto_session_t ses, > >> uint8_t > >> > >>>>> *iv); > >> > >>>>> > +@emdcode > >> > >>>>> > + > >> > >>>>> > +Change cipher or/and hash keys: > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_session_key_set(odp_crypto_session_t ses, > >> odp_key_t > >> > >>>>> *key); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Destroy crypto session. All pending operations are > >> cancelled. > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_session_destroy(odp_crypto_session_t > ses); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Get completion event information - algorithm error, > >> output and > >> > >>>>> context. Note that implementations MAY define their own > >> specific error > >> > >>>>> codes that have meaning in that context. For application > >> portability it is > >> > >>>>> sufficient to know whether an operation completed > >> successfully or > >> > >>>>> experienced an error of some sort. > >> > >>>>> > +@code > >> > >>>>> > +enum crypto_alg_err { > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_NONE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_MODE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_DATA_SIZE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_KEY_SIZE, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_ICV_CHECK, > >> > >>>>> > + ODP_CRYPTO_ALG_ERR_AAD_SIZE, > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +enum crypto_hw_err { > >> > >>>>> > + ODP_CRYPTO_HW_ERR_NONE, > >> > >>>>> > + ODP_CRYPTO_HW_ERR_DMA, > >> > >>>>> > + ODP_CRYPTO_HW_ERR_BP_DEPLETED, > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +struct odp_crypto_compl_status { > >> > >>>>> > + odp_crypto_alg_t alg; > >> > >>>>> > + enum crypto_alg_err alg_err; > >> > >>>>> > + enum crypto_hw_err hw_err; > >> > >>>>> > +}; > >> > >>>>> > + > >> > >>>>> > +void > >> > >>>>> > +odp_crypto_get_compl_status(odp_buffer_t > completion_event, > >> > >>>>> > + struct odp_crypto_compl_status > >> *auth, > >> > >>>>> > + struct odp_crypto_compl_status > >> *cipher); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Returns the output packet handle associated with the > >> completion > >> > >>>>> event : > >> > >>>>> > +@code > >> > >>>>> > +odp_packet_t > >> > >>>>> > +odp_crypto_get_out_pkt(odp_buffer_t completion_event); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Sets a context handle to be returned with the completion > >> event : > >> > >>>>> > +@code > >> > >>>>> > +void odp_crypto_set_compl_ctx(odp_buffer_t > >> completion_event, > >> > >>>>> odp_compl_ctx_t *ctx); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Returns the context associated with the completion > event : > >> > >>>>> > +@code > >> > >>>>> > +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t > >> > >>>>> completion_event); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +This section describes the API/Interface being defined > at > >> a > >> > >>>>> functional level in technical detail. Sub-sections include > >> header file > >> > >>>>> names, where implementation files are expected to reside in > >> the ODP git > >> > >>>>> tree, as well as the name, parameters, abstract data types, > >> functionality, > >> > >>>>> return codes, and exception conditions of each function > >> call defined by the > >> > >>>>> API/Interface. Appropriate diagrams, tables, etc. should be > >> used to allow > >> > >>>>> the programmer tasked with implementing the API/Interface > >> to understand the > >> > >>>>> function to be implemented as well as error conditions, > >> corner cases, > >> > >>>>> performance requirements, etc. needed to implement the > >> described > >> > >>>>> API/Interface in a functionally correct and efficient > manner. > >> > >>>>> > + > >> > >>>>> > +@subsubsection random_number_functions Random Number > >> Functions > >> > >>>>> > +As noted earlier, random number support consists of two > >> functions: > >> > >>>>> > +@code > >> > >>>>> > +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool > >> > >>>>> use_entropy); > >> > >>>>> > + > >> > >>>>> > +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +The difference is that the first provides access to > >> hardware random > >> > >>>>> number functions that return true random data. This is > >> typically used for > >> > >>>>> seed values. The second provides a deterministic random bit > >> generator > >> > >>>>> conforming to NIST standards and is used by various crypto > >> protocols and > >> > >>>>> algorithms. The use_entropy parameter on odp_hw_random_get > >> is used to > >> > >>>>> disable any hardware pre-processing normally provided by > >> the function and > >> > >>>>> is mainly intended to be used for testing/validation > >> purposes. > >> > >>>>> > + > >> > >>>>> > +@subsubsection buffer_pool_extensions Buffer Pool > >> Extensions > >> > >>>>> > +To support zeroization a buffer may be allocated with an > >> > >>>>> ODP_CLEAR_ON_FREE attribute that specifies that this buffer > >> should be > >> > >>>>> zeroized upon free. Alternately, a new type > >> (ODP_CLEAR_ON_FREE) is added to > >> > >>>>> odp_buffer_pool_create() that specifies that all buffers > >> allocated from > >> > >>>>> this pool must be zeroized upon free. Essentially, the > >> buffer security > >> > >>>>> attribute is set by default from the attributes of the > >> buffer pool that it > >> > >>>>> is allocated from. > >> > >>>>> > + > >> > >>>>> > +@subsubsection capability_inquiry Capability Inquiry > >> > >>>>> > +To enable applications to determine crypto capabilities. > >> > >>>>> > +@code > >> > >>>>> > +int odp_crypto_inquire (enum odp_cipher_alg, enum > >> odp_auth_alg); > >> > >>>>> > +@endcode > >> > >>>>> > + > >> > >>>>> > +Inquires whether the specified crypto and auth > >> algorithms are > >> > >>>>> supported. Responses include: > >> > >>>>> > +- ODP_HW_SYNC_SUPPORT > >> > >>>>> > +- ODP_HW_ASYNC_SUPPORT > >> > >>>>> > +- ODP_SW_SYNC_SUPPORT > >> > >>>>> > +- ODP_SW_ASYNC_SUPPORT > >> > >>>>> > +- ODP_NO_SUPPORT > >> > >>>>> > + > >> > >>>>> > +HW support means the combination is supported in > >> hardware, SW > >> > >>>>> support means the combination is supported in software by > the > >> > >>>>> implementation. No support means the combination is not > >> supported by the > >> > >>>>> implementation. The SYNC and ASYNC return options can help > >> the application > >> > >>>>> decide how to invoke these functions, or it can just check > >> whether or not > >> > >>>>> the response is ODP_NO_SUPPORT. > >> > >>>>> > + > >> > >>>>> > +@section implementation_considerations Implementation > >> Considerations > >> > >>>>> > +One of the main purposes for the ODP crypto APIs is to > >> provide > >> > >>>>> portable access across different SoCs whose hardware crypto > >> capabilities > >> > >>>>> largely overlap but vary in terms of their implementation > >> details. As a > >> > >>>>> result, implementations need not provide software fill-ins > >> for specific > >> > >>>>> cryptographic features that are not available as hardware > >> features on that > >> > >>>>> platform. Presumably applications needing specific features > >> will select > >> > >>>>> platforms on which these features are present. Therefore, > >> while all APIs > >> > >>>>> specified here MUST exist in each conforming ODP > >> implementation, it is > >> > >>>>> acceptable for these APIs to return > >> ODP_RC_FEATURE_NOT_PRESENT in response > >> > >>>>> to calls requesting crypto features not present on that > >> platform. > >> > >>>>> > + > >> > >>>>> > +For example, the linux-generic ODP implementation may > only > >> > >>>>> implement the null cipher suite (ODP_CIPHER_ALG_NULL) and > >> return a feature > >> > >>>>> not present error code for any other cipher. This > >> indication will also be > >> > >>>>> returned on that platform in response to odp_crypto_inquire > >> calls for > >> > >>>>> non-null cipher algorithms. > >> > >>>>> > + > >> > >>>>> > +@section verification Verification/Testing > >> > >>>>> > +This section describes the verification/test cases > >> needed to ensure > >> > >>>>> that the defined functionality is implemented correctly and > >> performs > >> > >>>>> adequately. This should be at a level of detail such that > >> the programmer > >> > >>>>> tasked with writing test scripts/programs to verify the > >> implementation(s) > >> > >>>>> of the defined functions can be written to ensure that all > >> relevant > >> > >>>>> functional variants and error/exception cases are properly > >> tested. > >> > >>>>> > + > >> > >>>>> > +This section needs to be completed before API testing > >> begins. > >> > >>>>> > + > >> > >>>>> > +*/ > >> > >>>>> > \ No newline at end of file > >> > >>>>> > diff --git a/images/syncmodels.png > b/images/syncmodels.png > >> > >>>>> > new file mode 100644 > >> > >>>>> > index > >> > >>>>> > >> > >> > 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 > >> > >>>>> > GIT binary patch > >> > >>>>> > literal 17179 > >> > >>>>> > > >> zcmch;XH?Tcv@Z$>iXhSqNDxrER8c~aDjh?WUL(Et-Vx~th$xXJz4smxnsljBLkDS* > >> > >>>>> > > >> z-U&T7c+PqEth3g=pWb`(A^(+`Ju`dSo?U(urKTcJLIfnj!NDO>RFHXxgM;UcgM-UP > >> > >>>>> > > >> zco&=V+&Rz%2S;jIQRa=N_smYZm=g1R%A)G;H}~-I@#)CiCI2J+roi>GZf!`WZf2C^ > >> > >>>>> > > >> z)RvpX$JcFtiQ5qoYL6FkUycg*4Vd+@&4{rjkG>nkclWe8rfD1Kcc1XHC~lIRaY%yb > >> > >>>>> > > >> z&#AzVI)|_y#V9pZhT`)S%d?B?+??Iw*B&jKn(0AesGPJrSZ@CB2`0NB4)JL96L+p} > >> > >>>>> > > >> z2EA*#7UJYgNNv7slHc$~o1KpsjkR7Barezu`JrcdID~L;+5)WX%*UJQ&Yi``U%4(X > >> > >>>>> > > >> zh-E}#FgHFdGdD9&|LPB(lF}u>&RE{s?M=6MF^#D=F|5EA<NV{oCcMa<zn~Mk<T(Ze > >> > >>>>> > > >> z&0HR0nL<AyH)RZQ<XDn1{1sHSG^Y=gE!Bz}JL8mgNokN{HQQR8?0sLmM}k+*VtSKU > >> > >>>>> > > >> z0(G5xjIBkg*mgar8dl?2>(#mwgCLf6u_Q?2KQ*N}ioKasK+MwbOk$c3&Z~KIZ=mPa > >> > >>>>> > > >> zLC?i`823#_G-G7OIGO%Zt?-*4ASFD1bOllAd=>Z=)0y0vs(aX((aGyG^fp5mz!EEf > >> > >>>>> > > >> zF>d?iB8)~$oLa4x=o~?8D}fg;$+MVIVN%ak%xZb5y40sy{T31f2D7)Al2jElI=#fN > >> > >>>>> > > >> zx)0-4Uf!(2BHt@6HeOe~;Bhg-@+!)V3ysYAsLS76mS&4ywdoKN<Xkcj8vRSH?CpA^ > >> > >>>>> > > >> zZ9jN`nyu1e6#Y_3nzMKf^V7svbi+ln5P6Btmp3WERhY<Khny?~P8Zpg?wVm3cV*HP > >> > >>>>> > > >> zF7irVsHEod?fy`fjUhz9{Io}Ph2yS$vZyi)rbl*X|6+P8NG4lr_T`IRUN`;zBs<+} > >> > >>>>> > > >> zT&;Tegh9lXEM8H#WzrQ4k0`6-rOIZab@5GnK@r4wCG}xiH?WAEvh^2e8oA|8_7(DV > >> > >>>>> > > >> z5#{zDv#r_|AZFJ|X*X!oF;&=4Fo&EnWes7Xf5LE1ZL%z@!1el5uR?cCfVh?NTYPzB > >> > >>>>> > > >> zBcJE;-j0G%Ppbn+w^1fHs*r*cspp$f(G$WC(1olV7+1;iP|5mP^(0==$z0aQYE_N1 > >> > >>>>> > > >> zFJ;$W95c_yL552$#QpDU9PXBRRb|F>CNv1JuK7MGSR~?}M)kid{}5SM^TJ#tde-1^ > >> > >>>>> > > >> zqHAH7)P6A@4^IsHUVRggU`~aL0v88o>F0e|d~9In=Gaqy9!h71JGknx1kk5a>{LRn > >> > >>>>> > > >> zJ7WiSU7d^tmr_kniLBtPMh%Gv_z#>Ks~I~B1j#>TDETJt+oLT^>%d$VrsQ^(^G805 > >> > >>>>> > > >> zKs`qV`Q@O}XIF0R3S5rE1tG5KaRey<eev{=NU2n>D%~0XZj&qBhgXJ-OXdPjX%P#o > >> > >>>>> > > >> z=imy!?b@^Bdbyh91U3fS1-8WVR+)p~rF@V<{4{`?m9{iM{V>%%rk<_FJQmO&;nng$ > >> > >>>>> > > >> zrTh`()rUt!GGJ4Hs6_n$G;B|fguqa@K59S3=7BW#S1Y_73S6kJOv%g%BFORd1>Wru > >> > >>>>> > > >> z!u2w4OV|4}Q}I>YDXg!02-Nv(Wm^-*Y!s7WMx3ro>HuA`z}u}pb7Wlla_sN$xCfeh > >> > >>>>> > > >> z-W5g#<HDupfx1pwl$br>rF8z`UH#Tx?|Sq_6f-@-8m^0-NE}>f=?0ZSkg?(OfT*s& > >> > >>>>> > > >> zb{*dZs*0x%Ty1n#a>?cGHq3Fy=zNod!EhM~!B6L4R*B;U-8PoMFD@Qd*}L}J^ON5Q > >> > >>>>> > > >> z3}1fu1ADd?Xm4aDO1ti>l2Ox^PN%VDw89)IJsE-(Op<Ns5)e4989DV%{7NE$`Jm+0 > >> > >>>>> > > >> z(K4#==OJ^AIAuaz@=bhu!^+GR4DM`H(~oaRaYLLQS(zSQ!MLA~$1{y#A$MTpS)qZ& > >> > >>>>> > > >> z*0}KkoEc%u(+GK>9QVU9&yPO_e*?h!qR&iJt;nIH)t~yf8;2sQj@A-&iD=n^v7>7X > >> > >>>>> > > >> zc;w7TG_d4bWf^7^5ZGMr?sur<9VshcD!Ne3bXi7tV9IfIr74>H=iHEynQ_Er1O;1W > >> > >>>>> > > >> zk>I$rnyotFAW|IyP#dhiq{>i+Ye7KUVEDs=;cp-67Si*Csi1BoR2<J!o$-Q|gS5|L > >> > >>>>> > > >> z4+g%AHrzW;vt^H{v=5sKp*aU1il;Y*r$;Ia^Y}#fbHM2rGIS}|nrc>1Ne1U9ee<(e > >> > >>>>> > > >> z{&18JjB@`B48?@mEPm@A`T+R6^(hEDWx-U@F$ouS;wIldeGtiCDpz<px&I1cf~^od > >> > >>>>> > > >> zN%W~-ywM^`V#T5x`m;+xXUl^t?Y1c#oPFl|)POywWv3Ue1Rf=pkRD22iI#s?!(zJg > >> > >>>>> > > >> zALmv^$p~`W5H3@mm}crh;p# > > > > ... > > > > [Message clipped] > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
diff --git a/crypto_design.dox b/crypto_design.dox new file mode 100644 index 0000000..1ad2ac6 --- /dev/null +++ b/crypto_design.dox @@ -0,0 +1,455 @@ +/* Copyright (c) 2043, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page crypto_design ODP Design - Crypto API +For the implimentation of the ODP crypto API please see @ref odp_crypto.h + +@tableofcontents + +@section revision_history Revision History +Revision | Issue Data | Description | Author +---------|------------|-------------|-------- +0.1 | 4/9/2014 | Introduction started, Basic Functions | Bill, Alexandru +0.2 | 4/15/2014 | Completed intro, added TOC, started use cases, miscellaneous formatting, API comments | Bill +0.3 | 4/22/2014 | Added Use Case section to include results of design discussions held during ODP team calls | Bill +0.4 | 4/30/2014 | Design review from ODP crypto sprint--action to resolve | Bill +0.5 | 5/5/2014 | Rewrite incorporating review comments--ready for final review | Bill +1.0 | 5/30/2014 | Final version for LNG-SC approval | Bill + +@section introduction Introduction +This document describes the ODP v1.0 Crypto API. Cryptography is an important part of data plane processing as many communication protocols make use of cryptographic functions. Moreover, many SoCs incorporate cryptographic hardware that can significantly accelerate these operations compared to their software equivalents as well as provide validated hardware functional correctness and security boundaries necessary for system-level security certifications such as FIPS-140 Level 2 and above. +@section requirements Requirements +@subsection use_of_terms Use of Terms +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 [RFC 2119](https://tools.ietf.org/html/rfc2119). +@subsection uses_of_cryptography Uses of Cryptography +Crypto functions cover a range of uses and capabilities designed to support data security, integrity, authentication, and non-repudiation. +@subsubsection data_security Data Security +Cryptography supports data security by making use of complex mathematical transformations that are not feasibly reversible without possession of the secret key used to encrypt message data. +@subsubsection data_integrity Data Integrity +Cryptography supports data integrity through the use of cryptographic checksums (also known as secure hashes) that ensure the recipient that message data has not been altered either accidentally or maliciously while in transit. +@subsubsection data_authentication Data Authentication +Cryptography supports data authentication through the uses of Message Authentication Codes (MACs) that enable the recipient to verify that a message was sent from an authorized counterparty, and hence was not forged. +@subsubsection data_non_repudiation Data Non-Repudiation +Cryptography supports data non-repudiation through the use of digital signatures that enable a recipient or third party to verify the identity of the sending party and prevents the sending party from later denying that they originated a signed message. +@subsection scope Scope +ODP v1.0 crypto support is designed to provide a portable framework for accessing SoC-specific cryptographic functions of most use to the data plane. This is predominantly symmetric crypto operations used to support the encryption and decryption of data at line rate using hardware acceleration and offload. Specifically excluded in this support are public key operations and other crypto functions mainly used in the control plane. +@subsection cryptographic_operations_in_the_data_plane Cryptographic Operations in the Data Plane +ODP v1.0 crypto APIs cover the following areas: +@subsubsection ciphering Ciphering +Ciphering refers to mathematical transformations that use a secret key to encipher data, transforming the original data (referred to as plaintext) into ciphertext, thereby making it unintelligible to anyone not in possession of the key. Similarly, ciphering is also used to decipher data, allowing someone in possession of the correct key to transform received ciphertext back into plaintext. Approved block ciphers are listed [here](http://csrc.nist.gov/groups/ST/toolkit/block_ciphers.html) and SHOULD be supported by each ODP implementation. +@subsubsection hasing Hashing +A hash is a cryptographic digest of a message that can be used to represent it for comparison or integrity checking. Hash functions are designed so that any alteration of a message will alter the hash and that it is computationally infeasible to craft a message that generates the same hash value as another message. Secure hash functions approved for cryptographic use are listed by NIST [here](http://csrc.nist.gov/groups/ST/toolkit/secure_hashing.html) and SHOULD be supported by each ODP implementation. +@subsubsection zeroization Zeroization +To preserve the security of data, certain transient data held in data buffers MUST be cleared to zeros upon buffer free. Such capability is referred to as zeroization. ODP supports zeroization as a buffer pool attribute. +@subsubsection random_number_generation Random Number Generation +Because cryptography relies heavily on “unguessable” keys of various sorts, random number generation (RNG) is an integral part of cryptographic processing. Random numbers are used in key generation, initialization vectors (IVs), various types of padding bytes, and various other uses collectively referred to as nonces, that serve to “harden” cryptographic processing. + +There are two types of random number support of interest. Hardware random data, also known as entropy, that is the result of inherently random physical processes, and deterministic random bit generation (DRBG) that is used in certain certified cryptographic operations. Approved DRBG algorithms are listed in [NIST SP 800-90A](http://en.wikipedia.org/wiki/NIST_SP_800-90A) and ODP does not specify which algorithms are available on a given implementation. As such ODP implementations MAY use any approved DRGB algorithm but SHOULD support at least one of them. Additionally, ODP implementations MUST NOT represent non-approved algorithms as DRBG implementations. Validated algorithms are listed in the [NIST DRBG Validation List](http://csrc.nist.gov/groups/STM/cavp/documents/drbg/drbgval.html). + +@subsubsection capability_inquiry Capability Inquiry +To enable applications to adapt to the implementation models offered across different SoC platforms, ODP provides APIs to allow applications to inquire about underlying crypto capabilities. A given ODP implementation may offer crypto as hardware features, software features, or not available on a given platform. +@subsection cryptographic_algorithms Cryptographic Algorithms and Protocols +A cryptographic algorithm is a mathematical transform that provides one of the cryptographic operations described above. They in turn are used as building blocks in creating cryptographic protocols. These are complete sets of rules for how to exchange data securely using cryptography. Both cryptographic algorithm and protocol design are highly specialized disciplines that involve high levels of public scrutiny and validation. As a result, applications simply make use of approved cryptographic algorithms and protocols. +@subsection cryptographic_operations Cryptographic Operations +Cryptographic operations may be initiated by software or directly by hardware as part of the RX or TX packet path processing. For ODP v1.0 software-initiated cryptographic operations are the primary use case. ODP provides APIs for performing data ciphering, hashing, random number generation, and capability inquiry. +@subsection performance_expectations Performance Expectations +In the data plane, the total processing budget for a packet may only be a few hundred cycles, so function invocation overhead MUST be kept to a minimum. This has several implications. + +-# When work is dispatched to a thread, all information needed by the thread to process the work request SHOULD be immediately at hand. Ideally any context or variables needed for the operation have been pre-warmed in the cache to avoid the latency hits associated with cache misses. SoCs having hardware schedulers generally do this pre-staging of data to minimize such latencies, and ODP implementations are expected to exploit such platform capabilities whenever possible.\n\n + +-# Calls to ODP functions SHOULD NOT involve excessive amounts of parameter passing and (depending on the implementation) SHOULD be inlined as much as possible to avoid call overhead. One technique that has proven useful is to allow for parameters to be passed as an explicit thread-local static structure. Such use of “templating” means that a single function can support a rich set of options but the caller can configure a template matched to specific use and only vary the one or two parameters that differ from call to call.\n\n + +-# Kernel traps or interrupts SHOULD NOT be part of any non-exception path function processing. Kernel calls and such are acceptable only during one-time initialization logic or certain types of unusual error recovery operations. Often the best way to handle the latter is to pass the work to a dedicated recovery thread (or back to the control plane) rather than attempting to handle the condition inline. For example, a link-down condition will trigger various recovery actions that might best be handled in this manner. + +@subsection use_by_existing_code Use by Existing Code +Most applications wishing to make use of ODP represent substantial existing investment that must be preserved. Insofar as possible, ODP functions need to be orthogonal to existing application environments and structures to permit easy intermixing with pre-existing code. +@subsection data_references Data References +Packet data is inherently of variable length however it is often more efficient to organize memory into fixed-sized buffers that can be chained together on demand to contain packets. The application SHOULD normally not need to be aware of such lower-level segmentation and should be able to treat a packet as a single object. Alternately, especially when dealing with existing code, data segmentation MUST be explicitly specifiable via scatter/gather lists. For example, data encryption or decryption may be invoked on a list of data segments as part of a single function call. +@subsection chained_operations Chained Operations +Crypto operations such as hashing and encryption, or decryption and verification, are very commonly used in combination. For ODP, it is sufficient to support one cipher and one hash/authentication operation in a single call and this combination MUST be supported to avoid the call and dispatch overhead of separate invocations. +@subsection key_management Key Management and Session Data +Keying is an area of particular sensitivity in crypto processing since keys are highly confidential and may be subject to legal requirements for safeguarding within special hardware enclosures. + +A session is the security context used to represent an active set of crypto operations that need to be applied to a flow on a packet-by-packet basis. Generally a session is established upon detection of a flow requiring crypto processing and retained for the life of that flow. It has been noted that this can involve cooperative processing between the control and data planes so several requirements stem from this: + +-# Session creation MAY need to be handled in an asynchronous manner. This is to allow these to be created in batches by thread(s) that specialize in this activity.\n\n + +-# Sessions MAY need to reference keying material indirectly via key handling modules.\n\n + +-# Session creation MAY be performed by non-ODP code and communicated to data plane routines that make use of ODP crypto functions that need to reference the session information. + +ODP session APIs and data structures SHOULD be represented by abstract data types that encapsulate implementation details for both platform efficiency and to accommodate these needs. +Use Cases +For ODP v1.0 the major use cases of interest involve cryptographic algorithm acceleration. Cryptographic protocol acceleration is reserved for future ODP releases. +Buffers and Data Blocks +Cryptographic operations may be performed directly on data contained in ODP packet buffers, or it may be performed on “raw” data blocks operating entirely under application control. Note that when using raw data blocks not managed by ODP, the application must perform any needed zeroization using either its own or ODP-supplied buffer zeroization functions. ODP automatic support for zeroization is limited to ODP-managed buffers. ODP buffers allocated from buffer pools designated for crypto use will also have whatever alignment and/or addressability attributes needed by the implementation to support crypto API calls. + +Note: Some implementations may have difficulty dealing with application buffer addresses, as these may be virtual addresses that are mapped discontiguously into physical memory. For such implementations, memory SHOULD be allocated contiguously and MAY need to be “registered” to have proper addressability for crypto operations. This area of the design will be updated based on experience in dealing with different crypto implementations that have such requirements. +Synchronization +ODP operations fall into one of three categories: + +-# Inline (Synchronous): Upon return from a call the operation is complete. Operation is thus completely synchronous to the caller. Inline is the appropriate model when the invoked function takes relatively few cycles or when the caller cannot feasibly progress without the results of the invoked function.\n\n + +-# Parallel: Upon return from a call the operation has been initiated, but is expected to complete shortly. The caller continues to execute until it needs the result at which point it waits to complete the parallel operation. The effect is as if the operation were inline except that the caller was able to execute in parallel with the operation for some application-determined period of time. Parallel is the appropriate model when the operation being performed is relatively short (a few dozen up to perhaps 100 or 200 cycles) and the caller can usefully accomplish other processing on the same unit of work while the parallel operation is in progress, but not enough to justify the overhead of a formal queued work dispatch.\n\n + +-# Offloaded (Asynchronous): Upon return from the call the operation has been queued for execution. A completion event will be queued back to the scheduler when the event is completed. Offload is the appropriate model when the invoked function will take a substantial amount of cycles (thousands to tens of thousands) allowing the invoking thread/core to service other work until the operation completes. For offloaded work, completion is indicated by a completion event being posted back to an application-designated completion queue. Upon receipt the unit of work that initiated the offloaded operation continues processing with the results of the call. + +The synchronization models of interest are summarized in Figure 1: + + + +Note: Because few implementations are expected to offer the Parallel mode of operation as described above, this mode is reserved for potential future use. For ODP v1.0 only synchronous and asynchronous crypto operations are defined. +@section functional_definition Functional Definition +@subsection abstract_data_types Abstract data types +The following enumerations define various algorithms used for ciphering and hashing. These are the basic operations applied to input data. + +A particular ODP implementation should map these values to the actual information to be passed to the crypto engine. As such, the actual values of these enums is implementation-defined. + +Cipher algorithm encoding specifies the algorithm and cipher mode employed (as per security relevant RFCs - [4305](http://tools.ietf.org/html/rfc4305), [4868](http://tools.ietf.org/html/rfc4868), [4494](http://tools.ietf.org/html/rfc4494)). + +@code +enum odp_cipher_alg { + ODP_CIPHER_ALG_NULL, + ODP_CIPHER_ALG_DES, + ODP_CIPHER_ALG_3DES_CBC, + ODP_CIPHER_ALG_AES_CBC, + ODP_CIPHER_ALG_AES_GCM, + ODP_CIPHER_ALG_AES_CTR, + ODP_CIPHER_ALG_KASUMI, + ODP_CIPHER_ALG_SNOW, + ... +}; +@endcode + +Authorization algorithm encoding specifies the algorithm and the length of the authorization used (as per security relevant RFCs - [4305](http://tools.ietf.org/html/rfc4305), [4868](http://tools.ietf.org/html/rfc4868), [4494](http://tools.ietf.org/html/rfc4494)): + +@code +enum odp_auth_alg { + ODP_AUTH_ALG_NULL, + ODP_AUTH_MD5_96, + ODP_AUTH_ALG_SHA1_96, + ODP_AUTH_ALG_SHA1_160 + ODP_AUTH_ALG_SHA2_256_128, + ODP_AUTH_ALG_SHA2_384_192, + ODP_AUTH_ALG_SHA2_512_256, + ODP_AUTH_ALG_AES_CMAC_96, + ODP_AUTH_ALG_AES_XCBC_MAC_96, + ODP_AUTH_ALG_SNOW, + ODP_AUTH_ALG_KASUMI, + ... +}; + +typedef union odp_crypto_alg_t { + enum odp_cipher_alg cipher; + enum odp_auth_alg auth; +}odp_crypto_alg_t; +@endcode +@subsection parameter_structures Parameter Structures +@subsubsection crypto_sessions Crypto Sessions +The following structure describes a crypto session. All packets / raw data buffers processed in a session share the data that defines the session. A crypto session is defined by: + +- Operation type : encode or decode\n\n + +- Algorithms specifications, keys and , if required, initialization vectors. When initialization vectors are not provided and they should be provided automatically by the crypto engine.\n\n + +- The operation mode: synchronous or asynchronous. Synchronous operation blocks the caller until an operation status and result are available. In synchronous mode there is at most only one outstanding crypto operation in the calling thread. In asynchronous mode, the caller starts the crypto operation and later it may receive the status and the result together with a request context. The operation status and result may also be received by a different thread.\n\n + +- Operation mode parameters: For asynchronous operation a completion event containing the status, the result and the request context is enqueued to a completion queue. In case the queue is under the scheduler control, the scheduler determines who will receive the completion event and when. When the completion queue is not scheduled, the thread which is supposed to get the operation output has to explicitly poll the completion queue. + +Note that this is an abstract data type and its structure is implementation-specific. The layout shown here is for illustrative purposes and the actual layout will vary from one implementation to the next to most closely align with the structures needed by the underlying SoC platform. Applications set and reference fields in the session structure via accessor functions that hide the actual layout. + +@code +typedef enum odp_crypto_op_t { + ODP_CRYPTO_OP_ENCODE, + ODP_CRYPTO_OP_DECODE +}odp_crypto_op_t; + +typedef struct odp_key_t { +}odp_key_t; + +typedef struct odp_crypto_session_t { + odp_crypto_op_t op; + struct { + enum odp_cipher_alg cipher_alg; + odp_key_t *key; + uint8_t *iv; + size_t iv_len; + } cipher; + + struct { + enum odp_auth_alg auth_alg; + enum odp_auth_len auth_len; + odp_key_t *key; + } auth; + + enum odp_crypto_op_mode { + ODP_CRYPTO_SYNC, + ODP_CRYPTO_ASYNC, + } op_mode; + + struct { + uint32_t timeout; + struct { + odp_queue_t completion_queue; + } async; + } op_mode_params; + + odp_session_proc_info_t session_proc_info; +} odp_crxsypto_session_t; +@endcode + +The completion queue contained in the session structure is an in/out parameter. If provided, then the queue specified is associated with the session and is used to ensure order preservation on that session. If not provided, one is created and returned to the caller. Note that this completion queue is used to order operations performed on this crypto session. It should not be confused with the completion queue specified on the odp_crypto_session_create() call (see below) that is used to control whether that call is itself processed in a synchronous vs. asynchronous manner. + +The following structure comprises processing information. This is logically divided in two parts: + +- Processing input info - When crypto engine provides support for protocol processing, this information is provided in a higher level common protocol terminology form and a particular implementation should be able to derive everything it needs from this definition. In addition, for crypto engines able to automate tasks like memory allocation for the output a buffer pool id may be specified.\n\n + +- Processing output information - statistics about processed bytes/packets. These are useful when a session expiration is based on traffic volume. These statistics may be updated by the software or by the hardware crypto engine. + +Again, this is an abstract type whose specific layout will vary based on implementation considerations. Access to fields contained in the structure is only via accessor functions. + +@code +typedef struct { + uint64_t pkts_processed; + uint64_t bytes_processed; + uint64_t pkts_errored; + uint64_t bytes_errored; + + odp_buffer_pool_t out_pool; + +} odp_session_proc_info_t; +@endcode + +This enumeration defines which operations are applied and the order. + +@code +enum odp_crypto_combination { +ODP_CRYPTO_CIPHER_ONLY, + ODP_CRYPTO_AUTH_ONLY, + ODP_CRYPTO_AUTH_CIPHERTEXT +}; +@endcode + +This structure defines a contiguous segment in the input data which starts at offset offset and is len bytes long. + +@code +struct odp_data_range { + unsigned offset:16; + unsigned len:16; +}; +@endcode + +@subsection api_functions API Functions + +@subsubfunction Session Creation + +This function is used to create a crypto session. The required parameters are : + +- Operation : encode/decode +- Processing info : cipher/auth/both +- Preferred mode : sync or async. +- Algorithms suites, keys and optional IV + +Session creation can be synchronous or asynchronous. Completion event argument is used to return the status and the session handle. When completion queue is not provided (synchronous call), the completion event is available upon function call return. When completion queue is provided (asynchronous call), the completion event is placed on the completion queue. + +@code +typedef uint64_t odp_crypto_session_t; + +struct odp_session_params { + enum odp_crypto_operation op; + odp_session_proc_info_t proc_info; + enum odp_crypto_op_mode pref_mode; + enum odp_cipher_alg cipher_alg; + odp_key_t *cipher_key; + uint8_t *iv; + size_t iv_len; + enum odp_auth_alg auth_alg; + odp_key_t *auth_key; +}; + +enum odp_crypto_ses_create_err { + ODP_CRYPTO_SES_CREATE_NONE, + ODP_CRYPTO_SES_CREATE_ENOMEM, + /* Session creation error codes */ +}; + +void +odp_crypto_get_ses_create_compl_status(odp_buffer_t completion_event, enum odp_crypto_ses_create_err *status); + +void +odp_crypto_get_ses_create_compl_handle(odp_buffer_t completion_event, odp_crypto_session_t *handle); + +int odp_crypto_session_create( + struct odp_session_params *params, + odp_buffer_t completion_event, + odp_queue_t completion_queue); +@endcode +@subsection crypto_operation Crypto Operation + +Crypto operations are described by a parameter structure: +@code +struct odp_crypto_op_params { + odp_crypto_session_t session; + odp_packet_t pkt; + odp_packet_t out_pkt; + uint8_t *override_iv_ptr; + unsigned hash_result_offset; + struct odp_data_range cipher_range; + struct odp_data_range auth_range; +}; +@endcode + +<table> +<tr><th>Parameter</th><th>Meaning</th></tr> +<tr><td>session</td><td>Session to perform the operation</td></tr> +<tr><td>pkt</td><td>Packet / buffer to be processed</td></tr> +<tr><td>out_pkt</td><td>Handle of an output packet / buffer to be returned as the result of the operation. There are three different ways this parameter is used, depending on the mode of operation requested by the caller and the capabilities of the underlying implementation:\n\n + +-# If out_pkt is the same as pkt this indicates that the operation should be performed in place.\n\n +-# If out_pkt is different from pkt this indicates that output should be placed in the buffer supplied by the caller.\n\n +-# If out_pkt is omitted (a null/invalid value supplied on input) this indicates that an output buffer should be allocated by the operation and returned as part of the completion event associated with the operation.\n\n + +Note that not every implementation will support all of these modes and MAY require that one mode be used in preference to others. Any such implementation restrictions are communicated as output from session creation.</td></tr> +<tr><td>override_iv_ptr</td><td>Optional IV to use for this request</td></tr> +<tr><td>hash_result_offset</td><td>Offset into the output packet where the hash result should be stored.</td></tr> +<tr><td>cipher_range</td><td>The byte range (offset:length) of the data to be processed for ciphering.</td></tr> +<tr><td>auth_range</td><td>The byte range (offset:length) of the data to be processed for authentication.</td></tr> +</table> + +The crypto operation is initiated with a single call that passes the parameters for the operation and an event (for asynchronous completion). +@code +int odp_crypto_operation( + struct odp_crypto_op_params *params, + odp_buffer_t completion_event); +@endcode + +Parameter | Meaning +----------|-------- +params | The parameter structure describing the crypto operation to be performed. +completion_event | The event delivered on completion. It provides information about the status of the operation, result and request context. In synchronous mode the event is available upon function call return. In asynchronous mode, the event is placed on the session / operation completion queue when the operation finished. + +Upon return the return code indicates whether the operation was synchronous or asynchronous, or if an error occurred that prevented the operation from being performed. + +Get session operation : +@code +odp_crypto_op_t +odp_crypto_session_get_op(odp_crypto_session_t ses); +@endcode + +Get session cipher information : +@code +odp_cipher_alg +odp_cipher_session_get_cipher_alg(odp_crypto_session_t ses); +@endcode + +Get session authentication information : +@code +odp_auth_alg +odp_crypto_session_get_auth_alg(odp_crypto_session_t ses); +@endcode + +Change session IV : +@code +int odp_crypto_session_iv_set(odp_crypto_session_t ses, uint8_t *iv); +@emdcode + +Change cipher or/and hash keys: +@code +int odp_crypto_session_key_set(odp_crypto_session_t ses, odp_key_t *key); +@endcode + +Destroy crypto session. All pending operations are cancelled. +@code +int odp_crypto_session_destroy(odp_crypto_session_t ses); +@endcode + +Get completion event information - algorithm error, output and context. Note that implementations MAY define their own specific error codes that have meaning in that context. For application portability it is sufficient to know whether an operation completed successfully or experienced an error of some sort. +@code +enum crypto_alg_err { + ODP_CRYPTO_ALG_ERR_NONE, + ODP_CRYPTO_ALG_ERR_MODE, + ODP_CRYPTO_ALG_ERR_DATA_SIZE, + ODP_CRYPTO_ALG_ERR_KEY_SIZE, + ODP_CRYPTO_ALG_ERR_ICV_CHECK, + ODP_CRYPTO_ALG_ERR_AAD_SIZE, +}; + +enum crypto_hw_err { + ODP_CRYPTO_HW_ERR_NONE, + ODP_CRYPTO_HW_ERR_DMA, + ODP_CRYPTO_HW_ERR_BP_DEPLETED, +}; + +struct odp_crypto_compl_status { + odp_crypto_alg_t alg; + enum crypto_alg_err alg_err; + enum crypto_hw_err hw_err; +}; + +void +odp_crypto_get_compl_status(odp_buffer_t completion_event, + struct odp_crypto_compl_status *auth, + struct odp_crypto_compl_status *cipher); +@endcode + +Returns the output packet handle associated with the completion event : +@code +odp_packet_t +odp_crypto_get_out_pkt(odp_buffer_t completion_event); +@endcode + +Sets a context handle to be returned with the completion event : +@code +void odp_crypto_set_compl_ctx(odp_buffer_t completion_event, odp_compl_ctx_t *ctx); +@endcode + +Returns the context associated with the completion event : +@code +odp_compl_ctx_t odp_crypto_get_compl_ctx(odp_buffer_t completion_event); +@endcode + +This section describes the API/Interface being defined at a functional level in technical detail. Sub-sections include header file names, where implementation files are expected to reside in the ODP git tree, as well as the name, parameters, abstract data types, functionality, return codes, and exception conditions of each function call defined by the API/Interface. Appropriate diagrams, tables, etc. should be used to allow the programmer tasked with implementing the API/Interface to understand the function to be implemented as well as error conditions, corner cases, performance requirements, etc. needed to implement the described API/Interface in a functionally correct and efficient manner. + +@subsubsection random_number_functions Random Number Functions +As noted earlier, random number support consists of two functions: +@code +int odp_hw_random_get (uint8_t *buf, uint32_t *len, bool use_entropy); + +int odp_drgb_random_get (uint8_t *buf, uint32_t *len); +@endcode + +The difference is that the first provides access to hardware random number functions that return true random data. This is typically used for seed values. The second provides a deterministic random bit generator conforming to NIST standards and is used by various crypto protocols and algorithms. The use_entropy parameter on odp_hw_random_get is used to disable any hardware pre-processing normally provided by the function and is mainly intended to be used for testing/validation purposes. + +@subsubsection buffer_pool_extensions Buffer Pool Extensions +To support zeroization a buffer may be allocated with an ODP_CLEAR_ON_FREE attribute that specifies that this buffer should be zeroized upon free. Alternately, a new type (ODP_CLEAR_ON_FREE) is added to odp_buffer_pool_create() that specifies that all buffers allocated from this pool must be zeroized upon free. Essentially, the buffer security attribute is set by default from the attributes of the buffer pool that it is allocated from. + +@subsubsection capability_inquiry Capability Inquiry +To enable applications to determine crypto capabilities. +@code +int odp_crypto_inquire (enum odp_cipher_alg, enum odp_auth_alg); +@endcode + +Inquires whether the specified crypto and auth algorithms are supported. Responses include: +- ODP_HW_SYNC_SUPPORT +- ODP_HW_ASYNC_SUPPORT +- ODP_SW_SYNC_SUPPORT +- ODP_SW_ASYNC_SUPPORT +- ODP_NO_SUPPORT + +HW support means the combination is supported in hardware, SW support means the combination is supported in software by the implementation. No support means the combination is not supported by the implementation. The SYNC and ASYNC return options can help the application decide how to invoke these functions, or it can just check whether or not the response is ODP_NO_SUPPORT. + +@section implementation_considerations Implementation Considerations +One of the main purposes for the ODP crypto APIs is to provide portable access across different SoCs whose hardware crypto capabilities largely overlap but vary in terms of their implementation details. As a result, implementations need not provide software fill-ins for specific cryptographic features that are not available as hardware features on that platform. Presumably applications needing specific features will select platforms on which these features are present. Therefore, while all APIs specified here MUST exist in each conforming ODP implementation, it is acceptable for these APIs to return ODP_RC_FEATURE_NOT_PRESENT in response to calls requesting crypto features not present on that platform. + +For example, the linux-generic ODP implementation may only implement the null cipher suite (ODP_CIPHER_ALG_NULL) and return a feature not present error code for any other cipher. This indication will also be returned on that platform in response to odp_crypto_inquire calls for non-null cipher algorithms. + +@section verification Verification/Testing +This section describes the verification/test cases needed to ensure that the defined functionality is implemented correctly and performs adequately. This should be at a level of detail such that the programmer tasked with writing test scripts/programs to verify the implementation(s) of the defined functions can be written to ensure that all relevant functional variants and error/exception cases are properly tested. + +This section needs to be completed before API testing begins. + +*/
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- crypto_design.dox | 455 ++++++++++++++++++++++++++++++++++++++++++++++++++ images/syncmodels.png | Bin 0 -> 17179 bytes 2 files changed, 455 insertions(+) create mode 100644 crypto_design.dox create mode 100644 images/syncmodels.png \ No newline at end of file diff --git a/images/syncmodels.png b/images/syncmodels.png new file mode 100644 index 0000000000000000000000000000000000000000..44e4c551bd803b7dd4320875699828d7f20d2044 GIT binary patch literal 17179 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 Z7*dM{yQhj}4sy3din1y)<x=lM{ueeblRN+b literal 0 HcmV?d00001