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 addressed by Fedora 38-39. 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 36-37 and 38 released, the operation should fail when run in the FUTURE (or TEST-FEDORA39) crypto-policy. Use update-crypto-policies --set FUTURE or update-crypto-policies --set TEST-FEDORA39 from the crypto-policies-scripts package to set the policy. When switching back to the DEFAULT or LEGACY policy using update-crypto-policy --set DEFAULT or update-crypto-policy --set LEGACY, the SHA-1 signature operation should work. If the problem persists in the DEFAULT or LEGACY policies, it isn't caused by the deprecation of SHA-1 signatures.

Use tracing

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 LEGACY crypto-policy, where SHA-1 operations work, 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 in the FUTURE or TEST-FEDORA39 crypto-policy, or the problem isn't caused by the deprecation of SHA-1 signatures.

Do nothing: Fedora 38 pre-Beta, Fedora 39 or newer

Fedora 38 will start with blocking SHA-1 usage in signatures by default, then revert in time for Beta to give you more time to file and fix bugs. Fedora 39 will start with blocking SHA-1 usage in signature by default since its branch-off and the change will not be reverted.

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