[dpdk-dev] [RFC] cryptodev/asymm: propose changes to RSA API

["Kusztal, ArkadiuszX" <arkadiuszx.kusztal@intel.com>]

Hi all,

I would like to propose some changes to RSA API,
I will put in this mail API comments I initially created and I will try additionally to elaborate about some of them too (with [AK]).
Any comments, critique or ideas are much appreciated :).

1) Crypto op:

@@ -395,9 +414,28 @@ struct rte_crypto_rsa_op_param {
             /**<
              * Pointer to data
              * - to be encrypted for RSA public encrypt.
-             * - to be decrypted for RSA private decrypt.
              * - to be signed for RSA sign generation.
              * - to be authenticated for RSA sign verification.
[AK] - some information would be good about behavior when buffer is not big enough.
+            */
+
+            rte_crypto_param cipher;
+            /**<
+            * Pointer to data
+            * - to be decrypted for RSA private decrypt.
+            *
+            * When RTE_CRYPTO_ASYM_OP_ENCRYPT op_type used size in bytes
+            * of this field need to be equal to the size of corresponding
+            * RSA key.
              */

[AK] - Asymmetric nature of RSA suggest cipher/plaintext relation should be asymmetric too, we don't know
how big will be output comparing to the input.

[AK] - I miss here some information about len of long number as a separate field I mentioned in earlier mails,
we could then have had size of the buffer (in case it would be reused) and size of number (removed leading zeroes).
For now empty buffer (i.e. message before decryption) length will be the size of the buffer, after decryption it will be
size of long number.
              rte_crypto_param sign;
@@ -408,8 +446,85 @@ struct rte_crypto_rsa_op_param {
              *
              * Length of the signature data will be equal to the
              * RSA prime modulus length.

+
+            struct {
+                           enum rte_crypto_rsa_padding_type type;
+                           /**<
+                           * In case RTE_CRYPTO_RSA_PADDING_PKCS1 is selected,
+                           * driver will distinguish between block type basing
+                           * on rte_crypto_asym_op_type of the operation.
[AK] - So block type 01 for signature, 02 for encryption. I dropped type 00 as it
                             is unsafe and not used anywhere.
+                           *
+                           * Which padding type is supported by the driver SHALL be
+                           * available in in specific driver guide or capabilities.
+                           */
+                           enum rte_crypto_hash_algorithm hash;
+                           /**<
+                           * -         For PKCS1-v1_5 signature (Block type 01) this field
+                           * represents hash function that will be used to create
+                           * message hash. This hash will be then concatenated with
+                           * hash algorithm identifier into DER encoded sequence.
[AK] - I wonder  about accepting signatures with BER encoding as it was
defined in 2313 rfc to be backward compatible.
+                           * If RTE_CRYPTO_HASH_INVALID is set, driver default will be set.
+                           * If RTE_CRYPTO_HASH_NONE is set, message will be signed as it is.
+                           *
+                           * -         For OAEP this field represents hash function that will
+                           * be used to produce hash of the optional label.
+                           * If RTE_CRYPTO_HASH_INVALID or RTE_CRYPTO_HASH_NONE is set
+                           * driver will use default value. For OAEP usually it is SHA-1.
+                           *
+                           * -         For PSS this field represents hash function that will be used
+                           * to produce hash (mHash) of message M and of M' (padding1 | mHash | salt)
+                           * If RTE_CRYPTO_HASH_INVALID or RTE_CRYPTO_HASH_NONE is set
+                           * driver will use default value.
+                           *
+                           * -         If driver supports only one function RTE_CRYPTO_HASH_NONE
+                           * according to aformentioned restrictions should be used or
+                           * specific function should be set, otherwise on dequeue the driver
+                           * SHALL set crypto_op_status to RTE_CRYPTO_OP_STATUS_INVALID_ARGS.
+                           */
+                           union {
+                                         struct {
+                                                       enum rte_crypto_hash_algorithm mgf;
+                                                       /**<
+                                                       * Mask genereation function hash algorithm.
+                                                       * If this field is not supported by the driver,
+                                                       * it should be set to RTE_CRYPTO_HASH_NONE.
+                                                       */
+                                                       rte_crypto_param label;
+                                                       /**<
+                                                       * Optional label, if driver does not support
+                                                       * this option, optional label is just an empty string.
+                                                       */
+                                         } OAEP;
+                                         struct {
+                                                       enum rte_crypto_hash_algorithm mgf;
+                                                       /**<
+                                                       * Mask genereation function hash algorithm.
+                                                       * If this field is not supported by the driver,
+                                                       * it should be set to RTE_CRYPTO_HASH_NONE.
+                                                       */
+                                                       int seed_len;
+                                                       /**<
+                                                       * Intended seed length. Nagative number has special
+                                                       * value as follows:
+                                                       * -1 : seed len = length of output ot used hash function
+                                                       * -2 : seed len is maximized
[AK] - It actually is taken from OPENSSL implementation, but looks like good idea tbh.
+                                                       */
+                                         } PSS;
+                           };
+            } padding;
+            /**<
+            * Padding type of RSA crypto operation.
+            * What are random number generator requirements and prerequisites
+            * SHALL be put in specific driver guide
              */
+            /* All fields below should be deprecated */
             enum rte_crypto_rsa_padding_type pad;
             /**< RSA padding scheme to be used for transform */


2) Padding:

enum rte_crypto_rsa_padding_type {
             RTE_CRYPTO_RSA_PADDING_NONE = 0,
-             /**< RSA no padding scheme */
+            /**< RSA no padding scheme.
+            * In this case user is responsible for providing and verification
+            * of padding.
+            * In case RTE_CRYPTO_ASYM_OP_VERIFY op type is used if no
+            * problems in public key 'encryption' detected driver SHALL return
+            * RTE_CRYPTO_OP_STATUS_SUCCESS, output data should be put in cipher data
+            * of crypto op.
+            * It is USER RESPONSABILITY to remove padding and verify signature. */
+            RTE_CRYPTO_RSA_PADDING_PKCS1,
+            /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01,
+            * for encryption block type 02 are used.
+            *
+            * In case RTE_CRYPTO_ASYM_OP_VERIFY op type is used crypto op status
+            * is set to RTE_CRYPTO_OP_STATUS_SUCCESS when signature is properly
+            * verified, RTE_CRYPTO_OP_STATUS_ERROR when it failed.
+            */
+            RTE_CRYPTO_RSA_PADDING_OAEP,
+            /**< RSA PKCS#1 OAEP padding scheme, can be used only for encryption/
+            * decryption. */
+            RTE_CRYPTO_RSA_PADDING_PSS,
+            /**< RSA PKCS#1 PSS padding scheme, can be used only for signatures.
+            *
+            * Crypto op status is set to RTE_CRYPTO_OP_STATUS_SUCCESS
+            * when signature is properly verified, RTE_CRYPTO_OP_STATUS_ERROR
+            * when it failed.
[AK] I consider some new flags like STATUS_SIGNATURE_VERIFIED, STATUS_SIGNED.
+            *
+            */
+
             RTE_CRYPTO_RSA_PKCS1_V1_5_BT0,
-             /**< RSA PKCS#1 V1.5 Block Type 0 padding scheme
-             * as descibed in rfc2313
+            /* DEPRECATED
              */
             RTE_CRYPTO_RSA_PKCS1_V1_5_BT1,
-             /**< RSA PKCS#1 V1.5 Block Type 01 padding scheme
-             * as descibed in rfc2313
+            /* DEPRECATED
              */
             RTE_CRYPTO_RSA_PKCS1_V1_5_BT2,
-             /**< RSA PKCS#1 V1.5 Block Type 02 padding scheme
-             * as descibed in rfc2313
+            /* DEPRECATED
              */
};
 3) Hash functions
 +enum rte_crypto_hash_algorithm {
+            RTE_CRYPTO_HASH_INVALID,
+            RTE_CRYPTO_HASH_NONE,
+            RTE_CRYPTO_HASH_MD5,
+            RTE_CRYPTO_HASH_SHA1,
+            RTE_CRYPTO_HASH_SHA244,
+            RTE_CRYPTO_HASH_SHA256,
+            RTE_CRYPTO_HASH_SHA384,
+            RTE_CRYPTO_HASH_SHA512,
+            RTE_CRYPTO_HASH_SHA512_224,
+            RTE_CRYPTO_HASH_SHA512_256,
+};

[AK] Instead of using auth enum i would just add to symmetric API hash functions.

[AK] If accepted some, or most of these fields could be somehow reflected in capabilities.

Regards,
Arek