pps-php

Duress Mode

Duress mode allows a user to silently signal coercion.

It uses a hidden duress key.

A Pulse signed by the duress key is called a Honey-Pulse.

---

Duress Key Registration

During registration, the client may register a duress public key.

use Pps\Client\RegistrationBuilder;

$builder = new RegistrationBuilder();
$registration = $builder
    ->rpId('example.com')
    ->nonce($nonceB64u)
    ->userHandle('user-123')
    ->withDuress(true)
    ->build();

The server stores:

current_pk
duress_pk

---

Creating a Duress Pulse

use Pps\Client\AuthenticatorClient;

$client = new AuthenticatorClient($clientState);
$pulse = $client
    ->rpId('example.com')
    ->nonce($nonceB64u)
    ->duress(true)
    ->createPulse();

---

Server Handling

The server verifies the Pulse normally.

If the signing public key matches the stored duress public key:

if ($result->honey) {
    // Return normal-looking response
    echo json_encode(['status' => 'ok']);

    // Internally:
    // - restrict account
    // - block high-value operations
    // - trigger silent alert
    // - delay settlement
}

---

Indistinguishability Requirement

The outward response must be indistinguishable from normal success.

Match:

HTTP status
JSON structure
response latency
cookies
UI navigation

Do not return:

{
    "status": "duress_detected"
}

---

Duress Trigger Mechanisms

Possible triggers:

duress PIN
long press
hidden gesture
alternate phrase selection
special accessibility toggle

The trigger mechanism is client-specific and not defined by the protocol.

---

Security Notes

• Duress keys should be protected separately.
• User safety is more important than asset protection.
• Silent alerts should be handled by trained personnel.
• False positives should be recoverable.

This site is open source. Improve this page.