Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/barseghyanartur/skajs
Sign data using symmetric-key algorithm encryption. Validate signed data and identify possible validation errors. Useful shortcut functions for signing (and validating) dictionaries.
https://github.com/barseghyanartur/skajs
data-encryption data-hash encryption javascript-library nodejs-library security
Last synced: about 1 month ago
JSON representation
Sign data using symmetric-key algorithm encryption. Validate signed data and identify possible validation errors. Useful shortcut functions for signing (and validating) dictionaries.
- Host: GitHub
- URL: https://github.com/barseghyanartur/skajs
- Owner: barseghyanartur
- License: mit
- Created: 2021-08-17T23:54:01.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-11-28T23:03:32.000Z (12 months ago)
- Last Synced: 2024-09-07T19:06:10.024Z (2 months ago)
- Topics: data-encryption, data-hash, encryption, javascript-library, nodejs-library, security
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/skajs
- Size: 45.9 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ska
Lets you easily sign data, using symmetric-key algorithm encryption. Allows
you to validate signed data and identify possible validation errors. Uses
sha/hmac for signature encryption. Comes with shortcut functions for signing (and
validating) dictionaries.
[](https://www.npmjs.com/package/skajs)
[](https://www.npmjs.com/package/skajs)
[](https://github.com/barseghyanartur/skajs/actions)
[](https://coveralls.io/github/barseghyanartur/skajs?branch=main)
[](https://github.com/barseghyanartur/skajs/#License)
## Key concepts
Hosts, that communicate with each other, share the Secret Key, which is used
to sign data (requests). Secret key is never sent around.
One of the cases is signing of HTTP requests. Each (HTTP) request is signed
on the sender side using the shared Secret Key and as an outcome produces the
triple (`signature`, `auth_user`, `valid_until`) which are used to sign
the requests.
- `signature` (`string`): Signature generated.
- `auth_user` (`string`): User making the request. Can be anything.
- `valid_until` (`float` or `string`): Signature expiration time (Unix timestamp).
On the recipient side, (HTTP request) data is validated using the shared
Secret Key. It's being checked whether signature is valid and not expired.
```
┌─────────────┐ Data ┌─────────────┐
│ Host 1 ├────────────────────────────>│ Host 2 │
│ ─────────── │ │ ─────────── │
│ secret key │ │ secret key │
│ 'my-secret' │<────────────────────────────┤ 'my-secret' │
└─────────────┘ Data └─────────────┘
```
## Features
- Sign URLs.
- Sign dictionaries.
- Validate signed dictionaries.
## Eco-system
Need ``ska`` for other languages? Check the following affiliated projects:
- [ska](https://github.com/barseghyanartur/ska): ``ska`` implementation
for Python. This was the first implementation from which current project
originated.
- [skaphp](https://github.com/barseghyanartur/skaphp): ``ska`` implementation
for PHP (>= 7.2).
Generated signatures are intercompatible between Python, NodeJS and PHP
implementations.
## Installation
Latest stable version from NPM registry:
```shell
npm install skajs
```
## Usage examples
Usage example are present for both CommonJS and ESM.
### CommonJS
```shell
node examples.js
```
### ESM
```shell
node examples.mjs
```
### Basic usage
#### Sender side
Signing dictionaries and URLs is as simple as follows.
##### Required imports.
**CommonJS**
```javascript
const { signatureToDict, signURL } = require("skajs");
```
**ESM**
```javascript
import { signatureToDict, signURL } from "skajs";
```
##### Sign data
**Sample usage, sign a dictionary:**
```javascript
const signatureDict = signatureToDict("user", "your-secret_key");
```
**Sample output:**
```javascript
{
signature: 'sf40lBWO5CquFfHr6jSXxhl2oW0=',
auth_user: 'user',
valid_until: '1631827551.6',
extra: ''
}
```
**Adding of additional data to the signature works in the same way:**
```javascript
const signatureDict = signatureToDict(
"user",
"your-secret_key",
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
}
);
```
**Sample output:**
```javascript
{
signature: 'B0sscS+xXWU+NR+9dBCoGFnDtlw=',
auth_user: 'user',
valid_until: '1631827551.6',
extra: 'email,first_name,last_name',
email: '[email protected]',
first_name: 'John',
last_name: 'Doe',
}
```
**Sample usage, sign a URL:**
```javascript
const signedURL = signURL("user", "your-secret_key", "http://e.com/api/");
```
**Sample output:**
```javascript
'http://e.com/api/?valid_until=1378045287.0&auth_user=user&signature=YlZpLFsjUKBalL4x5trhkeEgqE8%3D'
```
**Options and defaults:**
The `signatureToDict` function accepts an optional `options` argument.
Default value for the `validUntil` in the `options` is 10 minutes from now. If
you want it to be different, set `validUntil` in the `options` of
the `signatureToDict` function.
Default lifetime of a signature is 10 minutes (600 seconds). If you want it
to be different, set `lifetime` in the `options` of the `signatureToDict`
function.
Default name of the (GET) param holding the generated signature value
is `signature`. If you want it to be different,set the `signatureParam`
in the `options` of the `signatureToDict` function.
Default name of the (GET) param holding the `authUser` value is
`auth_user`. If you want it to be different, set `authUserParam`
in the `options` of the `signatureToDict` function.
Default name of the (GET) param holding the `validUntil` value is
`valid_until`. If you want it to be different, set the `validUntilParam`
in the `options` of the `signatureToDict` function.
Default name of the (GET) param holding the `extra` value is
`extra`. If you want it to be different, set the `extraParam`
in the `options` of the `signatureToDict` function.
Default hashing algorithm is `SHA1`. If you want it to be different, set the
`signatureCls` in the `options` of the `signatureToDict` function. Supported
classes are `HMACSHA1Signature` (alias of `Signature`), `HMACSHA256Signature`
and `HMACSHA512Signature`.
```javascript
signedData = signatureToDict(
"user",
"your-secret_key",
{
email: "[email protected]",
first_name: "John",
last_name: "Doe",
},
{
authUserParam: "webshop_id",
}
);
```
**Sample output:**
```javascript
{
webshop_id: "user",
email: "[email protected]",
extra: "email,first_name,last_name",
first_name: "John",
last_name: "Doe",
signature: "nu0Un+05z/cNOFnLwQnigoW/KmA=",
valid_until: 1631799172.0
}
```
#### Recipient side
Validating the signed request data is as simple as follows.
##### Required imports
**CommonJS**
```javascript
const { validateSignedRequestData } = require("skajs");
```
**ESM**
```javascript
import { validateSignedRequestData } from "skajs";
```
##### Validate signed requests
Validating the signed request data. Note, that `data` value is expected to
be a dictionary; `request.POST` is given as an example.
```javascript
validationResult = validateSignedRequestData(
request.POST, // Note, that ``request.POST`` is given as example.
"your-secret_key"
);
```
In case of signed URLs, it could look as follows:
```javascript
validationResult = validateSignedRequestData(
request.GET, // Note, that ``request.GET`` is given as example.
"your-secret_key"
);
```
**Options and defaults:**
Similarly to `signatureToDict` function, the `validateSignedRequestData`
also accepts a number of optional arguments (which have been described above):
- signatureParam
- authUserParam
- validUntilParam
- extraParam
- signatureCls
With some customizations, it would look as follows:
```javascript
validationResult = validateSignedRequestData(
request.GET,
"your-secret_key",
{
authUserParam: "webshop_id",
}
);
```
# Testing
Simply type:
```shell
npm test
```
# Code style
The `Prettier` is used.
```shell
npx prettier --write .
```
# License
MIT
# Support
For any issues contact me at the e-mail given in the [Author](#Author) section.
# Author
Artur Barseghyan