CoreCryptoContextProtocol

public protocol CoreCryptoContextProtocol : AnyObject, Sendable

The CoreCryptoContext holds the primary CoreCrypto APIs.

An instance of this struct is provided to the closure passed to CoreCryptoFfi::transaction.

Every mutable operation is done through this struct. Operations are buffered in memory and persisted to the keystore when the transaction completes.

  • Adds members to the conversation using their key packages, sending the resulting commit via the transport.

    Declaration

    Swift

    func addClientsToConversation(conversationId: ConversationId, keyPackages: [Keypackage]) async throws

  • Adds a Credential to this client.

    Note that while an arbitrary number of credentials can be generated, those which are added to a CoreCrypto instance must be distinct in credential type, signature scheme, and the timestamp of creation. This timestamp has only 1 second of resolution, limiting the number of credentials which can be added. This is a known limitation and will be relaxed in the future.

    Declaration

    Swift

    func addCredential(credential: Credential) async throws -> CredentialRef

  • Commits all pending proposals in the conversation, sending the resulting commit via the transport.

    Declaration

    Swift

    func commitPendingProposals(conversationId: ConversationId) async throws

  • Returns the ciphersuite in use for the given conversation.

    Declaration

    Swift

    func conversationCiphersuite(conversationId: ConversationId) async throws -> Ciphersuite

  • Get the credential ref for the given conversation.

    Declaration

    Swift

    func conversationCredential(conversationId: ConversationId) async throws -> CredentialRef

  • Returns the current MLS epoch of the given conversation.

    Declaration

    Swift

    func conversationEpoch(conversationId: ConversationId) async throws -> UInt64

  • Returns true if a conversation with the given id exists in the local state.

    Declaration

    Swift

    func conversationExists(conversationId: ConversationId) async throws -> Bool

  • Creates a new MLS group with the given conversation ID, using the specified credential.

    Declaration

    Swift

    func createConversation(conversationId: ConversationId, credentialRef: CredentialRef, externalSender: ExternalSenderKey?) async throws

  • Decrypts an MLS message received in the given conversation.

    Declaration

    Swift

    func decryptMessage(conversationId: ConversationId, payload: Data) async throws -> DecryptedMessage

  • Disables history sharing for the given conversation.

    Declaration

    Swift

    func disableHistorySharing(conversationId: ConversationId) async throws

  • Returns the end-to-end identity verification state of the given conversation.

    Declaration

    Swift

    func e2eiConversationState(conversationId: ConversationId) async throws -> E2eiConversationState

  • Returns true if end-to-end identity is enabled for the given ciphersuite.

    Declaration

    Swift

    func e2eiIsEnabled(ciphersuite: Ciphersuite) async throws -> Bool
  • e2eiIsPkiEnvSetup() Asynchronous

    Returns true if the PKI environment has been set up.

    Declaration

    Swift

    func e2eiIsPkiEnvSetup() async -> Bool

  • Enables history sharing for the given conversation.

    Declaration

    Swift

    func enableHistorySharing(conversationId: ConversationId) async throws

  • Encrypts a plaintext message for all members of the given conversation.

    Declaration

    Swift

    func encryptMessage(conversationId: ConversationId, message: Data) async throws -> Data

  • Derives and exports a secret of key_length bytes for the given conversation.

    The secret is derived from the MLS key schedule’s exporter mechanism (RFC 9420 §8.5), which produces output bound to the current group state and epoch. The exported value changes whenever the epoch advances.

    Declaration

    Swift

    func exportSecretKey(conversationId: ConversationId, keyLength: UInt32) async throws -> SecretKey

  • Get all credentials from this client which match the provided parameters.

    Parameters which are unset or None match anything. Those with a particular value find only credentials matching that value.

    Declaration

    Swift

    func findCredentials(clientId: ClientId?, publicKey: Data?, ciphersuite: Ciphersuite?, credentialType: CredentialType?, earliestValidity: UInt64?) async throws -> [CredentialRef]

  • Generate a KeyPackage from the referenced credential.

    Makes no attempt to look up or prune existing keypackages.

    If lifetime is set, the keypackages will expire that span into the future. If it is unset, a default lifetime of approximately 3 months is used.

    Declaration

    Swift

    func generateKeypackage(credentialRef: CredentialRef, lifetime: TimeInterval?) async throws -> Keypackage

  • Returns the client ids of all members of the given conversation.

    Declaration

    Swift

    func getClientIds(conversationId: ConversationId) async throws -> [ClientId]
  • getCredentials() Asynchronous

    Get all credentials from this client.

    Declaration

    Swift

    func getCredentials() async throws -> [CredentialRef]
  • getData() Asynchronous

    Returns data previously stored by set_data, or None if no data has been stored.

    Declaration

    Swift

    func getData() async throws -> Data?

  • Returns the E2EI identity claims for the specified devices in the given conversation.

    Declaration

    Swift

    func getDeviceIdentities(conversationId: ConversationId, deviceIds: [ClientId]) async throws -> [WireIdentity]

  • Returns the serialized public key of the external sender for the given conversation.

    Declaration

    Swift

    func getExternalSender(conversationId: ConversationId) async throws -> ExternalSenderKey
  • getKeypackages() Asynchronous

    Get a reference to each KeyPackage in the database.

    Declaration

    Swift

    func getKeypackages() async throws -> [KeypackageRef]

  • Returns the E2EI identity claims for the specified users in the given conversation, grouped by user ID.

    Declaration

    Swift

    func getUserIdentities(conversationId: ConversationId, userIds: [String]) async throws -> [String : [WireIdentity]]

  • Joins an existing conversation by constructing an external commit from the given group info.

    Declaration

    Swift

    func joinByExternalCommit(groupInfo: GroupInfo, credentialRef: CredentialRef) async throws -> ConversationId

  • Initializes the MLS client with the given client ID and message transport.

    Declaration

    Swift

    func mlsInit(clientId: ClientId, transport: MlsTransport) async throws

  • Joins a conversation by processing an MLS Welcome message, returning the new conversation’s ID.

    Declaration

    Swift

    func processWelcomeMessage(welcomeMessage: Welcome) async throws -> ConversationId

  • Decrypts a Proteus ciphertext in the given session, returning the plaintext.

    Declaration

    Swift

    func proteusDecrypt(sessionId: String, ciphertext: Data) async throws -> Data

  • Decrypt a message whether or not the proteus session already exists, and saves the session.

    This is intended to replace simple usages of proteusDecrypt.

    However, when decrypting large numbers of messages in a single session, the existing methods may be more efficient.

    Declaration

    Swift

    func proteusDecryptSafe(sessionId: String, ciphertext: Data) async throws -> Data

  • Encrypts a plaintext message in the given Proteus session.

    Declaration

    Swift

    func proteusEncrypt(sessionId: String, plaintext: Data) async throws -> Data

  • Encrypts a plaintext message in multiple Proteus sessions, returning a map from session ID to ciphertext.

    Declaration

    Swift

    func proteusEncryptBatched(sessions: [String], plaintext: Data) async throws -> [String : Data]
  • proteusFingerprint() Asynchronous

    Returns the hex-encoded public key fingerprint of this device’s Proteus identity.

    Declaration

    Swift

    func proteusFingerprint() async throws -> String

  • Returns the hex-encoded local public key fingerprint for the Proteus session with the given ID.

    Declaration

    Swift

    func proteusFingerprintLocal(sessionId: String) async throws -> String

  • Returns the hex-encoded remote public key fingerprint for the Proteus session with the given ID.

    Declaration

    Swift

    func proteusFingerprintRemote(sessionId: String) async throws -> String
  • proteusInit() Asynchronous

    Initializes the Proteus client.

    Declaration

    Swift

    func proteusInit() async throws

  • Returns the CBOR-serialized last resort prekey bundle, creating it if it does not yet exist.

    Declaration

    Swift

    func proteusLastResortPrekey() async throws -> Data

  • Creates a new Proteus prekey with the given ID and returns its CBOR-serialized bundle.

    Warning: the Proteus client must be initialized with proteus_init first or an error will be returned.

    Declaration

    Swift

    func proteusNewPrekey(prekeyId: UInt16) async throws -> Data
  • proteusNewPrekeyAuto() Asynchronous

    Creates a new Proteus prekey with an automatically assigned ID and returns its CBOR-serialized bundle.

    Warning: the Proteus client must be initialized with proteus_init first or an error will be returned.

    Declaration

    Swift

    func proteusNewPrekeyAuto() async throws -> ProteusAutoPrekeyBundle

  • Reloads all Proteus sessions from the keystore into memory.

    Declaration

    Swift

    func proteusReloadSessions() async throws

  • Deletes the Proteus session with the given ID from local storage.

    Declaration

    Swift

    func proteusSessionDelete(sessionId: String) async throws

  • Returns true if a Proteus session with the given ID exists in local storage.

    Declaration

    Swift

    func proteusSessionExists(sessionId: String) async throws -> Bool

  • Creates a new Proteus session from an incoming encrypted message, returning the decrypted message payload.

    Declaration

    Swift

    func proteusSessionFromMessage(sessionId: String, envelope: Data) async throws -> Data

  • Creates a new Proteus session from the given prekey bundle bytes, stored under the given session ID.

    Declaration

    Swift

    func proteusSessionFromPrekey(sessionId: String, prekey: Data) async throws

  • Saves the Proteus session with the given ID to the keystore.

    Note: this is not usually needed, as sessions are persisted automatically when decrypting or encrypting messages and when initializing sessions.

    Declaration

    Swift

    func proteusSessionSave(sessionId: String) async throws
  • randomBytes(len:) Asynchronous

    Generates len random bytes from the cryptographically secure RNG.

    Declaration

    Swift

    func randomBytes(len: UInt32) async throws -> Data

  • Removes the specified clients from the conversation, sending the resulting commit via the transport.

    Declaration

    Swift

    func removeClientsFromConversation(conversationId: ConversationId, clients: [ClientId]) async throws

  • Removes a Credential from this client.

    Declaration

    Swift

    func removeCredential(credentialRef: CredentialRef) async throws

  • Remove a KeyPackage from the database.

    Declaration

    Swift

    func removeKeypackage(kpRef: KeypackageRef) async throws

  • Remove all KeyPackages associated with this credential ref.

    Declaration

    Swift

    func removeKeypackagesFor(credentialRef: CredentialRef) async throws

  • Set the credential ref for the given conversation.

    Declaration

    Swift

    func setConversationCredential(conversationId: ConversationId, credentialRef: CredentialRef) async throws
  • setData(data:) Asynchronous

    Stores arbitrary data to be used as a transaction checkpoint.

    The stored data can be retrieved via get_data. Keep the data size reasonable; this is not a general-purpose key-value store.

    Declaration

    Swift

    func setData(data: Data) async throws

  • Updates this client’s key material in the conversation by sending an update commit.

    Declaration

    Swift

    func updateKeyingMaterial(conversationId: ConversationId) async throws

  • Destroys the local state of the given conversation; it can no longer be used locally after this call.

    Declaration

    Swift

    func wipeConversation(conversationId: ConversationId) async throws