For easy, trackable, standardized warrant canaries.


CanaryTail was developed to standardize criteria in warrant canaries as a means of simplifying the process of creating, distributing, monitoring, and administrating warrant canaries.

░  Warrant canary 

"Warrant canary" is a colloquial term for a regularly published statement that a service provider has not received legal process that it would be prohibited from saying it had received, such as a National Security Letter (NSL).

░  The Problem 

Warrant canaries introduce several issues as have been witnessed from organizations that employed or maintained them improperly. This standard seeks to resolve those issues through a proper standardized model of generation, administration, and distribution, with variance allowed only inside the boundaries of a defined protocol. Those issues are:

  • ▖    Confusion attributed to non-standardized language 
  • ▞    Loss of access leading to misinterpretation 
  • ▘    Imperfect generation, maintenance, and distribution 
  • ▙    Inability to automate the monitoring 
  • ▚    Reliance on centralized generation and maintenance 
  • ▛    Reliance on centralized distribution  


To resolve these issues, CanaryTail standardizes the very language of the canaries themselves through codification, whereas one can construct a human and machine readable warrant canary that can be programmatically verified. To consider what language should be standardized, we need to first define the purpose of the canary and under what conditions it is considered as failed.

In general, canaries are designed to fail when:

  • ▖    Warrants have been issued for searching, seizing, or monitoring data 
  • ▞    NSLs, gag orders, or other court orders have been given to hide, conceal, or otherwise withhold information from the public 
  • ▘    Backdoors have been planted to spy on and trap users 
  • ▙    Raids have been conducted on hardware and operating premises 
  • ▚    Integrity of access keys and leadership of a company is no longer sound or trustworthy 

In the case of gag orders, some make it unlawful to reveal the exact number of occurrences of requests for data for example, but do allow for an organization to reveal a broad range (e.g. “anywhere from 0 to 1,000”). This combined with a general statement that there has never been a request, one may deduce whether or not a request has in fact been made, and to a certain degree, how many times.

░  Codification 

Codes used in the canary are loosely named after their threat and response category:

gagGag orders
trapTrap and trace orders
ceaseCourt order to cease operations
duressCoercion, blackmail, or otherwise operating under duress
raidRaids with high confidence nothing containing useful data was seized
seizeRaids with low confidence nothing containing useful data was seized
xcredCompromised credentials
xopersCompromised operations

░  Trust levels 

Construction of the canary is done as JSON array with multiple options for verification based on trust needs.

▖ LOWThe canary can be authenticated to the original source by providing the DOMAIN it will be served at. This is a less secure method of authenticity as anyone with publishing access to the domain can modify the canary.
▞ MEDIUMAuthentication of the canary is done via ECDSA (​ Curve25519 ​) cryptographic signature of the JSON array by the public key provided inside as the variable ​PUBKEY​.
▘HIGHThe ECDSA (​ Curve25519 ​) ​PUBKEY​ can be a split-key created by n-of-p in order to ensure multiple parties consent to updates of the canary.