Skip to content

Encryption ​

Needs Skapi("<Project ID>", encryption = EncryptionOptions(...)). No extra dependency: it uses the platform's javax.crypto. See Encrypting Private Data. Every method that talks to the server is a suspend function and throws SkapiException.

EncryptionOptions ​

kotlin
public class EncryptionOptions(
    public val iterations: Int = 600000,
    public val trustPolicy: String = "tofu",
    public val withheld: String = "null",
    public val recovery: String = "code",
    public val table: String = "__skapi__keyring",
    public val persistDevice: Boolean = true,
    public val deviceKeyStore: DeviceKeyStore? = null,
)
java
EncryptionOptions encryption = new EncryptionOptionsBuilder()
    .iterations(600000)
    .trustPolicy("tofu")
    .withheld("null")
    .recovery("code")
    .table("__skapi__keyring")
    .persistDevice(true)
    .deviceKeyStore(null)
    .build();  // starts from these defaults: set only the ones you change
propertydefault
iterations600000PBKDF2 rounds for new password wraps; at least 100000
trustPolicy"tofu""strict": only pinned keys are used for sharing
withheld"null""sentinel": undecryptable data is {"__skapi_no_access__": true, "reason": ...}
recovery"code""none": no encryption recovery codes
table"__skapi__keyring"the table that holds keyrings
persistDevicetruekeep the master key in deviceKeyStore (when one is given), so a restored session stays unlocked
deviceKeyStorenullwhere to keep it; on Android, AndroidKeystoreDeviceKeyStore(context) from skapi-android. See Remember this device.

Any other value of trustPolicy, withheld or recovery is read as the default.

codemessage
INVALID_PARAMETER"encryption.iterations" must be at least 100000.

DeviceKeyStore ​

kotlin
public interface DeviceKeyStore {
    public fun save(entry: String, masterKey: ByteArray, keyringRecordId: String)
    public fun load(entry: String): DeviceKey?
    public fun delete(entry: String)
}

public class DeviceKey(public val masterKey: ByteArray, public val keyringRecordId: String)
java
public interface DeviceKeyStore {
    void save(String entry, byte[] masterKey, String keyringRecordId);
    DeviceKey load(String entry);  // or null
    void delete(String entry);
}

public final class DeviceKey {
    public DeviceKey(byte[] masterKey, String keyringRecordId)
    public byte[] getMasterKey()
    public String getKeyringRecordId()
}

A store for the encryption master key: "remember this device". Entries are named "<service>/<owner>#<user_id>". The core library has none on purpose, since a plain file would put the key on disk in the clear; skapi-android provides AndroidKeystoreDeviceKeyStore, which seals it with a key that never leaves the Android Keystore. An exception thrown by save or delete is logged, not passed on.

getEncryptionStatus ​

kotlin
suspend fun getEncryptionStatus(): JsonObject
java
CompletableFuture<Map<String, Object>> getEncryptionStatus()
json
{"status": "disabled"}
{"status": "locked", "reason": "NO_SESSION_KEY" | "OPENID_UNSUPPORTED", "user_id"?: ..., "fingerprint"?: ...}
{"status": "unlocked", "user_id": "...", "fingerprint": "..."}

fingerprint is the user's own public key fingerprint, for others to pin. A session restored from storage is first unlocked from the device key store, when there is one.

unlockEncryption ​

kotlin
suspend fun unlockEncryption(password: String): JsonObject
java
CompletableFuture<Map<String, Object>> unlockEncryption(String password)

Opens the keyring with the password. Returns {"status": "unlocked"}. It never sets encryption up: that happens at the first login with the password, so an account that has never logged in with its password gets NOT_EXISTS. With a device key store, the key is kept there too.

codemessage
INVALID_REQUESTEncryption is not enabled for this instance.
INVALID_REQUESTUser login is required.
INVALID_PARAMETER"password" is required.
NOT_EXISTSEncryption has not been set up for this account yet. It is set up at the first login with the password: log in with the password to start using it.
ENCRYPTION_BAD_PASSWORDIncorrect password: the encryption keyring could not be opened.
ENCRYPTION_KEYRING_CORRUPTThe encryption keyring does not belong to this user. / The keyring has no password wrap.
ENCRYPTION_LOCKEDEncryption could not be unlocked: <reason>

lockEncryption ​

