Skip to content

Commit 245134f

Browse files
Spomkygitbook-bot
Spomky
authored and
gitbook-bot
committed
GitBook: [master] 113 pages modified
1 parent 846e875 commit 245134f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+1264
-1392
lines changed

‎README.md

+75-73
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,109 @@
1+
# Introduction
2+
13
This document is available online at [https://web-token.spomky-labs.com](https://web-token.spomky-labs.com).
24

3-
JWT Framework
4-
=============
5+
## JWT Framework
56

67
This framework provides an implementation of:
78

8-
* JW**S** [JSON Web Signature (RFC 7515)](https://tools.ietf.org/html/rfc7515),
9-
* JW**T** [JSON Web Token (RFC 7519)](https://tools.ietf.org/html/rfc7519),
10-
* JW**E** [JSON Web Encryption (RFC 7516)](http://tools.ietf.org/html/rfc7516),
11-
* JW**A** [JSON Web Algorithms (RFC 7518)](http://tools.ietf.org/html/rfc7518).
12-
* JW**K** [JSON Web Key (RFC 7517)](http://tools.ietf.org/html/rfc7517).
13-
* JSON Web Key Thumbprint ([RFC 7638](https://tools.ietf.org/html/rfc7638)).
9+
* JW**S** [JSON Web Signature \(RFC 7515\)](https://tools.ietf.org/html/rfc7515),
10+
* JW**T** [JSON Web Token \(RFC 7519\)](https://tools.ietf.org/html/rfc7519),
11+
* JW**E** [JSON Web Encryption \(RFC 7516\)](http://tools.ietf.org/html/rfc7516),
12+
* JW**A** [JSON Web Algorithms \(RFC 7518\)](http://tools.ietf.org/html/rfc7518).
13+
* JW**K** [JSON Web Key \(RFC 7517\)](http://tools.ietf.org/html/rfc7517).
14+
* JSON Web Key Thumbprint \([RFC 7638](https://tools.ietf.org/html/rfc7638)\).
1415
* Unencoded Payload Option [RFC7797](https://tools.ietf.org/html/rfc7797).
1516

16-
This framework is not just a library, it also contains a Symfony bundle for an easy integration into your application.
17-
It also provides a standalone console command that will help you to manager your keys and key sets.
17+
This framework is not just a library, it also contains a Symfony bundle for an easy integration into your application. It also provides a standalone console command that will help you to manager your keys and key sets.
1818

19-
# Provided Features
19+
## Provided Features
2020

21-
## Supported Input Types:
21+
### Supported Input Types:
2222

2323
JWS or JWE objects support every input that can be encoded into JSON:
2424

2525
* `string`, `array`, `integer`, `float`...
2626
* Objects that implement the `\JsonSerializable` interface such as `JWK` or `JWKSet`
2727

28-
The [detached](https://tools.ietf.org/html/rfc7515#appendix-F) is supported.
28+
The [detached payload](https://tools.ietf.org/html/rfc7515#appendix-F) is supported.
2929

30-
## Supported Serialization Modes
30+
### Supported Serialization Modes
3131

3232
* Compact JSON Serialization Syntax for JWS and JWE
3333
* Flattened JSON Serialization Syntax for JWS and JWE
3434
* General JSON Serialization Syntax for JWS and JWE
3535

36-
## Supported Compression Methods
36+
### Supported Compression Methods
3737

38-
| Compression Method | Supported | Comment |
39-
| ------------------ |:---------:| --------------------------------------------------------------- |
40-
| Deflate (`DEF`) | YES | |
41-
| GZip (`GZ`) | YES | *This compression method is not described in the specification* |
42-
| ZLib (`ZLIB`) | YES | *This compression method is not described in the specification* |
38+
| Compression Method | Supported | Comment |
39+
| --- | :---: | --- |
40+
| Deflate \(`DEF`\) | YES | |
41+
| GZip \(`GZ`\) | YES | _This compression method is not described in the specification_ |
42+
| ZLib \(`ZLIB`\) | YES | _This compression method is not described in the specification_ |
4343

44-
## Supported Key Types (JWK)
44+
### Supported Key Types \(JWK\)
4545

46-
| Key Type | Supported | Comment |
47-
| -------- |:---------:| -------------------------------------------- |
48-
| `oct` | YES | Symmetric keys |
49-
| `RSA` | YES | RSA based asymmetric keys |
50-
| `EC` | YES | Elliptic Curves based asymmetric keys |
51-
| `OKP` | YES | Octet Key Pair based asymmetric keys |
46+
| Key Type | Supported | Comment |
47+
| --- | :---: | --- |
48+
| `oct` | YES | Symmetric keys |
49+
| `RSA` | YES | RSA based asymmetric keys |
50+
| `EC` | YES | Elliptic Curves based asymmetric keys |
51+
| `OKP` | YES | Octet Key Pair based asymmetric keys |
5252

53-
JWK objects support JSON Web Key Thumbprint ([RFC 7638](https://tools.ietf.org/html/rfc7638)).
53+
JWK objects support JSON Web Key Thumbprint \([RFC 7638](https://tools.ietf.org/html/rfc7638)\).
5454

55-
*Note: we use a `none` key type for the `none` algorithm only.*
55+
_Note: we use a _`none`_ key type for the _`none`_ algorithm only._
5656

57-
## Key Sets (JWKSet)
57+
### Key Sets \(JWKSet\)
5858

5959
JWKSet is fully supported.
6060

61-
## Supported Signature Algorithms
61+
### Supported Signature Algorithms
6262

63-
| Signature Algorithm | Supported | Comment |
64-
| ------------------------------ |:---------:| -------------------------------------------------------------------------------------------------- |
65-
| `HS256`, `HS384` and `HS512` | YES | |
66-
| `HS256`, `ES384` and `ES512` | YES | |
67-
| `RS256`, `RS384` and `RS512` | YES | |
68-
| `PS256`, `PS384` and `PS512` | YES | |
69-
| `none` | YES | **Please note that this is not a secured algorithm. USE IT WITH CAUTION!** |
70-
| *`EdDSA` with `Ed25519` curve* | YES | [For PHP 7.1, third party extension highly recommended](https://github.com/jedisct1/libsodium-php) |
71-
| *`EdDSA` with `Ed448` curve* | NO | No extension or built-in implementation available |
63+
| Signature Algorithm | Supported | Comment |
64+
| --- | :---: | --- |
65+
| `HS256`, `HS384` and `HS512` | YES | |
66+
| `HS256`, `ES384` and `ES512` | YES | |
67+
| `RS256`, `RS384` and `RS512` | YES | |
68+
| `PS256`, `PS384` and `PS512` | YES | |
69+
| `none` | YES | **Please note that this is not a secured algorithm. USE IT WITH CAUTION!** |
70+
| `EdDSA`_ with _`Ed25519`_ curve_ | YES | [With PHP 7.1, third party extension highly recommended](https://github.com/jedisct1/libsodium-php) |
71+
| `EdDSA`_ with _`Ed448`_ curve_ | NO | No extension or built-in implementation available |
7272

73-
## Supported Key Encryption Algorithms
73+
### Supported Key Encryption Algorithms
7474

75-
| Key Encryption Algorithm | Supported | Comment |
76-
| ------------------------------------------------------------------- |:---------:| -------------------------------------------------------------------------------------------------- |
77-
| `dir` | YES | |
78-
| `RSA1_5`, `RSA-OAEP` and `RSA-OAEP-256` | YES | |
79-
| `ECDH-ES`, `ECDH-ES+A128KW`, `ECDH-ES+A192KW` and `ECDH-ES+A256KW` | YES | |
80-
| `A128KW`, `A128KW` and `A128KW` | YES | |
81-
| `PBES2-HS256+A128KW`, `PBES2-HS384+A192KW` and `PBES2-HS512+A256KW` | YES | |
82-
| `A128GCMKW`, `A192GCMKW` and `A256GCMKW` | YES | |
83-
| `EdDSA` with `X25519` curve | YES | [For PHP 7.1, third party extension highly recommended](https://github.com/jedisct1/libsodium-php) |
84-
| `EdDSA` with `X448` curve | NO | No extension or built-in implementation available |
75+
| Key Encryption Algorithm | Supported | Comment |
76+
| --- | :---: | --- |
77+
| `dir` | YES | |
78+
| `RSA1_5`, `RSA-OAEP` and `RSA-OAEP-256` | YES | The algorithms `RSA1_5` and `RSA-OAEP`are now deprecated. Please use with caution. |
79+
| `ECDH-ES`, `ECDH-ES+A128KW`, `ECDH-ES+A192KW` and `ECDH-ES+A256KW` | YES | |
80+
| `A128KW`, `A128KW` and `A128KW` | YES | |
81+
| `PBES2-HS256+A128KW`, `PBES2-HS384+A192KW` and `PBES2-HS512+A256KW` | YES | |
82+
| `A128GCMKW`, `A192GCMKW` and `A256GCMKW` | YES | |
83+
| `EdDSA` with `X25519` curve | YES | [With PHP 7.1, third party extension highly recommended](https://github.com/jedisct1/libsodium-php) |
84+
| `EdDSA` with `X448` curve | NO | No extension or built-in implementation available |
8585

86-
## Supported Content Encryption Algorithms
86+
### Supported Content Encryption Algorithms
8787

88-
| Content Encryption Algorithm | Supported |
89-
| ---------------------------------------------------- |:---------:|
90-
| `A128CBC-HS256`, `A192CBC-HS384` and `A256CBC-HS512` | YES |
91-
| `A128GCM`, `A192GCM` and `A256GCM` | YES |
88+
| Content Encryption Algorithm | Supported |
89+
| --- | :---: |
90+
| `A128CBC-HS256`, `A192CBC-HS384` and `A256CBC-HS512` | YES |
91+
| `A128GCM`, `A192GCM` and `A256GCM` | YES |
9292

93-
# Prerequisites
93+
## Prerequisites
9494

9595
This framework needs at least:
96+
9697
* ![PHP 7.1+](https://img.shields.io/badge/PHP-7.1%2B-ff69b4.svg),
9798
* OpenSSL extension.
9899
* GMP extension.
99100
* MBString extension.
100101

101102
Please consider the following optional requirements:
103+
102104
* If you intent to use `EdDSA` or `ECDH-ES` algorithm with `Ed25519`/`X25519` curves on PHP 7.1, please install this [third party extension](https://github.com/jedisct1/libsodium-php)
103105

104-
# Continuous Integration
106+
## Continuous Integration
105107

106108
It has been successfully tested using `PHP 7.1`, `PHP 7.2` and `nightly` with all algorithms.
107109

@@ -113,31 +115,31 @@ Coding Standards are verified by [StyleCI](https://styleci.io/repos/105997386).
113115

114116
Code coverage is analyzed by [Coveralls.io](https://coveralls.io/github/web-token/jwt-framework).
115117

116-
# How to use
118+
## How to use
117119

118-
* [The components](component/index.md)
119-
* [The bundles](bundle/index.md)
120-
* [The console commands](console/index.md)
120+
* [The components](components/)
121+
* [The bundles](symfony-bundle/)
122+
* [The console commands](console/)
121123

122-
# Security Recommendations
124+
## Security Recommendations
123125

124-
**To avoid security issues on your application, please follow these [Security Recommendations](security/index.md) carefully**.
126+
**To avoid security issues on your application, please follow these **[**Security Recommendations**](security-recommendations.md)** carefully**.
125127

126-
# Performances
128+
## Performances
127129

128-
Please read the [performance page](benchmarks/index.md) to know how to test the algorithms of the framework.
130+
Please read the [performance page](benchmarks/) to know how to test the algorithms of the framework.
129131

130-
You can also see the [last benchmarks](benchmarks/results.md) made with our development environment.
132+
You can also see the [last benchmarks](benchmarks/result-table.md) made with our development environment.
131133

132-
# Contributing
134+
## Contributing
133135

134-
Requests for new features, bug fixed and all other ideas to make this framework useful are welcome.
135-
If you feel comfortable writing code, you could try to fix [opened issues where help is wanted](https://github.com/web-token/jwt-framework/labels/help+wanted) or [those that are easy to fix](https://github.com/web-token/jwt-framework/labels/easy-pick).
136+
Requests for new features, bug fixed and all other ideas to make this framework useful are welcome. If you feel comfortable writing code, you could try to fix [opened issues where help is wanted](https://github.com/web-token/jwt-framework/labels/help+wanted) or [those that are easy to fix](https://github.com/web-token/jwt-framework/labels/easy-pick).
136137

137138
Do not forget to [follow these best practices](https://github.com/web-token/jwt-framework/tree/master/.github/CONTRIBUTING.md).
138139

139-
**If you think you have found a security issue, DO NOT open an issue**. [You MUST submit your issue here](https://gitter.im/Spomky/).
140+
**If you think you have found a security issue, DO NOT open an issue**. [You MUST submit your issue here](https://gitter.im/Spomky/).
141+
142+
## Licence
140143

141-
# Licence
144+
This project is release under [MIT licence](https://github.com/web-token/jwt-framework/tree/846e8752fef1f7276488f52f80e69fcef54f8acc/LICENSE.md).
142145

143-
This project is release under [MIT licence](LICENSE.md).

‎SUMMARY.md

+57-56
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,62 @@
1-
# Summary
1+
# Table of contents
22

33
* [Introduction](README.md)
4-
* [Components](component/index.md)
5-
* [Algorithm Management (JWA)](component/jwa/index.md)
6-
* [Key (JWK) and Key Set (JWKSet)](component/jwk/index.md)
7-
* [Key Management](component/jwk/jwk.md)
8-
* [Key Set Management](component/jwk/jwkset.md)
9-
* [Header Checker](component/header_checker/index.md)
10-
* [Claim Checker](component/claim_checker/index.md)
11-
* [Signed Tokens (JWS)](component/jws/index.md)
12-
* [Signature Algorithms](component/jws/algorithms.md)
13-
* [JWS Creation](component/jws/creation.md)
14-
* [JWS Loading](component/jws/loading.md)
15-
* [Encrypted Tokens (JWE)](component/jwe/index.md)
16-
* [Encryption Algorithms](component/jwe/algorithms.md)
17-
* [JWE Creation](component/jwe/creation.md)
18-
* [JWE Loading](component/jwe/loading.md)
19-
* [Symfony Bundle](bundle/index.md)
20-
* [Algorithm Management](bundle/jwa/index.md)
21-
* [Key and Key Set Management](bundle/jwk/index.md)
22-
* [Key Management (JWK)](bundle/jwk/keys.md)
23-
* [Key Set Management (JWKSet)](bundle/jwk/keysets.md)
24-
* [Header and Claim Checker Management](bundle/checker/index.md)
25-
* [Signed Tokens](bundle/jws/index.md)
26-
* [JWS serializers](bundle/jws/serializers.md)
27-
* [JWS creation](bundle/jws/creation.md)
28-
* [JWS verification](bundle/jws/loading.md)
29-
* [Encrypted Tokens](bundle/jwe/index.md)
30-
* [JWE serializers](bundle/jwe/serializers.md)
31-
* [JWE creation](bundle/jwe/creation.md)
32-
* [JWE decryption](bundle/jwe/loading.md)
33-
* [Configuration Helper](bundle/helper/index.md)
34-
* [Console](console/index.md)
4+
* [Components](components/README.md)
5+
* [Algorithm Management \(JWA\)](components/algorithm-management-jwa.md)
6+
* [Key \(JWK\) and Key Set \(JWKSet\)](components/key-jwk-and-key-set-jwkset/README.md)
7+
* [Key Management](components/key-jwk-and-key-set-jwkset/key-management.md)
8+
* [Key Set Management](components/key-jwk-and-key-set-jwkset/key-set-management.md)
9+
* [Header Checker](components/header-checker.md)
10+
* [Claim Checker](components/claim-checker.md)
11+
* [Signed Tokens \(JWS\)](components/signed-tokens-jws/README.md)
12+
* [Signature Algorithms](components/signed-tokens-jws/signature-algorithms.md)
13+
* [JWS Creation](components/signed-tokens-jws/jws-creation.md)
14+
* [JWS Loading](components/signed-tokens-jws/jws-loading.md)
15+
* [Encrypted Tokens \(JWE\)](components/encrypted-tokens-jwe/README.md)
16+
* [Encryption Algorithms](components/encrypted-tokens-jwe/encryption-algorithms.md)
17+
* [JWE Creation](components/encrypted-tokens-jwe/jwe-creation.md)
18+
* [JWE Loading](components/encrypted-tokens-jwe/jwe-loading.md)
19+
* [Symfony Bundle](symfony-bundle/README.md)
20+
* [Algorithm Management](symfony-bundle/algorithm-management.md)
21+
* [Key and Key Set Management](symfony-bundle/key-and-key-set-management/README.md)
22+
* [Key Management \(JWK\)](symfony-bundle/key-and-key-set-management/key-management-jwk.md)
23+
* [Key Set Management \(JWKSet\)](symfony-bundle/key-and-key-set-management/key-set-management-jwkset.md)
24+
* [Header and Claim Checker Management](symfony-bundle/header-and-claim-checker-management.md)
25+
* [Signed Tokens](symfony-bundle/signed-tokens/README.md)
26+
* [JWS serializers](symfony-bundle/signed-tokens/jws-serializers.md)
27+
* [JWS creation](symfony-bundle/signed-tokens/jws-creation.md)
28+
* [JWS verification](symfony-bundle/signed-tokens/jws-verification.md)
29+
* [Encrypted Tokens](symfony-bundle/encrypted-tokens/README.md)
30+
* [JWE serializers](symfony-bundle/encrypted-tokens/jwe-serializers.md)
31+
* [JWE creation](symfony-bundle/encrypted-tokens/jwe-creation.md)
32+
* [JWE decryption](symfony-bundle/encrypted-tokens/jwe-decryption.md)
33+
* [Configuration Helper](symfony-bundle/configuration-helper.md)
34+
* [Console](console/README.md)
3535
* [Standalone](console/standalone.md)
36-
* [Symfony Console](console/symfony.md)
37-
* [PHAR Application](console/phar.md)
38-
* [Security Recommendations](security/index.md)
39-
* [Advanced Topics](advanced/index.md)
40-
* [Nested Tokens](advanced/nested_tokens.md)
41-
* [Serialization](advanced/serialization.md)
42-
* [Custom Algorithm](advanced/custom_algorithm.md)
36+
* [Symfony Console](console/symfony-console.md)
37+
* [PHAR Application](console/phar-application.md)
38+
* [Security Recommendations](security-recommendations.md)
39+
* [Advanced Topics](advanced-topics/README.md)
40+
* [Nested Tokens](advanced-topics/nested-tokens.md)
41+
* [Serialization](advanced-topics/serialization.md)
42+
* [Custom Algorithm](advanced-topics/custom-algorithm.md)
4343
* Signed tokens and
44-
* [Unprotected Header](advanced/jws/unprotected_header.md)
45-
* [Multiple Signatures](advanced/jws/multiple_signatures.md)
46-
* [Detached Payload](advanced/jws/detached_payload.md)
47-
* [Unencoded Payload](advanced/jws/unencoded_payload.md)
44+
* [Unprotected Header](advanced-topics/signed-tokens-and/unprotected-header.md)
45+
* [Multiple Signatures](advanced-topics/signed-tokens-and/multiple-signatures.md)
46+
* [Detached Payload](advanced-topics/signed-tokens-and/detached-payload.md)
47+
* [Unencoded Payload](advanced-topics/signed-tokens-and/unencoded-payload.md)
4848
* Encrypted tokens and
49-
* [Unprotected Headers](advanced/jwe/unprotected_header.md)
50-
* [Multiple Recipients](advanced/jwe/multiple_recipients.md)
51-
* [Additional Authentication Data (AAD)](advanced/jwe/aad.md)
52-
* [Benchmarks](benchmarks/index.md)
53-
* [Result table](benchmarks/results.md)
54-
* [Migration](migration/index.md)
55-
* [From spomky-labs/jose](migration/spomky-labs-jose/index.md)
56-
* [Keys (JWK)](migration/spomky-labs-jose/jwk.md)
57-
* [Key Sets (JWKSet)](migration/spomky-labs-jose/jwkset.md)
58-
* [Signed Tokens (JWS)](migration/spomky-labs-jose/jws.md)
59-
* [Encrypted Tokens (JWE)](migration/spomky-labs-jose/jwe.md)
60-
* [Header Checking](migration/spomky-labs-jose/header.md)
61-
* [Claim Checking](migration/spomky-labs-jose/claim.md)
49+
* [Unprotected Headers](advanced-topics/encrypted-tokens-and/unprotected-headers.md)
50+
* [Multiple Recipients](advanced-topics/encrypted-tokens-and/multiple-recipients.md)
51+
* [Additional Authentication Data \(AAD\)](advanced-topics/encrypted-tokens-and/additional-authentication-data-aad.md)
52+
* [Benchmarks](benchmarks/README.md)
53+
* [Result table](benchmarks/result-table.md)
54+
* [Migration](migration/README.md)
55+
* [From spomky-labs/jose](migration/from-spomky-labs-jose/README.md)
56+
* [Keys \(JWK\)](migration/from-spomky-labs-jose/keys-jwk.md)
57+
* [Key Sets \(JWKSet\)](migration/from-spomky-labs-jose/key-sets-jwkset.md)
58+
* [Signed Tokens \(JWS\)](migration/from-spomky-labs-jose/signed-tokens-jws.md)
59+
* [Encrypted Tokens \(JWE\)](migration/from-spomky-labs-jose/encrypted-tokens-jwe.md)
60+
* [Header Checking](migration/from-spomky-labs-jose/header-checking.md)
61+
* [Claim Checking](migration/from-spomky-labs-jose/claim-checking.md)
62+

0 commit comments

Comments
 (0)