• Stars
    star
    1,018
  • Rank 45,203 (Top 0.9 %)
  • Language
    Go
  • License
    MIT License
  • Created over 5 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A high-level OpenPGP library

GopenPGP V2

Build Status

GopenPGP is a high-level OpenPGP library built on top of a fork of the golang crypto library.

Table of Contents

Download/Install

Vendored install

To use this library using Go Modules just edit your go.mod configuration to contain:

require (
    ...
    github.com/ProtonMail/gopenpgp/v2 v2.0.1
)

It can then be installed by running:

go mod vendor

Finally your software can include it in your software as follows:

package main

import (
	"fmt"
	"github.com/ProtonMail/gopenpgp/v2/crypto"
)

func main() {
	fmt.Println(crypto.GetUnixTime())
}

Git-Clone install

To install for development mode, cloning the repository, it can be done in the following way:

cd $GOPATH
mkdir -p src/github.com/ProtonMail/
cd $GOPATH/src/github.com/ProtonMail/
git clone [email protected]:ProtonMail/gopenpgp.git
cd gopenpgp
ln -s . v2
go mod

Documentation

A full overview of the API can be found here: https://godoc.org/gopkg.in/ProtonMail/gopenpgp.v2/crypto

In this document examples are provided and the proper use of (almost) all functions is tested.

Using with Go Mobile

This library can be compiled with Gomobile too. First ensure you have a working installation of gomobile:

gomobile version

In case this fails, install it with:

go get -u golang.org/x/mobile/cmd/gomobile

Then ensure your path env var has gomobile's binary, and it is properly init-ed:

export PATH="$PATH:$GOPATH/bin"
gomobile init

Then you must ensure that the Android or iOS frameworks are installed and the respective env vars set.

Finally, build the application

sh build.sh

This script will build for both android and iOS at the same time, to filter one out you can comment out the line in the corresponding section.

Examples

Encrypt / Decrypt with password

import "github.com/ProtonMail/gopenpgp/v2/helper"

const password = []byte("hunter2")

// Encrypt data with password
armor, err := helper.EncryptMessageWithPassword(password, "my message")

// Decrypt data with password
message, err := helper.DecryptMessageWithPassword(password, armor)

To encrypt binary data or use more advanced modes:

import "github.com/ProtonMail/gopenpgp/v2/constants"

const password = []byte("hunter2")

var message = crypto.NewPlainMessage(data)
// Or
message = crypto.NewPlainMessageFromString(string)

// Encrypt data with password
encrypted, err := EncryptMessageWithPassword(message, password)
// Encrypted message in encrypted.GetBinary() or encrypted.GetArmored()

// Decrypt data with password
decrypted, err := DecryptMessageWithPassword(encrypted, password)

//Original message in decrypted.GetBinary()

Encrypt / Decrypt with PGP keys

import "github.com/ProtonMail/gopenpgp/v2/helper"

