Make any structure with potentially variable size opaque

[DemiMarie]

Problem:

The HPKE structure size had to be changed for ML-KEM support. This breaks ABI.

Solution:

Make these structs, and all structs with sizes that might change in the future, opaque.

• Does this change any public APIs? Structs that have sizes that might change in the future become pointers to heap-allocated opaque types.
• Which algorithm(s) will this impact? HPKE, possibly others.

Requirements / Acceptance Criteria:

Anything with a size that isn’t future-proof becomes a pointer to a heap-allocated opaque type.

• RFC links: None
• Related Issues: None
• Will the Usage Guide or other documentation need to be updated? Yes
• Testing: Normal testing of callers should suffice.
  • Will this change trigger AWS LibCrypto Formal Verification changes? No
  • Should this change be fuzz tested? Only for out of memory conditions.

Out of scope:

Being able to link OpenSSL and AWS-LC in the same binary.

[torben-hansen]

The HPKE structure size had to be changed for ML-KEM support. This breaks ABI.

Expanding HPKE support is something we might do, which would involve solving any blockers.

Being able to link OpenSSL and AWS-LC in the same binary.

This should be possible today using either symbol versioning or symbol prefixing build modes.

[DemiMarie]

The HPKE structure size had to be changed for ML-KEM support. This breaks ABI.

Expanding HPKE support is something we might do, which would involve solving any blockers.

My main concern is #3277 (comment): the HPKE ABI has already been broken. That’s why I suggest removing the old API, and replacing it with one that uses pointers to heap-allocated structs. The new struct is already too large to reasonably stack-allocate.

Being able to link OpenSSL and AWS-LC in the same binary.

This should be possible today using either symbol versioning or symbol prefixing build modes.

Does this require changing the code that uses AWS-LC? It would be awesome if a distro could link libcurl against AWS-LC, while continuing to use OpenSSL elsewhere.

[torben-hansen]

To answer your first question:

Does this require changing the code that uses AWS-LC? It would be awesome if a distro could link libcurl against AWS-LC, while continuing to use OpenSSL elsewhere.

This is doable, but it's not something we document in detail because it can be a bit fragile, nor provide specific support for. But we do use these methods ourselves.

One method is symbol prefixing. See e.g. https://github.com/aws/aws-lc-rs/blob/main/scripts/generate/_generate_prefix_headers.sh

Another method can be derived from AL2027 which ships with AWS-LC and OpenSSL: https://aws.amazon.com/linux/amazon-linux-2027. To see that you would have to get the source RPM and research the build.

[DemiMarie]

To answer your first question:

Does this require changing the code that uses AWS-LC? It would be awesome if a distro could link libcurl against AWS-LC, while continuing to use OpenSSL elsewhere.

This is doable, but it's not something we document in detail because it can be a bit fragile, nor provide specific support for. But we do use these methods ourselves.

I think this would be extremely useful for wider adoption of AWS-LC in distros. Libraries often use OpenSSL internally, but exposing its types in public APIs is much less common. Flag-day style all-at-once transitions tend to be a nightmare for distro packagers, whereas incremental transitions are much more likely to succeed.

One method is symbol prefixing. See e.g. https://github.com/aws/aws-lc-rs/blob/main/scripts/generate/_generate_prefix_headers.sh

Another method can be derived from AL2027 which ships with AWS-LC and OpenSSL: https://aws.amazon.com/linux/amazon-linux-2027. To see that you would have to get the source RPM and research the build.

Would symbol versioning solve this automatically, provided that AWS-LC is built as a shared library? Then libcurl would look for the symbol with AWS-LC’s version, which won’t collide with OpenSSL.