lysann/passforios-gopenpgp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Openpgp security update (V2) (#31)

Browse source 
* Change keyring unlock functionalities

* Add keyring#Lock, keyring#CheckIntegrity, tests

* Update helpers, fix bugs

* Update go.mod with ProtonMail/crypto commit

* Change key management system

* Clear keys from memory + tests

* Create SessionKey with direct encryption for datapackets. Move symmetrickey to password.

* Fix upstream dependencies

* Update module to V2, documentation

* Add linter

* Add v2 folder to .gitignore

* Minor changes to KeyID getters

* Remove old changelog

* Improve docs, remove compilation script
This commit is contained in:
wussler 2019-12-27 19:35:43 +01:00 • committed by GitHub
parent 136c0a5495
commit 54f45d0471
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
46 changed files with 2588 additions and 1770 deletions
Download patch file Download diff file Expand all files Collapse all files

251
README.md
View file

@ -1,4 +1,4 @@
# GopenPGP
# GopenPGP V2
GopenPGP is a high-level OpenPGP library built on top of [a fork of the golang
crypto library](https://github.com/ProtonMail/crypto).
@ -10,7 +10,6 @@ crypto library](https://github.com/ProtonMail/crypto).
- [Download/Install](#downloadinstall)
- [Documentation](#documentation)
- [Using with Go Mobile](#using-with-go-mobile)
- [Other notes](#other-notes)
- [Full documentation](#full-documentation)
- [Examples](#examples)
- [Set up](#set-up)
@ -24,102 +23,89 @@ crypto library](https://github.com/ProtonMail/crypto).
<!-- /TOC -->
## Download/Install
### Vendored install
To use this library using [Go Modules](https://github.com/golang/go/wiki/Modules) just edit your
`go.mod` configuration to contain:
```gomod
require {
...
github.com/ProtonMail/gopenpgp/v2 v2.0.0
}
This package uses [Go Modules](https://github.com/golang/go/wiki/Modules), and
thus requires Go 1.11+. If you're also using Go Modules, simply import it and
start using it (see [Set up](#set-up)). If not, run:
```bash
go get github.com/ProtonMail/gopenpgp # or git clone this repository into the following path
cd $GOPATH/src/github.com/ProtonMail/gopenpgp
GO111MODULE=on go mod vendor
replace golang.org/x/crypto => github.com/ProtonMail/crypto v0.0.0-20191122234321-e77a1f03baa0
```
(After that, the code will also work in Go 1.10, but you need Go 1.11 for the `go mod` command.)
It can then be installed by running:
```sh
go mod vendor
```
Finally your software can include it in your software as follows:
```go
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:
```bash
cd $GOPATH
mkdir -p src/github.com/ProtonMail/
cd $GOPATH/src/github.com/ProtonMail/
git clone git@github.com: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
https://godoc.org/github.com/ProtonMail/gopenpgp/crypto
In this document examples are provided and the proper use of (almost) all functions is tested.
## Using with Go Mobile
Setup Go Mobile and build/bind the source code:
Go Mobile repo: https://github.com/golang/mobile
Go Mobile wiki: https://github.com/golang/go/wiki/Mobile
1. Install Go: `brew install go`
2. Install Gomobile: `go get -u golang.org/x/mobile/cmd/gomobile`
3. Install Gobind: `go install golang.org/x/mobile/cmd/gobind`
4. Install Android SDK and NDK using Android Studio
5. Set env: `export ANDROID_HOME="/AndroidSDK"` (path to your SDK)
6. Init gomobile: `gomobile init -ndk /AndroidSDK/ndk-bundle/` (path to your NDK)
7. Copy Go module dependencies to the vendor directory: `go mod vendor`
8. Build examples:
`gomobile build -target=android #or ios`
Bind examples:
`gomobile bind -target ios -o frameworks/name.framework`
`gomobile bind -target android`
The bind will create framework for iOS and jar&aar files for Android (x86_64 and ARM).
## Other notes
If you wish to use build.sh, you may need to modify the paths in it.
Interfacing between Go and Swift:
https://medium.com/@matryer/tutorial-calling-go-code-from-swift-on-ios-and-vice-versa-with-gomobile-7925620c17a4.
## Full documentation
The full documentation for this API is available here: https://godoc.org/gopkg.in/ProtonMail/gopenpgp.v0/crypto
The use with gomobile is still to be documented
## Examples
### Set up
```go
import "github.com/ProtonMail/gopenpgp/crypto"
```
### Encrypt / Decrypt with password
```go
import "github.com/ProtonMail/gopenpgp/helper"
import "github.com/ProtonMail/gopenpgp/v2/helper"
const password = "my secret password"
const password = []byte("hunter2")
// Encrypt data with password
armor, err := helper.EncryptMessageWithToken(password, "my message")
armor, err := helper.EncryptMessageWithPassword(password, "my message")
// Decrypt data with password
message, err := helper.DecryptMessageWithToken(password, armor)
message, err := helper.DecryptMessageWithPassword(password, armor)
```
To use more encryption algorithms:
To encrypt binary data or use more advanced modes:
```go
import "github.com/ProtonMail/gopenpgp/constants"
import "github.com/ProtonMail/gopenpgp/helper"
import "github.com/ProtonMail/gopenpgp/v2/constants"
// Encrypt data with password
armor, err := helper.EncryptMessageWithTokenAlgo(password, "my message", constants.ThreeDES)
const password = []byte("hunter2")
// Decrypt data with password
message, err := helper.DecryptMessageWithToken(password, armor)
```
To encrypt binary data, reuse the key multiple times, or use more advanced modes:
```go
import "github.com/ProtonMail/gopenpgp/constants"
var key = crypto.NewSymmetricKeyFromToken("my secret password", constants.AES256)
var message = crypto.NewPlainMessage(data)
// Or
message = crypto.NewPlainMessageFromString(string)
// Encrypt data with password
encrypted, err := key.Encrypt(message)
encrypted, err := EncryptMessageWithPassword(message, password)
// Encrypted message in encrypted.GetBinary() or encrypted.GetArmored()
// Decrypt data with password
decrypted, err := key.Decrypt(password, encrypted)
decrypted, err := DecryptMessageWithPassword(encrypted, password)
//Original message in decrypted.GetBinary()
```
@ -127,7 +113,7 @@ decrypted, err := key.Decrypt(password, encrypted)
### Encrypt / Decrypt with PGP keys
```go
import "github.com/ProtonMail/gopenpgp/helper"
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-----
@ -138,7 +124,7 @@ const privkey = `-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----` // encrypted private key
const passphrase = `the passphrase of the private key` // what the privKey is encrypted with
const passphrase = []byte(`the passphrase of the private key`) // Passphrase of the privKey
// encrypt message using public key
armor, err := helper.EncryptMessageArmored(pubkey, "plain text")
@ -162,40 +148,51 @@ decrypted, err := helper.DecryptVerifyMessageArmored(pubkey, privkey, passphrase
With binary data or advanced modes:
```go
// Keys initialization as before (omitted)
var binMessage = NewPlainMessage(data)
var binMessage = crypto.NewPlainMessage(data)
publicKeyObj, err := crypto.NewKeyFromArmored(publicKey)
publicKeyRing, err := crypto.NewKeyFromArmored(publicKeyObj)
publicKeyRing, err := crypto.BuildKeyRingArmored(publicKey)
privateKeyRing, err := crypto.BuildKeyRingArmored(privateKey)
err = privateKeyRing.UnlockWithPassphrase(passphrase)
pgpMessage, err := publicKeyRing.Encrypt(binMessage, privateKeyRing)
// Armored message in pgpMessage.GetArmored()
// pgpMessage can be obtained from NewPGPMessageFromArmored(ciphertext)
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
### 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.
```go
const (
localPart = "name.surname"
domain = "example.com"
passphrase = "LongSecret"
name = "Max Mustermann"
email = "max.mustermann@example.com"
passphrase = []byte("LongSecret")
rsaBits = 2048
ecBits = 256
)
// RSA
rsaKey, err := crypto.GenerateKey(localPart, domain, passphrase, "rsa", rsaBits)
// RSA, string
rsaKey, err := helper.GenerateKey(name, email, passphrase, "rsa", rsaBits)
// Curve25519
ecKey, err := crypto.GenerateKey(localPart, domain, passphrase, "x25519", ecBits)
// 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
@ -206,14 +203,14 @@ The output is an armored signature.
```go
const privkey = `-----BEGIN PGP PRIVATE KEY BLOCK-----
...
-----END PGP PRIVATE KEY BLOCK-----` // encrypted private key
const passphrase = "LongSecret"
const trimNewlines = false
-----END PGP PRIVATE KEY BLOCK-----` // Encrypted private key
const passphrase = []byte("LongSecret") // Private key passphrase
var message = NewPlaintextMessage("Verified message")
var message = crypto.NewPlaintextMessage("Verified message")
signingKeyRing, err := crypto.BuildKeyRingArmored(privkey)
signingKeyRing.UnlockWithPassphrase(passphrase) // if private key is locked with passphrase
privateKeyObj, err := crypto.NewKeyFromArmored(privkey)
unlockedKeyObj = privateKeyObj.Unlock(passphrase)
signingKeyRing, err := crypto.NewKeyRing(unlockedKeyObj)
pgpSignature, err := signingKeyRing.SignDetached(message, trimNewlines)
@ -232,9 +229,11 @@ const signature = `-----BEGIN PGP SIGNATURE-----
...
-----END PGP SIGNATURE-----`
message := NewPlaintextMessage("Verified message")
pgpSignature, err := NewPGPSignatureFromArmored(signature)
signingKeyRing, err := crypto.BuildKeyRingArmored(pubkey)
message := crypto.NewPlaintextMessage("Verified message")
pgpSignature, err := crypto.NewPGPSignatureFromArmored(signature)
publicKeyObj, err := crypto.NewKeyFromArmored(pubkey)
signingKeyRing, err := crypto.NewKeyFromArmored(publicKeyObj)
err := signingKeyRing.VerifyDetached(message, pgpSignature, crypto.GetUnixTime())
@ -251,10 +250,11 @@ const privkey = `-----BEGIN PGP PRIVATE KEY BLOCK-----
-----END PGP PRIVATE KEY BLOCK-----` // encrypted private key
const passphrase = "LongSecret"
var message = NewPlainMessage(data)
var message = crypto.NewPlainMessage(data)
signingKeyRing, err := crypto.BuildKeyRingArmored(privkey)
signingKeyRing.UnlockWithPassphrase(passphrase) // if private key is locked with passphrase
privateKeyObj, err := crypto.NewKeyFromArmored(privkey)
unlockedKeyObj := privateKeyObj.Unlock(passphrase)
signingKeyRing, err := crypto.NewKeyRing(unlockedKeyObj)
pgpSignature, err := signingKeyRing.SignDetached(message)
@ -273,9 +273,11 @@ const signature = `-----BEGIN PGP SIGNATURE-----
...
-----END PGP SIGNATURE-----`
message := NewPlainMessage("Verified message")
pgpSignature, err := NewPGPSignatureFromArmored(signature)
signingKeyRing, err := crypto.BuildKeyRingArmored(pubkey)
message := crypto.NewPlainMessage("Verified message")
pgpSignature, err := crypto.NewPGPSignatureFromArmored(signature)
publicKeyObj, err := crypto.NewKeyFromArmored(pubkey)
signingKeyRing, err := crypto.NewKeyFromArmored(publicKeyObj)
err := signingKeyRing.VerifyDetached(message, pgpSignature, crypto.GetUnixTime())
@ -287,35 +289,56 @@ if err == nil {
### Cleartext signed messages
```go
// Keys initialization as before (omitted)
armored, err := SignCleartextMessageArmored(privateKey, passphrase, plaintext)
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.
```go
// Keys initialization as before (omitted)
var verifyTime = crypto.GetUnixTime()
verifiedPlainText, err := VerifyCleartextMessageArmored(publicKey, armored, verifyTime)
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
```go
// Keys initialization as before (omitted)
symmetricKey := &SymmetricKey{
Key: "RandomTokenabcdef",
Algo: constants.AES256,
}
sessionKey, err := crypto.GenerateSessionKey()
keyPacket, err := publicKey.EncryptSessionKey(symmetricKey)
keyPacket, err := publicKey.EncryptSessionKey(sessionKey)
keyPacketSymm, err := crypto.EncryptSessionKeyWithPassword(sessionKey, password)
```
`KeyPacket` is a `[]byte` containing the session key encrypted with the private key.
`KeyPacket` is a `[]byte` containing the session key encrypted with the private key or password.
```go
outputSymmetricKey, err := privateKey.DecryptSessionKey(keyPacket)
decodedKeyPacket, err := privateKey.DecryptSessionKey(keyPacket)
decodedSymmKeyPacket, err := crypto.DecryptSessionKeyWithPassword(keyPacketSymm, password)
```
`outputSymmetricKey` is an object of type `*SymmetricKey` that can be used to decrypt the correspondig message.
`decodedKeyPacket` and `decodedSymmKeyPacket` are objects of type `*SymmetricKey` that can
be used to decrypt the corresponding symmetrically encrypted data packets:
```go
var message = crypto.NewPlainMessage(data)
// Encrypt data with password
dataPacket, err := sessionKey.Encrypt(message)
// Decrypt data with password
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:
```go
pgpSplitMessage := NewPGPSplitMessage(keyPacket, dataPacket)
pgpMessage := pgpSplitMessage.GetPGPMessage()
// And vice-versa
newPGPSplitMessage, err := pgpMessage.SeparateKeyAndData()
// Key Packet is in newPGPSplitMessage.GetKeyPacket()
// Data Packet is in newPGPSplitMessage.GetDataPacket()
```