@wireapp/core-crypto 0.5.2 → 0.6.0-pre.2

package/README.md

@@ -55,9 +55,10 @@ rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim
 
 ### MacOS
 
-Install macOS rust targets (M1 macs are currently not supported)
+Install macOS rust targets
 ```ignore
 rustup target add x86_64-apple-darwin
+rustup target add aarch64-apple-darwin
 ```
 
 ### Linux

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wireapp/core-crypto",
-    "version": "0.5.2",
+    "version": "0.6.0-pre.2",
     "description": "CoreCrypto bindings for the Web",
     "type": "module",
     "module": "platforms/web/corecrypto.js",

package/platforms/web/corecrypto.d.ts

@@ -68,16 +68,6 @@ export declare type ClientId = Uint8Array;
  * Alias for proposal reference. It is a byte array of size 16.
  */
 export declare type ProposalRef = Uint8Array;
-/**
- * Alias for an MLS generic commit.
- * It contains:
- * * MLS Commit that needs to be fanned out to other (existing) members of the conversation
- * * (Optional) MLS Welcome message that needs to be fanned out to the clients newly added to the conversation (if any)
- * * TLS-serialized MLS PublicGroupState (GroupInfo in draft-15) which is required for joining a group by external commit + some metadatas for optimizations
- * (For final version. Requires to be implemented in the Delivery Service)
- * This is a freeform, uninspected buffer.
- */
-export declare type TlsCommitBundle = Uint8Array;
 /**
  * Data shape for the returned MLS commit & welcome message tuple upon adding clients to a conversation
  */
@@ -95,11 +85,11 @@ export interface MemberAddedMessages {
 	 */
 	welcome: Uint8Array;
 	/**
-	 * TLS-serialized MLS PublicGroupState (GroupInfo in draft-15) which is required for joining a group by external commit
+	 * MLS PublicGroupState (GroupInfo in draft-15) which is required for joining a group by external commit
 	 *
 	 * @readonly
 	 */
-	publicGroupState: Uint8Array;
+	publicGroupState: PublicGroupStateBundle;
 }
 /**
  * Data shape for a MLS generic commit + optional bundle (aka stapled commit & welcome)
@@ -118,11 +108,61 @@ export interface CommitBundle {
 	 */
 	welcome?: Uint8Array;
 	/**
-	 * TLS-serialized MLS PublicGroupState (GroupInfo in draft-15) which is required for joining a group by external commit
+	 * MLS PublicGroupState (GroupInfo in draft-15) which is required for joining a group by external commit
 	 *
 	 * @readonly
 	 */
-	publicGroupState: Uint8Array;
+	publicGroupState: PublicGroupStateBundle;
+}
+/**
+ * Wraps a PublicGroupState in order to efficiently upload it to the Delivery Service.
+ * This is not part of MLS protocol but parts might be standardized at some point.
+ */
+export interface PublicGroupStateBundle {
+	/**
+	 * see {@link PublicGroupStateEncryptionType}
+	 */
+	encryptionType: PublicGroupStateEncryptionType;
+	/**
+	 * see {@link RatchetTreeType}
+	 */
+	ratchetTreeType: RatchetTreeType;
+	/**
+	 * TLS-serialized PublicGroupState
+	 */
+	payload: Uint8Array;
+}
+/**
+ * Informs whether the PublicGroupState is confidential
+ * see [core_crypto::mls::conversation::public_group_state::PublicGroupStateEncryptionType]
+ */
+export declare enum PublicGroupStateEncryptionType {
+	/**
+	 * Unencrypted
+	 */
+	Plaintext = 1,
+	/**
+	 * Encrypted in a JWE (not yet implemented)
+	 */
+	JweEncrypted = 2
+}
+/**
+ * Represents different ways of carrying the Ratchet Tree with some optimizations to save some space
+ * see [core_crypto::mls::conversation::public_group_state::RatchetTreeType]
+ */
+export declare enum RatchetTreeType {
+	/**
+	 * Complete PublicGroupState
+	 */
+	Full = 1,
+	/**
+	 * Contains the difference since previous epoch (not yet implemented)
+	 */
+	Delta = 2,
+	/**
+	 * To define (not yet implemented)
+	 */
+	ByRef = 3
 }
 /**
  * Params for CoreCrypto initialization
@@ -166,19 +206,26 @@ export interface Invitee {
 	 */
 	kp: Uint8Array;
 }
