tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

CryptoEngineInterface.ts (6195B)

      1 import type * as asn1js from "asn1js";
      2 import type { AlgorithmIdentifier } from "../AlgorithmIdentifier";
      3 import type { EncryptedContentInfo } from "../EncryptedContentInfo";
      4 import type { PublicKeyInfo } from "../PublicKeyInfo";
      5 
      6 export type CryptoEngineAlgorithmOperation = "sign" | "encrypt" | "generateKey" | "importKey" | "exportKey" | "verify";
      7 
      8 /**
      9 * Algorithm parameters
     10 */
     11 export interface CryptoEngineAlgorithmParams {
     12  /**
     13   * Algorithm
     14   */
     15  algorithm: Algorithm | object;
     16  /**
     17   * Key usages
     18   */
     19  usages: KeyUsage[];
     20 }
     21 
     22 export interface CryptoEngineSignatureParams {
     23  signatureAlgorithm: AlgorithmIdentifier;
     24  parameters: CryptoEngineAlgorithmParams;
     25 }
     26 
     27 export interface CryptoEngineSignWithPrivateKeyParams {
     28  algorithm: Algorithm;
     29 }
     30 
     31 /**
     32 * Public key parameters
     33 */
     34 export interface CryptoEnginePublicKeyParams {
     35  /**
     36   * Algorithm
     37   */
     38  algorithm: CryptoEngineAlgorithmParams;
     39 }
     40 
     41 
     42 export type ContentEncryptionAesCbcParams = AesCbcParams & AesDerivedKeyParams;
     43 export type ContentEncryptionAesGcmParams = AesGcmParams & AesDerivedKeyParams;
     44 export type ContentEncryptionAlgorithm = ContentEncryptionAesCbcParams | ContentEncryptionAesGcmParams;
     45 
     46 export interface CryptoEngineEncryptParams {
     47  password: ArrayBuffer;
     48  contentEncryptionAlgorithm: ContentEncryptionAlgorithm;
     49  hmacHashAlgorithm: string;
     50  iterationCount: number;
     51  contentToEncrypt: ArrayBuffer;
     52  contentType: string;
     53 }
     54 
     55 export interface CryptoEngineDecryptParams {
     56  password: ArrayBuffer;
     57  encryptedContentInfo: EncryptedContentInfo;
     58 }
     59 
     60 export interface CryptoEngineStampDataWithPasswordParams {
     61  password: ArrayBuffer;
     62  hashAlgorithm: string;
     63  salt: ArrayBuffer;
     64  iterationCount: number;
     65  contentToStamp: ArrayBuffer;
     66 }
     67 
     68 export interface CryptoEngineVerifyDataStampedWithPasswordParams {
     69  password: ArrayBuffer;
     70  hashAlgorithm: string;
     71  salt: ArrayBuffer;
     72  iterationCount: number;
     73  contentToVerify: ArrayBuffer;
     74  signatureToVerify: ArrayBuffer;
     75 }
     76 
     77 export interface ICryptoEngine extends SubtleCrypto {
     78  name: string;
     79  crypto: Crypto;
     80  subtle: SubtleCrypto;
     81 
     82  getRandomValues<T extends ArrayBufferView | null>(array: T): T;
     83 
     84  /**
     85   * Get OID for each specific algorithm
     86   * @param algorithm WebCrypto Algorithm
     87   * @param safety If `true` throws exception on unknown algorithm. Default is `false`
     88   * @param target Name of the target
     89   * @throws Throws {@link Error} exception if unknown WebCrypto algorithm
     90   */
     91  getOIDByAlgorithm(algorithm: Algorithm, safety?: boolean, target?: string): string;
     92  /**
     93   * Get default algorithm parameters for each kind of operation
     94   * @param algorithmName Algorithm name to get common parameters for
     95   * @param operation Kind of operation: "sign", "encrypt", "generateKey", "importKey", "exportKey", "verify"
     96   */
     97  // TODO Use safety
     98  getAlgorithmParameters(algorithmName: string, operation: CryptoEngineAlgorithmOperation): CryptoEngineAlgorithmParams;
     99 
    100  /**
    101   * Gets WebCrypto algorithm by wel-known OID
    102   * @param oid algorithm identifier
    103   * @param safety if `true` throws exception on unknown algorithm identifier
    104   * @param target name of the target
    105   * @returns Returns WebCrypto algorithm or an empty object
    106   */
    107  getAlgorithmByOID<T extends Algorithm = Algorithm>(oid: string, safety?: boolean, target?: string): T | object;
    108  /**
    109   * Gets WebCrypto algorithm by wel-known OID
    110   * @param oid algorithm identifier
    111   * @param safety if `true` throws exception on unknown algorithm identifier
    112   * @param target name of the target
    113   * @returns Returns WebCrypto algorithm
    114   * @throws Throws {@link Error} exception if unknown algorithm identifier
    115   */
    116  getAlgorithmByOID<T extends Algorithm = Algorithm>(oid: string, safety: true, target?: string): T;
    117 
    118  /**
    119   * Getting hash algorithm by signature algorithm
    120   * @param signatureAlgorithm Signature algorithm
    121   */
    122  // TODO use safety
    123  getHashAlgorithm(signatureAlgorithm: AlgorithmIdentifier): string;
    124 
    125  /**
    126   * Get signature parameters by analyzing private key algorithm
    127   * @param privateKey The private key user would like to use
    128   * @param hashAlgorithm Hash algorithm user would like to use. Default is SHA-1
    129   */
    130  getSignatureParameters(privateKey: CryptoKey, hashAlgorithm?: string): Promise<CryptoEngineSignatureParams>;
    131 
    132  /**
    133   * Sign data with pre-defined private key
    134   * @param data Data to be signed
    135   * @param privateKey Private key to use
    136   * @param parameters Parameters for used algorithm
    137   */
    138  signWithPrivateKey(data: BufferSource, privateKey: CryptoKey, parameters: CryptoEngineSignWithPrivateKeyParams): Promise<ArrayBuffer>;
    139 
    140  /**
    141   * Verify data with the public key
    142   * @param data Data to be verified
    143   * @param signature Signature value
    144   * @param publicKeyInfo Public key information
    145   * @param signatureAlgorithm Signature algorithm
    146   * @param shaAlgorithm Hash algorithm
    147   */
    148  verifyWithPublicKey(data: BufferSource, signature: asn1js.BitString | asn1js.OctetString, publicKeyInfo: PublicKeyInfo, signatureAlgorithm: AlgorithmIdentifier, shaAlgorithm?: string): Promise<boolean>;
    149 
    150  getPublicKey(publicKeyInfo: PublicKeyInfo, signatureAlgorithm: AlgorithmIdentifier, parameters?: CryptoEnginePublicKeyParams): Promise<CryptoKey>;
    151 
    152  /**
    153   * Specialized function encrypting "EncryptedContentInfo" object using parameters
    154   * @param parameters
    155   */
    156  encryptEncryptedContentInfo(parameters: CryptoEngineEncryptParams): Promise<EncryptedContentInfo>;
    157 
    158  /**
    159   * Decrypt data stored in "EncryptedContentInfo" object using parameters
    160   * @param parameters
    161   */
    162  decryptEncryptedContentInfo(parameters: CryptoEngineDecryptParams): Promise<ArrayBuffer>;
    163 
    164  /**
    165   * Stamping (signing) data using algorithm similar to HMAC
    166   * @param parameters
    167   */
    168  stampDataWithPassword(parameters: CryptoEngineStampDataWithPasswordParams): Promise<ArrayBuffer>;
    169  verifyDataStampedWithPassword(parameters: CryptoEngineVerifyDataStampedWithPasswordParams): Promise<boolean>;
    170 }
    171 
    172 export interface CryptoEngineParameters {
    173  name?: string;
    174  crypto: Crypto;
    175  /**
    176   * @deprecated
    177   */
    178  subtle?: SubtleCrypto;
    179 }
    180 
    181 export interface CryptoEngineConstructor {
    182  new(params: CryptoEngineParameters): ICryptoEngine;
    183 }