Skip to content

Commit 28b9811

Browse files
bfoss765claude
andcommitted
docs(kotlin-sdk): clarify opensUnderNonGatedDeviceBoundSibling's "prompt-free" scope
Addresses suggestion 3408c9d1d301 on #4060. The KDoc said the DEVICE_BOUND sibling alias "never gates", which overstated it: a lock-bound DEVICE_BOUND key still carries setUnlockedDeviceRequired, so a decrypt probe run while the device is CURRENTLY LOCKED throws UserNotAuthenticatedException (a GeneralSecurityException) and the catch returns false. "Prompt-free" was only ever about the absence of a biometric prompt (no setUserAuthenticationRequired). Clarified that the currently-locked case returns false ("cannot disprove") is the conservative direction — the caller reports the blob decryptable rather than falsely offering repair, deferring the disproof to the next unlock (the same residual already documented for the locked FORMER-RSA path) — and that the key-health sheet runs in-app on an unlocked device where the probe is live. Doc only; no behavior change. :sdk compiles clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 82c682c commit 28b9811

1 file changed

Lines changed: 15 additions & 3 deletions

File tree

  • packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/security/KeystoreManager.kt

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -234,9 +234,21 @@ open class KeystoreManager(
234234

235235
/**
236236
* Whether [blob] opens under the non-auth-gated [KEYS_ALIAS_DEVICE_BOUND]
237-
* sibling — probed PROMPT-FREE (that alias never gates) and WITHOUT
238-
* generating a key (guarded on [hasIdentityKeysKey] presence; recovered
239-
* plaintext is scrubbed immediately).
237+
* sibling — probed PROMPT-FREE and WITHOUT generating a key (guarded on
238+
* [hasIdentityKeysKey] presence; recovered plaintext is scrubbed
239+
* immediately). "Prompt-free" means it never shows a biometric prompt: the
240+
* DEVICE_BOUND alias carries no `setUserAuthenticationRequired` gate, so a
241+
* positive result never blocks on user authentication. It is NOT
242+
* unconditional, though — a lock-bound DEVICE_BOUND key still has
243+
* `setUnlockedDeviceRequired`, so if this probe runs while the device is
244+
* CURRENTLY LOCKED the decrypt throws `UserNotAuthenticatedException` (a
245+
* [GeneralSecurityException] subclass), which the catch below treats as
246+
* "cannot disprove" and returns false. That is the conservative direction:
247+
* the caller ([WalletStorage.isPrivateKeyDecryptable]) then reports the blob
248+
* decryptable rather than falsely offering repair, and the disproof simply
249+
* defers to the next unlock (the same residual as the locked FORMER-RSA case
250+
* documented below). In practice the key-health sheet runs in-app on an
251+
* unlocked device, where the probe is live.
240252
*
241253
* An RSA-OAEP ciphertext opens under exactly one keypair, so a positive
242254
* result PROVES the blob belongs to the DEVICE_BOUND sibling rather than to

0 commit comments

Comments
 (0)