// put keys in backtick (``) to avoid errors caused by spaces or tabs
const pubkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----`

const privkey = `-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----` // encrypted private key

const passphrase = []byte(`the passphrase of the private key`) // Passphrase of the privKey

// encrypt plain text message using public key
armor, err := helper.EncryptMessageArmored(pubkey, "plain text")

// decrypt armored encrypted message using the private key and obtain plain text
decrypted, err := helper.DecryptMessageArmored(privkey, passphrase, armor)

// encrypt binary message using public key
armor, err := helper.EncryptBinaryMessageArmored(pubkey, []byte("plain text"))

// decrypt armored encrypted message using the private key expecting binary data
decrypted, err := helper.DecryptBinaryMessageArmored(privkey, passphrase, armor)

With signatures:

// Keys initialization as before (omitted)

// encrypt message using public key, sign with the private key
armor, err := helper.EncryptSignMessageArmored(pubkey, privkey, passphrase, "plain text")

// decrypt armored encrypted message using the private key, verify with the public key
// err != nil if verification fails
decrypted, err := helper.DecryptVerifyMessageArmored(pubkey, privkey, passphrase, armor)

For more advanced modes the full API (i.e. without helpers) can be used:

// Keys initialization as before (omitted)
var binMessage = crypto.NewPlainMessage(data)

publicKeyObj, err := crypto.NewKeyFromArmored(publicKey)
publicKeyRing, err := crypto.NewKeyRing(publicKeyObj)

pgpMessage, err := publicKeyRing.Encrypt(binMessage, privateKeyRing)

// Armored message in pgpMessage.GetArmored()
// pgpMessage can be obtained from NewPGPMessageFromArmored(ciphertext)

//pgpMessage can be obtained from a byte array
var pgpMessage = crypto.NewPGPMessage([]byte)

privateKeyObj, err := crypto.NewKeyFromArmored(privateKey)
unlockedKeyObj = privateKeyObj.Unlock(passphrase)
privateKeyRing, err := crypto.NewKeyRing(unlockedKeyObj)

message, err := privateKeyRing.Decrypt(pgpMessage, publicKeyRing, crypto.GetUnixTime())

privateKeyRing.ClearPrivateParams()

// Original data in message.GetString()
// `err` can be a SignatureVerificationError

Generate key

Keys are generated with the GenerateKey function, that returns the armored key as a string and a potential error. The library supports RSA with different key lengths or Curve25519 keys.

const (
  name = "Max Mustermann"
  email = "[email protected]"
  passphrase = []byte("LongSecret")
  rsaBits = 2048
)

// RSA, string
rsaKey, err := helper.GenerateKey(name, email, passphrase, "rsa", rsaBits)

// Curve25519, string
ecKey, err := helper.GenerateKey(name, email, passphrase, "x25519", 0)

// RSA, Key struct
rsaKey, err := crypto.GenerateKey(name, email, "rsa", rsaBits)

// Curve25519, Key struct
ecKey, err := crypto.GenerateKey(name, email, "x25519", 0)

Detached signatures for plain text messages

To sign plain text data either an unlocked private keyring or a passphrase must be provided. The output is an armored signature.

const privkey = `-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----` // Encrypted private key
const passphrase = []byte("LongSecret") // Private key passphrase

var message = crypto.NewPlaintextMessage("Verified message")

privateKeyObj, err := crypto.NewKeyFromArmored(privkey)
unlockedKeyObj = privateKeyObj.Unlock(passphrase)
signingKeyRing, err := crypto.NewKeyRing(unlockedKeyObj)

pgpSignature, err := signingKeyRing.SignDetached(message, trimNewlines)

// The armored signature is in pgpSignature.GetArmored()
// The signed text is in message.GetString()

To verify a signature either private or public keyring can be provided.

const pubkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----`

const signature = `-----BEGIN PGP SIGNATURE-----
...
-----END PGP SIGNATURE-----`

message := crypto.NewPlaintextMessage("Verified message")
pgpSignature, err := crypto.NewPGPSignatureFromArmored(signature)

publicKeyObj, err := crypto.NewKeyFromArmored(pubkey)
signingKeyRing, err := crypto.NewKeyRing(publicKeyObj)

err := signingKeyRing.VerifyDetached(message, pgpSignature, crypto.GetUnixTime())

if err == nil {
  // verification success
}

Detached signatures for binary data

const privkey = `-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----` // encrypted private key
const passphrase = "LongSecret"

var message = crypto.NewPlainMessage(data)

privateKeyObj, err := crypto.NewKeyFromArmored(privkey)
unlockedKeyObj := privateKeyObj.Unlock(passphrase)
signingKeyRing, err := crypto.NewKeyRing(unlockedKeyObj)

pgpSignature, err := signingKeyRing.SignDetached(message)

// The armored signature is in pgpSignature.GetArmored()
// The signed text is in message.GetBinary()

To verify a signature either private or public keyring can be provided.

