Appendix A: OCF Kernel API

• int32_t crypto_get_driverid();
  int crypto_register();
  int crypto_kregister();
  int crypto_unregister();

  Used by device drivers to register and unregister symmetric and asymmetric algorithm support with the OCF.

• void crypto_done();
  void crypto_kdone();

  Called by device drivers on completion of a request (symmetric and asymmetric, respectively).

• int crypto_newsession();

  Called by consumers of cryptographic services (such as the IPsec stack) that wish to establish a new session with the framework. On success, the first argument will contain the Session Identifier (SID). The second argument contains all the necessary information for the driver to establish the session (keys, algorithms, offsets, etc. The third argument indicates whether only hardware acceleration is acceptable.

• int crypto_freesession();

  Called to disestablish a previously-established session.

• int crypto_dispatch();

  Called to process a request, encapsulated in its only argument. The various fields in that structure contain:

  • The SID.
  • The total length in bytes of the buffer to be processed,
  • The total length of the result, which for symmetric crypto operations will be the same as the input length.
  • The type of input buffer, as used in the kernel malloc() routine. This will be used if the framework needs to allocate a new buffer for the result (or for re-formatting the input).
  • The routine that the OCF should invoke upon completion of the request, whether successful or not.
  • The error type, if any errors were encountered. If the EAGAIN error code is returned, the SID has changed. The consumer should record the new SID and use it in all subsequent requests. In this case, the request may be re-submitted immediately. This mechanism is used by the framework to perform session migration (move a session from one driver to another, because of availability, performance, or other considerations).
  • A bitmask of flags associated with this request. Currently, the only flag defined is CRYPTO_F_IMBUF, which indicates that the input buffer is an mbuf chain.
  • The input and output buffers. The input buffer may be an mbuf chain or a contiguous buffer (as identified by the flags). The output buffer will be of the same type.
  • A pointer to opaque data. This is passed through the crypto framework untouched and is intended for the invoking application's use.
  • A linked list of operation descriptors, which indicate what operations should be applied, and in what sequence, to the input data. The descriptors indicate where each operation should start, the length of the data to be processed, where on the output buffer should the results be placed, the key material to be used, and various operation-specific flags (e.g., what Initialization Vector to use for CBC-mode encryption).
  
  
• int crypto_kdispatch();

  Similar to crypto_dispatch(), for public-key operations.