diff options
Diffstat (limited to 'includes/external/matrix/node_modules/matrix-js-sdk/lib/crypto/OlmDevice.d.ts')
| -rw-r--r-- | includes/external/matrix/node_modules/matrix-js-sdk/lib/crypto/OlmDevice.d.ts | 454 |
1 files changed, 454 insertions, 0 deletions
diff --git a/includes/external/matrix/node_modules/matrix-js-sdk/lib/crypto/OlmDevice.d.ts b/includes/external/matrix/node_modules/matrix-js-sdk/lib/crypto/OlmDevice.d.ts new file mode 100644 index 0000000..3b8bbe9 --- /dev/null +++ b/includes/external/matrix/node_modules/matrix-js-sdk/lib/crypto/OlmDevice.d.ts @@ -0,0 +1,454 @@ +import { PrefixedLogger } from "../logger"; +import { CryptoStore, IProblem, ISessionInfo } from "./store/base"; +import { IOlmDevice, IOutboundGroupSessionKey } from "./algorithms/megolm"; +import { IMegolmSessionData, OlmGroupSessionExtraData } from "../@types/crypto"; +import { IMessage } from "./algorithms/olm"; +export declare class PayloadTooLargeError extends Error { + readonly data: { + errcode: string; + error: string; + }; +} +interface IInitOpts { + fromExportedDevice?: IExportedDevice; + pickleKey?: string; +} +/** data stored in the session store about an inbound group session */ +export interface InboundGroupSessionData { + room_id: string; + /** pickled Olm.InboundGroupSession */ + session: string; + keysClaimed: Record<string, string>; + /** Devices involved in forwarding this session to us (normally empty). */ + forwardingCurve25519KeyChain: string[]; + /** whether this session is untrusted. */ + untrusted?: boolean; + /** whether this session exists during the room being set to shared history. */ + sharedHistory?: boolean; +} +export interface IDecryptedGroupMessage { + result: string; + keysClaimed: Record<string, string>; + senderKey: string; + forwardingCurve25519KeyChain: string[]; + untrusted: boolean; +} +export interface IInboundSession { + payload: string; + session_id: string; +} +export interface IExportedDevice { + pickleKey: string; + pickledAccount: string; + sessions: ISessionInfo[]; +} +interface IInboundGroupSessionKey { + chain_index: number; + key: string; + forwarding_curve25519_key_chain: string[]; + sender_claimed_ed25519_key: string | null; + shared_history: boolean; + untrusted?: boolean; +} +type OneTimeKeys = { + curve25519: { + [keyId: string]: string; + }; +}; +/** + * Manages the olm cryptography functions. Each OlmDevice has a single + * OlmAccount and a number of OlmSessions. + * + * Accounts and sessions are kept pickled in the cryptoStore. + */ +export declare class OlmDevice { + private readonly cryptoStore; + pickleKey: string; + /** Curve25519 key for the account, unknown until we load the account from storage in init() */ + deviceCurve25519Key: string | null; + /** Ed25519 key for the account, unknown until we load the account from storage in init() */ + deviceEd25519Key: string | null; + private maxOneTimeKeys; + private outboundGroupSessionStore; + private inboundGroupSessionMessageIndexes; + sessionsInProgress: Record<string, Promise<void>>; + olmPrekeyPromise: Promise<any>; + constructor(cryptoStore: CryptoStore); + /** + * @returns The version of Olm. + */ + static getOlmVersion(): [number, number, number]; + /** + * Initialise the OlmAccount. This must be called before any other operations + * on the OlmDevice. + * + * Data from an exported Olm device can be provided + * in order to re-create this device. + * + * Attempts to load the OlmAccount from the crypto store, or creates one if none is + * found. + * + * Reads the device keys from the OlmAccount object. + * + * @param fromExportedDevice - (Optional) data from exported device + * that must be re-created. + * If present, opts.pickleKey is ignored + * (exported data already provides a pickle key) + * @param pickleKey - (Optional) pickle key to set instead of default one + */ + init({ pickleKey, fromExportedDevice }?: IInitOpts): Promise<void>; + /** + * Populates the crypto store using data that was exported from an existing device. + * Note that for now only the “account” and “sessions” stores are populated; + * Other stores will be as with a new device. + * + * @param exportedData - Data exported from another device + * through the “export” method. + * @param account - an olm account to initialize + */ + private initialiseFromExportedDevice; + private initialiseAccount; + /** + * extract our OlmAccount from the crypto store and call the given function + * with the account object + * The `account` object is usable only within the callback passed to this + * function and will be freed as soon the callback returns. It is *not* + * usable for the rest of the lifetime of the transaction. + * This function requires a live transaction object from cryptoStore.doTxn() + * and therefore may only be called in a doTxn() callback. + * + * @param txn - Opaque transaction object from cryptoStore.doTxn() + * @internal + */ + private getAccount; + private storeAccount; + /** + * Export data for re-creating the Olm device later. + * TODO export data other than just account and (P2P) sessions. + * + * @returns The exported data + */ + export(): Promise<IExportedDevice>; + /** + * extract an OlmSession from the session store and call the given function + * The session is usable only within the callback passed to this + * function and will be freed as soon the callback returns. It is *not* + * usable for the rest of the lifetime of the transaction. + * + * @param txn - Opaque transaction object from cryptoStore.doTxn() + * @internal + */ + private getSession; + /** + * Creates a session object from a session pickle and executes the given + * function with it. The session object is destroyed once the function + * returns. + * + * @internal + */ + private unpickleSession; + /** + * store our OlmSession in the session store + * + * @param sessionInfo - `{session: OlmSession, lastReceivedMessageTs: int}` + * @param txn - Opaque transaction object from cryptoStore.doTxn() + * @internal + */ + private saveSession; + /** + * get an OlmUtility and call the given function + * + * @returns result of func + * @internal + */ + private getUtility; + /** + * Signs a message with the ed25519 key for this account. + * + * @param message - message to be signed + * @returns base64-encoded signature + */ + sign(message: string): Promise<string>; + /** + * Get the current (unused, unpublished) one-time keys for this account. + * + * @returns one time keys; an object with the single property + * <tt>curve25519</tt>, which is itself an object mapping key id to Curve25519 + * key. + */ + getOneTimeKeys(): Promise<OneTimeKeys>; + /** + * Get the maximum number of one-time keys we can store. + * + * @returns number of keys + */ + maxNumberOfOneTimeKeys(): number; + /** + * Marks all of the one-time keys as published. + */ + markKeysAsPublished(): Promise<void>; + /** + * Generate some new one-time keys + * + * @param numKeys - number of keys to generate + * @returns Resolved once the account is saved back having generated the keys + */ + generateOneTimeKeys(numKeys: number): Promise<void>; + /** + * Generate a new fallback keys + * + * @returns Resolved once the account is saved back having generated the key + */ + generateFallbackKey(): Promise<void>; + getFallbackKey(): Promise<Record<string, Record<string, string>>>; + forgetOldFallbackKey(): Promise<void>; + /** + * Generate a new outbound session + * + * The new session will be stored in the cryptoStore. + * + * @param theirIdentityKey - remote user's Curve25519 identity key + * @param theirOneTimeKey - remote user's one-time Curve25519 key + * @returns sessionId for the outbound session. + */ + createOutboundSession(theirIdentityKey: string, theirOneTimeKey: string): Promise<string>; + /** + * Generate a new inbound session, given an incoming message + * + * @param theirDeviceIdentityKey - remote user's Curve25519 identity key + * @param messageType - messageType field from the received message (must be 0) + * @param ciphertext - base64-encoded body from the received message + * + * @returns decrypted payload, and + * session id of new session + * + * @throws Error if the received message was not valid (for instance, it didn't use a valid one-time key). + */ + createInboundSession(theirDeviceIdentityKey: string, messageType: number, ciphertext: string): Promise<IInboundSession>; + /** + * Get a list of known session IDs for the given device + * + * @param theirDeviceIdentityKey - Curve25519 identity key for the + * remote device + * @returns a list of known session ids for the device + */ + getSessionIdsForDevice(theirDeviceIdentityKey: string): Promise<string[]>; + /** + * Get the right olm session id for encrypting messages to the given identity key + * + * @param theirDeviceIdentityKey - Curve25519 identity key for the + * remote device + * @param nowait - Don't wait for an in-progress session to complete. + * This should only be set to true of the calling function is the function + * that marked the session as being in-progress. + * @param log - A possibly customised log + * @returns session id, or null if no established session + */ + getSessionIdForDevice(theirDeviceIdentityKey: string, nowait?: boolean, log?: PrefixedLogger): Promise<string | null>; + /** + * Get information on the active Olm sessions for a device. + * <p> + * Returns an array, with an entry for each active session. The first entry in + * the result will be the one used for outgoing messages. Each entry contains + * the keys 'hasReceivedMessage' (true if the session has received an incoming + * message and is therefore past the pre-key stage), and 'sessionId'. + * + * @param deviceIdentityKey - Curve25519 identity key for the device + * @param nowait - Don't wait for an in-progress session to complete. + * This should only be set to true of the calling function is the function + * that marked the session as being in-progress. + * @param log - A possibly customised log + */ + getSessionInfoForDevice(deviceIdentityKey: string, nowait?: boolean, log?: PrefixedLogger): Promise<{ + sessionId: string; + lastReceivedMessageTs: number; + hasReceivedMessage: boolean; + }[]>; + /** + * Encrypt an outgoing message using an existing session + * + * @param theirDeviceIdentityKey - Curve25519 identity key for the + * remote device + * @param sessionId - the id of the active session + * @param payloadString - payload to be encrypted and sent + * + * @returns ciphertext + */ + encryptMessage(theirDeviceIdentityKey: string, sessionId: string, payloadString: string): Promise<IMessage>; + /** + * Decrypt an incoming message using an existing session + * + * @param theirDeviceIdentityKey - Curve25519 identity key for the + * remote device + * @param sessionId - the id of the active session + * @param messageType - messageType field from the received message + * @param ciphertext - base64-encoded body from the received message + * + * @returns decrypted payload. + */ + decryptMessage(theirDeviceIdentityKey: string, sessionId: string, messageType: number, ciphertext: string): Promise<string>; + /** + * Determine if an incoming messages is a prekey message matching an existing session + * + * @param theirDeviceIdentityKey - Curve25519 identity key for the + * remote device + * @param sessionId - the id of the active session + * @param messageType - messageType field from the received message + * @param ciphertext - base64-encoded body from the received message + * + * @returns true if the received message is a prekey message which matches + * the given session. + */ + matchesSession(theirDeviceIdentityKey: string, sessionId: string, messageType: number, ciphertext: string): Promise<boolean>; + recordSessionProblem(deviceKey: string, type: string, fixed: boolean): Promise<void>; + sessionMayHaveProblems(deviceKey: string, timestamp: number): Promise<IProblem | null>; + filterOutNotifiedErrorDevices(devices: IOlmDevice[]): Promise<IOlmDevice[]>; + /** + * store an OutboundGroupSession in outboundGroupSessionStore + * + * @internal + */ + private saveOutboundGroupSession; + /** + * extract an OutboundGroupSession from outboundGroupSessionStore and call the + * given function + * + * @returns result of func + * @internal + */ + private getOutboundGroupSession; + /** + * Generate a new outbound group session + * + * @returns sessionId for the outbound session. + */ + createOutboundGroupSession(): string; + /** + * Encrypt an outgoing message with an outbound group session + * + * @param sessionId - the id of the outboundgroupsession + * @param payloadString - payload to be encrypted and sent + * + * @returns ciphertext + */ + encryptGroupMessage(sessionId: string, payloadString: string): string; + /** + * Get the session keys for an outbound group session + * + * @param sessionId - the id of the outbound group session + * + * @returns current chain index, and + * base64-encoded secret key. + */ + getOutboundGroupSessionKey(sessionId: string): IOutboundGroupSessionKey; + /** + * Unpickle a session from a sessionData object and invoke the given function. + * The session is valid only until func returns. + * + * @param sessionData - Object describing the session. + * @param func - Invoked with the unpickled session + * @returns result of func + */ + private unpickleInboundGroupSession; + /** + * extract an InboundGroupSession from the crypto store and call the given function + * + * @param roomId - The room ID to extract the session for, or null to fetch + * sessions for any room. + * @param txn - Opaque transaction object from cryptoStore.doTxn() + * @param func - function to call. + * + * @internal + */ + private getInboundGroupSession; + /** + * Add an inbound group session to the session store + * + * @param roomId - room in which this session will be used + * @param senderKey - base64-encoded curve25519 key of the sender + * @param forwardingCurve25519KeyChain - Devices involved in forwarding + * this session to us. + * @param sessionId - session identifier + * @param sessionKey - base64-encoded secret key + * @param keysClaimed - Other keys the sender claims. + * @param exportFormat - true if the megolm keys are in export format + * (ie, they lack an ed25519 signature) + * @param extraSessionData - any other data to be include with the session + */ + addInboundGroupSession(roomId: string, senderKey: string, forwardingCurve25519KeyChain: string[], sessionId: string, sessionKey: string, keysClaimed: Record<string, string>, exportFormat: boolean, extraSessionData?: OlmGroupSessionExtraData): Promise<void>; + /** + * Record in the data store why an inbound group session was withheld. + * + * @param roomId - room that the session belongs to + * @param senderKey - base64-encoded curve25519 key of the sender + * @param sessionId - session identifier + * @param code - reason code + * @param reason - human-readable version of `code` + */ + addInboundGroupSessionWithheld(roomId: string, senderKey: string, sessionId: string, code: string, reason: string): Promise<void>; + /** + * Decrypt a received message with an inbound group session + * + * @param roomId - room in which the message was received + * @param senderKey - base64-encoded curve25519 key of the sender + * @param sessionId - session identifier + * @param body - base64-encoded body of the encrypted message + * @param eventId - ID of the event being decrypted + * @param timestamp - timestamp of the event being decrypted + * + * @returns null if the sessionId is unknown + */ + decryptGroupMessage(roomId: string, senderKey: string, sessionId: string, body: string, eventId: string, timestamp: number): Promise<IDecryptedGroupMessage | null>; + /** + * Determine if we have the keys for a given megolm session + * + * @param roomId - room in which the message was received + * @param senderKey - base64-encoded curve25519 key of the sender + * @param sessionId - session identifier + * + * @returns true if we have the keys to this session + */ + hasInboundSessionKeys(roomId: string, senderKey: string, sessionId: string): Promise<boolean>; + /** + * Extract the keys to a given megolm session, for sharing + * + * @param roomId - room in which the message was received + * @param senderKey - base64-encoded curve25519 key of the sender + * @param sessionId - session identifier + * @param chainIndex - The chain index at which to export the session. + * If omitted, export at the first index we know about. + * + * @returns + * details of the session key. The key is a base64-encoded megolm key in + * export format. + * + * @throws Error If the given chain index could not be obtained from the known + * index (ie. the given chain index is before the first we have). + */ + getInboundGroupSessionKey(roomId: string, senderKey: string, sessionId: string, chainIndex?: number): Promise<IInboundGroupSessionKey | null>; + /** + * Export an inbound group session + * + * @param senderKey - base64-encoded curve25519 key of the sender + * @param sessionId - session identifier + * @param sessionData - The session object from the store + * @returns exported session data + */ + exportInboundGroupSession(senderKey: string, sessionId: string, sessionData: InboundGroupSessionData): IMegolmSessionData; + getSharedHistoryInboundGroupSessions(roomId: string): Promise<[senderKey: string, sessionId: string][]>; + /** + * Verify an ed25519 signature. + * + * @param key - ed25519 key + * @param message - message which was signed + * @param signature - base64-encoded signature to be checked + * + * @throws Error if there is a problem with the verification. If the key was + * too small then the message will be "OLM.INVALID_BASE64". If the signature + * was invalid then the message will be "OLM.BAD_MESSAGE_MAC". + */ + verifySignature(key: string, message: string, signature: string): void; +} +export declare const WITHHELD_MESSAGES: Record<string, string>; +export {}; +//# sourceMappingURL=OlmDevice.d.ts.map
\ No newline at end of file |