| Name | PyBWT JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Binary Web Token (BWT) implementation in Python |
| upload_time | 2025-01-12 00:44:20 |
| maintainer | None |
| docs_url | None |
| author | nullptr |
| requires_python | >=3.10 |
| license | AGPLv3 |
| keywords |
bwt
security
signing
token
web
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Binary Web Tokens (BWT)
Binary Web Tokens are a lightweight alternative to [JSON Web Tokens](https://jwt.io/) (JWT). They are simpler, more secure, more compact, use less space and are faster to create and verify.
## The format
A BWT consists of three parts, the header, the payload and the signature. Between header and payload and payload and signature are separator characters called `PART_SEPARATOR`. The header and the payload may not contain any `PART_SEPARATOR` characters. The signature has no such restriction. The token is base64URL encoded.
### Header
The header is 8 byte long and consists of 6 magic bytes, followed by one byte specifying the algorithm and one byte specifying the type.
The following table showcases the structure (table header is byte offset):
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| :----: | :----: | :----: | :----: | :----: | :----: | :---: | :----: |
| `0x01` | `0x42` | `0x57` | `0x54` | `0x13` | `0x37` | `ALG` | `TYPE` |
**Magic Bytes**:
- `\x01BWT\x13\x37`
- Since base64 encodes 3 source bytes to 4 destination bytes, the magic bytes will always be encoded to "`AUJXVBM3`", making a BWT easily recognizable even in encoded form.
**Algorithm**:
- `0xff`: HS256
- `0xfe`: HS384
- `0xfd`: HS512
- `0xfc`: RS256
- `0xfb`: RS384
- `0xfa`: RS512
- `0xf9`: ES256
- `0xf8`: ES384
- `0xf7`: ES512
- `0xf6`: PS256
- `0xf5`: PS384
- `0xf4`: PS512
**Type**:
- `0xff`: BWT
### Payload
The payload consists of arbitrarily many key-value pairs. The key and the value must be UTF-8 encoded strings and end with `PAYLOAD_SEPARATOR` characters. Thus they may not contain PAYLOAD_SEPARATOR characters. There is no way to store arrays or dictionaries as values. However if this is needed one might serialize the array/dictionary into a string and store it like this. Or alternatively one might encode them as `key_0`, `key_1`, ... for arrays or as `key_subkey`, `key_othersubkey` for dictionaries.
### Signature
Everything after the second `PART_SEPARATOR` up until the end of the token is considered to be the signature. Thus there are no restrictions as to what characters may appear here. For the signature, everything up to and including the second `PART_SEPARATOR` character (Header, `PART_SEPARATOR`, Payload, `PART_SEPARATOR`) is signed with the algorithm specified in the header using a given key.
### Special characters
- `PART_SEPARATOR`: `0x00`
- `PAYLOAD_SEPARATOR`: `0x03`
## Security
BWTs have been developed with security in mind. Thus:
- there is no insecure NONE algorithm
- they are as simple as possible
- every operation of every implementation should force the developer to specify the used algorithm and verify if it matches the one in the token to avoid [Algorithm confusion attacks](https://portswigger.net/web-security/jwt/algorithm-confusion).
# PyBWT
PyBWT is a Python wrapper for the BWT library `libbwt.so`, which is written in C for the sake of efficiency.
## Installation
Install with **pip**:
```
$ pip install PyBWT
```
## Usage
```
>>> import bwt
>>> encoded = bwt.encode({"some": "payload"}, "secret", algorithm="HS256")
>>> print(encoded)
AUJXVBM3__8Ac29tZQNwYXlsb2FkAwAOp__UBxRJlqHSNQTSt7lUhk1zh2D8sG2Dt3OkHSfoYg
>>> bwt.decode(encoded, "secret", algorithm="HS256")
{'some': 'payload'}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "PyBWT",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "bwt, security, signing, token, web",
"author": "nullptr",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5b/81/0d98d0f411f9cd05bcbc3c8099ccfc52c78d59100d84d2f2eb699ede2044/pybwt-0.1.1.tar.gz",
"platform": null,
"description": "# Binary Web Tokens (BWT)\n\nBinary Web Tokens are a lightweight alternative to [JSON Web Tokens](https://jwt.io/) (JWT). They are simpler, more secure, more compact, use less space and are faster to create and verify.\n\n## The format\nA BWT consists of three parts, the header, the payload and the signature. Between header and payload and payload and signature are separator characters called `PART_SEPARATOR`. The header and the payload may not contain any `PART_SEPARATOR` characters. The signature has no such restriction. The token is base64URL encoded.\n\n### Header\nThe header is 8 byte long and consists of 6 magic bytes, followed by one byte specifying the algorithm and one byte specifying the type.\n\nThe following table showcases the structure (table header is byte offset):\n\n| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |\n| :----: | :----: | :----: | :----: | :----: | :----: | :---: | :----: |\n| `0x01` | `0x42` | `0x57` | `0x54` | `0x13` | `0x37` | `ALG` | `TYPE` |\n\n**Magic Bytes**:\n - `\\x01BWT\\x13\\x37`\n - Since base64 encodes 3 source bytes to 4 destination bytes, the magic bytes will always be encoded to \"`AUJXVBM3`\", making a BWT easily recognizable even in encoded form.\n\n**Algorithm**:\n - `0xff`: HS256\n - `0xfe`: HS384\n - `0xfd`: HS512\n - `0xfc`: RS256\n - `0xfb`: RS384\n - `0xfa`: RS512\n - `0xf9`: ES256\n - `0xf8`: ES384\n - `0xf7`: ES512\n - `0xf6`: PS256\n - `0xf5`: PS384\n - `0xf4`: PS512\n\n**Type**:\n - `0xff`: BWT\n\n### Payload\nThe payload consists of arbitrarily many key-value pairs. The key and the value must be UTF-8 encoded strings and end with `PAYLOAD_SEPARATOR` characters. Thus they may not contain PAYLOAD_SEPARATOR characters. There is no way to store arrays or dictionaries as values. However if this is needed one might serialize the array/dictionary into a string and store it like this. Or alternatively one might encode them as `key_0`, `key_1`, ... for arrays or as `key_subkey`, `key_othersubkey` for dictionaries.\n\n### Signature\nEverything after the second `PART_SEPARATOR` up until the end of the token is considered to be the signature. Thus there are no restrictions as to what characters may appear here. For the signature, everything up to and including the second `PART_SEPARATOR` character (Header, `PART_SEPARATOR`, Payload, `PART_SEPARATOR`) is signed with the algorithm specified in the header using a given key.\n\n### Special characters\n - `PART_SEPARATOR`: `0x00`\n - `PAYLOAD_SEPARATOR`: `0x03`\n\n## Security\nBWTs have been developed with security in mind. Thus:\n - there is no insecure NONE algorithm\n - they are as simple as possible\n - every operation of every implementation should force the developer to specify the used algorithm and verify if it matches the one in the token to avoid [Algorithm confusion attacks](https://portswigger.net/web-security/jwt/algorithm-confusion).\n\n# PyBWT\nPyBWT is a Python wrapper for the BWT library `libbwt.so`, which is written in C for the sake of efficiency.\n\n## Installation\n\nInstall with **pip**:\n\n```\n$ pip install PyBWT\n```\n\n## Usage\n```\n>>> import bwt\n>>> encoded = bwt.encode({\"some\": \"payload\"}, \"secret\", algorithm=\"HS256\")\n>>> print(encoded)\nAUJXVBM3__8Ac29tZQNwYXlsb2FkAwAOp__UBxRJlqHSNQTSt7lUhk1zh2D8sG2Dt3OkHSfoYg\n>>> bwt.decode(encoded, \"secret\", algorithm=\"HS256\")\n{'some': 'payload'}\n```\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Binary Web Token (BWT) implementation in Python",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"bwt",
" security",
" signing",
" token",
" web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "21dc2cc298815c377871c9ba8173af87dc671f0311bac54f2d5c10363c359f1a",
"md5": "d79c6fcc473d0f70b8409d3c39ca7840",
"sha256": "b8cc1edd25b7ab28e3b818b1b1388cd6fd1793dcdb677b540127ec577bb6e843"
},
"downloads": -1,
"filename": "PyBWT-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d79c6fcc473d0f70b8409d3c39ca7840",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 2417595,
"upload_time": "2025-01-12T00:43:32",
"upload_time_iso_8601": "2025-01-12T00:43:32.629836Z",
"url": "https://files.pythonhosted.org/packages/21/dc/2cc298815c377871c9ba8173af87dc671f0311bac54f2d5c10363c359f1a/PyBWT-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5b810d98d0f411f9cd05bcbc3c8099ccfc52c78d59100d84d2f2eb699ede2044",
"md5": "ffe138652b54f340862e388052ab1d31",
"sha256": "fc5bdd5d74eae34e216d4f7201dce36976754c6d7304cd08c199653b141b5a33"
},
"downloads": -1,
"filename": "pybwt-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ffe138652b54f340862e388052ab1d31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2407316,
"upload_time": "2025-01-12T00:44:20",
"upload_time_iso_8601": "2025-01-12T00:44:20.245052Z",
"url": "https://files.pythonhosted.org/packages/5b/81/0d98d0f411f9cd05bcbc3c8099ccfc52c78d59100d84d2f2eb699ede2044/pybwt-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 00:44:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pybwt"
}
