diff options
author | VirtualTam <virtualtam@flibidi.net> | 2017-07-29 15:26:27 +0200 |
---|---|---|
committer | VirtualTam <virtualtam@flibidi.net> | 2017-07-29 15:32:22 +0200 |
commit | 84d0632a2df1cf833610bc8dd45d4808e4a8dc0e (patch) | |
tree | c550f8a21c8f243d305125f41e7d4c59646f257b /doc/REST-API.md | |
parent | 57ee53d6c6be4b641764b0a635b2998c6cdc8197 (diff) | |
download | Shaarli-84d0632a2df1cf833610bc8dd45d4808e4a8dc0e.tar.gz Shaarli-84d0632a2df1cf833610bc8dd45d4808e4a8dc0e.tar.zst Shaarli-84d0632a2df1cf833610bc8dd45d4808e4a8dc0e.zip |
docker: remove `dev` image, update documentation
Relates to https://github.com/shaarli/Shaarli/issues/843
Changed:
- Update Docker image list
- Update Docker documentation structure
Removed:
- Delete Dockerfile and resources for the `dev` image
- Cleanup `doc/` resources
Signed-off-by: VirtualTam <virtualtam@flibidi.net>
Diffstat (limited to 'doc/REST-API.md')
-rw-r--r-- | doc/REST-API.md | 105 |
1 files changed, 0 insertions, 105 deletions
diff --git a/doc/REST-API.md b/doc/REST-API.md deleted file mode 100644 index d7909978..00000000 --- a/doc/REST-API.md +++ /dev/null | |||
@@ -1,105 +0,0 @@ | |||
1 | #REST API | ||
2 | ## Usage | ||
3 | |||
4 | See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html) | ||
5 | |||
6 | ## Authentication | ||
7 | |||
8 | All requests to Shaarli's API must include a JWT token to verify their authenticity. | ||
9 | |||
10 | This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`. | ||
11 | |||
12 | JWT resources : | ||
13 | |||
14 | * [jwt.io](https://jwt.io) (including a list of client per language).[](.html) | ||
15 | * RFC : https://tools.ietf.org/html/rfc7519 | ||
16 | * https://float-middle.com/json-web-tokens-jwt-vs-sessions/ | ||
17 | * HackerNews thread: https://news.ycombinator.com/item?id=11929267 | ||
18 | |||
19 | |||
20 | ### Shaarli JWT Token | ||
21 | |||
22 | JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: | ||
23 | |||
24 | ``` | ||
25 | [header].[payload].[signature][](.html) | ||
26 | ``` | ||
27 | |||
28 | #### Header | ||
29 | |||
30 | Shaarli only allow one hash algorithm, so the header will always be the same: | ||
31 | |||
32 | ```json | ||
33 | { | ||
34 | "typ": "JWT", | ||
35 | "alg": "HS512" | ||
36 | } | ||
37 | ``` | ||
38 | |||
39 | Encoded in base64, it gives: | ||
40 | |||
41 | ``` | ||
42 | ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== | ||
43 | ``` | ||
44 | |||
45 | #### Payload | ||
46 | |||
47 | **Validity duration** | ||
48 | |||
49 | To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes. | ||
50 | |||
51 | ```json | ||
52 | { | ||
53 | "iat": 1468663519 | ||
54 | } | ||
55 | ``` | ||
56 | |||
57 | See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html) | ||
58 | |||
59 | |||
60 | #### Signature | ||
61 | |||
62 | The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page. | ||
63 | |||
64 | Signature example with PHP: | ||
65 | |||
66 | ```php | ||
67 | $content = base64_encode($header) . '.' . base64_encode($payload); | ||
68 | $signature = hash_hmac('sha512', $content, $secret); | ||
69 | ``` | ||
70 | |||
71 | |||
72 | ### Complete example | ||
73 | |||
74 | #### PHP | ||
75 | |||
76 | ```php | ||
77 | function generateToken($secret) { | ||
78 | $header = base64_encode('{ | ||
79 | "typ": "JWT", | ||
80 | "alg": "HS512" | ||
81 | }'); | ||
82 | $payload = base64_encode('{ | ||
83 | "iat": '. time() .' | ||
84 | }'); | ||
85 | $signature = hash_hmac('sha512', $header .'.'. $payload , $secret); | ||
86 | return $header .'.'. $payload .'.'. $signature; | ||
87 | } | ||
88 | |||
89 | $secret = 'mysecret'; | ||
90 | $token = generateToken($secret); | ||
91 | echo $token; | ||
92 | ``` | ||
93 | |||
94 | > `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68` | ||
95 | |||
96 | ```php | ||
97 | $options = [[](.html) | ||
98 | 'http' => [[](.html) | ||
99 | 'method' => 'GET', | ||
100 | 'jwt' => $token, | ||
101 | ], | ||
102 | ]; | ||
103 | $context = stream_context_create($options); | ||
104 | file_get_contents($apiEndpoint, false, $context); | ||
105 | ``` | ||