-
-
Notifications
You must be signed in to change notification settings - Fork 602
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Luís Cobucci <[email protected]>
- Loading branch information
Showing
3 changed files
with
221 additions
and
0 deletions.
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
version: 2 | ||
|
||
build: | ||
os: ubuntu-22.04 | ||
tools: | ||
python: 3 | ||
|
||
mkdocs: | ||
configuration: mkdocs.yml |
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,211 @@ | ||
# Rotating Keys | ||
|
||
Key rotation consists in retiring and replacing cryptographic keys with new ones. | ||
Performing that operation on a regular basis is an industry standard. | ||
|
||
## Why should I rotate my keys? | ||
|
||
Rotating keys allows us to: | ||
|
||
1. Limit the number of tokens signed with the same key, helping the prevention of attacks enabled by cryptanalysis | ||
2. Adopt other algorithms or stronger keys | ||
3. Limit the impact of eventual compromised keys | ||
|
||
## The challenges | ||
|
||
After rotating keys, apps will likely receive requests with tokens issues with the previous key. | ||
If the key rotation of an app is done with a "hard cut", requests with non-expired tokens issued with the old key **will fail**! | ||
|
||
Imagine if you were the user who logged in just before a key rotation on that kind of app, you'd probably have to log in again! | ||
|
||
That's rather frustrating, right!? | ||
|
||
## Preventing issues | ||
|
||
It's possible to handle key rotation in a smoother way by leveraging the `SignedWithOneInSet` validation constraint! | ||
|
||
Say your application uses the symmetric algorithm `HS256` with a not so secure key to issue tokens: | ||
|
||
```php | ||
<?php | ||
declare(strict_types=1); | ||
|
||
namespace MyApp; | ||
|
||
require 'vendor/autoload.php'; | ||
|
||
use DateTimeImmutable; | ||
use Lcobucci\Clock\FrozenClock; | ||
use Lcobucci\JWT\Builder; | ||
use Lcobucci\JWT\JwtFacade; | ||
use Lcobucci\JWT\Signer; | ||
use Lcobucci\JWT\Signer\Key\InMemory; | ||
|
||
// `FrozenClock` is used here to fix to a point in time that allows our validation to pass | ||
$clock = new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:01+00:00')); | ||
$token = (new JwtFacade(clock: $clock))->issue( | ||
new Signer\Hmac\Sha256(), | ||
InMemory::plainText( | ||
'a-very-long-and-secure-key-that-should-actually-be-something-else' | ||
), | ||
static fn (Builder $builder): Builder => $builder | ||
->issuedBy('https://api.my-awesome-app.io') | ||
->permittedFor('https://client-app.io') | ||
); | ||
``` | ||
|
||
!!! Sample | ||
Here's a token issued with the code above, if you want to test the script locally: | ||
|
||
<details> | ||
<summary>Sample token</summary> | ||
// line breaks added for readability | ||
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 | ||
.eyJpYXQiOjE2OTkxMzE5NjEsIm5iZiI6MTY5OTEzMTk2MSwiZXhwIjoxNjk5MTMyMjYxLCJpc3MiOiJ | ||
odHRwczovL2FwaS5teS1hd2Vzb21lLWFwcC5pbyIsImF1ZCI6Imh0dHBzOi8vY2xpZW50LWFwcC5pbyJ9 | ||
.IA9S0n8Q2O97lyR8KczVE8g-hxbbH6_TfJS-JWTQR4c | ||
</details> | ||
|
||
Your parsing logic (with validations) look like: | ||
|
||
```php | ||
<?php | ||
declare(strict_types=1); | ||
|
||
namespace MyApp; | ||
|
||
require 'vendor/autoload.php'; | ||
|
||
use DateTimeImmutable; | ||
use Lcobucci\Clock\FrozenClock; | ||
use Lcobucci\JWT\JwtFacade; | ||
use Lcobucci\JWT\Signer; | ||
use Lcobucci\JWT\Signer\Key\InMemory; | ||
use Lcobucci\JWT\Validation\Constraint; | ||
|
||
$validationConstraints = [ | ||
new Constraint\SignedWith( | ||
new Signer\Hmac\Sha256(), | ||
InMemory::plainText( | ||
'a-very-long-and-secure-key-that-should-actually-be-something-else' | ||
), | ||
), | ||
new Constraint\StrictValidAt( | ||
// `FrozenClock` is used here to fix to a point in time that allows our | ||
// validation to pass | ||
new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:35+00:00')) | ||
) | ||
]; | ||
|
||
$jwt = ''; // Fetched from, for example, a request header | ||
|
||
$token = (new JwtFacade())->parse($jwt, ...$validationConstraints); | ||
``` | ||
|
||
### Performing a backwards compatible rotation | ||
|
||
Now Imagine that you want to adopt the new `BLAKE2B` symmetric algorithm. | ||
|
||
These are the changes to your issuing logic: | ||
|
||
```diff | ||
<?php | ||
declare(strict_types=1); | ||
|
||
namespace MyApp; | ||
|
||
require 'vendor/autoload.php'; | ||
|
||
use DateTimeImmutable; | ||
use Lcobucci\Clock\FrozenClock; | ||
use Lcobucci\JWT\Builder; | ||
use Lcobucci\JWT\JwtFacade; | ||
use Lcobucci\JWT\Signer; | ||
use Lcobucci\JWT\Signer\Key\InMemory; | ||
|
||
// `FrozenClock` is used here to fix to a point in time that allows our validation to pass | ||
$clock = new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:01+00:00')); | ||
$token = (new JwtFacade(clock: $clock))->issue( | ||
- new Signer\Hmac\Sha256(), | ||
+ new Signer\Blake2b(), | ||
- InMemory::plainText( | ||
- 'a-very-long-and-secure-key-that-should-actually-be-something-else' | ||
+ InMemory::base64Encoded( | ||
+ 'GOu4rLyVCBxmxP+sbniU68ojAja5PkRdvv7vNvBCqDQ=' | ||
), | ||
static fn (Builder $builder): Builder => $builder | ||
->issuedBy('https://api.my-awesome-app.io') | ||
->permittedFor('https://client-app.io') | ||
); | ||
``` | ||
|
||
!!! Sample | ||
Here's a token issued with the code above, if you want to test the script locally: | ||
|
||
<details> | ||
<summary>Sample token</summary> | ||
// line breaks added for readability | ||
eyJ0eXAiOiJKV1QiLCJhbGciOiJCTEFLRTJCIn0 | ||
.eyJpYXQiOjE2OTkxMzE5NjEsIm5iZiI6MTY5OTEzMTk2MSwiZXhwIjoxNjk5MTMyMjYxLCJpc3Mi | ||
OiJodHRwczovL2FwaS5teS1hd2Vzb21lLWFwcC5pbyIsImF1ZCI6Imh0dHBzOi8vY2xpZW50LWFwc | ||
C5pbyJ9.bD67s8IXpAJiBTIZn1et_M5WSS7kfmuNiacNRz5lArQ | ||
</details> | ||
|
||
So far, nothing different that a normal rotation. | ||
|
||
Now check the changes on the parsing and validation logic: | ||
|
||
```diff | ||
<?php | ||
declare(strict_types=1); | ||
|
||
namespace MyApp; | ||
|
||
require 'vendor/autoload.php'; | ||
|
||
use DateTimeImmutable; | ||
use Lcobucci\Clock\FrozenClock; | ||
use Lcobucci\JWT\JwtFacade; | ||
use Lcobucci\JWT\Signer; | ||
use Lcobucci\JWT\Signer\Key\InMemory; | ||
use Lcobucci\JWT\Validation\Constraint; | ||
|
||
$validationConstraints = [ | ||
- new Constraint\SignedWith( | ||
- new Signer\Hmac\Sha256(), | ||
- InMemory::plainText( | ||
- 'a-very-long-and-secure-key-that-should-actually-be-something-else' | ||
- ), | ||
- ), | ||
+ new Constraint\SignedWithOneInSet( | ||
+ new Constraint\SignedWith( | ||
+ new Signer\Blake2b(), | ||
+ InMemory::base64Encoded( | ||
+ 'GOu4rLyVCBxmxP+sbniU68ojAja5PkRdvv7vNvBCqDQ=' | ||
+ ), | ||
+ ), | ||
+ new Constraint\SignedWith( | ||
+ new Signer\Hmac\Sha256(), | ||
+ InMemory::plainText( | ||
+ 'a-very-long-and-secure-key-that-should-actually-be-something-else' | ||
+ ), | ||
+ ), | ||
+ ), | ||
new Constraint\StrictValidAt( | ||
// `FrozenClock` is used here to fix to a point in time that allows our | ||
// validation to pass | ||
new FrozenClock(new DateTimeImmutable('2023-11-04 21:06:35+00:00')) | ||
) | ||
]; | ||
|
||
$jwt = ''; // Fetched from, for example, a request header | ||
|
||
$token = (new JwtFacade())->parse($jwt, ...$validationConstraints); | ||
``` | ||
|
||
Now the application is able to accept non-expired tokens issued with either old and new keys! | ||
|
||
!!! Important | ||
The order of `SignedWith` constraints given to `SignedWithOneInSet` does matter, and it's recommended to leave older keys at the end of the list. |
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