1 | import { JsonWebKey } from '../util.js'
|
2 |
|
3 | /**
|
4 | * A wrapper around `mySecretKey` that can compute a shared secret using `theirPublicKey`.
|
5 | * The promise should resolve to a `Uint8Array` containing the raw shared secret.
|
6 | *
|
7 | * This method is meant to be used when direct access to a secret key is impossible or not desired.
|
8 | *
|
9 | * @param theirPublicKey `Uint8Array` the other party's public key
|
10 | * @returns a `Promise` that resolves to a `Uint8Array` representing the computed shared secret
|
11 | */
|
12 | export type ECDH = (theirPublicKey: Uint8Array) => Promise<Uint8Array>
|
13 |
|
14 | // eslint-disable-next-line @typescript-eslint/no-explicit-any
|
15 | export type ProtectedHeader = Record<string, any> & Partial<RecipientHeader>
|
16 |
|
17 | /**
|
18 | * The JWK representation of an ephemeral public key.
|
19 | * See https://www.rfc-editor.org/rfc/rfc7518.html#section-6
|
20 | */
|
21 | export interface EphemeralPublicKey {
|
22 | kty?: string
|
23 | //ECC
|
24 | crv?: string
|
25 | x?: string
|
26 | y?: string
|
27 | //RSA
|
28 | n?: string
|
29 | e?: string
|
30 | }
|
31 |
|
32 | /**
|
33 | * A pair of an ephemeral public key (JWK) and its corresponding secret key.
|
34 | * This is used to encrypt content encryption key (cek) for a recipient.
|
35 | *
|
36 | * @see {@link KekCreator}
|
37 | */
|
38 | export interface EphemeralKeyPair {
|
39 | publicKeyJWK: EphemeralPublicKey
|
40 | secretKey: Uint8Array
|
41 | }
|
42 |
|
43 | export interface RecipientHeader {
|
44 | alg?: string
|
45 | iv?: string
|
46 | tag?: string
|
47 | epk?: EphemeralPublicKey
|
48 | kid?: string
|
49 | apv?: string
|
50 | apu?: string
|
51 | }
|
52 |
|
53 | export interface Recipient {
|
54 | header: RecipientHeader
|
55 | encrypted_key: string
|
56 | }
|
57 |
|
58 | export interface JWE {
|
59 | protected: string
|
60 | iv: string
|
61 | ciphertext: string
|
62 | tag: string
|
63 | aad?: string
|
64 | recipients?: Recipient[]
|
65 | }
|
66 |
|
67 | export interface EncryptionResult {
|
68 | ciphertext: Uint8Array
|
69 | tag?: Uint8Array
|
70 | iv?: Uint8Array
|
71 | protectedHeader?: string
|
72 | recipient?: Recipient
|
73 | cek?: Uint8Array
|
74 | }
|
75 |
|
76 | export interface WrappingResult {
|
77 | ciphertext: Uint8Array
|
78 | tag?: Uint8Array
|
79 | iv?: Uint8Array
|
80 | }
|
81 |
|
82 | /**
|
83 | * An object that can perform content encryption and optionally key wrapping and key generation.
|
84 | */
|
85 | export interface Encrypter {
|
86 | // key agreement + key wrapping algorithms (e.g. ECDH-ES+A256KW)
|
87 | alg: string
|
88 |
|
89 | // content encryption algorithm (e.g. A256GCM)
|
90 | enc: string
|
91 |
|
92 | // The content encryption method.
|
93 | encrypt: (
|
94 | cleartext: Uint8Array,
|
95 | protectedHeader: ProtectedHeader,
|
96 | aad?: Uint8Array,
|
97 | ephemeralKeyPair?: EphemeralKeyPair
|
98 | ) => Promise<EncryptionResult>
|
99 |
|
100 | // The method to encrypt the content encryption key (cek) for a recipient.
|
101 | encryptCek?: (cek: Uint8Array, ephemeralKeyPair?: EphemeralKeyPair) => Promise<Recipient>
|
102 |
|
103 | // The method to generate an ephemeral key pair.
|
104 | genEpk?: () => EphemeralKeyPair
|
105 | }
|
106 |
|
107 | /**
|
108 | * An object that can perform decryption of a ciphertext.
|
109 | * It also describes the content encryption (enc) and key agreement + wrapping (alg) algorithms it supports.
|
110 | */
|
111 | export interface Decrypter {
|
112 | alg: string
|
113 | enc: string
|
114 | decrypt: (sealed: Uint8Array, iv: Uint8Array, aad?: Uint8Array, recipient?: Recipient) => Promise<Uint8Array | null>
|
115 | }
|
116 |
|
117 | /**
|
118 | * An object that can perform key unwrapping.
|
119 | */
|
120 | export type KeyWrapper = {
|
121 | /**
|
122 | * Create a key wrapper from a key encryption key (kek).
|
123 | * @param kek
|
124 | */
|
125 | // eslint-disable-next-line @typescript-eslint/no-explicit-any
|
126 | from: (kek: Uint8Array) => { wrap: (cek: Uint8Array, options?: any) => Promise<WrappingResult> }
|
127 | // key wrapping algorithm (e.g. A256KW, XC20PKW)
|
128 | alg: 'A256KW' | 'XC20PKW' | string
|
129 | }
|
130 |
|
131 | export type KekCreator = {
|
132 | createKek(
|
133 | recipientPublicKey: Uint8Array,
|
134 | senderSecret: Uint8Array | ECDH | undefined,
|
135 | // key agreement + key wrapping algorithm. e.g. ECDH-ES+A256KW
|
136 | alg: string,
|
137 | apu: string | undefined,
|
138 | apv: string | undefined,
|
139 | ephemeralKeyPair: EphemeralKeyPair | undefined
|
140 | ): Promise<{ epk: JsonWebKey; kek: Uint8Array }>
|
141 |
|
142 | // key agreement algorithm
|
143 | alg: 'ECDH-ES' | 'ECDH-1PU' | string
|
144 | }
|
145 |
|
146 | export type ContentEncrypter = {
|
147 | /**
|
148 | * Create a content `Encrypter` from a content encryption key (cek).
|
149 | * @param cek
|
150 | */
|
151 | from(cek: Uint8Array): Encrypter
|
152 | // content encryption algorithm
|
153 | enc: 'XC20P' | 'A256GCM' | 'A256CBC-HS512' | string
|
154 | }
|
155 |
|
156 | /**
|
157 | * Extra parameters for JWE using authenticated encryption
|
158 | */
|
159 | export type AuthEncryptParams = {
|
160 | /**
|
161 | * recipient key ID
|
162 | */
|
163 | kid?: string
|
164 |
|
165 | /**
|
166 | * See {@link https://datatracker.ietf.org/doc/html/rfc7518#section-4.6.1.2}
|
167 | * base64url encoded
|
168 | */
|
169 | apu?: string
|
170 |
|
171 | /**
|
172 | * See {@link https://datatracker.ietf.org/doc/html/rfc7518#section-4.6.1.3}
|
173 | * base64url encoded
|
174 | */
|
175 | apv?: string
|
176 | }
|
177 |
|
178 | /**
|
179 | * Extra parameters for JWE using anonymous encryption
|
180 | */
|
181 | export type AnonEncryptParams = {
|
182 | /**
|
183 | * recipient key ID
|
184 | */
|
185 | kid?: string
|
186 |
|
187 | /**
|
188 | * See {@link https://datatracker.ietf.org/doc/html/rfc7518#section-4.6.1.3}
|
189 | * base64url encoded
|
190 | */
|
191 | apv?: string
|
192 | }
|