Just my 2 cents. API abstraction seems to be fine but we need to decide on, Are we taking the crypto protocol offload path or not in ODP crypto specification? If we are taking the protocol offload path then we should enumerate all the protocols and find the meta data.
Thanks, Jerin. From: [email protected] <[email protected]> on behalf of Job Abraham <[email protected]> Sent: Tuesday, September 16, 2014 3:03 PM To: [email protected] Subject: [lng-odp] ODP API enhancement porposal for IPsec Hi All, Here is a proposal for enhancing ODP crypto APIs to support security protocols like IPsec. As part of the ODP crypto API definitions, the framework for supporting a wide variety of security protocols is defined. The definition of data structures and APIs for crypto functions is defined below. Specifically, a detailed presentation of IPsec related parameters and their usage are defined. IPsec implementation is done by means of specialized offload engines that interface with general cores/other specific cores that perform other network processing functions. Crypto Session Create:- Crypto engine can be used by any of the Security protocols like IPsec/SRTP/SRTCP/TLS etc, hence protocol specific parameters shall be passed during crypto session create. These protocol specific parameters allow accelerator engines to provide more offloaded functionality in NPU. Following APIs are expected to undergo changes during crypto session create: Crypto session create APIs int odp_crypto_session_create(odp_crypto_session_params_t *params, odp_crypto_session_t *session, enum odp_crypto_ses_create_err *status ) int odp_crypto_session_create_async(odp_crypto_session_params_t * params, odp_buffer_t completion_event, odp_queue_t completion_queue ) These API creates the crypto session (blocking/non-blocking). Changes proposed to these API are below. New Enums or Structures:- /** * Crypto protocol - more types can be added based on Security Accelerator capability. */ enum odp_crypto_protocol_type { CRYPTO_IPSEC, CRYPTO_SRTP, CRYPTO_TLS, NONE }; /** * Crypto IPsec direction */ enum odp_ipsec_direction { IPSEC_INBOUND, IPSEC_OUTBOUND }; /** * Crypto IPsec mode */ enum odp_ipsec_mode{ IPSEC_TUNNEL, IPSEC_TRANSPORT }; /** * Crypto IPsec protocol */ enum odp_ipsec_proto{ IPSEC_AH, IPSEC_ESP }; /** * Crypto protocol specific parameters * IPsec parameters * softLifetime: Soft lifetime of an SA, shall be specified either in time or bytes * hardLifetime: Hard lifetime of an SA, shall be specified either in time or bytes * dir: IPsec direction based on operation either INBOUND/OUTBOUND * mode: IPsec mode, can be Tunnel or Transport mode * proto: IPsec Protocol, can be ESP/AH * spi: Security Parameter Index for the IPsec SA session * srcAddr: Source address of tunnel header, (Valid only in Tunnel mode) * dstAddr: Destination address of tunnel header, (Valid only in Tunnel mode) * seqOverFlowFlag: Flag to indicate that the sequence number Over flow is enabled */ struct odp_crypto_protocol_params{ odp_crypto_protocol_type type; union{ /* IPsec Protocol specific parameters */ struct{ uint64_t softLifetime; uint64_t hardLifetime; odp_ipsec_direction dir; odp_ipsec_mode mode; odp_ipsec_proto proto; uint32_t spi; uint32_t srcAddr; uint32_t dstAddr; bool seqOverFlowFlag; }ipsec; /* SRTP Protocol specific parameters */ struct{ }srtp; /* TLS Protocol specific parameters */ struct{ }tls; }; }; Modified Structure:- /** * Crypto API session creation paramters * * TODO: add "odp_session_proc_info_t" */ struct odp_crypto_session_params { enum odp_crypto_op op; /**< Encode versus decode */ enum odp_crypto_combination comb; /**< Operation order */ enum odp_crypto_op_mode pref_mode; /**< Preferred sync vs async */ enum odp_cipher_alg cipher_alg; /**< Cipher algorithm */ odp_key_t *cipher_key; /**< Cipher key */ uint8_t *iv; /**< Cipher Initialization Vector (IV) */ size_t iv_len; /**< Cipher IV length */ enum odp_auth_alg auth_alg; /**< Authentication algorithm */ odp_key_t *auth_key; /**< Authentication key */ odp_queue_t compl_queue; /**< Async mode completion event queue */ odp_crypto_protocol proto_params; /**< ##new Param## Protocol specific params */ }; Crypto Operation in data-path:- int odp_crypto_operation(odp_crypto_op_params_t *params, bool * posted, odp_buffer_t completion_event) This API does the Crypto operation (Encryption/Decryption) in data-path. This API prototype is not changed. But based on crypto protocol defined in crypto session creation, the operation varies. If crypto protocol is none, the existing behavior continues (only the crypto) If the Security protocol is "CRYPTO_IPSEC" during crypto session create, then this API is expected to do following specific IPsec offload functionality. IPsec Encryption:- Plain IP packet with payload is passed to this API to do the IPsec Encryption. API is expected to add the IP tunnel header if required, add the ESP/AH protocol & encrypt the packet. ODP APIs can use crypto accelerators to do the following, else partial functionality can be implemented in CPU & rest can be offloaded to crypto accelerators. o Tunnel IP headers are encapsulated during Tunnel Encryption scenario. o AH/ESP headers are encapsulated during Tunnel/Transport Encryption scenario · Sequence number generation, · Sequence number overflow, · Adding Padding bytes for crypto algorithm block size After completion of crypto operation, application can expect the complete encrypted buffer with Tunnel IP header if any, IPsec protocol ESP/AH & encrypted payload. IPsec Decryption:- Encrypted IP packet with IP header is passed to this API to do the IPsec Decryption. API is expected to remove the IP tunnel header if any, remove the ESP/AH protocol & decrypt the packet. ODP APIs can use crypto accelerators to do the following, else partial functionality can be implemented in CPU & rest can be offloaded to crypto accelerators. o Tunnel IP headers are removed during Tunnel Decryption scenario. o AH/ESP headers removed during Tunnel/Transport Decryption scenario · Anti replay Window mechanism shall be taken care by this API After completion of crypto operation, application can expect the complete decrypted buffer (with removal Tunnel IP header if any, with removal of IPsec protocol ESP/AH). Please share your thoughts on this proposal. Regards, Job _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
