The short version, for everyone: When an activist goes missing, Kengele can publish an alert the activist wrote in advance: their name, their lawyer, their own words. That alert must never go out because one person panicked, was tricked or was forced. So it only opens when 2 of the activist's 3 trusted contacts agree, and that rule is built into the encryption itself. Every step of the alarm is also stamped into Bitcoin, so a court can later see exactly when it happened. This post shows how, with code you can run.
Kengele (Swahili for "bell") is an open-source alarm for activists in East Africa. The first post in this series covered the deadline engine that decides when a check-in is missed, and the second the 228-byte message that carries every event:
This one covers what happens after an alarm: who can make it public, who can end it, and how we prove when it happened.
altradits / kengele
An alarm for when an activist goes missing. No servers, works through shutdowns. Swahili first.
Kengele
When an activist goes silent, the right people know within minutes, and nobody can switch the alarm off.
Ukinyamaza, kengele inalia. ("If you go quiet, the bell rings.")
Warning
Status: design stage. Not for real use. There is no working app yet. Do not rely on Kengele to protect anyone until an independent security review is complete and published here. People's lives may depend on this tool, so we will not cut corners to ship it sooner.
Why
When an activist disappears, how fast the public finds out often decides how quickly they are freed.
- In Kenya, more than 80 people were abducted or forcibly disappeared after the 2024 protests. In January 2025, abducted young men were released within hours of public outcry.
- Boniface Mwangi and Agather Atuhaire, detained in Tanzania in May 2025, were released after their disappearance became public.
- Governments switch networks off when it…
Kengele is still in design and not for real use until an independent security review is published. All code is at commit e10d277.
Contents
- Escalation in three levels
- Why "if confirmations >= 2" is not enough
- Setup: sealing the alert under a split key
- Binding the kit with associated data
- Confirming: a share on the wire
- Counting: epochs, freshness and duplicates
- A bad share cannot forge or block
- Run it yourself: two of three
- Ending an alarm
- No location trail, enforced
- Proving when: OpenTimestamps
- What is still open
Escalation in three levels
When an activist misses a check-in, presses the panic trigger or uses the duress PIN, the alarm escalates in steps:
| Level | Who knows | What happens |
|---|---|---|
| 1. Private | The guardians | Each guardian's device raises the alarm. They try to reach the activist |
| 2. Public | Everyone | Once k guardians (default 2 of 3) confirm, the alert the activist wrote in advance is published on Nostr |
| 3. Legal | The lawyer | A habeas corpus packet with signed, timestamped evidence is ready |
Level 2 is the dangerous one. A public alert puts pressure on whoever is holding the activist, which is the point. But a false public alert (the activist was just at a funeral with their phone off) burns trust, and a malicious one (a guardian whose phone was seized) could be used to discredit the activist or the tool. So the rule is: nothing about an activist goes public until k guardians confirm the same alarm.
Why "if confirmations >= 2" is not enough
The obvious implementation is a counter in the guardian app:
if confirmations >= 2 { publish(alert) } The problem is where the alert lives. For any guardian's app to publish it, that app must hold the alert text and the key that signs it. So every guardian's phone holds everything needed to publish. Now consider adversary A4 in the threat model: a guardian who is compromised, pressured, or whose phone is seized. Anyone who controls one phone can patch out the if, or just read the alert and the key from storage. The "2 of 3" was a policy in the user interface, not a property of the system.
Kengele makes it a property of the cryptography: with one guardian's data, the alert cannot even be decrypted.
Setup: sealing the alert under a split key
At setup, on the activist's device, confirm.NewKits does four things:
- Generates a random 32-byte key K.
- Encrypts the alert and a separate alert key (the Nostr key that will sign the public note) with XChaCha20-Poly1305 under K.
- Splits K into one share per guardian with Shamir's secret sharing, so that any k shares rebuild K and fewer reveal nothing about it.
- Gives each guardian a kit: the ciphertext, their own share, the guardian list and the threshold. Then wipes K.
k := make([]byte, keySize) if _, err := io.ReadFull(rnd, k); err != nil { return nil, fmt.Errorf("confirm: random key: %w", err) } defer wipe(k) plain, err := json.Marshal(sealed{Alert: alert, AlertKey: hex.EncodeToString(alertKey.Serialize())}) ... defer wipe(plain) aead, err := chacha20poly1305.NewX(k) nonce := make([]byte, aead.NonceSize()) if _, err := io.ReadFull(rnd, nonce); err != nil { ... } ct := aead.Seal(append([]byte(nil), nonce...), nonce, plain, tmpl.associatedData()) shares, err := shamir.Split(k, len(guardians), threshold) A few decisions worth explaining:
Why a separate alert key? The public note must be verifiable by journalists and the public. If it were signed with the activist's own key, anyone who rebuilt K would also hold the activist's identity. So the alert key is different from the activist's key (NewKits refuses if they are equal), and its public half goes on the activist's public profile before any alarm. When an alert appears, anyone can check it was signed by the key the activist published in advance.
Why XChaCha20-Poly1305? It is an AEAD with a 24-byte nonce, which makes random nonces safe without bookkeeping, and the authentication tag means a wrong key fails loudly instead of producing garbage. That second property is what makes the "bad share" defence below work.
Which Shamir? The split uses OpenBao's sdk/v2/helper/shamir, the community fork of the code HashiCorp Vault has used for its unseal keys for years. We use OpenBao rather than hashicorp/vault/shamir because Vault is no longer open source (BUSL since 1.15). Shamir over GF(256) adds one byte (the x coordinate) to each share, so a 32-byte key gives 33-byte shares.
Limits. k must be at least 2 (one guardian alone must never be able to publish) and at most the number of guardians. At most 10 guardians. Guardians must be distinct and must not include the activist.
Binding the kit with associated data
Here is a subtle attack. A guardian holds kits for two activists. Or the same activist re-ran setup with a different guardian list. Could someone mix a ciphertext from one setup with shares or a guardian list from another, and get the app to do something it should not?
The ciphertext's associated data commits to everything else in the kit:
// associatedData binds the ciphertext to everything else in the kit, so a // kit cannot be mixed with another activist's or another guardian set's. func (k GuardianKit) associatedData() []byte { h := sha256.New() h.Write([]byte("kengele/alert-kit/v1")) var b [8]byte binary.BigEndian.PutUint32(b[:4], uint32(k.Version)) binary.BigEndian.PutUint32(b[4:], uint32(k.Threshold)) h.Write(b[:]) h.Write([]byte(k.Activist)) h.Write([]byte(k.AlertPub)) for _, g := range k.Guardians { h.Write([]byte(g)) } return h.Sum(nil) } Change the threshold, the activist, the alert key or any guardian in a kit, and decryption fails even with the right K. TestKitTampering covers it. The associated data costs nothing at runtime and closes a whole class of mix-and-match bugs.
Confirming: a share on the wire
A guardian confirms an alarm by sending a guardian-confirm event whose body carries their share:
| Kind | Body | Size |
|---|---|---|
guardian-confirm | 0x01 · activist key (32) · epoch (4) · share (33) | 70 bytes |
all-clear | 0x02 · activist key (32) · epoch (4) | 37 bytes |
Both fit in the message format's 86-byte body, so they travel in the same fixed-size, signed, encrypted 228-byte message as a check-in. A relay or a telecom cannot tell a guardian confirming a public alarm from an activist saying "I'm fine".
The confirmation goes only to the other guardians, never to the activist:
// Recipients returns the guardians a confirmation must be sealed to: every // guardian except this one. The activist is deliberately not included. func (t *Tally) Recipients() [][32]byte { The activist's phone may already be in the captors' hands. If confirmations went to it, the captors would collect the shares and could open the alert themselves, or learn exactly who the guardians are and how close the alert is to going public.
Counting: epochs, freshness and duplicates
Each guardian's device runs a Tally per watched activist. Every opened event goes through Handle, including the guardian's own confirmation. A confirmation counts only if all of these hold:
func (t *Tally) confirm(e *message.Event, now time.Time) (Outcome, error) { if !t.enr[e.Signer] { return Outcome{}, ErrNotGuardian // the activist cannot confirm their own alarm } c, err := decodeConfirm(e.Body) ... if c.activist != t.p.activist { return Outcome{}, ErrNotActivist } if err := t.checkEpoch(c.epoch); err != nil { return Outcome{}, err // stale, or too far ahead } if t.released == c.epoch { return Outcome{}, ErrAlreadyReleased } if t.spent { return Outcome{}, ErrSpent } if !fresh(e.CreatedAt, now, t.ttl) { return Outcome{}, ErrExpired } st := t.state(c.epoch) if _, ok := st.confirms[e.Signer]; ok { return Outcome{}, ErrDuplicate } st.confirms[e.Signer] = vote{at: e.CreatedAt, share: c.share} return t.tryRelease(c.epoch, now), nil } Each check maps to an attack:
- Enrolled guardians only. The activist cannot confirm their own alarm, because their phone may be controlled by someone else.
- Epochs stop replays. The epoch numbers alarms for one activist: it starts at 1 and goes up each time an alarm ends. A confirmation from last month's alarm can never count towards today's. Confirmations up to 3 epochs ahead are kept (a guardian who missed an all-clear can catch up); anything further is refused, so a misbehaving guardian cannot fill memory.
- Freshness. A confirmation counts for 24 hours by default (
DefaultConfirmTTL) and must not be from the future (beyond the message format's 10-minute skew). An old confirmation must never combine with a new one days later. Confirmations that expire while waiting stop counting. - One vote per guardian per alarm. Sending your confirmation twice does not make 2 of 3.
- One alert per kit. Once released, the kit is "spent": it can sign a "found safe" update but never a second alert. The activist must make a new kit. That prevents a stolen alert key from being used to publish fresh, authentic-looking alerts later.
A bad share cannot forge or block
What if a guardian sends a wrong share, on purpose or because of a bug? With k shares, the tally rebuilds K and tries to open the ciphertext. A wrong share gives a wrong K, and the AEAD tag fails. So a bad share cannot forge a release.
Could it block one? With three guardians, suppose guardian 1 sends garbage and guardians 0 and 2 send good shares. The tally now holds three shares. If it only tried the first two it received, the garbage would block the release. So tryRelease tries every k-sized group until one opens:
// tryRelease rebuilds the alert key from k fresh shares. A bad share from a // misbehaving guardian makes the authenticated decryption fail, so every // k-sized group is tried before giving up and waiting for more. combinations(len(shares), k, func(idx []int) bool { parts := make([][]byte, k) for i, j := range idx { parts[i] = shares[j] } key, err := shamir.Combine(parts) if err != nil { return true } s, priv, err := t.kit.open(key) wipe(key) if err != nil { return true // this group included a bad share: try the next } t.released, t.spent = epoch, true ... return false }) With at most 10 guardians, C(10, k) is at most 252 groups, so trying them all is cheap. The test:
func TestBadShareCannotForgeOrBlock(t *testing.T) { f := newFixture(t, 3, 2) tl := f.tally(t, 0) // Guardian 1 sends a garbage share: no release with only it and one other... bad := message.Event{Kind: message.KindGuardianConfirm, CreatedAt: t0, Body: encodeConfirm(f.activist.pub, 1, make([]byte, shareSize))} bad.Body[len(bad.Body)-1] = 7 o, err := tl.Handle(f.over(t, bad, f.guardians[1].priv, f.guardians[0], tl.Senders(), t0), t0) mustAction(t, o, err, None) o, err = f.confirm(t, tl, 0, 1, t0, t0) mustAction(t, o, err, None) // ...but two honest guardians still release. o, err = f.confirm(t, tl, 2, 1, t0, t0) mustAction(t, o, err, Release) } The honest residual: a bad share delays the release until another honest guardian confirms. With 3 guardians and k = 2, one bad guardian plus one honest one is not enough; that is why the docs recommend picking guardians who do not live, work or get arrested together.
Run it yourself: two of three
This example builds kits for three guardians, shows that an alert containing GPS coordinates is refused, then walks guardian 0's tally through a duplicate confirmation and a real 2-of-3 release. Save it as internal/confirm/blog_example_test.go in a clone:
package confirm import ( "bytes" "fmt" "time" "github.com/altradits/kengele/internal/message" "github.com/btcsuite/btcd/btcec/v2" ) func Example_twoOfThree() { priv := func(b byte) *btcec.PrivateKey { k, _ := btcec.PrivKeyFromBytes(bytes.Repeat([]byte{b}, 32)); return k } activist, alertKey := priv(0xa1), priv(0xa2) // made-up test keys gs := []*btcec.PrivateKey{priv(0xb1), priv(0xb2), priv(0xb3)} var gPubs [][32]byte for _, g := range gs { gPubs = append(gPubs, message.PublicKey(g)) } alert := Alert{Name: "Amina W.", Lawyer: "LSK duty line", Text: "If you read this, I did not check in."} kits, err := NewKits(alert, message.PublicKey(activist), alertKey, gPubs, 2, nil) fmt.Println("kits:", len(kits), "err:", err) _, err =...