-export interface MlsConversationInitMessage {
+export interface ConversationInitBundle {
 	/**
-	 * Group ID
+	 * Conversation ID of the conversation created
 	 *
 	 * @readonly
 	 */
-	group: Uint8Array;
+	conversationId: ConversationId;
 	/**
-	 * TLS-serialized MLS Commit that needs to be fanned out
+	 * TLS-serialized MLS External Commit that needs to be fanned out
 	 *
 	 * @readonly
 	 */
 	commit: Uint8Array;
+	/**
+	 * MLS Public Group State (aka Group Info) which becomes valid when the external commit is accepted by the Delivery Service
+	 * with {@link CoreCrypto.mergePendingGroupFromExternalCommit}
+	 *
+	 * @readonly
+	 */
+	publicGroupState: PublicGroupStateBundle;
 }
 /**
  * This is a wrapper for all the possible outcomes you can get after decrypting a message
@@ -207,6 +254,10 @@ export interface DecryptedMessage {
 	 * Client identifier of the sender of the message being decrypted. Only present for application messages.
 	 */
 	senderClientId?: ClientId;
+	/**
+	 * true when the decrypted message resulted in an epoch change i.e. it was a commit
+	 */
+	hasEpochChanged: boolean;
 }
 /**
  * Returned by all methods creating proposals. Contains a proposal message and an identifier to roll back the proposal
@@ -305,7 +356,7 @@ export interface CoreCryptoCallbacks {
 	 * in the given conversationId. Think of it as a "isAdmin" callback conceptually
 	 *
 	 * This callback exists because there are many business cases where CoreCrypto doesn't have enough knowledge
-	 * (such as what can exists on a backend) to inform the decision
+	 * (such as what can exist on a backend) to inform the decision
 	 *
 	 * @param conversationId - id of the group/conversation
 	 * @param clientId - id of the client performing an operation requiring authorization
@@ -313,10 +364,25 @@ export interface CoreCryptoCallbacks {
 	 */
 	authorize: (conversationId: Uint8Array, clientId: Uint8Array) => boolean;
 	/**
-	 * Callback to ensure that the given `clientId` belongs to one of the provided `otherClients`
+	 * A mix between {@link authorize} and {@link clientIsExistingGroupUser}. We currently use this callback to verify
+	 * external commits to join a group ; in such case, the client has to:
+	 * * first, belong to a user which is already in the MLS group (similar to {@link clientIsExistingGroupUser})
+	 * * then, this user should be authorized to "write" in the given conversation (similar to {@link authorize})
+	 *
+	 * @param conversationId - id of the group/conversation
+	 * @param externalClientId - id of the client performing an operation requiring authorization
+	 * @param existingClients - all the clients currently within the MLS group
+	 * @returns true if the external client is authorized to write to the conversation
+	 */
+	userAuthorize: (conversationId: Uint8Array, externalClientId: Uint8Array, existingClients: Uint8Array[]) => boolean;
+	/**
+	 * Callback to ensure that the given `clientId` belongs to one of the provided `existingClients`
 	 * This basically allows to defer the client ID parsing logic to the caller - because CoreCrypto is oblivious to such things
+	 *
+	 * @param clientId - id of a client
+	 * @param existingClients - all the clients currently within the MLS group
 	 */
