Update README.md to include HMAC key length recommendations #447
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Added JWA HMAC secret key length requirement information
panva
reviewed
Oct 24, 2020
| @@ -70,6 +70,12 @@ Algorithm algorithmRS = Algorithm.RSA256(publicKey, privateKey); | |||
|
|
|||
| > Note: How you obtain or read keys is not in the scope of this library. For an example of how you might implement this, see [this gist](https://gist.github.com/lbalmaceda/9a0c7890c2965826c04119dcfb1a5469). | |||
|
|
|||
| ##### HMAC Key Length and Security | |||
|
|
|||
| When using a Hash-based Message Authenticaton Code e.g. HS256 or HS512, in order to comply with the strict requirements of the JSON Web Algorithms (JWA) specification (RFC7518), you **must** use a secret key which has the same bit length as the size of the output hash - to avoid weakening the security strength of the authentication code (see NIST recomendations NIST SP 800-117). For example, when using HMAC256, the secret key length must be a minimum of 256 bits (larger key sizes do not increase the security strength further). | |||
There was a problem hiding this comment.
Suggested change
| When using a Hash-based Message Authenticaton Code e.g. HS256 or HS512, in order to comply with the strict requirements of the JSON Web Algorithms (JWA) specification (RFC7518), you **must** use a secret key which has the same bit length as the size of the output hash - to avoid weakening the security strength of the authentication code (see NIST recomendations NIST SP 800-117). For example, when using HMAC256, the secret key length must be a minimum of 256 bits (larger key sizes do not increase the security strength further). | |
| When using a Hash-based Message Authenticaton Code e.g. HS256 or HS512, in order to comply with the strict requirements of the JSON Web Algorithms (JWA) specification (RFC7518), you **must** use a secret key which has the same (or larger) bit length as the size of the output hash - to avoid weakening the security strength of the authentication code (see NIST recomendations NIST SP 800-117). For example, when using HMAC256, the secret key length must be a minimum of 256 bits. |
panva
reviewed
Oct 24, 2020
|
|
||
| When using a Hash-based Message Authenticaton Code e.g. HS256 or HS512, in order to comply with the strict requirements of the JSON Web Algorithms (JWA) specification (RFC7518), you **must** use a secret key which has the same bit length as the size of the output hash - to avoid weakening the security strength of the authentication code (see NIST recomendations NIST SP 800-117). For example, when using HMAC256, the secret key length must be a minimum of 256 bits (larger key sizes do not increase the security strength further). | ||
|
|
||
| Note, the secret key string is converted to bytes assuming a UTF-8 encoding, you must therefore gurantee the results of that conversion produce the required bit length. For example, if only ASCII characters where used in the secret key, each character would convert to a single byte (8 bits), which means for HS256 you would need a mimimum of a 32 character secret. |
There was a problem hiding this comment.
is there no affordance for passing non-utf8 secrets? As in - providing the byte array directly?
There was a problem hiding this comment.
I think the API for the Algorithm class supports byte arrays directly, yes. You could perhaps remove the last paragraph if you wanted.
However, I still think it is probably wise to let people know what happens if they do use a String input to the Algorithm API. Because I can not see there is an option to tell it that the String is actually a binary to text representation e.g. base64.
panva
reviewed
Feb 4, 2021
There was a problem hiding this comment.
I'd suggest to make the changes previously suggested and remove the second paragraph.
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Added JWA HMAC secret key length requirement information
Changes
Please describe both what is changing and why this is important. Include:
References
Please include relevant links supporting this change such as a:
Testing
Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and/or integration testing, tests should be added for new functionality and existing tests should complete without errors.
Checklist