const pubkey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----`

const signature = `-----BEGIN PGP SIGNATURE-----
...
-----END PGP SIGNATURE-----`

message := crypto.NewPlainMessage("Verified message")
pgpSignature, err := crypto.NewPGPSignatureFromArmored(signature)

publicKeyObj, err := crypto.NewKeyFromArmored(pubkey)
signingKeyRing, err := crypto.NewKeyRing(publicKeyObj)

err := signingKeyRing.VerifyDetached(message, pgpSignature, crypto.GetUnixTime())

if err == nil {
  // verification success
}

Cleartext signed messages

// Keys initialization as before (omitted)
armored, err := helper.SignCleartextMessageArmored(privateKey, passphrase, plaintext)

To verify the message it has to be provided unseparated to the library. If verification fails an error will be returned.

// Keys initialization as before (omitted)
verifiedPlainText, err := helper.VerifyCleartextMessageArmored(publicKey, armored, crypto.GetUnixTime())

Encrypting and decrypting session Keys

A session key can be generated, encrypted to a Asymmetric/Symmetric key packet and obtained from it

// Keys initialization as before (omitted)

sessionKey, err := crypto.GenerateSessionKey()

keyPacket, err := publicKeyRing.EncryptSessionKey(sessionKey) // Will encrypt to all the keys in the keyring
keyPacketSymm, err := crypto.EncryptSessionKeyWithPassword(sessionKey, password)

KeyPacket is a []byte containing the session key encrypted with the public key or password.

decodedKeyPacket, err := privateKeyRing.DecryptSessionKey(keyPacket) // Will decode with the first valid key found
decodedSymmKeyPacket, err := crypto.DecryptSessionKeyWithPassword(keyPacketSymm, password)

decodedKeyPacket and decodedSymmKeyPacket are objects of type *SymmetricKey that can be used to decrypt the corresponding symmetrically encrypted data packets:

var message = crypto.NewPlainMessage(data)

// Encrypt data with session key
dataPacket, err := sessionKey.Encrypt(message)

// Decrypt data with session key
decrypted, err := sessionKey.Decrypt(password, dataPacket)

//Original message in decrypted.GetBinary()

Note that it is not possible to process signatures when using data packets directly. Joining the data packet and a key packet gives us a valid PGP message:

pgpSplitMessage := NewPGPSplitMessage(keyPacket, dataPacket)
pgpMessage := pgpSplitMessage.GetPGPMessage()

// And vice-versa
newPGPSplitMessage, err := pgpMessage.SeparateKeyAndData()
// Key Packet is in newPGPSplitMessage.GetBinaryKeyPacket()
// Data Packet is in newPGPSplitMessage.GetBinaryDataPacket()

Checking keys

Keys are now checked on import and the explicit check via Key#Check() is deprecated and no longer necessary.

More Repositories

1

WebClients

Monorepo hosting the proton web clients
TypeScript
4,315
star
2

proton-mail-android

Proton Mail Android app
Kotlin
1,741
star
3

ios-mail

Secure email that protects your privacy
Swift
1,439
star
4

proton-bridge

Proton Mail Bridge application
Go
1,137
star
5

proton-python-client

Python Proton client module
Python
343
star
6

gluon

An IMAP server library written in Go
Go
339
star
7

go-crypto

Fork of go/x/crypto, providing an up-to-date OpenPGP implementation
Go
323
star
8

react-components

List of React components for Proton web-apps
TypeScript
177
star
9

proton-mail

React web application to manage ProtonMail
TypeScript
172
star
10

android-mail

Proton Mail Android app
Kotlin
141
star
11

protoncore_android

Proton Core components for Android
Kotlin
129
star
12

design-system

Design system for new Proton project
SCSS
124
star
13

proton-calendar

Proton Calendar built with React.
TypeScript
120
star
14

proton-drive

TypeScript
115
star
15

proton-shared

Shared logic for Proton web-app
TypeScript
71
star
16

go-appdir

Minimalistic Go package to get application directories such as config and cache
Go
63
star
17

inbox-desktop

Desktop application for Mail and Calendar, made with Electron
63
star
18

proton-mail-settings

React web application to manage ProtonMail settings
TypeScript
52
star
19

ct-monitor

A monitoring tool for certificate transparency of ProtonMail's SSL/TLS certificates
Python
42
star
20

go-srp

Go
38
star
21

pmcrypto

TypeScript
37
star
22

go-proton-api

Proton API library used by Go-based clients and tools
Go
32
star
23

gosop

Stateless CLI for GopenPGP
Go
24
star
24

libsieve-php

libsieve-php is a library to manage and modify sieve (RFC5228) scripts. It contains a parser for the sieve language (including extensions) and a client for the managesieve protocol. It is written entirely in PHP 8+.
PHP
21
star
25

mutex-browser

Acquire a mutex in the browser through IndexedDB or cookies
TypeScript
19
star
26

releaser

A release note generator that reads and parses git commits and retrieves issue links from GitHub.
JavaScript
16
star
27

go-mime

Go
15
star
28

encrypted-search

Encrypted search functionality for the browser
JavaScript
14
star
29

proton-account

Proton account settings
TypeScript
13
star
30

sieve.js

Javascript library to wrap sieve configuration
JavaScript
13
star
31

protoncore_ios

Swift
11
star
32

cpp-openpgp

C++
10
star
33

proton-pack

Command to run a dev-server, build etc. with OpenPGP. On top of webpack.
JavaScript
10
star
34

proton-bundler

CLI tools to bundle Proton web clients for deploys
JavaScript
9
star
35

apple-fusion

fusion is a lightweight and easy-to-use UI testing framework built on top of Apple XCTest that supports testing on iOS and macOS platforms. Developed with readability and reliability in mind.
Swift
9
star
36

bip39

JavaScript implementation of Bitcoin BIP39
TypeScript
8
star
37

componentGenerator

CLI to create new components for the Front-End @ ProtonMail.
JavaScript
7
star
38

interval-tree

Red-black interval tree
TypeScript
7
star
39

php-coding-standard

ProtonLabs Coding Standard for PHP_CodeSniffer (extending PER coding style)
PHP
7
star
40

pm-srp

ProtonMail SRP and auth library
JavaScript
7
star
41

source-map-parser

Command line utility to parse js source maps with with node.js
JavaScript
6
star
42

haproxy-health-check

HAProxy Health Check for EXABGP
Python
6
star
43

pt-formgenerator

Html form generator library
JavaScript
6
star
44

account

JavaScript
6
star
45

go-rfc5322

An RFC5322 address/date parser written in Go
Go
6
star
46

proton-translations

6
star
47

go-ecvrf

Golang implementation of ECVRF-EDWARDS25519-SHA512-TAI, a verifiable random function described in draft-irtf-cfrg-vrf-10.
Go
5
star
48

protonmail.github.io

HTML
5
star
49

therecipe_qt

Go
5
star
50

proton-parking

Gatsby website for parking domains
TypeScript
4
star
51

webcrypto-spec

Specification for extension of webcrypto api
HTML
4
star
52

ios-networking

shared networking framworks
Swift
4
star
53

android-fusion

Android Fusion is a extensible lightweight Android instrumented test framework that combines Espresso, UI Automator and Compose Ui Test into one easy-to-use API with the clear syntax, at the same time keeping the native Android frameworks APIs unchanged.
Kotlin
4
star
54

proton-i18n

CLI to manage translations for client apps
JavaScript
3
star
55

proton-lint

Modern eslint config for a more civilized age
JavaScript
3
star
56

fe-proxy

A simple proxy server that redirects to different urls
JavaScript
3
star
57

Illuminate-Foundation

Illuminate Foundation Mirror
PHP
2
star
58

opendkim

This is a fork of https://sourceforge.net/p/opendkim/git/ci/master/tree/
C
2
star
59

logging

go logging
Go
2
star
60

openpgp-interop-test-analyzer

Python scripts to analyze results from the Openpgp interoperability test suite
Python
2
star
61

danger-random_reviewers

Ruby
1
star
62

u2f

JavaScript
1
star
63

react-storybook

Isolated React components from https://github.com/ProtonMail/react-components
JavaScript
1
star
64

key-transparency-web-client

TypeScript
1
star
65

x509-sign

Simple endpoint to sign ASN1 strings
PHP
1
star
66

openpgp-interop-test-docker

Docker image to run the OpenPGP interoperability test suite
Dockerfile
1
star
67

gomobile-build-tool

Go
1
star
68

therecipe_env_darwin_arm64_513

C++
1
star
69

pm-key-transparency-go-client

Go
1
star
70

proton-mobile-test

HTML
1
star