Skip to content
WiP: RFC 4880 (OpenPGP) library and utilities in OCaml
OCaml
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
doc
lib
pkg
rfc
test
.gitattributes
.gitignore
.merlin
.ocamlinit
.travis.yml
CHANGES.md
LICENSE.md
README.md
_tags
opam

README.md

OpenPGP library (RFC 4880) Build Status

This library implements rudimentary support for OpenPGP as used with signatures, and has basic support for decryption of messages.

Right now it's a work in progress and should not be used for anything critical to security in a real-world situation.

  • Encryption is being worked on; currently GnuPG won't read our messages (but we can read their messages!).

  • Supporting El-Gamal and elliptic curve keys are out of scope due to lack of support for these in nocrypto.

I could be persuaded to add these if someone can point me to maintained libraries implementing these.

Contributing

Contributions are greatly appreciated!

To prevent duplication/collision of work, please consider leaving a note in the issues section before implementing large changes.

The library and API is still a volatile as it is still being developed.

Suggestions for things to improve:

  • Writing more tests, for example for primitives in types.ml.
    • Tests for vulnerabilities that have affected other OpenPGP implementations.
    • Tests pertaining to diverse/"exotic" keys
  • Adding useful debug output, or extending existing pretty-printers with more information.
  • Suggestions / signatures for a better API, or scenarios that the library should support.
  • CLI commands or arguments (this is one of my first times using cmdliner - I'm sure things can be improved)
  • Performance improvements

Building

The library currently depends on the unreleased Usane library for unsigned arithmetic, and on my unreleased wrappers around Cstruct, called cs.

opam pin add -n usane 'https://github.com/hannesm/usane.git'
opam pin add -n cs 'https://github.com/cfcs/ocaml-cs.git'
opam pin add -n gmap 'https://github.com/hannesm/gmap.git'
opam pin add -n nocrypto -k git 'https://github.com/mirleft/ocaml-nocrypto.git#79d5db2488e338d161d7e170cd681a8120ce07d1'
opam pin add -n mrmime -k git https://github.com/oklm-wsh/MrMime.git
opam install alcotest bos cmdliner cs cstruct fmt fpath gmap hex logs \
             nocrypto ptime qcheck rresult usane topkg mrmime
ocaml pkg/pkg.ml build

Roadmap

  • Consider support for inline signatures
  • GPG-agent protocol the GPG-agent protocol is inherently unsafe for signing operations. Other projects (git, qubes, enigmail) seem to implement GnuPG integration by shelling out to the gpg cli. Some limited compatibility with that seems more useful to implement.
  • Git signing / verification, see section below
  • MirageOS version of Qubes split-gpg

Cmdline usage

The library ships with a sample application in app/opgp.ml.

Usage details is available with opgp --help.

Examples of how to use the application are also given there.

It can currently:

  • opgp genkey: Generate a (DSA | RSA) private key with subkeys for signing+encryption
  • opgp sign: Produce a detached signature on a file
  • opgp convert: Derive a public key from a private key
  • opgp verify: Verify a detached signature
  • opgp list-packets: List packets contained in armored or binary PGP streams
  • opgp decrypt: Decrypt messages to RSA keys
    • Decompress ZIP(RFC1951) and ZLIB messages - BZip2 is still missing
  • opgp encrypt: Encrypt messages to RSA keys
  • opgp mail-decrypt: Carve out PGP/MIME messages and decrypt them. Currently does not check signatures.

Git / OpenPGP integration

git integrates cryptographic signature creation and verification by calling out to gpg. Peter Todd has a nice article about that in the documentation for his OpenTimeStamps project (which is a separate project that combines gpg-signatures with date proofs using append-only logs like BitCoin).

A minimally GnuPG-compatible program opgp-git is provided with the ocaml-openpgp distribution to replace the use of gpg in this scenario.

  • NB: At the moment only verification is supported, and only against a single public key contained in ~/opgp-git.asc - as thus this is not super useful, but is there as an example, and to remind me to fix the API to support some sort of PKI / key database.

To activate it, you will have to change the gpg.program variable to point to opgp-git instead of gpg:

$ git config --global gpg.program "$(opam config var openpgp:bin)/opgp-git"
  • NOTE that opgp-git does not implement the full GnuPG command-line interface, it merely implements the handling of the functionality expected by git, namely ["opgp-git", "--verify", "$file", "-"] and ["opgp-git", "-bsau", "$key"]. See the gpg.program entry in man git-config for more details.

Once configured, you can "manually" sign commits at commit-time with git commit --gpg-sign=KEYID, or you can configure git to do this automatically (see the commit.gpgSign entry in man git-config for more details).

Resources

The spec is included in this repository in the rfc/ subdirectory.

RFC 4880 - OpenPGP Message Format TODO - IANA registry updates

Alternative implementations

You can’t perform that action at this time.