App Shield

The security chapter covers a lot of ground that ends at the same place: every check runs on the device, and a device the attacker fully controls is a device where every check can be patched out. Root detection returns false. The pinning code is skipped. The jailbreak probe is stubbed. None of it reaches your server, which is where the money is.

App Shield closes that loop. The app obtains a short-lived, Codename One-signed attestation token backed by a server-side verification of Apple’s App Attest and Google’s Play Integrity statements, and your own API refuses to serve a request that doesn’t carry a valid one. The statement that matters is made by a party the attacker doesn’t control, and your backend can check it in about twenty lines of middleware.

This is an Enterprise feature. The public API in com.codename1.security.shield ships in the open-source core and is safe to call in any build — in a build without the attestation engine it degrades to a documented no-op rather than failing — but tokens are only ever minted for entitled accounts.

Three parties are involved: the app, the Codename One attestation service, and your own API. A protected request goes through five steps.

Steps 1 to 4 are the framework’s job and happen on the network thread. Step 5 is automatic for every ConnectionRequest to a host you registered. The decision — what to do about a device the service declined — is yours, and it belongs in step 5, on your server.

Two things have to be true: the account has to be entitled, and the build has to ask for it.

Registration is the whole configuration. A host you don’t register is never touched — no header, no certificate check, no behaviour change of any kind.

HostPolicy is two independent decisions plus what to do when the shield can’t deliver:

Fail-closed is a promise that a request without a valid token never leaves the device, so it applies to the awkward cases too: a protected host reached over plain http is refused rather than handed the bearer token in clear text, and a shield that was interrupted before it finished starting refuses rather than guessing.

If most of your hosts want the same failure mode, set it once and register them the short way:

A pattern may be an exact host or a leading . wildcard covering its subdomains — .example.com matches api.example.com and a.b.example.com, but not the apex example.com and not example.com.somewhere-else.test. The most specific rule wins, so an exact registration is never relaxed by a wildcard.

Backends the app only learns about after it starts — a regional endpoint chosen at login, a tenant-specific host — are registered the same way, with the same matching:

Once init() has run, ConnectionRequest, Rest, RequestBuilder and anything else built on NetworkManager are covered without further code. For a request to a protected host, on the network thread:

The response side is just as narrow: the guard sees the status code and the headers it asked for, which is how a backend tells the app its token was refused as opposed to the user’s credentials.

The default is X-CN1-Attest. It isn’t Authorization, by design: that slot belongs to your own user authentication, and the two answer different questions — who the user is, versus whether this is a genuine unmodified app on an uncompromised device. Your backend needs both, so they have to compose.

ShieldConfig.tokenHeader(String) changes it, and refuses names that can’t carry a token rather than accepting them and failing out of sight later:

The most important distinction in the API is between "the shield couldn’t be reached" and "the shield looked at this device and said no." Reacting to the first the way you react to the second is how an app locks a paying customer out on a train.

ShieldStatus is a constant object rather than an enum on purpose: the vocabulary is visible on the wire and the service must be able to add a status without breaking apps built against an older release. Compare with equals, branch on isSuccess() and isTransient(), and treat an id you don’t recognize as a non-success.

Listeners are delivered on the EDT, so they may touch the UI directly. The framework never shows a dialog and never terminates the app over a shield event — what the user sees is entirely your decision:

For anything the guard doesn’t cover — a third-party HTTP client, a payload you sign yourself, a handshake — ask for the token directly. fetchToken() is asynchronous and returns immediately, including during a cold start:

Pass a binding value to tie the token to one specific request, so a token lifted from it can’t be replayed onto another:

AppShield.attach(ConnectionRequest) does the same work synchronously for a request you are about to send. It blocks on a network round trip, so it must not be called on the EDT:

Token lifetime is measured from a monotonic clock, never from exp against the device clock, because on a rooted device the wall clock is whatever the attacker wants it to be. getCachedToken() returns the current token without any network access, and invalidateToken() discards it so the next request re-attests — which is what to call when your backend tells you the token itself was refused:

Pins are published by the service and refreshed with the token, so rotating a certificate is a console action rather than an app store release. They’re pinned over the subject public key info, so renewing a certificate on the same key pair doesn’t invalidate the pin, and a chain matches if any certificate in it matches any pin for the host — which is what makes it safe to pin an issuing CA as the backup.

Pinning is the one part of the shield that can take an app offline for a reason the developer can’t fix remotely, so the failure behaviour is asymmetric by design:

The framework’s own detections — root, jailbreak, hooking frameworks, emulators, debuggers, repackaging, untrusted accessibility services — are reported to ShieldSignals rather than acted on locally, and ride along with the next token fetch. There is no separate beacon to block and no extra battery cost.

This is a deliberate inversion of the older exit(0) style checks. Terminating the app is trivially patched out, destroys the telemetry that makes the feature useful, and turns a detection into a crash report. The client reports; the service decides. An emulator signal is normal on a developer’s machine; ten high-severity signals from one device in an hour is a device the service can keep flagging on its next clean-looking attestation.

Your own code can report what only it can notice — a server-side consistency check that failed, a sequence of actions no human performs:

The bus is bounded and repeat reports of an id collapse onto the existing entry, so a detector that trips on every frame can’t exhaust memory. An identical repeat refreshes the entry without notifying listeners again; a changed severity or detail is a new observation and is announced.

Coverage matters more here than anywhere else in this chapter, because a gap is invisible at the call site: the code compiles, the request succeeds, and no token was ever attached.

NetworkManager holds exactly one guard and seals the slot after the first one is installed, so an app that needs its own interception has to delegate to the shield’s rather than displace it:

The token is a compact ES256 JWT with typ of cn1-attest+jwt, signed by a key published at /.well-known/cn1-attest-jwks.json and named by the header’s kid. Verification is ordinary JWT verification against a JWKS URL — NimbusJwtDecoder.withJwkSetUri in Spring, jose in Node, PyJWT[crypto] in Python — and the console renders a copy-paste quickstart for each, including a Cloudflare Worker for the zero-code-change case.

Beyond the standard iss, aud, sub, iat, exp and jti, the claims your middleware acts on are:

Roll it out in two stages, and keep the two sides independent. While the service is in monitor mode it mints a token for everyone and marks the ones it would have refused, so you can watch the would-deny rate against real traffic before anything breaks. Your middleware has its own switch: log and pass through, or reject. Move one at a time.

Apple’s model is one attestation, then many assertions: the first token carries a hardware-backed public key and its attestation, and every later token is a small assertion naming the key. The framework manages the key, the state and the retry policy in the keychain, including recovery when iOS invalidates the key — a restore to a new device, or a reinstall — and Apple’s rate limits, which are strict enough that attesting per request gets an app throttled.

The one thing your code has to do is close the loop when the backend has stored the key, because a registration call that was lost leaves the device asserting against a key the server has never seen:

DeviceIntegrity.resetAttestation() throws the key away and starts again, which is the recovery path for a backend that no longer knows the key.

None of this is testable against a real service on a developer’s desktop, so the simulator ships a simulation engine behind Simulate > App Shield. Switching on any item installs it; leaving the menu alone leaves the shield inert.

The simulated token is stamped so it can’t be mistaken for a real one, and the simulator’s engine never contacts the service. A backend that accepts a simulated token is a backend that isn’t verifying signatures.

Every method in this chapter is safe to call in a build without the engine — an open-source build, an unentitled account, the simulator with the menu untouched. The degradation contract is explicit, and it’s the reason you don’t need to guard your call sites: