{"id":18841930,"url":"https://github.com/diskuv/dirsp-exchange","last_synced_at":"2026-01-30T15:30:13.826Z","repository":{"id":114369053,"uuid":"372114817","full_name":"diskuv/dirsp-exchange","owner":"diskuv","description":"Provide software engineers with auditable source code that has some level of safety assurance (typically proofs) from security researchers.","archived":false,"fork":false,"pushed_at":"2023-02-16T18:00:14.000Z","size":6099,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-30T10:50:43.706Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://diskuv.github.io/dirsp-exchange/index.html","language":"Standard ML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diskuv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-30T03:29:04.000Z","updated_at":"2023-08-21T11:27:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"1e2730fb-9d0e-4f4b-b305-75eaf107eee1","html_url":"https://github.com/diskuv/dirsp-exchange","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fdirsp-exchange","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fdirsp-exchange/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fdirsp-exchange/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fdirsp-exchange/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diskuv","download_url":"https://codeload.github.com/diskuv/dirsp-exchange/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239780120,"owners_count":19695734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T02:53:04.470Z","updated_at":"2026-01-30T15:30:13.757Z","avatar_url":"https://github.com/diskuv.png","language":"Standard ML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dirsp-exchange\n\n\"dirsp\" is a short form for Diskuv Implementations of Research Security Protocols.\n\nThe first protocol we've included is \"KBB2017\" which is what the authors (security researchers) call a variant of\n[Signal Protocol v3](https://www.signal.org/docs/specifications/x3dh/).\nWe love it because it has been formally verified using two complementary proof checking tools. With the programming language OCaml\nand `dirsp-exchange` you could write secure code like:\n\n```ocaml\nmodule P       = Dirsp_proscript_mirage.Make()\nmodule ED25519 = P.Crypto.ED25519\nmodule K       = Dirsp_exchange_kbb2017.Make(P)\nmodule U       = K.UTIL\n\n(* Alice sends a message to Bob *)\nlet aliceSessionWithBob = T.newSession (* ... supply some keys you create with ED25519 and U ... *) ;;\nlet aliceToBobSendOutput = T.send\n  aliceIdentityKey\n  aliceSessionWithBob\n  (P.of_string \"Hi Bob!\")\n\n(* Now you can send the output \"aliceToBobSendOutput\" from Alice to Bob.\n   Let's switch to Bob's computer. He gets notified of a new message using a notification library of your choosing, and then does ...  *)\n\nlet bobSessionWithAlice = T.newSession (* ... supply some keys ... *);;\nlet bobFromAliceReceiveOutput = T.recv\n  bobIdentityKey\n  bobSignedPreKey\n  bobSessionWithAlice\n  theEncryptedMessageBobReceivedFromAlice\nassert (bobFromAliceReceiveOutput.output.valid)\nFormat.printf \"Bob just received a new message: %s\\n\"\n  (bobFromAliceReceiveOutput.plaintext |\u003e P.to_bytes |\u003e Bytes.to_string)\n```\n\nBindings to other languages and implementations of other security algorithms may follow\nlater.\n\n\u003e Looking for other implementations? Skip down to [Comparison to Other Libraries](#comparison-to-other-libraries)\n\nThe intent of the **[dirsp]** libraries is to provide software engineers with auditable\nsource code that has some level of safety assurance (typically proofs) from security researchers.\nBy \"auditable\" we mean the ability to justify every line of source code when undergoing an audit\nby a competent security engineer. No third-party vetting of the source code has been\nconducted (unless noted explicitly), and the original authors at Diskuv did not have security\nresearchers or engineers on staff when the libraries were originally written.\nContact [security@diskuv.com](mailto:security@diskuv.com) to report any security issues, and feel\nfree to publicly shame the [Twitter handle @diskuv](https://twitter.com/diskuv) if Diskuv is not being\nresponsive.\n\nThe implementations in this library are licensed permissively to broaden use and scrutiny. Sometimes\nthat means writing an implementation from scratch based only on an academic paper.\nIn contrast, placing security primitives like KBB2017 under restrictive licenses (ex. GPL and especially AGPL)\ndiscourages scrutiny because many security engineers work for\ncompanies which discourage or [prohibit](https://opensource.google/docs/using/agpl-policy/)\nrestrictive licenses. Note this lessened scrutiny is\nparticular to _low level security libraries_ that are restrictively licensed; even the original author of these libraries\nwill use copy-left licenses for other types of libraries and applications.\n\n## Programming Languages\n\nTLDR: We don't expect you to run your code in OCaml. Embed it in your host language instead.\n\nMost of the **[dirsp]** libraries are based in the programming language OCaml. Among other things OCaml is commonly used to\nwrite domain-specific languages for proof analysis. [Coq](https://coq.inria.fr/about-coq) is one example of a\nwell-known DSL for developing proofs.\n\nProScript is another DSL. It is a restricted JavaScript language meant to be easily accessible to software engineers,\nexecuted in production yet formally verifiable. The design fits well with the software engineering intent\nof **[dirsp]**. The only soft spot is that the ProScript execution model is JavaScript which (at least for the authors of\n**[dirsp]**) is not an ideal production language! So we built a tool `dirsp-ps2ocaml` to translate algorithms written\nin ProScript into OCaml.\n\nLet's be clear ... we don't think OCaml is an ideal production language for many people either; we suspect many teams will\nfind the OCaml ecosystem to be too small. But we think there is a navigable path compared to JavaScript for OCaml to be embedded\nin several host languages (Java, Objective-C, JavaScript, etc.) and able to run logic (security and privacy algorithms) on many\ndifferent host platforms (desktop, server, mobile, etc.).\n\n## Libraries\n\nThis repository contains:\n\n- [dirsp-exchange-kbb2017](https://diskuv.github.io/dirsp-exchange/ocaml/dirsp-exchange-kbb2017/) - The KBB2017 protocol for securing a two-party conversation. Similar to\n  Signal Protocol v3 [[1]](https://signal.org/docs/specifications/x3dh) [[2]](https://signal.org/docs/specifications/doubleratchet)\n  and Olm [[3]](https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/olm.md)\n- [dirsp-proscript](https://diskuv.github.io/dirsp-exchange/ocaml/dirsp-proscript/) - The ProScript Cryptographic Library (PSCL) API interface\n- [dirsp-proscript-mirage](https://diskuv.github.io/dirsp-exchange/ocaml/dirsp-proscript-mirage/) - A PSCL implementation based on `mirage-crypto` and related libraries\n- [dirsp-ps2ocaml](https://diskuv.github.io/dirsp-exchange/ocaml/dirsp-ps2ocaml/) - A ProScript to OCaml translator with [documentation available](https://diskuv.github.io/dirsp-exchange/src-proscript/proscript-messaging/PS2OCAML.html).\n\n`dirsp-exchange-kbb2017` has a build process that generates its own OCaml code\nusing `dirsp-ps2ocaml` on formally verified ProScript source code.\n\nThe online documentation is at:\n\n- [Sphinx Documentation](https://diskuv.github.io/dirsp-exchange)\n- [OCaml Libraries](https://diskuv.github.io/dirsp-exchange/ocaml)\n\n## Installation\n\nMake sure you have `opam` installed. If you don't have OCaml and `opam`, it is probably\nbest to follow the [Real World OCaml Installation Instructions](https://dev.realworldocaml.org/install.html).\n\nYou'll install the executables (currently only `dirsp-ps2ocaml`) as follows:\n\n```bash\nopam update\nopam install dirsp-ps2ocaml\neval $(opam env)\n\ndirsp-ps2ocaml --help\n```\n\nThe libraries are also available on Opam:\n\n```bash\nopam update\nopam install dirsp-exchange-kbb2017 dirsp-proscript-mirage\n```\n\nNote: Installing with [esy](https://esy.sh/) likely works as well, but hasn't been tested.\n\n## Comparison to Other Libraries\n\n| Library                                                                                                                                                                | Lineage                                              | Language. Bindings                                     | License                           | Papers                                                                                                                                                                          | Usage                                                                                                                        |\n| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| [dirsp-exchange-kbb2017](https://diskuv.github.io/dirsp-exchange/ocaml/dirsp-exchange-kbb2017/)                                                                        | [Cryptocat](https://en.wikipedia.org/wiki/Cryptocat) | OCaml                                                  | Apache v2                         | [Automated Verification for Secure Messaging Protocols and Their Implementations: A Symbolic and Computational Approach](https://ieeexplore.ieee.org/abstract/document/7961995) | Original code formally verified. **[dirsp]** has not been audited                                                            |\n| [libsignal-client (modern)](https://github.com/signalapp/libsignal-client), [libsignal-protocol-java (inactive)](https://github.com/signalapp/libsignal-protocol-java) | [Signal](https://www.signal.org/download/)           | Rust. Java, Swift, and TypeScript                      | AGPLv3 (modern). GPLv3 (inactive) | [Signal Specifications](https://signal.org/docs/)                                                                                                                               | Well-known cryptographers. [\"Use outside of Signal is unsupported.\"](https://github.com/signalapp/libsignal-client#overview) |\n| [libolm](https://gitlab.matrix.org/matrix-org/olm)                                                                                                                     | [Matrix](https://matrix.org/)                        | C++ 11. JavaScript, Python, Android Java, Objective-C. | Apache v2                         | [Olm: A Cryptographic Ratchet](https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/olm.md)                                                                              | Audited in 2016. [Actively being re-analysed](https://matrix.org/blog/2021/06/14/adventures-in-fuzzing-libolm)               |\n\nOur recommendation for secure 1-on-1 messaging?\n\n- Prefer **[libolm]** over **[dirsp-exchange-kbb2017]** unless you need to go beyond what **[libolm]** offers.\n  In other words, use **[dirsp-exchange-kbb2017]** if you need to extend an algorithm in ProScript _or_ need to adopt new published research (please contribute it here if you do!)\n- Don't use **[libsignal-client]** because its owners actively discourage you from using it today. But since\n  we suspect their stance is based on a lack of engineering resources rather than their [donation-based mission of developing open source privacy technology](https://www.signal.org/donate/), you may want to directly ask them.\n\n## Next Steps\n\n### Getting/Staying in Touch\n\n- Announcements will be on [Twitter: @diskuv](https://twitter.com/diskuv). Q\u0026A is fine!\n- Use GitHub to \"Watch\" this repository (the top right corner of your browser)\n- Disclose security vulnerabilities at security@diskuv.com\n- Report bugs at [dirsp-exchange Issues](https://github.com/diskuv/dirsp-exchange/issues)\n\n### Contributing\n\n**Engineers**: We are actively looking for a) bindings to other languages and b) implementations of other security algorithms and c) multiple pairs of eyes vetting the code base. Please contribute if any of those interest you,\nor if you have other ideas!\n\n**Researchers**: Looking for a test subject for an upcoming paper? If you use **[dirsp]** you have a reasonable opportunity for your research to impact production systems and apps.\n\nSee [Contributing](https://diskuv.github.io/dirsp-exchange/CONTRIBUTING.html).\n\n---\n\nThanks for your interest!\n\nJonah Beckford. Maintainer and Diskuv, Inc. Founder\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiskuv%2Fdirsp-exchange","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiskuv%2Fdirsp-exchange","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiskuv%2Fdirsp-exchange/lists"}