# WARNING!
As of June, 2018, this library has become **DEPRECATED**. There are no plans to remove it, but it will no longer be maintained. It has been replaced by an `npm` publishable version of `cryptolib-js` whose source code is also located in the project `scytl-cryptolib`, with folder names that follow the pattern `cryptolib-js-*` (for example, `cryptolib-js-securerandom`). The module `cryptolib-js-buildtools` is used to publish these modules to Nexus. The URL where the library is published is and the library may be `npm` installed via the following module names: `scytl-*` (where: `*`=`codec`, `bitwise`, `cryptopolicy`, `securerandom`, `messagedigest`, `pbkdf`, `symmetric`, `asymmetric`, `certificate`, `digitalenvelope`, `keystore`, `mathematical`, `elgamal`, `zkproof`). Please use this version of `crytolib-js` for all of your future projects and convert any of your existing projects to this version, when time allows.
# Cryptolib-JS - A quick start to the Scytl javascript cryptography library
# Released artifacts
CryptoLib JS and Forge are released in a zip file, located at
http://bcngpp1vsprdcitest.scytl.net:8080/job/COMM-alice-and-bobs-scytl-cryptoLib-js-master/lastSuccessfulBuild/artifact/dist/
Folder labeled ‘lib’ has crypto-lib.js and ‘sample/vendor/forge.min’ includes index.js
# Html setup
Html page used to render JS code should declare Forge and CryptoLib JS:
```html
From released zip file<-->
From released zip file<-->
From https://scm.scytl.net/stash/projects/COMM/repos/scytl-cryptolib-js/browse/src/lib/cryptolib.spec.js<-->
Your code goes there<-->
```
3rd resource declared here refers to properties file for policy, that should be based on https://scm.scytl.net/stash/projects/COMM/repos/scytl-cryptolib-js/browse/src/lib/cryptolib.spec.js
Last one refers to usage example detailed at continuation.
So with such an html header set, javascript functions from 'myTestCode.js' can be called when an html event happens (e.g. clicking a button).
Custom functions are then in charge of calling CryptoLib JS modules.
# Symmetric service
Unit tests (files named '*.spec.js') are another good starting point in order to find examples of JS code snippets involving CryptoLib JS, at location: https://scm.scytl.net/stash/projects/COMM/repos/scytl-cryptolib-js/browse/src/lib
## How to getSecretKeyForEncryption (full example)
``` javascript
function testGetSecretKeyForEncryption() {
cryptoPRNG.startEntropyCollection();
//in a production environment, entropy source events take place before stopping entropy collection
cryptoPRNG.stopEntropyCollectionAndCreatePRNG();
cryptolib('symmetric.service', function(box) {
var cryptoSecretKey = box.symmetric.service.getSecretKeyForEncryption();
//send SecretKey to html
document.form1.symmetricKey.value = cryptoSecretKey;
});
}
```
Note that html would need the following to trigger this function:
``` html
[...]
```
## How to getSecretKeyForMac (from unit test)
``` javascript
cryptolib('symmetric.service', function(box) {
var secretKey = box.symmetric.service.getSecretKeyForMac();
});
```
## How to encrypt and decrypt (from unit test)
``` javascript
cryptolib('symmetric.service', 'commons.utils', function(box) {
// generate a secret key
var secretKeyB64 = box.symmetric.service.getSecretKeyForEncryption();
// encrypt and decrypt data
var converters = new box.commons.utils.Converters();
var dataB64 = converters.base64Encode("anyString");
var encryptedDataBase64 = box.symmetric.service.encrypt(secretKeyB64, dataB64);
var decryptedDataBase64 = box.symmetric.service.decrypt(secretKeyB64, encryptedDataBase64);
});
```
## How to getMac and verifyMac (from unit test)
``` javascript
cryptolib('symmetric.service', 'commons.utils', function(box) {
// generate a secret key
var secretKeyB64 = box.symmetric.service.getSecretKeyForMac();
// encrypt and decrypt data
var converters = new box.commons.utils.Converters();
var dataB64 = converters.base64Encode("anyString");
var macB64 = box.symmetric.service.getMac(secretKeyB64, [dataB64]);
var verified = box.symmetric.service.verifyMac(macB64, secretKeyB64, [dataB64]);
});
```
# Asymmetric service
## How to getKeyPairForEncryption (from unit test)
``` javascript
cryptolib('asymmetric.service', function(box) {
var encryptionKeyPair = box.asymmetric.service.getKeyPairForEncryption();
});
```
## How to encrypt and decrypt (from unit test)
``` javascript
cryptolib('asymmetric.service', 'commons.utils', function(box) {
var converters = new box.commons.utils.Converters();
var dataB64= converters.base64Encode("anyString");
var publicKeyB64="placeYourPublicKeyHere";
var privateKeyB64="placeYourPrivateKeyHere";
var encryptedDataB64 = box.asymmetric.service.encrypt(publicKeyB64, dataB64);
var decryptedDataB64 = box.asymmetric.service.decrypt(privateKeyB64, encryptedDataB64);
});
```
## How to sign and verifySignature (from unit test)
``` javascript
cryptolib('asymmetric.service', 'commons.utils', function(box) {
var converters = new box.commons.utils.Converters();
var dataB64 = converters.base64Encode("anyString");
var arrayDataBase64 = [dataB64];
var publicKeyB64="placeYourPublicKeyHere";
var privateKeyB64="placeYourPrivateKeyHere";
var signatureBase64 = box.asymmetric.service.sign(privateKeyB64, arrayDataBase64);
var verified = box.asymmetric.service.verifySignature(signatureBase64, publicKeyB64, arrayDataBase64);
});
```
## How to verifyXmlSignature (from QA interface)
``` javascript
function xmlSigVerification() {
cryptoPRNG.startEntropyCollection();
var htmlpublicKey = document.form1.publicKey.value.toString();
var htmlsignatureParentNode = document.form1.signatureParentNode.value.toString();
var htmlxmlfile = document.form1.xmlfile.value.toString();
cryptoPRNG.stopEntropyCollectionAndCreatePRNG();
cryptolib('*', function(box) {
var abCert = box.forge.pki.certificateFromPem(htmlpublicKey, true);
var publicKey = abCert.publicKey;
verificationResult = box.asymmetric.service.verifyXmlSignature(publicKey, htmlxmlfile, htmlsignatureParentNode);
});
}
```
# Certificates service
## How to load (from unit test)
``` javascript
cryptolib('certificates', function (box) {
var myX509pemCertificate = "placeYourX509PemCertificateHere";
var loadedCertificate = new box.certificates.service.load(myX509pemCertificate);
});
```
## How to validateCertificate (from unit test)
``` javascript
var myX509pemCertificate = "placeYourX509PemCertificateHere";
cryptolib('certificates', function(box) {
var validationData = {
subject: {
commonName: "Subject CN",
organization: "Subject Org",
organizationUnit: "Subject Org Unit",
country: "Subject Country"
}
};
var validator = new box.certificates.CryptoX509CertificateValidator(validationData);
var failedValidations = validator.validate(myX509pemCertificate);
});
```
## How to validateX509CertificateChain (from unit test)
``` javascript
cryptolib('certificates', function(box) {
var certificateChain = {
leaf: {
pem: "-----BEGIN CERTIFICATE----------END CERTIFICATE-----",
keytype: "Sign",
subject: {
commonName: "leafCommonName",
organization: "leafOrganization",
organizationUnit: "leafOrganizationUnit",
country: "ES"
},
time: "2014-12-25'T'00:00:00Z"
},
root: "-----BEGIN CERTIFICATE----------END CERTIFICATE-----",
certificates: {
pems: [
"-----BEGIN CERTIFICATE----------END CERTIFICATE-----"
],
subjects: [
{
commonName: "intermediateCommonName",
organization: "intermediateOrganization",
organizationUnit: "intermediateOrganizationUnit",
country: "ES"
}
]
}
};
var validationFailed = box.certificates.service.validateX509CertificateChain(certificateChain);
});
```
## How to flattenFailedValidations (from unit test)
``` javascript
cryptolib('certificates', function(box) {
var failedValidations = box.certificates.service.validateX509CertificateChain(certificateChain);
var flattenFailedValidations = box.certificates.service.flattenFailedValidations(failedValidations);
});
```
# Proof service
Unit tests (files named '*.spec.js') are another good starting point in order to find examples of JS code snippets involving CryptoLib JS, at location: https://scm.scytl.net/stash/projects/COMM/repos/scytl-cryptolib-js/browse/src/lib
## How to createSimplePlaintextEqualityProof:
``` javascript
var proof = box.proofs.service.createSimplePlaintextEqualityProof(
primaryCiphertext, primaryPublicKey, witness, secondaryCiphertext,
secondaryPublicKey, zpSubgroup);
```
## How to createSimplePlaintextEqualityProof with precomputed values:
``` javascript
var preComputedValues = box.proofs.service.preComputeSimplePlaintextEqualityProof(
primaryPublicKey, secondaryPublicKey, zpSubgroup);
var proof = box.proofs.service.createSimplePlaintextEqualityProof(
primaryCiphertext, primaryPublicKey, witness, secondaryCiphertext,
secondaryPublicKey, zpSubgroup, preComputedValues);
```
preComputedValues´s type is box.proofs.ProofPreComputedValues.
## How to createSimplePlaintextEqualityProof with progress meter:
``` javascript
var proof = box.proofs.service.createSimplePlaintextEqualityProof(
primaryCiphertext, primaryPublicKey, witness, secondaryCiphertext,
secondaryPublicKey, zpSubgroup, progressCallback, progressPercentMinCheckInterval);
```
## How to createSimplePlaintextEqualityProof with precomputed values with progress meter:
``` javascript
var preComputedValues = box.proofs.service.preComputeSimplePlaintextEqualityProof(
primaryPublicKey, secondaryPublicKey, zpSubgroup, progressCallback, progressPercentMinCheckInterval);
var proof = box.proofs.service.createSimplePlaintextEqualityProof(
primaryCiphertext, primaryPublicKey, witness, secondaryCiphertext,
secondaryPublicKey, zpSubgroup, preComputedValues);
```
# More examples
More examples of html pages used by QA can be found at 2 places:
- integrated level, ready for testing (this depends on jenkins job execution status and can be out of order) : http://bcngpp1vsprdcitest.scytl.net:8080/view/Alice%20and%20Bobs/job/COMM-alice-and-bobs-scytl-qa-cryptoLibClient-master/ws/from-scratch/target/appassembler/webapp/
- repository level: https://scm.scytl.net/stash/projects/COMM/repos/scytl-qa-cryptolibclient/browse/from-scratch/src/main/webapp/WEB-INF
# Library technical design
[Read more »](libraryDesign.md)
# Versions
[Read more »](versioning-scytl-projects.md)
# Changelog
Use of conventional-changelog grunt plugin [Read more »](conventional-changelog.md), based by this commit conventions [Read more »](commit-conventions.md)