kotlin
suspend fun lockEncryption(forgetDevice: Boolean = false): JsonObject
java
CompletableFuture<Map<String, Object>> lockEncryption(boolean forgetDevice)
// also lockEncryption()

Forgets the keys in memory. Returns {"status": "locked"}, or {"status": "disabled"}. An encryption recovery code not collected yet is kept: the next getConnectionInfo() still returns it, once.

argument
forgetDevicetrue also removes the key kept by the DeviceKeyStore, so the next restored session stays locked until unlockEncryption. Left false, the stored key stays and the next restored session unlocks again.

logout forgets the keys and removes the stored key as well.

isWithheld ​

kotlin
fun isWithheld(value: JsonElement?): Boolean
java
boolean isWithheld(Object value)  // a plain Java value, such as a record's "data"

true for the "sentinel" placeholder of undecryptable data. Not a suspend function.

Encryption recovery code ​

Shown once, in getConnectionInfo as "encryption_recovery", after the first password login with encryption on. See Encryption recovery codes.

unlockEncryptionWithRecoveryCode ​

kotlin
suspend fun unlockEncryptionWithRecoveryCode(code: String, password: String? = null): JsonObject
java
CompletableFuture<Map<String, Object>> unlockEncryptionWithRecoveryCode(String code, String password)
// also unlockEncryptionWithRecoveryCode(code)

Unlocks encryption with the saved encryption recovery code, for a user signed in after a password reset. With password, the keyring opens with that password from now on. The code is replaced by a new one.

json
{"status": "unlocked", "repaired": <boolean>, "encryptionRecoveryCode": "<new code>" | null}
codemessage
INVALID_REQUESTEncryption is not enabled for this instance.
INVALID_REQUESTUser login is required. Reset the password and log in first, then use the encryption recovery code.
INVALID_PARAMETER"code" is required.
NOT_EXISTSThis account has no encryption keyring, so there is nothing to recover.
ENCRYPTION_BAD_RECOVERY_CODEThat does not look like an encryption recovery code: expected 28 characters, got <n>. / ... "<c>" is not a valid character. / That encryption recovery code has a typo in it: the check characters do not match. / That encryption recovery code did not open the keyring. ...

regenerateEncryptionRecoveryCode ​

kotlin
suspend fun regenerateEncryptionRecoveryCode(): JsonObject
java
CompletableFuture<Map<String, Object>> regenerateEncryptionRecoveryCode()

A new encryption recovery code, {"encryptionRecoveryCode": "..."}; the old one stops working. Needs encryption unlocked.

codemessage
INVALID_REQUESTEncryption is not enabled for this instance.
ENCRYPTION_LOCKEDEncryption must be unlocked to issue an encryption recovery code. ...
INVALID_REQUESTEncryption recovery codes are turned off for this instance ("encryption.recovery" is "none").

pinPeerKey ​

kotlin
suspend fun pinPeerKey(userId: String, fingerprint: String): Unit
java
CompletableFuture<Void> pinPeerKey(String userId, String fingerprint)  // completes with null

Trusts fingerprint as userId's key for sharing, saved in the keyring. Throws ENCRYPTION_LOCKED (Encryption is locked.) when not unlocked.

Errors from other methods ​

With encryption on, these can come from postRecord, postRecords, getFile (and the other download methods), grantPrivateRecordAccess, removePrivateRecordAccess and changePassword:

codewhen
ENCRYPTION_LOCKEDwriting a private record, changing the password, or opening an encrypted file while locked
ENCRYPTION_NOT_RECORD_OWNERwriting another user's encrypted record
ENCRYPTION_CANNOT_REWRITE_WITHHELDwriting back a withheld placeholder
ENCRYPTED_DATA_TOO_LARGEthe encrypted data is over 2 MB
ENCRYPTION_GRANT_REQUIRES_OWNERsharing or removing access on a record you do not own
ENCRYPTION_RECIPIENT_HAS_NO_KEYthe user never signed in with encryption on
ENCRYPTION_PEER_KEY_CHANGED / ENCRYPTION_PEER_NOT_PINNEDsee Sharing
ENCRYPTION_DATA_UNAVAILABLEthe record's data could not be read while changing its sharing
ENCRYPTION_FILE_CORRUPT / ENCRYPTION_FILE_STALE_KEYan encrypted file does not open with the record's key
INVALID_PARAMETER"__skapi_enc__" is a reserved key in record data. / "__skenc__" is reserved in an upload form key.

skapi-kotlin 2.4.1