1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
== Cryptographic services
ODP provides APIs to perform cryptographic operations required by
applications. ODP cryptographic APIs are session based and provide
cryptographic algorithm offload services. ODP also offers cryptographic
protocol offload services for protocols such as IPsec using a different set
of APIs. This section covers the main crypto APIs.
ODP provides APIs for following cryptographic services:
* Ciphering
* Authentication/data integrity via Keyed-Hashing (HMAC)
* Random number generation
* Crypto capability inquiries
=== Crypto Sessions
To apply a cryptographic operation to a packet a session must be created. All
packets processed by a session share the parameters that define the session.
ODP supports synchronous and asynchronous crypto sessions. For asynchronous
sessions, the output of crypto operation is posted in a queue defined as
the completion queue in its session parameters.
ODP crypto APIs support chained operation sessions in which hashing and
ciphering both can be achieved using a single session and operation call. The
order of cipher and hashing can be controlled by the `auth_cipher_text`
session parameter.
Other Session parameters include algorithms, keys, initialization vector
lengths, encode or decode, output queue for async mode and output packet
pool for allocation of an output packet if required.
The parameters that describe the characteristics of a crypto session are
encoded in the `odp_crypto_session_param_t` struct that is passed to the
`odp_crypto_session_create()` API. A successful call returns an
`odp_crypto_session_t` object that in turn is passed as an input parameter to
crypto operation calls.
When an application is finished with a crypto session the
`odp_crypto_session_destroy()` API is used to release the resources associated
with an `odp_crypto_session_t`.
=== Crypto operations
After session creation, a cryptographic operation can be applied to a packet
synchronously or asynchronously. `odp_crypto_op()` is the synchronous API
while `odp_crypto_op_enq()` is the asynchronous API. To check which of these
are supported by the ODP implementation, examine the `sync_mode` and
`async_mode` fields in the `odp_crypto_capability_t` struct returned by the
`odp_crypto_capability()` API.
Both forms take an input array of packets, an optional output array of packets
to receive the results, and an array of `odp_crypto_packet_op_param_t` structs
that describe the operation to be performed on each input packet. The output
array may be the same packets to request in-place operation, or may be
specified as `ODP_PACKET_INVALID` to request that ODP allocate output packets
from the pool associated with the `odp_crypto_session_t` being used.
The op_mode field of `odp_crypto_session_t` indicates whether asynchronous
or synchronous operations are used with the session. If `op_mode` is set
to `ODP_CRYPTO_SYNC` then the synchronous API must be used and if `op_mode`
is set to `ODP_CRYPTO_ASYNC` then the asynchronous API must be used. It is
an error to use a form of the API that does not match the mode of the crypto
session.
The output of a crypto operation is an `odp_packet_t` (one for each input
packet) that is returned either synchronously or asynchronously. Asynchronous
return is in the form of `ODP_EVENT_PACKET` events that have event subtype
`ODP_EVENT_PACKET_CRYPTO`. The packet associated with such events is obtained
via the `odp_crypto_packet_from_event()` API. The `odp_crypto_result()` API,
in turn, retrieves the `odp_crypto_packet_result_t` from this `odp_packet_t`
that contains:
* An indication of whether the crypto operation was successful or not
* The `odp_crypto_op_status_t` for the requested cipher operation
* The `odp_crypto_op_status_t` for the requested authentication operation
=== Random number Generation
ODP provides two APIs to generate various kinds of random data bytes. Random
data is characterized by _kind_, which specifies the "quality" of the
randomness required. ODP support three kinds of random data:
ODP_RANDOM_BASIC:: No specific requirement other than the data appear to be
uniformly distributed. Suitable for load-balancing or other non-cryptographic
use.
ODP_RANDOM_CRYPTO:: Data suitable for cryptographic use. This is a more
stringent requirement that the data pass tests for statistical randomness.
ODP_RANDOM_TRUE:: Data generated from a hardware entropy source rather than
any software generated pseudo-random data. May not be available on all
platforms.
These form a hierarchy with BASIC being the lowest kind of random and TRUE
being the highest. The main API for accessing random data is:
[source,c]
-----
int32_t odp_random_data(uint8_t buf, uint32_t len, odp_random_kind_t kind);
-----
The expectation is that lesser-quality random is easier and faster to generate
while higher-quality random may take more time. Implementations are always free
to substitute a higher kind of random than the one requested if they are able
to do so more efficiently, however calls must return a failure indicator
(rc < 0) if a higher kind of data is requested than the implementation can
provide. This is most likely the case for ODP_RANDOM_TRUE since not all
platforms have access to a true hardware random number generator.
The `odp_random_max_kind()` API returns the highest kind of random data
available on this implementation.
For testing purposes it is often desirable to generate repeatable sequences
of "random" data. To address this need ODP provides the additional API:
[source,c]
-----
int32_t odp_random_test_data(uint8_t buf, uint32_t len, uint64_t *seed);
-----
This operates the same as `odp_random_data()` except that it always returns
data of kind `ODP_RANDOM_BASIC` and an additional thread-local `seed`
parameter is provide that specifies a seed value to use in generating the
data. This value is updated on each call, so repeated calls with the same
variable will generate a sequence of random data starting from the initial
specified seed. If another sequence of calls is made starting with the same
initial seed value, then `odp_random_test_data()` will return the same
sequence of data bytes.
=== Capability inquiries
ODP provides the API `odp_crypto_capability()` to inquire the implementation’s
crypto capabilities. This interface returns a the maximum number of crypto
sessions supported as well as bitmasks for supported algorithms and hardware
backed algorithms.
|
