Download the PHP package firehed/jwt without Composer
On this page you can find all versions of the php package firehed/jwt. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package jwt
JWT - JSON Web Tokens
Installation
composer require firehed/jwt
Usage
Basic encoding example:
Basic decoding example:
Security: Signing Keys
Generation
The HMAC-SHA family of algorithms supports a key length of up to 512 bits (64 bytes). It is recommended to use the longest supported key.
If on PHP>=7, use random_bytes()
: $secret = random_bytes(64)
;
Since these probably contain binary data, it's best to store them base64-encoded:
Your configuration file, explained below, should base64_decode
the encoded string before returning it
IDs and rotation
It is highly recommended to regularly rotate your signing keys, and the JWT spec makes this easy to handle thanks to the kid
header. Encoded output will always include the key id used to sign the token, and that value will automatically be used during decoding.
In your application config, have multiple keys and their IDs defined:
Simply adding additional keys to the container should more-or-less automatically handle key rotation for all new tokens, but your application may behave in a different way that doesn't ensure this is the case.
By default, the KeyContainer
will use the most recently added key if one is not explicitly requested. You may override this by explicitly setting a default key:
$keys->setDefaultKey('20160101');
Note: key ID can take any scalar format. The example above uses a datestamp, but sequential integers are also fine. It is recommended to use something semantically meaningful to the application, but not in any way meaningful to the end-user.
Security: Exception Handling
When calling getClaims()
, an exception may be thrown if the signature cannot be verified or the time validity specified in standard nbf
or exp
claims is out of line.
Be prepared to catch InvalidSignatureException
, TokenExpiredException
, and TokenNotYetValidException
when calling those methods.
If an invalid token is passed to JWT::fromEncoded()
, an InvalidFormatException
will be thrown.
Exception tree:
Algorithm Support
As of v2.0.0, the following algorithms are supported:
none
HS256
(HMAC-SHA256)HS384
(HMAC-SHA384)HS512
(HMAC-SHA512)
Because the none
algorithm is inherently insecure, the encoded data may only be accessed with the getUnverifiedClaims()
API call. This is to call explicit attention to the fact that the data cannot be trusted. It is strongly recommended to never use the none
algorithm.
The algorithm in the header is intentionally ignored during verification to avoid algorithm-swapping attacks. This library instead uses the kid
(Key ID) header, matching the value to the keys available in the KeyContainer
. Asymmetric keys are not supported at this time.
Sessions
Because JWTs are cryptographically signed, it's now both possible and practical to keep basic session handling completely client-side, removing the dependency on a database connection or the filesystem (and the complexity of scaling that to multiple servers). A class implementing PHP's SessionHandlerInterface
is included to make this easier.
Generally speaking, storing session data other than identifiers client-side is a bad decision. It's useful for quick prototying, or in extremely resource-constrained environments.
There are some very important considerations:
-
The JWT session cookie will use the values from
session_get_cookie_params
. PHP HAS INSECURE DEFAULT VALUES FOR THESE, and you must reconfigure them withsession_set_cookie_params
to ensure thesecure
andhttponly
cookie flags are set. This is not done automatically nor enforced to make local testing easier. -
The session MUST NOT contain sensitive information. JWTs are not encrypted, just encoded and signed. You must be OK with any data in the session being visible to the user.
-
Because this uses only cookies for storage, there is very limited space available (~4096b for all cookies) and all future network requests will incur the overhead. This makes basic authentication info (e.g.
$_SESSION['user_id'] = 12345;
) and state management practical, but a poor choice if your sessions contain a lot of data or you use several other cookies. -
Because the data is stored entirely client-side, it will be largely impractical to build functionality like "log me out everywhere" if used to store authentication data.
-
Like any other session management, the whole thing is pointless if not done over HTTPS.
- The concept of a session ID is largely ignored
Whenever possible, the SessionHandler
class attempts to use existing PHP configuration for session handling to be a drop-in replacement.
That out of the way, here's how it's done:
Session Example
SessionHandler
will always use the default value from the KeyContainer
. That means the most recently key will be used unless one was specified with ->setDefaultKey()
.