https://github.com/busyloop/suzuri
Authenticated and encrypted tokens
https://github.com/busyloop/suzuri
crypto crystal security
Last synced: 5 months ago
JSON representation
Authenticated and encrypted tokens
- Host: GitHub
- URL: https://github.com/busyloop/suzuri
- Owner: busyloop
- License: mit
- Created: 2020-05-01T11:12:58.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-13T02:11:35.000Z (about 3 years ago)
- Last Synced: 2024-05-06T00:05:08.795Z (almost 2 years ago)
- Topics: crypto, crystal, security
- Language: Crystal
- Homepage:
- Size: 57.6 KB
- Stars: 8
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Suzuri
[](https://github.com/busyloop/suzuri/actions?query=workflow%3ABuild+branch%3Amaster) [](https://en.wikipedia.org/wiki/MIT_License) [](https://github.com/busyloop/suzuri/releases)
Suzuri is a secure and easy to use token format that employs
[XChaCha20-Poly1305 AEAD](https://doc.libsodium.org/secret-key_cryptography/aead/chacha20-poly1305/xchacha20-poly1305_construction) symmetric encryption to create
authenticated, encrypted, tamperproof tokens.
It compresses and encrypts an arbitrary sequence of bytes,
then encodes the result to url-safe Base64.
Suzuri tokens can be used as a secure alternative to JWT
or for any type of general purpose message passing.
## Installation
1. Add the dependency to your `shard.yml`:
```yaml
dependencies:
suzuri:
github: busyloop/suzuri
```
2. Run `shards install`
## Documentation
* [API Documentation](https://busyloop.github.io/suzuri/Suzuri.html)
## Usage
```crystal
require "suzuri"
TEST_KEY = "TheKeyLengthMustBeThirtyTwoBytes"
## Encode
token_str = Suzuri.encode("hello world", TEST_KEY) # => "(url-safe base64)"
## Decode
token = Suzuri.decode(token_str, TEST_KEY) # => Suzuri::Token
token.to_s # => "hello world"
token.timestamp # => 2020-01-01 01:23:45.0 UTC
## Decode with a TTL constraint
token_str = Suzuri.encode("hello world", TEST_KEY) # => "(url-safe base64)"
sleep 5
Suzuri.decode(token_str, TEST_KEY, 2.seconds) # => Suzuri::Error::TokenExpired
```
## Usage (with [JSON::Serializable](https://crystal-lang.org/api/0.34.0/JSON/Serializable.html))
```crystal
require "suzuri/json_serializable"
TEST_KEY = "TheKeyLengthMustBeThirtyTwoBytes"
class Person
include JSON::Serializable
@[JSON::Field]
property name : String
def initialize(@name)
end
end
bob = Person.new(name: "bob")
token_str = bob.to_suzuri(TEST_KEY)
bob2 = Person.from_suzuri(token_str, TEST_KEY)
bob2.name # => "bob"
```
## Compression
By default Suzuri applies zstd compression before encryption when the
payload is larger than 512 bytes. The compression threshold and level
can be chosen at runtime.
## Contributing
1. Fork it ()
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request
## Credits
Suzuri is inspired by (but not compatible to) [Branca](https://github.com/tuupola/branca-spec/)-tokens. The underlying encryption is identical.
Suzuri adds compression support and serializes to url-safe Base64 instead of Base62.