packages/crypto/lib/worker/api.models.ts

   1 import type {
   2     AlgorithmInfo,
   3     Data,
   4     DecryptOptionsPmcrypto,
   5     DecryptResultPmcrypto,
   6     DecryptSessionKeyOptionsPmcrypto,
   7     EncryptOptionsPmcrypto,
   8     EncryptSessionKeyOptionsPmcrypto,
   9     GenerateKeyOptions,
  10     GenerateSessionKeyOptionsPmcrypto,
  11     MIMEAttachment,
  12     ProcessMIMEOptions,
  13     ProcessMIMEResult,
  14     ReformatKeyOptions,
  15     SessionKey,
  16     SignOptionsPmcrypto,
  17     VerifyCleartextOptionsPmcrypto,
  18     VerifyMessageResult,
  19     VerifyOptionsPmcrypto,
  20 } from 'pmcrypto-v6-canary';
  21 import type { PartialConfig, SubkeyOptions, enums } from 'pmcrypto-v6-canary/lib/openpgp';
  22
  23 export type MaybeArray<T> = T[] | T;
  24 export type { enums, SessionKey, AlgorithmInfo, MIMEAttachment };
  25
  26 // TODO TS: do not allow mutually exclusive properties
  27 export interface WorkerDecryptionOptions
  28     extends Omit<
  29         DecryptOptionsPmcrypto<Data>,
  30         'message' | 'signature' | 'encryptedSignature' | 'verificationKeys' | 'decryptionKeys'
  31     > {
  32     armoredSignature?: string;
  33     binarySignature?: Uint8Array;
  34     armoredMessage?: string;
  35     binaryMessage?: Uint8Array;
  36     armoredEncryptedSignature?: string;
  37     binaryEncryptedSignature?: Uint8Array;
  38     verificationKeys?: MaybeArray<PublicKeyReference>;
  39     decryptionKeys?: MaybeArray<PrivateKeyReference>;
  40     sessionKeys?: MaybeArray<SessionKey>;
  41     config?: PartialConfigForV5AndV6;
  42 }
  43 export interface WorkerDecryptionResult<T extends Data> extends Omit<DecryptResultPmcrypto<T>, 'signatures'> {
  44     signatures: Uint8Array[];
  45 }
  46
  47 // TODO to make Option interfaces easy to use for the user, might be best to set default param types (e.g. T extends Data = Data).
  48 export interface WorkerVerifyOptions<T extends Data>
  49     extends Omit<VerifyOptionsPmcrypto<T>, 'signature' | 'verificationKeys'> {
  50     armoredSignature?: string;
  51     binarySignature?: Uint8Array;
  52     verificationKeys: MaybeArray<PublicKeyReference>;
  53     config?: PartialConfigForV5AndV6;
  54 }
  55 export interface WorkerVerifyCleartextOptions
  56     extends Omit<VerifyCleartextOptionsPmcrypto, 'cleartextMessage' | 'verificationKeys'> {
  57     armoredCleartextMessage: string;
  58     verificationKeys: MaybeArray<PublicKeyReference>;
  59     config?: PartialConfigForV5AndV6;
  60 }
  61 export interface WorkerVerificationResult<T extends Data = Data> extends Omit<VerifyMessageResult<T>, 'signatures'> {
  62     signatures: Uint8Array[];
  63 }
  64
  65 export interface WorkerSignOptions<T extends Data> extends Omit<SignOptionsPmcrypto<T>, 'signingKeys'> {
  66     format?: 'armored' | 'binary';
  67     signingKeys?: MaybeArray<PrivateKeyReference>;
  68 }
  69 export interface WorkerEncryptOptions<T extends Data>
  70     extends Omit<EncryptOptionsPmcrypto<T>, 'signature' | 'signingKeys' | 'encryptionKeys'> {
  71     format?: 'armored' | 'binary';
  72     armoredSignature?: string;
  73     binarySignature?: Uint8Array;
  74     encryptionKeys?: MaybeArray<PublicKeyReference>;
  75     signingKeys?: MaybeArray<PrivateKeyReference>;
  76     compress?: boolean;
  77     config?: PartialConfigForV5AndV6;
  78 }
  79
  80 export interface WorkerProcessMIMEOptions extends Omit<ProcessMIMEOptions, 'verificationKeys'> {
  81     verificationKeys?: MaybeArray<PublicKeyReference>;
  82 }
  83
  84 export interface WorkerProcessMIMEResult extends Omit<ProcessMIMEResult, 'signatures'> {
  85     signatures: Uint8Array[];
  86 }
  87
  88 export type WorkerExportedKey<F extends 'armored' | 'binary' | undefined = 'armored'> = F extends 'armored'
  89     ? string
  90     : Uint8Array;
  91
  92 export interface WorkerImportDecryptedPrivateKeyOptions<T extends Data> {
  93     armoredKey?: T extends string ? T : never;
  94     binaryKey?: T extends Uint8Array ? T : never;
  95 }
  96
  97 export interface WorkerImportEncryptedPrivateKeyOptions<T extends Data> {
  98     armoredKey?: T extends string ? T : never;
  99     binaryKey?: T extends Uint8Array ? T : never;
 100     passphrase: string;
 101 }
 102
 103 export interface WorkerImportPrivateKeyOptions<T extends Data> {
 104     armoredKey?: T extends string ? T : never;
 105     binaryKey?: T extends Uint8Array ? T : never;
 106     /**
 107      * null if the key is expected to be already decrypted, e.g. when user uploads a new private key that is unencrypted
 108      */
 109     passphrase: string | null;
 110     /**
 111      * Check whether the key is compatible with all Proton clients.
 112      * This should be used when importing a key that was generate outside of Proton.
 113      */
 114     checkCompatibility?: boolean;
 115 }
 116
 117 export type WorkerImportPublicKeyOptions<T extends Data> = {
 118     armoredKey?: T extends string ? T : never;
 119     binaryKey?: T extends Uint8Array ? T : never;
 120     /**
 121      * Check whether the key is compatible with all Proton clients.
 122      * This should be used when importing a key that was generate outside of Proton.
 123      */
 124     checkCompatibility?: boolean;
 125 };
 126
 127 // OpenPGP.js v6 introduces some new algos, and renames existing ones. Since the corresponding config settings are unused in the apps,
 128 // we just filter them out at the TS level.
 129 interface PartialConfigForV5AndV6
 130     extends Omit<
 131         PartialConfig,
 132         | 'rejectPublicKeyAlgorithms'
 133         | 'preferredSymmetricAlgorithm'
 134         | 'preferredHashAlgorithm'
 135         | 'rejectHashAlgorithms'
 136         | 'rejectMessageHashAlgorithms'
 137         | 'constantTimePKCS1DecryptionSupportedSymmetricAlgorithms'
 138         | 'rejectCurves'
 139         | 'aeadProtect' // slightly different behaviours in v5 and v6
 140         // the following ones are not present in v5
 141         | 'ignoreSEIPDv2FeatureFlag'
 142         | 'v6Keys'
 143         | 'allowMissingKeyFlags'
 144         | 'useEllipticFallback'
 145         | 'revocationsExpire'
 146     > {}
 147 interface WorkerGenerateSubkeyOptions extends SubkeyOptions {
 148     config?: PartialConfigForV5AndV6;
 149 }
 150 export interface WorkerGenerateKeyOptions extends Omit<GenerateKeyOptions, 'format' | 'passphrase'> {
 151     config?: PartialConfigForV5AndV6;
 152     subkeys?: WorkerGenerateSubkeyOptions[];
 153 }
 154
 155 export interface WorkerReformatKeyOptions extends Omit<ReformatKeyOptions, 'privateKey' | 'format' | 'passphrase'> {
 156     privateKey: PrivateKeyReference;
 157     config?: PartialConfigForV5AndV6;
 158 }
 159
 160 export interface WorkerEncryptSessionKeyOptions extends Omit<EncryptSessionKeyOptionsPmcrypto, 'encryptionKeys'> {
 161     algorithm: SessionKey['algorithm'];
 162     format?: 'armored' | 'binary';
 163     encryptionKeys?: MaybeArray<PublicKeyReference>;
 164     config?: PartialConfigForV5AndV6;
 165 }
 166
 167 export interface WorkerGenerateSessionKeyOptions extends Omit<GenerateSessionKeyOptionsPmcrypto, 'recipientKeys'> {
 168     recipientKeys?: MaybeArray<PublicKeyReference>;
 169     config?: PartialConfigForV5AndV6;
 170 }
 171
 172 export interface WorkerDecryptSessionKeyOptions
 173     extends Omit<DecryptSessionKeyOptionsPmcrypto, 'message' | 'decryptionKeys'> {
 174     armoredMessage?: string;
 175     binaryMessage?: Uint8Array;
 176     decryptionKeys?: MaybeArray<PrivateKeyReference>;
 177 }
 178
 179 export interface WorkerGetMessageInfoOptions<T extends Data> {
 180     armoredMessage?: T extends string ? T : never;
 181     binaryMessage?: T extends Uint8Array ? T : never;
 182 }
 183
 184 export interface MessageInfo {
 185     signingKeyIDs: KeyID[];
 186     encryptionKeyIDs: KeyID[];
 187 }
 188
 189 export interface WorkerGetSignatureInfoOptions<T extends Data> {
 190     armoredSignature?: T extends string ? T : never;
 191     binarySignature?: T extends Uint8Array ? T : never;
 192 }
 193
 194 export interface WorkerGetKeyInfoOptions<T extends Data> {
 195     armoredKey?: T extends string ? T : never;
 196     binaryKey?: T extends Uint8Array ? T : never;
 197 }
 198
 199 export interface SignatureInfo {
 200     signingKeyIDs: KeyID[];
 201 }
 202
 203 export interface KeyInfo {
 204     keyIsPrivate: boolean;
 205     /**
 206      * Whether the key is decrypted, or `null` for public keys
 207      */
 208     keyIsDecrypted: boolean | null;
 209     fingerprint: string;
 210     /**
 211      * Key IDs of primary key and subkeys in hex format
 212      */
 213     keyIDs: KeyID[];
 214 }
 215
 216 export type KeyID = string;
 217
 218 export interface KeyReference {
 219     /** Internal unique key identifier for the key store */
 220     readonly _idx: any;
 221     /**
 222      * (Internal) key content identifier to determine equality.
 223      * First entry includes the full key.
 224      * Second entry does not include 3rd party certifications (e.g. from Proton CA).
 225      **/
 226     readonly _keyContentHash: [string, string];
 227     /**
 228      * Return compatibility error if the key not compatible with all Proton clients.
 229      * This function is intended for logging purposes.
 230      * Use `options.checkCompatibility` with `importPrivateKey` and `importPublicKeys` to avoid importing incompatible keys.
 231      */
 232     _getCompatibilityError(): Error | null;
 233
 234     getFingerprint(): string;
 235     /**
 236      * Key ID of primary key in hex format.
 237      */
 238     getKeyID(): KeyID;
 239     /**
 240      * Key IDs of primary key and subkeys in hex format
 241      */
 242     getKeyIDs(): KeyID[];
 243     getAlgorithmInfo(): AlgorithmInfo;
 244     getCreationTime(): Date;
 245     isPrivate: () => this is PrivateKeyReference;
 246     getExpirationTime(): Date | number | null;
 247     getUserIDs(): string[];
 248     /**
 249      * Whether the primary key or the subkeys fail to meet our recommended security level.
 250      * A key is considered secure (i.e. not weak) if it is:
 251      * - RSA of size >= 2047 bits
 252      * - ECC using curve 25519 or any of the NIST curves
 253      */
 254     isWeak(): boolean;
 255     /**
 256      * Compare public key content. Keys are considered equal if they have same key and subkey material,
 257      * as well as same certification signatures, namely same expiration time, capabilities, algorithm preferences etc.
 258      * @param [ignoreOtherCerts] - whether third-party certifications (e.g. from Proton CA) should be ignored.
 259      */
 260     equals(otherKey: KeyReference, ignoreOtherCerts?: boolean): boolean;
 261     subkeys: {
 262         getAlgorithmInfo(): AlgorithmInfo;
 263         getKeyID(): KeyID;
 264     }[];
 265 }
 266 export interface PublicKeyReference extends KeyReference {}
 267 export interface PrivateKeyReference extends PublicKeyReference {
 268     /** Dummy field needed to distinguish a PrivateKeyReference from  a PublicKeyReference, as they are otherwise seen as equivalent by TS */
 269     readonly _dummyType: 'private';
 270 }
 271
 272 export interface ComputeHashStreamOptions {
 273     algorithm: 'unsafeSHA1';
 274     dataStream: ReadableStream<Uint8Array>;
 275 }