|WARNING| [v2] crypto: add RSA-specific capability parameters

[dpdklab at iol.unh.edu]

Test-Label: ai-code-review
Test-Status: WARNING
https://dpdk.org/patch/167990

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-08-19

# DPDK Patch Review

## Patch Summary
Adding RSA-specific capability parameters to cryptodev API to allow PMDs to advertise support for padding schemes and MGF1 hash algorithms independently from primary hash algorithms.

---

## Findings

### Errors

None.

### Warnings

**1. Missing `__rte_experimental` tag on new API structure**

The new `struct rte_crypto_rsa_capa` is part of the public API (declared in an installed header) but is not marked as experimental. New API additions must be marked `__rte_experimental`.

```c
/* Current - missing experimental tag */
struct rte_crypto_rsa_capa {
    /* ... */
};

/* Suggested fix */
__rte_experimental
struct rte_crypto_rsa_capa {
    struct rte_crypto_param_range modlen;
    uint8_t pad_types;
    uint64_t mgf1_hash_algos;
};
```

**2. Missing release notes update**

This patch adds new API structures and fields to the public cryptodev interface. The current release notes should be updated to document this API addition.

Add an entry to `doc/guides/rel_notes/release_26_11.rst` (or the appropriate current release file) under "New Features" describing the RSA capability reporting enhancement.

**3. Missing Doxygen for `hash_algos` usage context**

The new RSA capability structure documents that "Primary hash algorithms for RSA operations (e.g. OAEP, PSS) are reported separately via hash_algos" but the `hash_algos` field in `struct rte_cryptodev_asymmetric_xform_capability` does not document this RSA-specific usage.

Consider adding to the `hash_algos` field documentation:
```c
uint64_t hash_algos;
/**< Bitmask of supported hash algorithms.
 * For RSA transforms, represents primary digest algorithms
 * (e.g., for OAEP and PSS). MGF1 hash support is reported
 * separately in rsa_capa.mgf1_hash_algos.
 * Each bit corresponds to enum rte_crypto_auth_algorithm.
 */
```

**4. Zero-value semantics could be clearer**

The documentation states "A value of 0 means ... is not reported and the PMD default may apply" for multiple fields. The phrase "PMD default may apply" is vague about application behavior. Consider clarifying whether applications should:
- Query the PMD through another mechanism
- Assume common defaults (e.g., PKCS#1 v1.5 padding)
- Treat the capability as unknown

Suggested improvement:
```c
/**< Bitmask of supported RSA padding schemes.
 * Each bit corresponds to enum rte_crypto_rsa_padding_type.
 * A value of 0 indicates padding capability is not advertised;
 * applications must consult PMD documentation or test at runtime
 * for supported padding types.
 */
```

### Info

**1. Structure alignment consideration**

The new `struct rte_crypto_rsa_capa` contains:
- `struct rte_crypto_param_range modlen` (likely 12 bytes: 3 x uint32_t)
- `uint8_t pad_types` (1 byte)
- `uint64_t mgf1_hash_algos` (8 bytes)

This creates 3 bytes of padding between `pad_types` and `mgf1_hash_algos`. Consider reordering fields to minimize padding:

```c
struct rte_crypto_rsa_capa {
    struct rte_crypto_param_range modlen;
    uint64_t mgf1_hash_algos;
    uint8_t pad_types;
    /* 7 bytes padding at end instead of 3 bytes in middle */
};
```

While this is not an error, it slightly reduces structure size and makes the padding explicit at the end rather than hidden in the middle.

**2. Enum reference precision**

The documentation states "Each bit corresponds to enum rte_crypto_rsa_padding_type" and "Each bit corresponds to enum rte_crypto_auth_algorithm" but doesn't specify the bit-to-enum mapping convention. Consider adding a cross-reference or example:

```c
/**< Bitmask of supported RSA padding schemes.
 * Bit N set indicates support for (enum rte_crypto_rsa_padding_type)N.
 * Example: (1 << RTE_CRYPTO_RSA_PADDING_PKCS1_5) indicates PKCS#1 v1.5 support.
 */
```

---

## Summary

The patch correctly extends the asymmetric crypto capability structure to support RSA-specific parameters. The main issue is the missing `__rte_experimental` tag on the new structure, which is required for all new API additions. Release notes should also be updated. The documentation is generally clear but could be improved with more specific guidance on zero-value semantics and bit-to-enum mapping.