Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
sop committed Aug 2, 2017
1 parent f145b26 commit c4f121f
Showing 1 changed file with 44 additions and 40 deletions.
84 changes: 44 additions & 40 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
[![License](https://poser.pugx.org/sop/jwx/license)](https://github.com/sop/jwx/blob/master/LICENSE)

# JWX

A PHP library for JSON web tokens
([JWT](https://tools.ietf.org/html/rfc7519))
with signature
Expand All @@ -15,40 +16,44 @@ Also implements unencoded payload option
([RFC 7797](https://tools.ietf.org/html/rfc7797)).

## Features
* Signing and signature validation (JWS)
* HMAC, RSA and EC
* Encryption and decryption with compression and integrity protection (JWE)
* AES
* Claims validation
* Configurable with sensible defaults
* JSON Web Keys (JWK)
* Convert PEM encoded keys to JWK and vice versa

- Signing and signature validation (JWS)
- HMAC, RSA and EC
- Encryption and decryption with compression and integrity protection (JWE)
- AES
- Claims validation
- Configurable with sensible defaults
- JSON Web Keys (JWK)
- Convert PEM encoded keys to JWK and vice versa

## Supported algorithms
* Signature
* HMAC with SHA-256, SHA-384 and SHA-512
* RSASSA-PKCS1-v1_5 with SHA-256, SHA-384 and SHA-512
* ECDSA with P-256, P-384 and P-521 curves
* Content encryption
* AES-CBC with 128, 192 and 256-bit key sizes
* AES-GCM with 128, 192 and 256-bit key sizes
* Key management
* Shared symmetric key (direct)
* RSAES-PKCS1-v1_5
* RSAES OAEP
* AES Key Wrap with 128, 192 and 256-bit key sizes
* AES-GCM key encryption with 128, 192 and 256-bit key sizes
* Password-based key encryption (PBES2 with AES Key Wrap)
* Compression
* DEFLATE

- Signature
- HMAC with SHA-256, SHA-384 and SHA-512
- RSASSA-PKCS1-v1_5 with SHA-256, SHA-384 and SHA-512
- ECDSA with P-256, P-384 and P-521 curves
- Content encryption
- AES-CBC with 128, 192 and 256-bit key sizes
- AES-GCM with 128, 192 and 256-bit key sizes
- Key management
- Shared symmetric key (direct)
- RSAES-PKCS1-v1_5
- RSAES OAEP
- AES Key Wrap with 128, 192 and 256-bit key sizes
- AES-GCM key encryption with 128, 192 and 256-bit key sizes
- Password-based key encryption (PBES2 with AES Key Wrap)
- Compression
- DEFLATE

## Installation

This library is available on
[Packagist](https://packagist.org/packages/sop/jwx).

composer require sop/jwx

## Usage

`Claims` class holds `Claim` objects that represent the claims.
The claims shall be encoded into a JWT which may further be
signed or encrypted, producing a JWS or a JWE respectively.
Expand All @@ -58,7 +63,9 @@ JWS and JWE may also be used to carry arbitrary payload, not just JSON claims.
## Code examples

### Simple JWT

Parse JWT from [https://jwt.io/](https://jwt.io/#debugger-io) example.

```php
$jwt = new JWT($token);
// create context for the claims validation
Expand All @@ -72,7 +79,9 @@ echo $claims->subject()->value() . "\n";
```

### Additional Validation

Parse the same token as above but additionally validate subject and admin claims.

```php
$jwt = new JWT($token);
// validate that the subject is "1234567890"
Expand All @@ -89,24 +98,19 @@ foreach ($claims as $claim) {
```

### More Examples

See [`/examples`](https://github.com/sop/jwx/tree/master/examples)
directory for more examples.
* [Create a signed JWT](
https://github.com/sop/jwx/blob/master/examples/jws-create.php)
* [Consume a signed JWT](
https://github.com/sop/jwx/blob/master/examples/jws-consume.php)
* [Create an encrypted JWT](
https://github.com/sop/jwx/blob/master/examples/jwe-create.php)
* [Consume an encrypted JWT](
https://github.com/sop/jwx/blob/master/examples/jwe-consume.php)
* [Create a nested JWT](
https://github.com/sop/jwx/blob/master/examples/nested-create.php)
* [Consume a nested JWT](
https://github.com/sop/jwx/blob/master/examples/nested-consume.php)
* [Encrypt arbitrary data](
https://github.com/sop/jwx/blob/master/examples/arbitrary-encrypt.php)
* [Decrypt arbitrary data](
https://github.com/sop/jwx/blob/master/examples/arbitrary-decrypt.php)

- [Create a signed JWT](https://github.com/sop/jwx/blob/master/examples/jws-create.php)
- [Consume a signed JWT](https://github.com/sop/jwx/blob/master/examples/jws-consume.php)
- [Create an encrypted JWT](https://github.com/sop/jwx/blob/master/examples/jwe-create.php)
- [Consume an encrypted JWT](https://github.com/sop/jwx/blob/master/examples/jwe-consume.php)
- [Create a nested JWT](https://github.com/sop/jwx/blob/master/examples/nested-create.php)
- [Consume a nested JWT](https://github.com/sop/jwx/blob/master/examples/nested-consume.php)
- [Encrypt arbitrary data](https://github.com/sop/jwx/blob/master/examples/arbitrary-encrypt.php)
- [Decrypt arbitrary data](https://github.com/sop/jwx/blob/master/examples/arbitrary-decrypt.php)

## License

This project is licensed under the MIT License.

0 comments on commit c4f121f

Please sign in to comment.