-	clientIdBelongsToOneOf: (clientId: Uint8Array, otherClients: Uint8Array[]) => boolean;
+	clientIsExistingGroupUser: (clientId: Uint8Array, existingClients: Uint8Array[]) => boolean;
 }
 /**
  * Wrapper for the WASM-compiled version of CoreCrypto
@@ -515,72 +581,6 @@ export declare class CoreCrypto {
 	 * @returns A {@link CommitBundle} or `undefined` when there was no pending proposal to commit
 	 */
 	commitPendingProposals(conversationId: ConversationId): Promise<CommitBundle | undefined>;
-	/**
-	 * Adds new clients to a conversation, assuming the current client has the right to add new clients to the conversation.
-	 * The returned {@link CommitBundle} is a TLS struct that needs to be fanned out to Delivery Service in order to validate the commit.
-	 * It also contains a Welcome message the Delivery Service will forward to invited clients and
-	 * an updated PublicGroupState required by clients willing to join the group by an external commit.
-	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
-	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
-	 * epoch, use new encryption secrets etc...
-	 *
-	 * @param conversationId - The ID of the conversation
-	 * @param clients - Array of {@link Invitee} (which are Client ID / KeyPackage pairs)
-	 *
-	 * @returns A {@link CommitBundle} byte array to fan out to the Delivery Service
-	 */
-	finalAddClientsToConversation(conversationId: ConversationId, clients: Invitee[]): Promise<TlsCommitBundle>;
-	/**
-	 * Removes the provided clients from a conversation; Assuming those clients exist and the current client is allowed
-	 * to do so, otherwise this operation does nothing.
-	 *
-	 * The returned {@link CommitBundle} is a TLS struct that needs to be fanned out to Delivery Service in order to validate the commit.
-	 * It also contains a Welcome message the Delivery Service will forward to invited clients and
-	 * an updated PublicGroupState required by clients willing to join the group by an external commit.
-	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
-	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
-	 * epoch, use new encryption secrets etc...
-	 *
-	 * @param conversationId - The ID of the conversation
-	 * @param clientIds - Array of Client IDs to remove.
-	 *
-	 * @returns A {@link CommitBundle} byte array to fan out to the Delivery Service, or `undefined` if for any reason, the operation would result in an empty commit
-	 */
-	finalRemoveClientsFromConversation(conversationId: ConversationId, clientIds: ClientId[]): Promise<TlsCommitBundle>;
-	/**
-	 * Creates an update commit which forces every client to update their keypackages in the conversation
-	 *
-	 * The returned {@link CommitBundle} is a TLS struct that needs to be fanned out to Delivery Service in order to validate the commit.
-	 * It also contains a Welcome message the Delivery Service will forward to invited clients and
-	 * an updated PublicGroupState required by clients willing to join the group by an external commit.
-	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
-	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
-	 * epoch, use new encryption secrets etc...
-	 *
-	 * @param conversationId - The ID of the conversation
-	 *
-	 * @returns A {@link CommitBundle} byte array to fan out to the Delivery Service
-	 */
-	finalUpdateKeyingMaterial(conversationId: ConversationId): Promise<TlsCommitBundle>;
-	/**
-	 * Commits the local pending proposals and returns the {@link CommitBundle} object containing what can result from this operation.
-	 *
-	 * The returned {@link CommitBundle} is a TLS struct that needs to be fanned out to Delivery Service in order to validate the commit.
-	 * It also contains a Welcome message the Delivery Service will forward to invited clients and
-	 * an updated PublicGroupState required by clients willing to join the group by an external commit.
-	 *
-	 * **CAUTION**: {@link CoreCrypto.commitAccepted} **HAS TO** be called afterwards **ONLY IF** the Delivery Service responds
-	 * '200 OK' to the {@link CommitBundle} upload. It will "merge" the commit locally i.e. increment the local group
-	 * epoch, use new encryption secrets etc...
-	 *
-	 * @param conversationId - The ID of the conversation
-	 *
-	 * @returns A {@link CommitBundle} byte array to fan out to the Delivery Service or `undefined` when there was no pending proposal to commit
-	 */
-	finalCommitPendingProposals(conversationId: ConversationId): Promise<TlsCommitBundle | undefined>;
 	/**
 	 * Creates a new proposal for the provided Conversation ID
 	 *
@@ -599,23 +599,35 @@ export declare class CoreCrypto {
 	 */
 	exportGroupState(conversationId: ConversationId): Promise<Uint8Array>;
 	/**
-	 * Allows to create an external commit to "apply" to join a group through its public group state
+	 * Allows to create an external commit to "apply" to join a group through its public group state.
 	 *
-	 * Also see the second step of this process: {@link CoreCrypto.mergePendingGroupFromExternalCommit}
+	 * If the Delivery Service accepts the external commit, you have to {@link CoreCrypto.mergePendingGroupFromExternalCommit}
+	 * in order to get back a functional MLS group. On the opposite, if it rejects it, you can either retry by just
+	 * calling again {@link CoreCrypto.joinByExternalCommit}, no need to {@link CoreCrypto.clearPendingGroupFromExternalCommit}.
+	 * If you want to abort the operation (too many retries or the user decided to abort), you can use
+	 * {@link CoreCrypto.clearPendingGroupFromExternalCommit} in order not to bloat the user's storage but nothing
+	 * bad can happen if you forget to except some storage space wasted.
 	 *
-	 * @param publicGroupState - The public group state that can be fetched from the backend for a given conversation
-	 * @returns see {@link MlsConversationInitMessage}
+	 * @param publicGroupState - a TLS encoded PublicGroupState fetched from the Delivery Service
+	 * @returns see {@link ConversationInitBundle}
 	 */
