ksecuremessage-client-core/dev.kreienbuehl.ksecuremessage.client

Package-level declarations

Types

enum AbandonStatus : Enum<AbandonStatus>

What SecureMessageClient.abandonPendingMessage did (docs/outbound-message-lifecycle.md). Abandoning is local: nothing is sent, and it is not a recall.

CommitResult

class CommitResult(val sender: DeviceAddress, val id: LogicalMessageId, val status: CommitStatus, val ackSent: Boolean)

Result of SecureMessageClient.commitReceivedMessage. ackSent is false if the acknowledgement could not be sent; the commit stands, and the sender's next retry of the message triggers a new acknowledgement.

CommitStatus

enum CommitStatus : Enum<CommitStatus>

What SecureMessageClient.commitReceivedMessage did.

DeviceAuthenticationHealth

sealed interface DeviceAuthenticationHealth

The state of this device's server authentication credentials, as classified by SecureMessageClient.deviceAuthenticationHealth (docs/device-authentication-health.md). A read-only composition of the local device authentication key slots and, only when they do not decide, the signed registration status: factual states only, no severity and no recommendation. The application decides what to show and what to do.

DeviceAuthenticationHealthInconsistency

enum DeviceAuthenticationHealthInconsistency : Enum<DeviceAuthenticationHealthInconsistency>

Why DeviceAuthenticationHealth.Inconsistent was returned. Carries no key material.

DeviceAuthenticationRecoveryKind

enum DeviceAuthenticationRecoveryKind : Enum<DeviceAuthenticationRecoveryKind>

Which recovery DeviceAuthenticationHealth.RecoveryPending reports.

DeviceAuthenticationRotationDecision

sealed interface DeviceAuthenticationRotationDecision

Result of SecureMessageClient.evaluateDeviceAuthenticationRotation. Evaluation never rotates.

DeviceAuthenticationRotationPolicy

class DeviceAuthenticationRotationPolicy(val maxKeyAge: Duration)

An application's policy for routine device authentication key rotation (docs/device-authentication-rotation.md): rotate once the registered key is at least maxKeyAge old. The library has no default policy and never applies one on its own; the application passes it to SecureMessageClient.evaluateDeviceAuthenticationRotation or SecureMessageClient.rotateDeviceAuthenticationKeyIfNeeded when it chooses.

DeviceAuthenticationRotationResult

sealed interface DeviceAuthenticationRotationResult

Result of SecureMessageClient.rotateDeviceAuthenticationKeyIfNeeded.

DeviceAuthenticationRotationStatus

data class DeviceAuthenticationRotationStatus(val authEpoch: Long, val authKeyInstalledAt: Instant, val evaluatedAt: Instant, val pendingRotation: Boolean, val pendingRecovery: Boolean)

This device's server authentication state, for display, logging and policy decisions. Contains no key material.

DiscardResult

class DiscardResult(val sender: DeviceAddress, val id: LogicalMessageId, val status: DiscardStatus, val ackSent: Boolean)

Result of SecureMessageClient.discardReceivedMessage. ackSent is false if the acknowledgement could not be sent; the discard stands, and the sender's next retry of the message triggers a new acknowledgement.

DiscardStatus

enum DiscardStatus : Enum<DiscardStatus>

What SecureMessageClient.discardReceivedMessage did.

LastDeviceRecoveryKeyResetCancellationResult

sealed interface LastDeviceRecoveryKeyResetCancellationResult

The outcome of a recovery key reset cancellation (docs/recovery-key-reset.md).

LastDeviceRecoveryKeyResetResult

enum LastDeviceRecoveryKeyResetResult : Enum<LastDeviceRecoveryKeyResetResult>

A successful SecureMessageClient.completeLastDeviceRecoveryKeyReset (docs/recovery-key-reset.md).

LastDeviceRecoveryKeyRevocationResult

enum LastDeviceRecoveryKeyRevocationResult : Enum<LastDeviceRecoveryKeyRevocationResult>

A successful SecureMessageClient.revokeLastDeviceRecoveryKey (docs/recovery-key-lifecycle.md).

LastDeviceRecoveryKeyRotationResult

enum LastDeviceRecoveryKeyRotationResult : Enum<LastDeviceRecoveryKeyRotationResult>

A successful SecureMessageClient.rotateLastDeviceRecoveryKey (docs/recovery-key-lifecycle.md).

PendingMessage

class PendingMessage(val recipient: DeviceAddress, val id: LogicalMessageId, val sequence: Long, val plaintext: ByteArray)

A sent message that recipient has not acknowledged yet (docs/outbound-message-lifecycle.md). plaintext is a copy.

