From e3ed3114b7f032ea092dd911a7e5b26ba74ab25e Mon Sep 17 00:00:00 2001 From: Phil Smart Date: Sat, 24 Oct 2020 10:09:02 +0100 Subject: [PATCH] Update README.md Added JWA HMAC secret key length requirement information --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d1b5948c..fc268af0 100644 --- a/README.md +++ b/README.md @@ -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). + +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. + #### Using a KeyProvider: By using a `KeyProvider` you can change in runtime the key used either to verify the token signature or to sign a new token for RSA or ECDSA algorithms. This is achieved by implementing either `RSAKeyProvider` or `ECDSAKeyProvider` methods: @@ -435,4 +441,4 @@ If you have found a bug or if you have a feature request, please report them at This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info. -[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fjava-jwt.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fjava-jwt?ref=badge_large) \ No newline at end of file +[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fjava-jwt.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fjava-jwt?ref=badge_large)