-	joinByExternalCommit(publicGroupState: Uint8Array): Promise<MlsConversationInitMessage>;
+	joinByExternalCommit(publicGroupState: Uint8Array): Promise<ConversationInitBundle>;
 	/**
-	 * This is the second step of the process of joining a group through an external commit
-	 *
-	 * This step makes the group operational and ready to encrypt/decrypt message
+	 * This merges the commit generated by {@link CoreCrypto.joinByExternalCommit}, persists the group permanently
+	 * and deletes the temporary one. This step makes the group operational and ready to encrypt/decrypt message
 	 *
 	 * @param conversationId - The ID of the conversation
 	 * @param configuration - Configuration of the group, see {@link ConversationConfiguration}
 	 */
 	mergePendingGroupFromExternalCommit(conversationId: ConversationId, configuration: ConversationConfiguration): Promise<void>;
+	/**
+	 * In case the external commit generated by {@link CoreCrypto.joinByExternalCommit} is rejected by the Delivery Service, and we
+	 * want to abort this external commit once for all, we can wipe out the pending group from the keystore in order
+	 * not to waste space
+	 *
+	 * @param conversationId - The ID of the conversation
+	 */
+	clearPendingGroupFromExternalCommit(conversationId: ConversationId): Promise<void>;
 	/**
 	 * Allows to mark the latest commit produced as "accepted" and be able to safely merge it
 	 * into the local group state
@@ -646,6 +658,24 @@ export declare class CoreCrypto {
 	 * @param conversationId - The group's ID
 	 */
 	clearPendingCommit(conversationId: ConversationId): Promise<void>;
+	/**
+	 * Derives a new key from the group
+	 *
+	 * @param conversationId - The group's ID
+	 * @param keyLength - the length of the key to be derived. If the value is higher than the
+	 * bounds of `u16` or the context hash * 255, an error will be returned
+	 *
+	 * @returns A `Uint8Array` representing the derived key
+	 */
+	exportSecretKey(conversationId: ConversationId, keyLength: number): Promise<Uint8Array>;
+	/**
+	 * Returns all clients from group's members
+	 *
+	 * @param conversationId - The group's ID
+	 *
+	 * @returns A list of clients from the members of the group
+	 */
+	getClientIds(conversationId: ConversationId): Promise<ClientId[]>;
 	/**
 	 * Allows {@link CoreCrypto} to act as a CSPRNG provider
 	 * @note The underlying CSPRNG algorithm is ChaCha20 and takes in account the external seed provider either at init time or provided with {@link CoreCrypto.reseedRng}
@@ -661,6 +691,82 @@ export declare class CoreCrypto {
 	 * @param seed - **exactly 32** bytes buffer seed
 	 */
 	reseedRng(seed: Uint8Array): Promise<void>;
