post-e-voting/source-code/scytl-cryptolib/cryptolib-js-policy/lib/index.js

/*
 * Copyright 2018 Scytl Secure Electronic Voting SA
 *
 * All rights reserved
 *
 * See our extended copyright notice in *file 'Copyright.txt' which is part of this source code package
 */
/* jshint node:true */
'use strict';

var CryptographicPolicy = require('./policy');
var options = require('./options');
var validator = require('./input-validator');

module.exports = {
  /**
   * Creates a new CryptographicPolicy object, which encapsulates a
   * cryptographic policy.
   *
   * <p>
   * By default, this object is created from the default cryptographic policy.
   * A customized policy may be provided instead, with the requirement that it
   * only uses options defined in {@link options}.
   *
   * @function newInstance
   * @global
   * @param {Object}
   *            [policy=Default policy] The cryptographic policy to use, as a
   *            JSON object.
   * @returns {CryptographicPolicy} The new CryptographicPolicy object.
   * @throws {Error} If the input data validation fails.
   */
  newInstance: function(policy) {
    checkData(policy);

    return new CryptographicPolicy(policy);
  },

  /**
   * The cryptographic policy options.
   *
   * @name options
   * @global
   *
   * @property {object} primitives.securerandom - Policy for generating
   *           message digests.
   * @property {object} primitives.messageDigest.algorithm - Hash algorithm.
   * @property {string} primitives.messageDigest.algorithm.SHA256 - 'SHA256'
   * @property {string} primitives.messageDigest.algorithm.SHA512_224
   *           -'SHA512/224'
   *
   * @property {object} primitives.keyDerivation - Policy for deriving keys.
   * @property {object} primitives.keyDerivation.pbkdf - Password-based key
   *           derivation function (PBKDF)
   * @property {object} primitives.keyDerivation.pbkdf.keyLengthBytes - Key
   *           length, in bytes.
   * @property {number} primitives.keyDerivation.pbkdf.keyLengthBytes.KL_16 -
   *           16
   * @property {number} primitives.keyDerivation.pbkdf.keyLengthBytes.KL_32 -
   *           32
   * @property {object} primitives.keyDerivation.pbkdf.minSaltLengthBytes -
   *           Minimum salt length, in bytes.
   * @property {number}
   *           primitives.keyDerivation.pbkdf.minSaltLengthBytes.SL_20 - 20.
   * @property {number}
   *           primitives.keyDerivation.pbkdf.minSaltLengthBytes.SL_32 - 32
   * @property {object} primitives.keyDerivation.pbkdf.hashAlgorithm - Hash
   *           algorithm.
   * @property {string} primitives.keyDerivation.pbkdf.hashAlgorithm.SHA256 -
   *           'SHA256'
   * @property {string}
   *           primitives.keyDerivation.pbkdf.hashAlgorithm.SHA512_224 -
   *           'SHA512/224'
   * @property {object} primitives.keyDerivation.pbkdf.numIterations - Number
   *           of iterations.
   * @property {number} primitives.keyDerivation.pbkdf.I_1 - 1
   * @property {number} primitives.keyDerivation.pbkdf.I_8000 - 8000
   * @property {number} primitives.keyDerivation.pbkdf.I_16000 - 16000
   * @property {number} primitives.keyDerivation.pbkdf.I_32000 - 32000
   * @property {number} primitives.keyDerivation.pbkdf.I_64000 - 64000
   *
   * @property {object} symmetric.secretkey - Policy for generating secret
   *           keys.
   * @property {object} symmetric.secretkey.encryption - Secret key for
   *           encryption.
   * @property {object} symmetric.secretKey.encryption.lengthBytes - Key
   *           length, in bytes.
   * @property {number} symmetric.secretKey.encryption.lengthBytes.KL_16 - 16
   * @property {number} symmetric.secretKey.encryption.lengthBytes.KL_32 - 32
   * @property {object} symmetric.secretkey.mac - Secret key for MAC
   *           generation.
   * @property {object} symmetric.secretKey.mac.lengthBytes - Key length, in
   *           bytes.
   * @property {number} symmetric.secretKey.mac.lengthBytes.KL_16 - 16
   * @property {number} symmetric.secretKey.mac.lengthBytes.KL_32 - 32
   *
   * @property {object} symmetric.cipher - Policy for symmetrically encrypting
   *           and decrypting data.
   * @property {object} symmetric.cipher.algorithm - Cipher algorithm.
   * @property {object} symmetric.cipher.algorithm.AES_GCM - AES-GCM
   *           algorithm.
   * @property {string} symmetric.cipher.algorithm.AES_GCM.name - 'AES-GCM'
   * @property {object} symmetric.cipher.algorithm.AES_GCM.keyLengthBytes -
   *           Key length, in bytes.
   * @property {number}
   *           symmetric.cipher.algorithm.AES_GCM.keyLengthBytes.KL_16 - 16
   * @property {number}
   *           symmetric.cipher.algorithm.AES_GCM.keyLengthBytes.KL_32 - 32
   * @property {object} symmetric.cipher.algorithm.AES_GCM.tagLengthBytes -
   *           Tag length, in bytes.
   * @property {number}
   *           symmetric.cipher.algorithm.AES_GCM.tagLengthBytes.TL_16 - 16
   * @property {number}
   *           symmetric.cipher.algorithm.AES_GCM.tagLengthBytes.TL_32 - 32
   * @property {object} symmetric.cipher.ivLengthBytes - Initialization vector
   *           length, in bytes.
   * @property {number} symmetric.cipher.ivLengthBytes.IVL_12 - 12
   * @property {number} symmetric.cipher.ivLengthBytes.IVL_16 - 16
   * @property {number} symmetric.cipher.ivLengthBytes.IVL_32 - 32
   * @property {number} symmetric.cipher.ivLengthBytes.IVL_64 - 64
   *
   * @property {object} symmetric.mac - Policy for generating MAC's.
   * @property {object} symmetric.mac.hashAlgorithm - Hash algorithm.
   * @property {string} symmetric.mac.hashAlgorithm.SHA256 = 'SHA256'
   * @property {string} symmetric.mac.hashAlgorithm.SHA512_224 = 'SHA512/224'
   *
   * @property {object} asymmetric.keyPair - Policy for generating key pairs.
   * @property {object} asymmetric.keyPair.encryption - Encryption key pair.
   * @property {object} asymmetric.keyPair.encryption.algorithm - Key pair
   *           generation algorithm.
   * @property {string} asymmetric.keyPair.encryption.algorithm.RSA - 'RSA'.
   * @property {object} asymmetric.keyPair.encryption.keyLengthBits - Key
   *           length, in bits.
   * @property {number} asymmetric.keyPair.encryption.keyLengthBits.KL_2048 -
   *           2048
   * @property {number} asymmetric.keyPair.encryption.keyLengthBits.KL_3072 -
   *           3072
   * @property {number} asymmetric.keyPair.encryption.keyLengthBits.KL_4096 -
   *           4096
   * @property {object} asymmetric.keyPair.encryption.publicExponent - Public
   *           exponent.
   * @property {number} asymmetric.keyPair.encryption.publicExponent.F4 -
   *           65537
   *
   * @property {object} asymmetric.signer - Policy for signing data and
   *           verifying signatures.
   * @property {object} asymmetric.signer.algorithm - Signer algorithm.
   * @property {string} asymmetric.signer.algorithm.RSA - 'RSA'
   * @property {object} asymmetric.signer.hashAlgorithm - Hash algorithm.
   * @property {string} asymmetric.signer.hashAlgorithm.SHA256 - SHA256'.
   * @property {string} asymmetric.signer.hashAlgorithm.SHA256_224 -
   *           'SHA512/224'
   * @property {object} asymmetric.signer.padding - Padding.
   * @property {object} asymmetric.signer.padding.PSS - PSS padding.
   * @property {string} asymmetric.signer.padding.PSS.name - 'PSS'
   * @property {object} asymmetric.signer.padding.PSS.hashAlgorithm - Hash
   *           algorithm.
   * @property {string} asymmetric.signer.padding.hashAlgorithm.SHA256 -
   *           'SHA256'
   * @property {string} asymmetric.signer.padding.hashAlgorithm.SHA256_224 -
   *           'SHA512/224'
   * @property {object} asymmetric.signer.padding.PSS.saltLengthBytes - Salt
   *           length, in bytes.
   * @property {number} asymmetric.signer.padding.PSS.saltLengthBytes.SL_32 -
   *           32
   * @property {number} asymmetric.signer.padding.PSS.saltLengthBytes.SL_64 -
   *           64
   * @property {object} asymmetric.signer.padding.PSS.maskGenerator - Mask
   *           generation function.
   * @property {object} asymmetric.signer.padding.PSS.maskGenerator.MGF1 -
   *           MGF1 mask generation algorithm.
   * @property {string} asymmetric.signer.padding.PSS.maskGenerator.MGF1.name -
   *           'MGF1'
   * @property {object}
   *           asymmetric.signer.padding.PSS.maskGenerator.MGF1.hashAlgorithm -
   *           Hash algorithm.
   * @property {string}
   *           asymmetric.signer.padding.PSS.maskGenerator.MGF1.hashAlgorithm.SHA256
   *           -'SHA256'
   * @property {string}
   *           asymmetric.signer.padding.PSS.maskGenerator.MGF1.hashAlgorithm.SHA256_224
   * - 'SHA512/224'
   * @property {object} asymmetric.signer.publicExponent - Public exponent.
   * @property {number} asymmetric.signer.publicExponent.F4 - 65537
   *
   * @property {object} asymmetric.cipher - Policy for asymmetrically
   *           encrypting and decrypting data.
   * @property {object} asymmetric.cipher.algorithm - Cipher algorithm.
   * @property {object} asymmetric.cipher.algorithm.RSA_OAEP - RSA-OAEP
   *           algorithm.
   * @property {string} asymmetric.cipher.algorithm.RSA_OAEP.name. -
   *           'RSA-OAEP'.
   * @property {object} asymmetric.cipher.algorithm.RSA_OAEP.hashAlgorithm -
   *           Hash algorithm.
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_OAEP.hashAlgorithm.SHA256 -
   *           'SHA-256'
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_OAEP.hashAlgorithm.SHA512_224 -
   *           'SHA512/224'
   * @property {object} asymmetric.cipher.algorithm.RSA_OAEP.maskGenerator -
   *           Mask generation function.
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_OAEP.maskGenerator.MGF1 - MGF1
   *           mask generation function.
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_OAEP.maskGenerator.MGF1.name -
   *           'MGF1'
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_OAEP.maskGenerator.MGF1.hashAlgorithm
   * - Hash algorithm.
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_OAEP.maskGenerator.MGF1.hashAlgorithm.SHA256
   * - 'SHA256'
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_OAEP.maskGenerator.MGF1.hashAlgorithm.SHA512_224
   * - 'SHA512/224'
   * @property {object} asymmetric.cipher.algorithm.RSA_KEM - RSA-KEM
   *           algorithm.
   * @property {string} asymmetric.cipher.algorithm.RSA_KEM.name - 'RSA-KEM'
   * @property {object} asymmetric.cipher.algorithm.RSA_KEM.hashAlgorithm -
   *           Hash algorithm.
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.hashAlgorithm.SHA256 -
   *           'SHA256'
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.hashAlgorithm.SHA512_224 -
   *           'SHA512/224'
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_KEM.secretKeyLengthBytes -
   *           Secret key length, in bytes.
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.secretKeyLengthBytes.KL_16 -
   *           16
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.secretKeyLengthBytes.KL_24 -
   *           24
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.secretKeyLengthBytes.KL_32 -
   *           32
   * @property {object} asymmetric.cipher.algorithm.RSA_KEM.ivLengthBytes -
   *           Initialization vector length, in bytes.
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.ivLengthBytes.IVL_12 - 12
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.ivLengthBytes.IVL_16 - 16
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.ivLengthBytes.IVL_32 - 32
   * @property {number}
   *           asymmetric.cipher.algorithm.RSA_KEM.ivLengthBytes.IVL_64 - 64
   * @property {object} asymmetric.cipher.algorithm.RSA_KEM.tagLengthBytes
   *           -Tag length, in bytes.
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_KEM.tagLengthBytes.TL_12 - 12
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_KEM.tagLengthBytes.TL_16 - 16
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_KEM.tagLengthBytes.TL_32 - 32
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_KEM.tagLengthBytes.TL_64 - 64
   * @property {object} asymmetric.cipher.algorithm.RSA_KEM.keyDeriver - Key
   *           deriver
   * @property {object} asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.name -
   *           Key deriver name.
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.name.KDF1 -
   *           'KDF1'
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.name.KDF2 -
   *           'KDF2'
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.name.MGF1 -
   *           'MGF1'
   * @property {object}
   *           asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.hashAlgorithm -
   *           Hash function.
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.hashAlgorithm.SHA256
   * - 'SHA256'
   * @property {string}
   *           asymmetric.cipher.algorithm.RSA_KEM.keyDeriver.hashAlgorithm.SHA512_224
   * - 'SHA512/224'
   *
   * @property {object} proofs - Policy for generating zero-knowledge proofs.
   * @property {object} proofs.messageDigest - Policy for generating message
   *           digests.
   *
   * @property {object} digitalEnvelope - Policy for generating digital
   *           envelopes.
   * @property {object} digitalEnvelope.symmetric - Policy for symmetric
   *           cryptography operations.
   * @property {object} digitalEnvelope.asymmetric.cipher - Policy for
   *           asymmetric cipher operations.
   */
  options: options
};

function checkData(policy) {
  if (typeof policy !== 'undefined') {
    validator.checkIsObjectWithProperties(policy, 'Cryptographic policy');
  }
}