Download the PHP package nimbly/proof without Composer

On this page you can find all versions of the php package nimbly/proof. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package proof

Proof

Latest Stable Version GitHub Workflow Status Codecov branch License

A simple library capable of encoding, decoding, and validating signed JWTs.

Requirements

Installing

Usage overview

Instantiate

Create a new Proof instance with your SignerInterface instance. The signer is responsible for signing your JWT to prevent tampering of your tokens. The Proof instance must be provided with your signing preference: HmacSigner or KeypairSigner (see Signers section for more information).

Create a Token

Create a new Token with claims.

Encode the Token into a JWT string

Encode the Token instance into a JWT string.

Decode the JWT string into a Token

Decode the JWT string into a Token instance.

Tokens

A Token instance represents the payload of the JWT, where the meaningful application level data is stored. Things like the subject of the token, the expiration timestamp, etc. This data is called a claim. For a full list of predefined public claims, see https://www.iana.org/assignments/jwt/jwt.xhtml#claims. You can also use your own custom claims to fit your needs.

Creating a Token

When creating a Token instance, claims may be passed in through the constructor as a simple key => value pair.

Or you can set a claim on a Token by calling the setClaim method.

Encode a Token into a JWT

With a Token instance, you can encode it into a signed JWT by passing it into the encode method. You will be returned a signed JWT string.

Exceptions when encoding

When encoding a Token, there are several failure points that will throw an exception:

Decode a JWT into a Token

When you decode a JWT string it will also verify the signature and check the expiration (exp) and "not before" (nbf) claims (if present). If successful, you will receive a Token instance back loaded with the claims from the payload of the JWT.

You can get a claim on a Token by calling the getClaim method.

You can check whether a claim exists or not by calling the hasClaim method.

You can get all claims on the Token by calling the toArray method.

Exceptions when decoding

When decoding a JWT, there are several failure points that will throw an exception:

Signers

You need a SignerInterface instance to do the signing and verifying of JWTs.

HMAC

The HmacSigner uses a shared secret to sign messages and verify signatures. It is a less secure alternative than using a key pair, as the same secret value used to sign messages must be used in any other system or service that needs to verify that signature.

When using a shared secret, remember that it should be considered highly sensitive data and, as such, should not be persisted in a code repository (public or private) or deployed within your application. If an unauthorized 3rd party is able to gain access to your shared secret, they will be able to create their own tokens which could lead to leakage of sensitive data of your users and systems. If you suspect your shared secret has been leaked, generate a new shared secret immediately.

Key pair

The KeypairSigner is the preferred signing method as it is more secure than using the HmacSigner. The key pair signer relies on using a private and public key pair. The private key is used to sign the JWT however the public key can only be used to verify signatures.

The KeypairSigner relies on a private and/or a public key as an instance of OpenSSLAsymmetricKey available in PHP since version 4.0 with the openssl extension/module. You can load the keys using the openssl_get_privatekey and openssl_get_publickey PHP functions.

The private key is optional and only required if you need to sign new tokens. The public key is optional and only required if you need to verify signatures of tokens.

For example:

Generating a key pair

If you don't already have one, you can create a key pair using openssl found on most Linux systems.

Using the private key file that was just created (private.pem), output a public key.

You should now have two files called private.pem and public.pem. The private.pem file is your private key and can be used to sign your JWTs. The public.pem file is your public key and can only be used to validate signatures on your signed JWTs.

Separating private and public keys is especially useful in a distributed or microservice architecture where most services only need to validate a JWT but do not generate their own tokens. For those services you only need the public key.

When creating a key pair, remember that your private key should be considered highly sensitive data and, as such, should not be persisted in a code repository (public or private) or deployed within your application. If an unauthorized 3rd party is able to gain access to your private key, they will be able to create their own tokens which could lead to leakage of sensitive data of your users and systems. If you suspect your private key has been leaked, generate a new key pair immediately.

Supporting multiple keys

JWT allows a kid (short for Key ID) claim/property in the header to include a key ID. This key ID should map to a single unique signing key. Proof supports multiple signing keys via the keyMap property in the constructor: you provide a key/value pair array of strings to instances of SignerInterface.

For JWTs that need to be decoded, Proof will check the header for a kid property and, if it exists, will pull the matching SignerInterface instance from the keyMap. If no match was found, a SignerNotFoundException is thrown. If the header does not include a kid property, the default signer will be used to decode.

For encoding new JWTs, you can pass in an optional kid parameter into the encode method. The value of the kid must exist in the key map and will be used to sign the token. If no match was found, a SignerNotFoundException is thrown.

If you do not pass in a kid parameter, the encoding will be done with the default signer.

Custom signers

If you would like to implement your own custom signing solution, a Nimbly\Proof\SignerInterface is provided. Simply implement this interface with your own solution and pass into the Proof constructor.

PSR-15 Middleware

Proof ships with a PSR-15 middleware you can use in your HTTP applications that will validate a JWT from the ServerRequestInterface instance. If the JWT is valid, a Nimbly\Proof\Token attribute will be added to the ServerRequestInterface instance that contains the Nimbly\Proof\Token instance. The Token instance can be used in a further middleware that adds additional context to your request such as a User instance.

If the JWT is invalid, an exception will be thrown. This exception will need to be handled by your application as you see fit. The possible exceptions thrown are:

The middleware defaults to looking for the JWT in the Authorization HTTP header with a Bearer scheme. For example:

You can override this behavior in the constructor by supplying the header name (case insensitive) and scheme (case sensitive). If there is no scheme, you can use a null or empty string value instead.

Decorating ServerRequestInterface instance

A common practice is to decorate your requests with additional attributes to add more context for your request handlers, such as a User entity that contains the user making the request. With the use of the Nimbly\Proof\Middleware\ValidateJwtMiddleware and your own middleware, this becomes a fairly trivial task.

In this example, each request that requires a user account has had that User instance attached to the ServerRequestInteface instance.


All versions of proof with dependencies

PHP Build Version
Package Version
Requires php Version ^8.0
ext-openssl Version *
paragonie/hidden-string Version ^2.0
psr/http-message Version ^1.0
psr/http-server-middleware Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package nimbly/proof contains the following files

Loading the files please wait ....