Skip to content
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

Jump to bottom

[SDK-3125] Updated documentation regarding HMAC Key length #580

Merged
merged 1 commit into from
May 5, 2022
Merged

[SDK-3125] Updated documentation regarding HMAC Key length #580

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
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ You'll first need to create a `JWTVerifier` instance by calling `JWT.require()`
```java
String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
try {
Algorithm algorithm = Algorithm.HMAC256("secret");
Algorithm algorithm = Algorithm.HMAC256("secret"); //use more secure key
JWTVerifier verifier = JWT.require(algorithm)
.withIssuer("auth0")
.build(); //Reusable verifier instance
Expand Down Expand Up @@ -175,7 +175,7 @@ When using RSA or ECDSA algorithms and you just need to **sign** JWTs you can av

```java
//HMAC
Algorithm algorithmHS = Algorithm.HMAC256("secret");
Algorithm algorithmHS = Algorithm.HMAC256("secret"); //use more secure key

//RSA
RSAPublicKey publicKey = //Get the key instance
Expand All @@ -185,9 +185,9 @@ 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
##### :key: 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 (or larger) bit length as the size of the output hash. This is to avoid weakening the security strength of the authentication code (see NIST recommendations NIST SP 800-117). For example, when using HMAC256, the secret key length must be a minimum of 256 bits.
When using a Hash-based Message Authentication 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. This is to avoid weakening the security strength of the authentication code (see NIST recommendations NIST SP 800-117). For example, when using HMAC256, the secret key length must be a minimum of 256 bits.

#### 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:
Expand Down
18 changes: 15 additions & 3 deletions lib/src/main/java/com/auth0/jwt/algorithms/Algorithm.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,9 @@ public static Algorithm RSA512(RSAKey key) throws IllegalArgumentException {
/**
* Creates a new Algorithm instance using HmacSHA256. Tokens specify this as "HS256".
*
* @param secret the secret to use in the verify or signing instance.
* @param secret the secret bytes to use in the verify or signing instance.
* Ensure the length of the secret is at least 256 bit long
* See <a href="https://github.com/auth0/java-jwt#hmac-key-length-and-security">HMAC Key Length and Security in README</a>
* @return a valid HMAC256 Algorithm.
* @throws IllegalArgumentException if the provided Secret is null.
*/
Expand All @@ -142,6 +144,8 @@ public static Algorithm HMAC256(String secret) throws IllegalArgumentException {
* Creates a new Algorithm instance using HmacSHA256. Tokens specify this as "HS256".
*
* @param secret the secret bytes to use in the verify or signing instance.
* Ensure the length of the secret is at least 256 bit long
* See <a href="https://github.com/auth0/java-jwt#hmac-key-length-and-security">HMAC Key Length and Security in README</a>
* @return a valid HMAC256 Algorithm.
* @throws IllegalArgumentException if the provided Secret is null.
*/
Expand All @@ -152,7 +156,9 @@ public static Algorithm HMAC256(byte[] secret) throws IllegalArgumentException {
/**
* Creates a new Algorithm instance using HmacSHA384. Tokens specify this as "HS384".
*
* @param secret the secret to use in the verify or signing instance.
* @param secret the secret bytes to use in the verify or signing instance.
* Ensure the length of the secret is at least 384 bit long
* See <a href="https://github.com/auth0/java-jwt#hmac-key-length-and-security">HMAC Key Length and Security in README</a>
* @return a valid HMAC384 Algorithm.
* @throws IllegalArgumentException if the provided Secret is null.
*/
Expand All @@ -164,6 +170,8 @@ public static Algorithm HMAC384(String secret) throws IllegalArgumentException {
* Creates a new Algorithm instance using HmacSHA384. Tokens specify this as "HS384".
*
* @param secret the secret bytes to use in the verify or signing instance.
* Ensure the length of the secret is at least 384 bit long
* See <a href="https://github.com/auth0/java-jwt#hmac-key-length-and-security">HMAC Key Length and Security in README</a>
* @return a valid HMAC384 Algorithm.
* @throws IllegalArgumentException if the provided Secret is null.
*/
Expand All @@ -174,7 +182,9 @@ public static Algorithm HMAC384(byte[] secret) throws IllegalArgumentException {
/**
* Creates a new Algorithm instance using HmacSHA512. Tokens specify this as "HS512".
*
* @param secret the secret to use in the verify or signing instance.
* @param secret the secret bytes to use in the verify or signing instance.
* Ensure the length of the secret is at least 512 bit long
* See <a href="https://github.com/auth0/java-jwt#hmac-key-length-and-security">HMAC Key Length and Security in README</a>
* @return a valid HMAC512 Algorithm.
* @throws IllegalArgumentException if the provided Secret is null.
*/
Expand All @@ -186,6 +196,8 @@ public static Algorithm HMAC512(String secret) throws IllegalArgumentException {
* Creates a new Algorithm instance using HmacSHA512. Tokens specify this as "HS512".
*
* @param secret the secret bytes to use in the verify or signing instance.
* Ensure the length of the secret is at least 512 bit long
* See <a href="https://github.com/auth0/java-jwt#hmac-key-length-and-security">HMAC Key Length and Security in README</a>
* @return a valid HMAC512 Algorithm.
* @throws IllegalArgumentException if the provided Secret is null.
*/
Expand Down