Skip to content
/ pangolin Public

The Secret Pangolin Code, Fastest Proximity Tracing in the West (FPTW)

License

Notifications You must be signed in to change notification settings

dyne/pangolin

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

20 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Pangolin

The Secret Pangolin Code
Fastest Proximity Tracing in the West (FPTW)

Dyne.org





This is a library implementing "proximity tracing" protocols for privacy-preserving contact tracing.

The Secret Pangolin Code has the ambition to run at blazing fast speeds while being easy to maintain and fully compliant with FIPS.

This code is the Fastest Proximity Tracing in the West, until proven wrong of course! and developed with the embedded first mindset.

At this moment the first and only protocol implemented is DP3T

Pangolin is crafted with care by developers of the DECODE project about data-ownership and technological sovereignty. Our effort is that of improving people's awareness of how their data is processed by algorithms, as well facilitate the work of developers to create along privacy by design principles using algorithms that can be deployed in any situation without any change.

๐Ÿšฉ Table of Contents (click to expand)

๐Ÿ’พ Install

Simply run the default target of Makefile

make

๐ŸŽฎ Quick start

To see Pangolin in action your best move is to run the tests like

make check

๐Ÿ API

Look a the header file to see the current API, more documentation will come soon.

Functions:

void renew_key(sk_t dest, sk_t src);

int32_t generate_beacons(beacons_t *beacons, uint32_t max_beacons,
                         const sk_t oldest_sk, const uint32_t day, const uint32_t ttl,
                         const char *bk, uint32_t bklen);

int32_t match_positive(matches_t *matches, uint32_t max_matches,
                       const sk_t positive, const contacts_t *contacts);
					   

Data structures:

// simple offset structure of num elements sized EPHID_LEN bytes
typedef struct {
	uint32_t epochs;           //< data length (capacity) provided by caller
	char     broadcast[32];   //< broadcast key
	uint32_t broadcast_len;  //< broadcast key length
	beacon_t ephids[0];    //< data offset provided by caller
} beacons_t;

typedef struct __attribute__((packed)) {
	uint8_t day;
	uint8_t epoch;
	uint8_t rssi;
	uint8_t reserved;
	uint8_t data[16];
} contact_t;

typedef struct {
	uint32_t count;             //< number of ephids stored
	contact_t *ephids;         //< array of ephids
	uint32_t epochs;          //< how many epochs in a day
	char     broadcast[32];  //< broadcast key
	uint32_t broadcast_len; //< broadcast key length
} contacts_t; // always const

// struct filled with match_positive results, it does not use more
// memory but returns pointers to contact_t data passed in from
// contacts_t
typedef struct {
	uint32_t count;           //< number of ephids stored
	contact_t *ephids[0];     //< array of pointers to contacts found
} matches_t;

๐Ÿ“‹ Testing

Running the test with

make check

will test the build against DP3T vectors published here.

To ease the maintainance, production and comparison of test vectors one can also use our other software Zenroom which also includes a DP3T implemetation in Zencode


๐Ÿ› Troubleshooting & debugging

Nothing to report as per now

If you find any problem or suspicious behaviours please open an issue


๐Ÿ˜ Acknowledgements

Copyright ยฉ 2020 by Dyne.org foundation, Amsterdam.

The Secret Pangolin Code is licensed as AGPLv3; we are open to grant license exceptions for specific needs.

Designed, written and maintained by Daniele Lacamera & Denis "Jaromil" Roio.

with contributions by Puria Nafisi Azizi.

This software relies on the awesome wolfSSL/wolfCrypt library.

The temporary Icon is made by Freepik from www.flaticon.com

The name of this project is a tribute to the Secret Rabbit Code by Erik de Castro Lopo, a seminal project in the Linux Audio scene.


๐ŸŒ Links

The Secret Pangolin Code is used by:

  • DECODE Proximity HW: our own implementation for NRF52DK, Arduino Nano 33 IoT, Pinetime etc.
  • ESP32-DP3T: third party, beware use of mbedTLS may break FIPS compliancy at the moment

More links:


๐Ÿ‘ฅ Contributing

Please first take a look at the Dyne.org - Contributor License Agreement then

  1. ๐Ÿ”€ FORK IT
  2. Create your feature branch git checkout -b feature/branch
  3. Commit your changes git commit -am 'Add some fooBar'
  4. Push to the branch git push origin feature/branch
  5. Create a new Pull Request
  6. ๐Ÿ™ Thank you

๐Ÿ’ผ Disclaimer

The Secret Pangolin Code, aka the Fastest Proximity Tracing in the West (FPTW)
Copyright (c) 2020 Dyne.org foundation, Amsterdam

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

๐Ÿ” back to top

About

The Secret Pangolin Code, Fastest Proximity Tracing in the West (FPTW)

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published