add Examples: JWT page

Author: terrafrost

docs/ec.md

@@ -144,7 +144,7 @@ SSH2-formatted signatures employee the format discussed in [RFC4253](https://too
 
 ### IEEE
 
-This format used with [JSON Web Signatures](https://en.wikipedia.org/wiki/JSON_Web_Signature) (JWS; [RFC7515#page-45](https://datatracker.ietf.org/doc/html/rfc7515#page-45)), JavaScript's [Web Cryptography API](https://en.wikipedia.org/wiki/Web_Cryptography_API), et al. [SubtleCrypto: sign() method - Web APIs | MDN](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) explains why IEEE is used as the name:
+This format used with [JSON Web Signatures](https://en.wikipedia.org/wiki/JSON_Web_Signature) (JWS; see [RFC7515#page-45](https://datatracker.ietf.org/doc/html/rfc7515#page-45)), JavaScript's [Web Cryptography API](https://en.wikipedia.org/wiki/Web_Cryptography_API), et al. [SubtleCrypto: sign() method - Web APIs | MDN](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/sign#ecdsa) explains why IEEE is used as the name:
 
 > This encoding was also proposed by the [IEEE 1363-2000](https://standards.ieee.org/ieee/1363/2049/) standard, and is sometimes referred to as the IEEE P1363 format. It differs from the [X.509](https://www.itu.int/rec/T-REC-X.509) signature structure, which is the default format produced by some tools and libraries such as [OpenSSL](https://www.openssl.org/).
 

docs/jwt.md

@@ -0,0 +1,118 @@
+---
+id: jwt
+title: Example: JWT
+---
+
+A [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) consists of three parts - a header a payload and a signature - each encoded separately using [Base64url](https://en.wikipedia.org/wiki/Base64#URL_applications) (`\phpseclib3\Common\Functions\Strings::base64url_encode()`) and concatenated together using periods. eg.
+
+```
+const token = base64urlEncoding(header) + '.' +
+              base64urlEncoding(payload) + '.' +
+              base64urlEncoding(signature)
+```
+The signature is created from the concatenation of the Base64url encoded header and payload. The algorithm used for the signature is specified in the header.
+
+A list of all the algorithms and how to implement them with phpseclib is discussed below. In these examples `$header` and `$payload` are assumed to already be Base64url encoded and `Strings` is assumed to be namespaced to `\phpseclib3\Common\Functions\Strings`.
+
+## ES256
+
+```php
+assert($private instanceof \phpseclib3\Crypt\EC);
+assert($private->getCurve() == 'secp256r1');
+
+$private = $private->withHash('sha256')->withSignatureFormat('IEEE');
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## ES384
+
+```php
+assert($private instanceof \phpseclib3\Crypt\EC);
+assert($private->getCurve() == 'secp384r1');
+
+$private = $private->withHash('sha384')->withSignatureFormat('IEEE');
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## ES512
+
+```php
+assert($private instanceof \phpseclib3\Crypt\EC);
+assert($private->getCurve() == 'secp521r1');
+
+$private = $private->withHash('sha512')->withSignatureFormat('IEEE');
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## RS256
+
+```php
+assert($private instanceof \phpseclib3\Crypt\RSA);
+
+$private = $private->withHash('sha256')->withPadding(RSA::SIGNATURE_PKCS1);
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## RS384
+
+```php
+assert($private instanceof \phpseclib3\Crypt\RSA);
+
+$private = $private->withHash('sha384')->withPadding(RSA::SIGNATURE_PKCS1);
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## RS512
+
+```php
+assert($private instanceof \phpseclib3\Crypt\RSA);
+
+$private = $private->withHash('sha512')->withPadding(RSA::SIGNATURE_PKCS1);
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## PS256
+
+```php
+assert($private instanceof \phpseclib3\Crypt\RSA);
+
+$private = $private->withHash('sha256')->withPadding(RSA::SIGNATURE_PSS);
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## PS384
+
+```php
+assert($private instanceof \phpseclib3\Crypt\RSA);
+
+$private = $private->withHash('sha384')->withPadding(RSA::SIGNATURE_PSS);
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## PS512
+
+```php
+assert($private instanceof \phpseclib3\Crypt\RSA);
+
+$private = $private->withHash('sha512')->withPadding(RSA::SIGNATURE_PSS);
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```
+
+## EdDSA
+
+```php
+assert($private instanceof \phpseclib3\Crypt\EC);
+assert($private->getCurve() == 'Ed25519');
+
+$sig = $private->sign("$header.$payload");
+$sig = Strings::base64url_encode($sig);
+```