Document the AWS-LC provider - #3434
Conversation
|
🔒 Security Review — View Report Please review before merging. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3434 +/- ##
=======================================
Coverage ? 78.14%
=======================================
Files ? 700
Lines ? 125595
Branches ? 17373
=======================================
Hits ? 98143
Misses ? 26582
Partials ? 870 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
896d62b to
73cf88a
Compare
73cf88a to
8b1bbf1
Compare
5ac2ebc to
5276086
Compare
| ```bash | ||
| # Build OpenSSL from source. It supplies the provider headers AWS-LC's tree | ||
| # does not carry. The minimum required OpenSSL version is 3.5. | ||
| git clone https://github.com/openssl/openssl.git |
There was a problem hiding this comment.
The CI pins openssl-3.5.5; I think the README should too. (An unpinned clone builds OpenSSL master -- "4.x-dev".)
| git clone https://github.com/openssl/openssl.git | |
| git clone --branch openssl-3.5.5 --depth 1 https://github.com/openssl/openssl.git |
There was a problem hiding this comment.
I commented in the 3.5 minimum requirement and I consider it a safe assumption that master is always newer than that. Forcing in this 3.5.5 tag just adds in a staleness liability (in fact the latest 3.5.x is already 3.5.8) that we need to maintain.
| # Build AWS-LC and the provider. The provider uses shared libraries and the | ||
| # upstream OpenSSL build for header files and testing. |
There was a problem hiding this comment.
"uses shared libraries" reads as descriptive, but BUILD_SHARED_LIBS=ON is a requirement: with a static libcrypto.a, it gets linked into the module and every AWS-LC public symbol becomes an export of awslc.so -- see comment on #3433. Suggest stating it here as a requirement (unless the build properly supports BUILD_SHARED_LIBS=OFF).
| # Build AWS-LC and the provider. The provider uses shared libraries and the | |
| # upstream OpenSSL build for header files and testing. | |
| # Build AWS-LC and the provider. BUILD_SHARED_LIBS=ON is required. The provider uses | |
| # shared libraries and the upstream OpenSSL build for header files and testing. |
There was a problem hiding this comment.
Support for BUILD_SHARED_LIBS=OFF would be incidental and not something we're explicitly guaranteeing would work. I'll make the doc change here, but I don't think we need to explicitly restrict the ability to build that configuration.
| # Build with symbol versioning via ENABLE_DIST_PKG in AWS-LC (Linux only) | ||
| cmake -GNinja -Bbuild -DCMAKE_BUILD_TYPE=Release \ | ||
| -DBUILD_SHARED_LIBS=ON -DENABLE_DIST_PKG=ON \ | ||
| -DBUILD_AWSLC_PROVIDER=ON -DAWSLC_PROVIDER_OPENSSL_ROOT="${OPENSSL_ROOT}" |
There was a problem hiding this comment.
- This build gets a
FATAL_ERRORon macOS and Windows. - Suggest framing it as a Linux alternative:
| # Build with symbol versioning via ENABLE_DIST_PKG in AWS-LC (Linux only) | |
| cmake -GNinja -Bbuild -DCMAKE_BUILD_TYPE=Release \ | |
| -DBUILD_SHARED_LIBS=ON -DENABLE_DIST_PKG=ON \ | |
| -DBUILD_AWSLC_PROVIDER=ON -DAWSLC_PROVIDER_OPENSSL_ROOT="${OPENSSL_ROOT}" | |
| # On Linux, add ENABLE_DIST_PKG=ON to get the versioned soname CI ships with | |
| # (see "Installing the module" below for why that matters). Not supported on | |
| # macOS or Windows. | |
| cmake -GNinja -Bbuild -DCMAKE_BUILD_TYPE=Release \ | |
| -DBUILD_SHARED_LIBS=ON -DENABLE_DIST_PKG=ON \ | |
| -DBUILD_AWSLC_PROVIDER=ON -DAWSLC_PROVIDER_OPENSSL_ROOT="${OPENSSL_ROOT}" |
There was a problem hiding this comment.
The original comment already states "(Linux Only)". How is this change qualitatively different?
| OpenSSL loads a provider by bare name from its modules directory, appending the platform's | ||
| suffix. Copy the built module there: | ||
|
|
||
| ```bash | ||
| # Where the OpenSSL you are configuring looks for modules. | ||
| MODULES_DIR="$(openssl version -m | sed 's/^MODULESDIR: //; s/"//g')" | ||
|
|
||
| cp build/provider/awslc.so "${MODULES_DIR}/" |
There was a problem hiding this comment.
This is the biggest gap. With BUILD_SHARED_LIBS=ON, awslc.so has an undefined dependency on AWS-LC's libcrypto.so. After cp into MODULESDIR, dlopen resolves that by soname, and without ENABLE_DIST_PKG the soname is plain libcrypto.so -- the same name as OpenSSL's, which is already loaded in the process. So the copy either fails to load (AWS-LC's libcrypto not on the loader path) or silently binds the backend to OpenSSL's libcrypto, which is exactly the misbinding verify_linkage.sh exists to catch.
The section should say that installing requires the ENABLE_DIST_PKG build (versioned soname) with AWS-LC's libcrypto installed on the loader path, or an INSTALL_RPATH on the module. As written, a reader following this verbatim gets a non-working or misbound setup.
There was a problem hiding this comment.
Good catch, we're definitely lacking clear guidance on how to fully build/deploy the AWS-LC part of this.
4 participants
Description of changes:
This change documents how to build, test, install, activate, and verify the
AWS-LC provider. It includes configuration-file and programmatic activation
examples, explains the optional
?provider=awslcpreference and default-providerfallback, and describes the frontend/backend source layout.
It also adds
ALGORITHM_SUPPORT.md, organized by OpenSSL operation class, withSHA2-256 recorded as the provider's initial supported algorithm.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.