+	/**
+	 * Initiailizes the proteus client
+	 */
+	proteusInit(): Promise<void>;
+	/**
+	 * Create a Proteus session using a prekey
+	 *
+	 * @param sessionId - ID of the Proteus session
+	 * @param prekey - CBOR-encoded Proteus prekey of the other client
+	 */
+	proteusSessionFromPrekey(sessionId: string, prekey: Uint8Array): Promise<void>;
+	/**
+	 * Create a Proteus session from a handshake message
+	 *
+	 * @param sessionId - ID of the Proteus session
+	 * @param envelope - CBOR-encoded Proteus message
+	 */
+	proteusSessionFromMessage(sessionId: string, envelope: Uint8Array): Promise<void>;
+	/**
+	 * Locally persists a session to the keystore
+	 *
+	 * @param sessionId - ID of the Proteus session
+	 */
+	proteusSessionSave(sessionId: string): Promise<void>;
+	/**
+	 * Deletes a session
+	 * Note: this also deletes the persisted data within the keystore
+	 *
+	 * @param sessionId - ID of the Proteus session
+	 */
+	proteusSessionDelete(sessionId: string): Promise<void>;
+	/**
+	 * Decrypt an incoming message for an existing Proteus session
+	 *
+	 * @param sessionId - ID of the Proteus session
+	 * @param ciphertext - CBOR encoded, encrypted proteus message
+	 * @returns The decrypted payload contained within the message
+	 */
+	proteusDecrypt(sessionId: string, ciphertext: Uint8Array): Promise<Uint8Array>;
+	/**
+	 * Encrypt a message for a given Proteus session
+	 *
+	 * @param sessionId - ID of the Proteus session
+	 * @param plaintext - payload to encrypt
+	 * @returns The CBOR-serialized encrypted message
+	 */
+	proteusEncrypt(sessionId: string, plaintext: Uint8Array): Promise<Uint8Array>;
+	/**
+	 * Batch encryption for proteus messages
+	 * This is used to minimize FFI roundtrips when used in the context of a multi-client session (i.e. conversation)
+	 *
+	 * @param sessions - List of Proteus session IDs to encrypt the message for
+	 * @param plaintext - payload to encrypt
+	 * @returns A map indexed by each session ID and the corresponding CBOR-serialized encrypted message for this session
+	 */
+	proteusEncryptBatched(sessions: string[], plaintext: Uint8Array): Promise<Map<string, Uint8Array>>;
+	/**
+	 * Creates a new prekey with the requested ID.
+	 *
+	 * @param prekeyId - ID of the PreKey to generate. This cannot be bigger than a u16
+	 * @returns: A CBOR-serialized version of the PreKeyBundle corresponding to the newly generated and stored PreKey
+	 */
+	proteusNewPrekey(prekeyId: number): Promise<Uint8Array>;
+	/**
+	 * Proteus public key fingerprint
+	 * It's basically the public key encoded as an hex string
+	 *
+	 * @returns Hex-encoded public key string
+	 */
+	proteusFingerprint(): Promise<string>;
+	/**
+	 * Imports all the data stored by Cryptobox into the CoreCrypto keystore
+	 *
+	 * @param storeName - The name of the IndexedDB store where the data is stored
+	 */
+	proteusCryptoboxMigrate(storeName: string): Promise<void>;
 	/**
 	 * Returns the current version of {@link CoreCrypto}
 	 *