Skip to content

secure-hardware.md

Latest commit

 

History

History
104 lines (76 loc) · 5.13 KB

secure-hardware.md

File metadata and controls

104 lines (76 loc) · 5.13 KB
Raw

Secure hardware (Android)

SecureHardware.getStatus() · check id secureHardware

This is a capability report, not a threat detection. There is no adversary here and nothing is hiding. detected means a weakness indicator fired — the platform offers less protection than an application handling sensitive material would want.

The reverse matters just as much. A device having a hardware-backed keystore says nothing about whether this application uses it, or uses it correctly. secure means the hardware is available. It does not mean your data is safe.

1. What it detects

  • whether keys generated by this application are backed by secure hardware;
  • whether StrongBox — a dedicated secure element rather than a TEE — is present;
  • whether hardware-backed key attestation is available.

2. Why a key is generated

RNSEC-RUNTIME-HARDWARE-001 does not read a capability flag. It generates a throwaway EC key in the Android Keystore, inspects the resulting KeyInfo, and deletes it.

Capability flags describe what a device has. Only generating a key tells you what your keys will actually get, which is the question an application is really asking. The alias is unique per call and deletion runs in a finally block, so no probe key is ever left in the user's keystore.

KeyInfo.getSecurityLevel() is used from API 31; below that the deprecated isInsideSecureHardware() is the only thing available.

3. Signals

ID Indicator Confidence
RNSEC-RUNTIME-HARDWARE-001 Keys are software-backed rather than hardware-backed high
RNSEC-RUNTIME-HARDWARE-002 StrongBox is not available low
RNSEC-RUNTIME-HARDWARE-003 Hardware-backed key attestation is not available (API 31+) medium

HARDWARE-002 is low deliberately: most Android devices have no StrongBox, and its absence is entirely ordinary. It matters only to applications that specifically require that tier, and it must never drive a verdict on its own.

unknown is not trusted-environment

From API 31 the platform can report SECURITY_LEVEL_UNKNOWN_SECURE: backed by something secure that it will not name. That is reported as indeterminate, not as hardware-backed. Rounding it up would be exactly the kind of small overstatement that makes a security report untrustworthy.

4. Confidence

Result Meaning
secure + high Keys are hardware-backed, StrongBox present, attestation available.
detected + high Keys are software-backed. Genuinely worth designing around.
detected + low Only StrongBox is missing. Normal for most devices.
unknown + low A capability could not be determined.

5. False positives

  • Emulators and some virtualised images report software-backed keys, correctly. That is a fact about the environment, not a fault in the app.
  • HARDWARE-002 fires on the large majority of real devices. If your policy treats it as a problem, you will block most of your users. Treat it as informational unless you know you need StrongBox.

6. False negatives

  • A compromised device can lie. Everything here is a claim the device makes about itself, and key attestation — verified server-side — is the only thing that turns those claims into evidence. That is why HARDWARE-003 exists: it tells you whether such evidence is obtainable at all.

7. Known limitations

  • The check reports platform capability. It cannot see whether your application stores its secrets in the Keystore, in SharedPreferences, or in a plain file — and a hardware-backed keystore next to a plaintext token file is not a secure application.
  • Key attestation itself is not performed here. HARDWARE-003 reports availability; performing and verifying an attestation requires a server and belongs in an application's own flow.

8. Recommended application response

const hardware = await SecureHardware.getStatus();

const softwareBackedKeys = hardware.signals.some(
  (signal) => signal.id === 'RNSEC-RUNTIME-HARDWARE-001' && signal.detected
);

if (softwareBackedKeys) {
  // Reasonable: keep less material on the device, shorten token lifetimes,
  // require server-side re-authentication more often.
}

Inspect the individual signal rather than the check status when you care about one capability — HARDWARE-002 firing on a perfectly good phone should not be read as "this device is weak".

9. Tests

android/src/test/java/com/rnsecurity/detectors/hardware/SecureHardwareDetectorsTest.kt — 11 cases covering hardware-backed, software-backed and StrongBox-backed keys, an unnamed security level reporting indeterminate rather than trusted, an unusable keystore, and the API-level gate on attestation.