Skip to content

gh-129327: revise hashlib documentation to account for FIPS removing sha1 #129334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

gh-129327: revise hashlib documentation to account for FIPS removing sha1 #129334

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions Doc/library/hashlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,12 @@

--------------

This module implements a common interface to many different secure hash and
message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
SHA224, SHA256, SHA384, SHA512, (defined in `the FIPS 180-4 standard`_),
the SHA-3 series (defined in `the FIPS 202 standard`_) as well as RSA's MD5
algorithm (defined in internet :rfc:`1321`). The terms "secure hash" and
"message digest" are interchangeable. Older algorithms were called message
digests. The modern term is secure hash.
This module implements a common interface to many different hash algorithms.
Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512,
(defined in `the FIPS 180-4 standard`_), the SHA-3 series (defined in `the FIPS
202 standard`_) as well as the non-cryptographically-secure algorithms SHA1
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, "non-cryptographically-secure" may be too verbose. Let just say "as well as SHA1 (formerly...) and RSA's MD5 (..))". If we want to be precise we should rather add a note concerning the weaknesses of sha1/md5 as cryptographically secure hash functions but I don't know if we wouldn't reinvent the wheel instead in this PR.

WDYT @gpshead? do you think it's fine not to talk too much about security/applications in the first paragraph of hashlib?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd just go with "legacy".

"""... as well as the legacy algorithms SHA1 (formerly part of ...) and the MD5 algorithm (defined in ...)"""

perhaps. This elides attributing MD5 to RSA as well as it isn't important where MD5 came from, that's what the linked-to RFC is for.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with that but I would have used the term "legacy" when talking about something that is only kept for backwards compatibility, and not something that I expect to see in production. Maybe it's more a language issue on my side though.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm however happy if we can remove the mention to RSA though

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

legacy means a lot of things. It is simpler and more pedantically accurate than saying not-cryptographically-secure.

I'd edit this PR myself with those words but it appears the author unchecked the allow-edits checkbox on it (Github isn't showing me an edit option)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eli-schwartz do you plan to update this?

(`formerly part of FIPS`_) and RSA's MD5 algorithm (defined in internet
:rfc:`1321`).

.. note::

Expand Down Expand Up @@ -812,6 +811,7 @@ Domain Dedication 1.0 Universal:
.. _the FIPS 180-4 standard: https://csrc.nist.gov/pubs/fips/180-4/upd1/final
.. _the FIPS 202 standard: https://csrc.nist.gov/pubs/fips/202/final
.. _HACL\* project: https://github.com/hacl-star/hacl-star
.. _formerly part of FIPS: https://csrc.nist.gov/news/2023/decision-to-revise-fips-180-4


.. _hashlib-seealso:
Expand Down
3 changes: 3 additions & 0 deletions Misc/NEWS.d/next/Documentation/2025-01-27-01-21-55.gh-issue-129327.sv2NB1.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Clarify that hashlib's SHA1 is no longer a FIPS secure algorithm. Clarify that
hashlib has a mixture of cryptographically secure and non cryptographically
secure hash algorithms. Patch by Eli Schwartz.
Comment on lines +1 to +3
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doc changes don't need NEWS entries

Loading