ksecuremessage-core-protocol/dev.kreienbuehl.ksecuremessage.protocol/LastDeviceRecovery

LastDeviceRecovery

Last-device recovery, format version 1 (docs/last-device-recovery.md). Recovery statement:

u32 length | target userId (UTF-8) | u32 length | target deviceId (UTF-8)
recovery public key (32)
challenge ID (16)
challenge nonce (32)
expected authentication epoch: i64 (>= 1)
challenge expiry: i64, epoch milliseconds
replacement public key (32)

Each construction prefixes u32 length | domain (UTF-8):

recovery authorization, Ed25519 by the recovery key: KSecureMessage-LastDeviceRecovery-v1;
proof of possession, Ed25519 by the replacement key: KSecureMessage-LastDeviceRecovery-PoP-v1;
LastDeviceRecoveryId, SHA-256: KSecureMessage-LastDeviceRecoveryId-v1.

The key registration's proof of possession signs u32 length | KSecureMessage-LastDeviceRecoveryKey-PoP-v1 | u32 length | userId (UTF-8) | recovery public key (32).

Integers are big-endian. No domain is shared with server request authentication, device recovery or routine rotation.

Properties

CHALLENGE_LIFETIME

val CHALLENGE_LIFETIME: Duration

How long a server-issued challenge is valid: issuedAt + CHALLENGE_LIFETIME = expiresAt.

PUBLIC_KEY_SIZE

const val PUBLIC_KEY_SIZE: Int

Size of a recovery or replacement public key (Ed25519).

SIGNATURE_SIZE

const val SIGNATURE_SIZE: Int

Size of a signature (Ed25519).

Functions

authorizationInput

fun authorizationInput(statement: LastDeviceRecoveryStatement): ByteArray

The bytes the recovery key signs.

authorize

fun authorize(recoveryKey: LastDeviceRecoveryKey, replacement: DeviceAuthenticationKeyPair, challenge: LastDeviceRecoveryChallenge): LastDeviceRecoveryAuthorization

The recovery of challenge's target to replacement, signed by recoveryKey and by replacement. Throws IllegalArgumentException if both keys are the same.

keyRegistrationInput

fun keyRegistrationInput(userId: UserId, publicKey: ByteArray): ByteArray

The bytes the recovery key signs when it is registered for userId.

proofOfPossessionInput

fun proofOfPossessionInput(statement: LastDeviceRecoveryStatement): ByteArray

The bytes the replacement key signs.

recoveryId

fun recoveryId(statement: LastDeviceRecoveryStatement): LastDeviceRecoveryId

The ID of statement.

registerKey

fun registerKey(key: LastDeviceRecoveryKey, userId: UserId): LastDeviceRecoveryKeyRegistration

The registration of key for userId, with the key's proof of possession.

verifyKeyRegistration

fun verifyKeyRegistration(registration: LastDeviceRecoveryKeyRegistration): Boolean

true if registration's proof of possession verifies with its public key.

verifyProofOfPossession

fun verifyProofOfPossession(authorization: LastDeviceRecoveryAuthorization): Boolean

true if the proof of possession verifies with the statement's replacement key.

verifyRecoverySignature

fun verifyRecoverySignature(recoveryPublicKey: ByteArray, authorization: LastDeviceRecoveryAuthorization): Boolean

true if authorization's recovery signature verifies with recoveryPublicKey. The server passes the user's registered recovery key. Does not check the proof of possession.