@blackcube/aurelia2-powshield
v2.0.1
Published
Blackcube Aurelia 2 Powshield
Downloads
7
Readme
Blackcube Aurelia 2 powshield toolkit
This toolkit allows easy setup of Powshield.
Install
Package is available on npm
Then you can install the package:
npm install @blackcube/aurelia2-powshield
Howto
Process is simple:
- Fetch a new challenge from the API
- Solve the challenge to get a solution
- Verify the solution with the API
- If the solution is correct, you can submit your form
- Check the solution serverside to avoid any issue
API
In order to be mst robust, you should limit the use of a challenge For example, you can limit the use of a challenge to 2 times:
- First time to allow validation by the JS (frontend)
- Second time to allow validation by the server (backend)
encrypt and decrypt functions should be symmetric to allow the server to encrypt/decrypt the timestamp and validate the challenge
PseudoCode to generate a challenge
// app constants
key = 'your-secret'
// generate a random string of 12 characters
salt = generateRandomString(12)
// generate a random number between 0 and 50000
// values 0 and 50000 can be tuned to your needs
secretNumber = random_int(0, 50000)
algorithm = 'SHA-256'
// algorithm can be SHA-1, SHA-256, SHA-512
timestamp = time()
cypheredTimestamp = base64_encode(encrypt(timestamp, key))
challenge = hash(algorithm, concat(salt, secretNumber, cypheredTimestamp)
signature = hash_hmac(algorithm, challenge, key);
result = base64_encode(json_encode({
'algorithm': algorithm,
'timestamp': cypheredTimestamp,
'challenge': challenge,
'salt': salt,
'signature': $signature,
'start': 0,
'max': maxIterations,
}));
// return the result as a base64 encoded JSON object
PseudoCode to verify a solution
// app constants
key = 'your-secret'
timeValidity = 300 // 5 minutes
// received payload
payload = json_decode(base64_decode($payload))
algorithm = payload.algorithm
cypheredTimestamp = base64_decode(payload.timestamp)
challenge = payload.challenge
number = payload.number
salt = payload.salt
signature = payload.signature
checkChallenge = hash(algorithm, concat(salt, secretNumber, cypheredTimestamp)
checkSignature = hash_hmac(algorithm, challenge, key)
timestamp = decrypt(base64_decode(cypheredTimestamp), key)
validityOk = time < timestamp + timeValidity
challengeOk = hash_equals(checkChallenge, challenge)
signatureOk = hash_equals(checkSignature, signature)
verfied = challengeOk and signatureOk;
Registering it in app
import Aurelia, { ConsoleSink, LoggerConfiguration, LogLevel} from 'aurelia';
import { PowshieldConfiguration } from "@blackcube/aurelia2-powshield";
import { MyApp } from './my-app';
Aurelia
.register(PowshieldConfiguration)
.register(LoggerConfiguration.create({
level: LogLevel.trace,
colorOptions: 'colors',
sinks: [ConsoleSink]
}))
.app(MyApp)
.start();
Additional configuration if needed
You can configure the toolkit by passing a configuration object to the configure method:
import Aurelia, { ConsoleSink, LoggerConfiguration, LogLevel} from 'aurelia';
import { PowshieldConfiguration } from "@blackcube/aurelia2-powshield";
import { MyApp } from './my-app';
Aurelia
.register(PowshieldConfiguration.configure({
generateChallengeUrl: '/powshield/generate-challenge',
verifySolutionUrl: '/powshield/verify-solution',
solutionInputSelector: '#powshieldSolution'
}))
.register(LoggerConfiguration.create({
level: LogLevel.trace,
colorOptions: 'colors',
sinks: [ConsoleSink]
}))
.app(MyApp)
.start();
Default values are:
generateChallengeUrl: '/powshield/generate-challenge',
verifySolutionUrl: '/powshield/verify-solution',
solutionInputSelector: '#powshieldSolution'
generateChallengeUrl URL used to generate a new challenge
verifySolutionUrl URL used to verify a solution
solutionInputSelector selector used to get the solution input element which will be used to send the solution to the server
Usage in HTML
<template>
<form bc-powshield="#powshieldSolution">
<input type="hidden" id="powshieldSolution" name="powshieldSolution" />
<div>
<label for="email">EMail</label>
<input type="email" id="email" name="email" />
</div>
<div>
<button type="submit">Submit</button>
</div>
</form>
</template>
Form will be protected by Powshield. When the form is submitted, the toolkit will generate a new challenge, and will add the solution to the hidden input field. The form will be submitted with the solution. The server will be able to verify the solution.