Our components rely on cryptographic primitives provided by NSS. Every month or so, a new version of NSS is published and we should try to keep our version as up-to-date as possible.

Because it makes unit testing easier on Android, and helps startup performance on iOS, we compile NSS ourselves and link to it statically. Note that NSS is mainly used by Mozilla as a dynamic library and the NSS project is missing related CI jobs (iOS builds, windows cross-compile builds etc.) so you should expect breakage when updating the library (hence this guide).

## Updating the Version

The build code is located in the libs/ folder.

The version string is located in the beginning of build-all.sh. For most NSS upgrades, the only action needed is to bump the version number in this file and update the downloaded archive checksum. The actual build invocations are located in platform-specific script files (e.g. build-nss-ios.sh) but usually don't require any changes.

To test out updating NSS version:

• Ensure you've bumped the NSS in build-all.sh
• Clear any old NSS build artifacts: rm -rf ./libs/desktop && cargo clean
• Install the updates version: ./libs/verify-desktop-environment.sh
• Try it out: cargo test

### Updating the Cross-Compiled NSS Artifacts

We use a Linux TC worker for cross-compiling NSS for iOS, Android and Linux desktop machines. However, due to the complexity of the NSS build process, there is no easy way for cross-compiling MacOS and Windows -- so we currently use pre-built artifacts for MacOS desktop machines (ref #5210).

1. Look for the tagged version Taskcluster builds from the NSS CI and pull the appropiate build (usually the first task with the title "B"):
• For Intel MacOS: mac opt-static
2. You'll then need to copy the link to the artifact dist.tar.bz2 and update the URLs and corresponding checksums in build-nss-desktop.sh.
• Note: To get the checksum, you can run shasum -a 256 {path-to-artifact} or you can make a PR and see the output of the failed log.

## Exposing new functions

If the new version of NSS comes with new functions that you want to expose, you will need to:

## Tips for Fixing Bustage

On top of the primitives provided by NSS, we have built a safe Rust wrapper named rc_crypto that links to NSS and makes these cryptographic primitives available to our components.

The linkage is done by the nss_build_common crate. Note that it supports a is_gecko feature to link to NSS dynamically on Desktop.

Because the NSS static build process does not output a single .a file (it would be great if it did), this file must describe for each architecture which modules should we link against. It is mostly a duplication of logic from the NSS gyp build files. Note that this logic is also duplicated in our NSS lib build steps (e.g. build-nss-desktop.sh).

One of the most common build failures we get when upgrading NSS comes from NSS adding new vectorized/asm versions of a crypto algorithm for a specific architecture in order to improve performance. This new optimized code gets implemented as a new gyp target/module that is emitted only for the supported architectures. When we upgrade our copy of NSS we notice the linking step failing on CI jobs because of undefined symbols.

This PR shows how we update nss_common_build and the build scripts to accommodate for these new modules. Checking the changelog for any suspect commit relating to hardware acceleration is rumored to help.