PendingMessagePage

class PendingMessagePage(val messages: List<PendingMessage>, val nextAfterSequence: Long?)

One page of SecureMessageClient.pendingMessages (docs/outbound-message-lifecycle.md): messages in ascending PendingMessage.sequence order.

PendingReceivedMessagePage

class PendingReceivedMessagePage(val messages: List<ReceivedMessage>, val nextAfterSequence: Long?)

One page of SecureMessageClient.pendingReceivedMessages (docs/message-discard.md): messages in ascending ReceivedMessage.sequence order.

PreKeyConfiguration

data class PreKeyConfiguration(val oneTimePreKeyTarget: Int = 100, val signedPreKeyRotationAge: Duration = 7.days, val signedPreKeyGracePeriod: Duration = 30.days)

Local prekey inventory and signed prekey lifecycle settings, see docs/signed-prekey-lifecycle.md.

ProcessedInboundRetentionPolicy

class ProcessedInboundRetentionPolicy(val maxAge: Duration)

How long finalized (committed or discarded) message IDs are kept for duplicate suppression (docs/application-delivery.md). Applied only by SecureMessageClient.pruneProcessedMessages; there is no default.

ReceivedMessage

class ReceivedMessage(val sender: DeviceAddress, val id: LogicalMessageId, val sequence: Long, val receivedAt: Instant, val plaintext: ByteArray)

A received application message that waits for the application's decision (docs/application-delivery.md, docs/message-discard.md). It is delivered again, by SecureMessageClient.decrypt and SecureMessageClient.pendingReceivedMessages, until the application finalizes it with SecureMessageClient.commitReceivedMessage or SecureMessageClient.discardReceivedMessage.

ReceiveResult

sealed interface ReceiveResult

Outcome of SecureMessageClient.decrypt (docs/message-reliability.md, docs/application-delivery.md).

RecoveryKeyResetAwareness

sealed interface RecoveryKeyResetAwareness

Whether a recovery key reset is pending for this user, as classified by SecureMessageClient.recoveryKeyResetAwareness (docs/recovery-key-reset.md, "Reset awareness"). A read-only composition of the signed recovery key status and the signed reset status: factual states only, no severity and no recommendation. The application decides what to show and what to do.

RecoveryKeyResetAwarenessInconsistency

enum RecoveryKeyResetAwarenessInconsistency : Enum<RecoveryKeyResetAwarenessInconsistency>

Why RecoveryKeyResetAwareness.Inconsistent was returned. Carries no key material.

RemoteIdentityChange

class RemoteIdentityChange

A change of remote's identity from previousIdentityKey (pinned) to presentedIdentityKey, as reported by SecureMessageClientException.IdentityChanged. Accepting it (SecureMessageClient.acceptRemoteIdentityChange) installs exactly presentedIdentityKey, and only while previousIdentityKey is still pinned. Only the client creates changes, so an application can accept only a key that a peer actually presented.

RemoteIdentityTrust

class RemoteIdentityTrust(val address: DeviceAddress, val identityKey: PublicIdentityKey, val verification: VerificationState)

The trust state of one remote device (docs/identity-verification.md): the identity key pinned on first use or by an accepted change, and whether the user verified exactly that key. Pinning and verification are separate: a pin is always present here, verification only after the user compared the safety number.

SecureMessageClient

class SecureMessageClient(val localAddress: DeviceAddress, storage: ClientStorage, protocol: ProtocolEngine, transport: SecureMessageTransport, preKeyConfiguration: PreKeyConfiguration = PreKeyConfiguration(), clock: Clock = Clock.System)

Sends and receives messages for localAddress. Envelope payloads are CiphertextMessageCodec-encoded ciphertext messages; their plaintext is a SecurePayloadCodec reliability frame.

SecureMessageClientException

sealed class SecureMessageClientException : Exception

Lifecycle and local-state failures of SecureMessageClient. Messages never contain key material.

SecureMessageTransport

interface SecureMessageTransport

Network boundary of SecureMessageClient. Implementations report server rejections as SecureMessageTransportException.

SecureMessageTransportException

sealed class SecureMessageTransportException : Exception

Server rejections reported by a SecureMessageTransport. Messages never contain key material.

SentMessage

class SentMessage(val id: LogicalMessageId, val envelope: EncryptedEnvelope)

Result of SecureMessageClient.send: the logical message and the envelope of its first attempt. Retries use new envelopes with the same id.

ServerRequestSigner

fun interface ServerRequestSigner

Signs a device-scoped server request with the local device authentication key. Every call uses the current time and a fresh nonce, so a request sent again must be signed again. Never sees or returns private key bytes.