New docs for signing tokens (#316)

* save docs for adding your own algo

* formatting and syntax

docs/faqs.md

@@ -4,7 +4,7 @@
 
 ### The generated JWT token can be decoded, is this correct and secure?
 
-This is the expected behaviour. While the integrity of tokens is ensured by the generated/verified hash,
+This is the expected behavior. While the integrity of tokens is ensured by the generated/verified hash,
 the contents of the token are only **encoded and not encrypted**. This means you can be sure the token
 has not been modified by an unauthorized party, but you should not store confidential information in it.
 Anyone with access to the token can read all the claims you put into it. They can however not modify
@@ -26,7 +26,7 @@ Here are a few links for your convenience:
 ### Can this library encrypt/decrypt claims?
 
 No it does not, see [#115](https://github.com/Thalhammer/jwt-cpp/issues/115) for more details.
-More importantly you probably dont want to be using JWTs for anything sensitive. Read [this](https://stackoverflow.com/a/43497242/8480874)
+More importantly you probably don't want to be using JWTs for anything sensitive. Read [this](https://stackoverflow.com/a/43497242/8480874)
 for more.
 
 ### Why are my tokens immediately expired?
@@ -53,8 +53,8 @@ That should result in the token being rejected. For more details checkout [#194]
 This was brought up in [#212](https://github.com/Thalhammer/jwt-cpp/issues/212#issuecomment-1054344192) and
 [#101](https://github.com/Thalhammer/jwt-cpp/issues/101) as it's an excellent question.
 
-It simply was not required to handle the required keys in JWTs for signing or verification. All the the mandatory keys are numeric,
-string or array types which required type definitions and access.
+It simply was not required to handle the required keys in JWTs for signing or verification. All the the mandatory keys 
+are numeric, string or array types which required type definitions and access.
 
 The alternative is to use the `to_json()` method and use the libraries own APIs to pick the data type you need.
 
@@ -63,13 +63,16 @@ The alternative is to use the `to_json()` method and use the libraries own APIs
 ### Missing \_HMAC and \_EVP_sha256 symbols on Mac
 
 There seems to exists a problem with the included openssl library of MacOS. Make sure you link to one provided by brew.
-See [here](https://github.com/Thalhammer/jwt-cpp/issues/6) for more details.
+See [#6](https://github.com/Thalhammer/jwt-cpp/issues/6) for more details.
 
 ### Building on windows fails with syntax errors
 
-The header `<Windows.h>`, which is often included in windowsprojects, defines macros for MIN and MAX which screw up std::numeric_limits.
-See [here](https://github.com/Thalhammer/jwt-cpp/issues/5) for more details. To fix this do one of the following things:
+The header `<Windows.h>`, which is often included in Windows projects, defines macros for MIN and MAX which conflicts
+with `std::numeric_limits`. See [#5](https://github.com/Thalhammer/jwt-cpp/issues/5) for more details or 
+[this StackOverflow thread](https://stackoverflow.com/questions/13416418/define-nominmax-using-stdmin-max). 
 
-* define NOMINMAX, which suppresses this behaviour
-* include this library before you include windows.h
+To fix this do one of the following things:
+
+* define `NOMINMAX`, which suppresses this behavior
+* include this library before you `#include <Windows.h>`
 * place `#undef max` and `#undef min` before you include this library

docs/signing.md

@@ -0,0 +1,34 @@
+# Signing Tokens
+
+## Custom Signature Algorithms
+
+The libraries design is open so you can implement your own algorithms, see [existing examples](https://github.com/Thalhammer/jwt-cpp/blob/73f23419235661e89a304ba5ab09d6714fb8dd94/include/jwt-cpp/jwt.h#L874) for ideas.
+
+```cpp
+struct your_algorithm{
+	std::string sign(const std::string& /*unused*/, std::error_code& ec) const {
+		ec.clear();
+        // CALL YOUR METHOD HERE
+		return {};
+	}
+	void verify(const std::string& /*unused*/, const std::string& signature, std::error_code& ec) const {
+		ec.clear();
+		if (!signature.empty()) { ec = error::signature_verification_error::invalid_signature; }
+        
+        // CALL YOUR METHOD HERE
+	}
+	std::string name() const { return "your_algorithm"; }
+};
+```
+
+Then everything else is the same, just pass in your implementation such as:
+
+
+```cpp
+auto token = jwt::create()
+                .set_id("custom-algo-example")
+                .set_issued_at(std::chrono::system_clock::now())
+                .set_expires_at(std::chrono::system_clock::now() + std::chrono::seconds{36000})
+                .set_payload_claim("sample", jwt::claim(std::string{"test"}))
+                .sign(your_algorithm{/* what ever you want */});
+```