SHA1SignaturesGuidance

My package uses SHA-1 and now it is broken. What do I do?

If you discover that a package you maintain uses SHA-1 signatures, or a user files a bug alleging that your package breaks when using SHA-1 signatures, this will have to be planned for Fedora 41. Follow the steps below:

Reproduce

Try to reproduce the problem and verify that it is actually caused by use of a SHA-1 signature. Depending on the Fedora version, you have multiple ways to do this.

Make it fail

On Fedora 41 rawhide, the operation should fail when run under the TEST-FEDORA41 crypto-policy. The plan is to make it DEFAULT if the change is accepted. Use update-crypto-policies --set TEST-FEDORA41 from the crypto-policies-scripts package to set the policy. When switching back to the previous policy (usually DEFAULT) using update-crypto-policy --set DEFAULT the SHA-1 signature operation should work. If the problem persists in the DEFAULT policy, it isn't caused by the deprecation of SHA-1 signatures.

Use tracing

Warning: this first needs the following patch to openssl.

Alternatively, in a policy that doesn't block SHA-1 signature operations, you can use sha1sig-tracer from asosedkin's copr:

sudo dnf copr enable asosedkin/sha1sig-tracer
sudo dnf install sha1sig-tracer

In the DEFAULT or any other crypto-policy where SHA-1 signatures are trusted, start sha1sig-tracer as root. Then run your test. If your component uses a SHA-1 signature, the tracer is going to print a line that matches

command-name[PID] uses mdnid={sha1,md5_sha1,sha1WithRSA} in fedora_probe_name

If sha1sig-tracer doesn't print a line, the operation either failed completely, for example, because your system was using the TEST-FEDORA41 crypto-policy, or the problem isn't caused by the deprecation of SHA-1 signatures.

Do nothing

Provided the change will be accepted, the bug reports will start flowing in as soon as TEST-FEDORA41 becomes the DEFAULT.

Reproduction says my package uses SHA-1 signatures. What now?

We're deprecating SHA-1 in signatures because chosen-prefix collision attacks on SHA-1 are becoming increasingly feasible. Specifically, https://sha-mbles.github.io claims a complexity of 2^63.4, and a cost of 45k US dollars, with an estimated cost of 10k US dollars by 2025 to find a chosen-prefix collision for a SHA-1 signature.

In the worst case, a chosen-prefix collision can mean that an existing signature can be re-used for different content. In this case signature verification would pass although an attacker modified the signed content. This breaks the security guarantees of the signature.

If your package supports different digest algorithms, you should change defaults to prefer a newer hash algorithm, such as SHA-256 or SHA-3.

Cryptographic agility

Ideally, the software you are packaging supports cryptographic algorithm agility. This means that it includes algorithm identifiers in messages it transmits or sends, so that remote systems accept messages signed with newer digest algorithms and don't cause interoperability problems.

Incoming messages signed with SHA-1 signatures aren't going to verify. Where necessary for uninterrupted operation, you should modify your package's configuration or source code to no longer expect SHA-1 signatures to verify and instead treat them as if they were unsigned.

Cryptographic immobility or outdated standards

If your package doesn't support cryptographic agility or attempts to comply with a standard that demands that you support SHA-1 signatures, you should start a discussion upstream or with the authors of the standard to adopt modern digest algorithms. You should refer to the discussion of the cost of breaking a SHA-1 signature using a chosen-prefix collision. For this reason, multiple standardization bodies have moved to deprecate SHA-1 signatures years ago, for example the CA/Browser forum in 2014 with a final sunset date of 2017.

Detecting SHA-1 signature support at runtime

Your application may want to detect whether SHA-1 signatures are supported at runtime. Unfortunately, OpenSSL currently doesn't offer a dedicated API to do this. For now, we recommend that you attempt verification of a known-good SHA-1 signature to determine whether they're supported. We're planning to work with OpenSSL upstream to potentially introduce a more suitable API for supported digests in signatures in the future.

My package's tests fail because they use SHA-1 signatures

For package builds, you can export the OPENSSL_ENABLE_SHA1_SIGNATURES environment variable. Its value doesn't matter, the code only checks for its presence. Note that this environment variable is explicitly unsupported at runtime, and we're going to remove it without forewarning in a future version of OpenSSL on Fedora.

Don't use this environment variable to work around problems at runtime.

Switching SHA-1 signature support on at runtime

At the moment, we don't provide a public API to enable SHA-1 signature support in OpenSSL programmatically. We ask you to respect the system administrator's configuration choice on this. We're planning to work with OpenSSL upstream to introduce a more suitable API in the future, and are going to update these instructions when such an API becomes available.

As soon as it does, you must however not unconditionally re-enable SHA-1 signatures, but make users explicitly opt-in into re-enabling SHA-1 signatures for your package. Moreover, component going for the workaround must be added to the WeakCryptographyException list, describing the explicit opt-in procedure and linking to the ongoing effort to migrate from SHA-1.

When in doubt, contact the Fedora security team: https://lists.fedoraproject.org/admin/lists/security.lists.fedoraproject.org