Skip to content

Latest commit

 

History

History
1153 lines (977 loc) · 44.1 KB

CHANGELOG.md

File metadata and controls

1153 lines (977 loc) · 44.1 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.8.0-alpha.1] 2024-04-09

Added

  • API to serialize KeyRings to binary data: 
     func (keyRing *KeyRing) Serialize() ([]byte, error)
  • API to parse KeyRings from binary data: 
     func NewKeyRingFromBinary(binKeys []byte) (*KeyRing, error)

[2.8.0-alpha.0] 2024-02-28

Added

  • Adds support for the OpenPGP crypto-refresh by updating the go-crypto dependency to v1.1.0-alpha.1.
  • Adapts the session key logic to handle PKESK/SKESK v6 packets without an algorithm attached
  • Updates the min go version to 1.17 as required by go-crypto v1.1.0-alpha.1.
  • Update the cricl dependency to 1.3.7 matching go-crypto.

[2.7.5] 2023-31-01

Added

  • API to get signature key IDs for mobile: 
     func (msg *PGPMessage) GetHexSignatureKeyIDsJson() []byte
  • API to get encryption key IDs for mobile: 
     func (msg *PGPMessage) GetHexEncryptionKeyIDsJson() []byte
  • API to get the number of key packets in a PGP message: 
     func (msg *PGPSplitMessage) GetNumberOfKeyPackets() (int, error)
  • API in package helper to encrypt a PGP message to an additional key: 
     func EncryptPGPMessageToAdditionalKey(messageToModify *crypto.PGPSplitMessage, keyRing *crypto.KeyRing, additionalKey *crypto.KeyRing) error

[2.7.4] 2023-10-27

Fixed

  • Ensure that (SessionKey).Decrypt functions return an error if no integrity protection is present in the encrypted input. To protect SEIPDv1 encrypted messages, SED packets must not be allowed in decryption.

[2.7.3] 2023-08-28

Added

  • Add helper.QuickCheckDecrypt function to the helper package. The function allows to check with high probability if a session key can decrypt a SEIPDv1 data packet given its 24-byte prefix.

[2.7.2] 2023-07-17

Changed

  • Updated underlying crypto library

Fixed

  • Ensure DecryptSessionKey returns an error for a missing key packet

[2.7.1] 2023-04-21

Added

  • Add mobile helpers for signature verification with contexts.

[2.7.0] 2023-04-14

Changed

  • The SignatureVerificationError struct now has a Cause error field, which is returned by the the Unwrap function. The cause is also included in the error message. NB: If the caller was relying on the exact message of the error, it might break the flow.
  • When a signature fails verification because of the signature context, it returns a SignatureVerificationError with status constants.SIGNATURE_BAD_CONTEXT instead of constants.SIGNATURE_FAILED.

Added

  • Add api for signature context on streams SignDetachedStreamWithContext.
  • Add API for signature context on embedded signatures.

Fixed

  • When verifying detached signatures, gopenpgp sometimes needs to reattempt verification a second time to check for edge cases of signature expiration. This logic was broken because it was not rewinding the data readers.

[2.6.1] 2023-03-22

Security fix

  • Update github.com/ProtonMail/go-crypto and github.com/ProtonMail/go-mime to fix panic on invalid inputs.

[2.6.0] 2023-03-15

Added

  • API for adding context to detached signatures: 
     sig, err := keyRing.SignDetachedWithContext(message, context)
  • API to verify the context of detached signatures: 
     err := keyRing.VerifyDetachedWithContext(message, signature, verifyTime, verificationContext)

Changed

  • Update github.com/ProtonMail/go-crypto to the latest version
  • More strictly verify detached signatures: reject detached signatures from revoked and expired keys.
  • In GetVerifiedSignatureTimestamp, use the new VerifyDetachedSignatureAndHash function to get the verified signature, instead of parsing the signature packets manually to get the timestamp.
  • Upgraded golang.org/x/crypto dependency to v0.7.0

[2.5.2] 2023-01-25

Changed

  • Update github.com/ProtonMail/go-crypto to the latest version

[2.5.1] 2023-01-24

Added

  • Streaming API to encrypt with compression:
    • func (keyRing *KeyRing) EncryptStreamWithCompression
    • func (keyRing *KeyRing) EncryptSplitStreamWithCompression
    • func (sk *SessionKey) EncryptStreamWithCompression

[2.5.0] 2022-12-16

Changed

  • Update github.com/ProtonMail/go-crypto to the latest version
  • Update github.com/ProtonMail/go-mime to the latest version, which cleans up unneeded dependencies. And fix an issue with PGP/MIME messages with non standard encodings.
  • Sanitize strings returned in MIMECallbacks.OnBody() and PlainMessage.GetString(). Strings that have non utf8 characters will be sanitized to have the "character unknown" character : � instead.
  • Detached sign text messages with signature type text. Similarly, clearsigned messages now also use signature type text.
  • Leave trailing spaces of text messages intact (except for clearsigned messages, where the spec requires us to trim trailing spaces). Note that for backwards compatibility, when verifying detached signatures over text messages, the application will have to trim trailing spaces in order for the signature to verify, if it was created by a previous version of this library (using crypto.NewPlainMessageFromString()).

[2.4.10] 2022-08-22

Changed

  • Updated underlying crypto library

[2.4.9] 2022-08-19

Changed

  • Updated underlying crypto library and adjusted key clearing functions
  • Fixed typos in errors and comments

[2.4.8] 2022-06-22

Changed

  • SessionKey.Decrypt() and SessionKey.DecryptAndVerify(), now support the decryption of AEAD encrypted data packets (packet type 20).

[2.4.7] 2022-04-27

Changed

  • DecryptMIMEMessage will return the decrypted content in the OnBody callback, even when there's a signature verification error. That lets the caller decide whether they want to use the content with a warning or hard fail on signature errors.
  • Key generation functions no longer return an error if either the name or email is empty

[2.4.6] 2022-03-25

Fixed

  • Update dependency github.com/ProtonMail/go-mime. It makes the parsing of MIME messages more flexible to messages with no specified charsets.
  • Fix the verification of PGP/MIME signature, the signature is now verified against the canonicalized content rather than the raw content.

[2.4.5] 2022-03-01

Added

  • (msg *PGPMessage) SplitMessage() to split PGP messages, replacing SeparateKeyAndData.

Changed

  • SeparateKeyAndData is now deprecated.

[2.4.4] 2022-02-28

Changed

  • SeparateKeyAndData clones the returned byte slices to avoid overwriting.

[2.4.3] 2022-02-24

Security

  • Fixed incorrect MDC parsing for session key decryption

Changed

  • SeparateKeyAndData is now implemented in a more generic way, by checking for the location in the bytes of the last session key packet, then splitting the binary message after that point.

Fixed

  • SeparateKeyAndData now correctly parses AEAD packets.
  • (ap *AttachmentProcessor) Finish() now returns encryption errors correctly.

[2.4.2] 2022-01-13

Changed

  • Updated underlying crypto library and prevented AEAD messages from being created until the specification is stable

[2.4.1] 2022-01-10

Fixed

  • Fixed bug with NewPGPSplitMessageFromArmored(armored) and PGPMessage.SeparateKeyAndData(). Those functions didn't parse AEAD encrypted messages correctly (eg messages encrypted with the latest versions of gnupg), resulting in a nil DataPacket.

[2.4.0] 2021-12-21

Added

  • Function to verify a detached signature and get its creation time:
func (keyRing *KeyRing) GetVerifiedSignatureTimestamp(message *PlainMessage, signature *PGPSignature, verifyTime int64) (int64, error)

Changed

  • Updated the underlying crypto library

[2.3.1] 2021-12-15

Fixed

  • Fix the verification of PGP/MIME message signatures:
    • Improve the handling of the dual verification status so that it is considered invalid if both embedded and PGP/MIME signatures are invalid.
    • start calling callback.OnVerified(status int) to communicate the status verification of the message.

[2.3.0] 2021-11-15

Added

  • Key.IsRevoked() to check the revocation status of a key

Security

  • Upgraded underlying crypto library to fix handling of revoked keys

[2.2.5] 2021-11-11

Fixed

  • Protect the global pgp variable fields with a lock.
  • Unlock and lock dummy keys correctly

[2.2.4] 2021-09-29

Fixed

  • Use the provided verifyTime instead of the current time when verifying embedded signatures.

[2.2.3] 2021-09-21

Changed

  • Keys are now generated with ZLIB as preferred compression algorithm
  • Upgraded underlying crypto library

[2.2.2] 2021-08-04

Added

  • NewKeyFromEntity to create a key from an openpgp entity

Changed

  • Improved documentation for differences between text and binary messages

Deprecated

  • (key *Key) Check() (bool, error) is now deprecated, all keys are now checked upon import from x/crypto

Fixed

  • Dummy keys now show the correct locked/unlocked status

Security

  • All keys are now checked on parsing from the underlying library

[2.2.1] 2021-07-27

Changed

  • Changed the returned SignatureVerificationError.Status when trying to verify a message with no embedded signature. It used to return constants.SIGNATURE_NO_VERIFIER and now returns constants.SIGNATURE_NOT_SIGNED. This change impacts :
    • func (sk *SessionKey) DecryptAndVerify(...)
    • func (msg *PlainMessageReader) VerifySignature(...)
    • func (keyRing *KeyRing) Decrypt(...)
  • Improved error messages for failures in password protected message decryption

Added

  • Helper to access the SignatureVerificationError explicitly when decrypting streams in mobile apps: 
     func VerifySignatureExplicit(
 	reader *crypto.PlainMessageReader,
 ) (signatureVerificationError *crypto.SignatureVerificationError, err error)

[2.2.0] 2021-06-30

Added

  • Streaming API:

    • New structs:

      • PlainMessageMetadata: holds the metadata of a plain PGP message 
         type PlainMessageMetadata struct {
 	IsBinary bool
 	Filename string
 	ModTime  int64
 }
      • PlainMessageReader implements Reader and: 
         func (msg *PlainMessageReader) GetMetadata() *PlainMessageMetadata
 func (msg *PlainMessageReader) VerifySignature() (err error)
      • EncryptSplitResult implements WriteCloser and: 
         func (res *EncryptSplitResult) GetKeyPacket() (keyPacket []byte, err error)

    • Keyring methods:

      • Encrypt (and optionally sign) a message directly into a Writer:

         func (keyRing *KeyRing) EncryptStream(
 	pgpMessageWriter Writer,
 	plainMessageMetadata *PlainMessageMetadata,
 	signKeyRing *KeyRing,
 ) (plainMessageWriter WriteCloser, err error)

      • Encrypt (and optionally sign) a message directly into a Writer (split keypacket and datapacket):

         func (keyRing *KeyRing) EncryptSplitStream(
 	dataPacketWriter Writer,
 	plainMessageMetadata *PlainMessageMetadata,
 	signKeyRing *KeyRing,
 ) (*EncryptSplitResult, error)

      • Decrypt (and optionally verify) a message from a Reader:

         func (keyRing *KeyRing) DecryptStream(
 	message Reader,
 	verifyKeyRing *KeyRing,
 	verifyTime int64,
 ) (plainMessage *PlainMessageReader, err error)

        N.B.: to verify the signature, you will need to call plainMessage.VerifySignature() after all the data has been read from plainMessage.

      • Decrypt (and optionally verify) a split message, getting the datapacket from a Reader:

         func (keyRing *KeyRing) DecryptSplitStream(
 	keypacket []byte,
 	dataPacketReader Reader,
 	verifyKeyRing *KeyRing, verifyTime int64,
 ) (plainMessage *PlainMessageReader, err error)

        N.B.: to verify the signature, you will need to call plainMessage.VerifySignature() after all the data has been read from plainMessage.

      • Generate a detached signature from a Reader:

         func (keyRing *KeyRing) SignDetachedStream(message Reader) (*PGPSignature, error)

      • Verify a detached signature for a Reader:

         func (keyRing *KeyRing) VerifyDetachedStream(
 	message Reader,
 	signature *PGPSignature,
 	verifyTime int64,
 ) error

      • Generate an encrypted detached signature from a Reader:

         func (keyRing *KeyRing) SignDetachedEncryptedStream(
 	message Reader,
 	encryptionKeyRing *KeyRing,
 ) (encryptedSignature *PGPMessage, err error)

      • Verify an encrypted detached signature for a Reader:

         func (keyRing *KeyRing) VerifyDetachedEncryptedStream(
 	message Reader,
 	encryptedSignature *PGPMessage,
 	decryptionKeyRing *KeyRing,
 	verifyTime int64,
 ) error

    • SessionKey methods:

      • Encrypt (and optionally sign) a message into a Writer: 
         func (sk *SessionKey) EncryptStream(
 	dataPacketWriter Writer,
 	plainMessageMetadata *PlainMessageMetadata,
 	signKeyRing *KeyRing,
 ) (plainMessageWriter WriteCloser, err error)
      • Decrypt (and optionally verify) a message from a Reader: 
         func (sk *SessionKey) DecryptStream(
 	dataPacketReader Reader,
 	verifyKeyRing *KeyRing,
 	verifyTime int64,
 ) (plainMessage *PlainMessageReader, err error)
        N.B.: to verify the signature, you will need to call plainMessage.VerifySignature() after all the data has been read from plainMessage.

    • Mobile apps helpers for Reader and Writer: Due to limitations of gomobile, mobile apps can't implement the Reader and Writer interfaces directly.

      • Implementing Reader: Apps should implement the interface:

         type MobileReader interface {
 	Read(max int) (result *MobileReadResult, err error)
 }
 type MobileReadResult struct {
 	N     int    // N, The number of bytes read
 	IsEOF bool   // IsEOF, If true, then the reader has reached the end of the data to read.
 	Data  []byte // Data, the data that has been read
 }

        And then wrap it with Mobile2GoReader(mobileReader) to turn it into a Reader.

      • Implementing Writer:

        The apps should implement the Writer interface directly, but still need to wrap the writer with Mobile2GoWriter(mobileWriter). We also provide the Mobile2GoWriterWithSHA256 if you want to compute the SHA256 hash of the written data.

      • Using a Reader: To use a reader returned by golang in mobile apps: you should wrap it with:

        • Android: Go2AndroidReader(reader), implements the Reader interface, but returns n == -1 instead of err == io.EOF
        • iOS: Go2IOSReader(reader), implements MobileReader.

      • Using a Writer: you can use a writer returned by golang directly.

[2.1.10] 2021-06-16

Fixed

  • Removed time interpolation via monotonic clock that can cause signatures in the future

[2.1.9] 2021-05-12

Changed

  • Updated the underlying crypto library

[2.1.8] 2021-04-27

Added

  • Key and KeyRing methods to check if a key/keyring can Encrypt or Verify
(key *Key) CanVerify() bool
(key *Key) CanEncrypt() bool
(keyRing *KeyRing) CanVerify() bool
(keyRing *KeyRing) CanEncrypt() bool
  • SessionKey methods to encrypt/decrypt and simultaneously sign/verify with an asymmetric key (embedded signature)
(sk *SessionKey) EncryptAndSign(message *PlainMessage, signKeyRing *KeyRing) ([]byte, error)
(sk *SessionKey) DecryptAndVerify(dataPacket []byte, verifyKeyRing *KeyRing, verifyTime int64) (*PlainMessage, error)
  • The mobile helper DecryptSessionKeyExplicitVerify to allow using session key decryption + verification operations via gomobile

[2.1.7] 2021-03-30

Added

  • ManualAttachmentProcessor: a new kind of attachment processor where the caller has to first allocate a buffer large enough for the whole data packet to be written to. It can be created with processor, err := keyRing.NewManualAttachmentProcessor(estimatedSize, filename, dataBuffer).

Fixed

  • Fix random failure in AES tests

Changed

  • Updated the x/mobile fork and the build script to work with golang 1.16

[2.1.6] 2021-03-17

Added

  • Decryption tests for attachments

Fixed

  • Armoring headers for public or private keys
  • Session key decoding on invalid keys
  • Support for multiple embedded signatures (not nested)

Security

  • Updated the underlying crypto library

[2.1.5] 2021-02-19

Changed

  • Removed an unnecessary cloning in the attachment processor, to perform better in low memory settings

[2.1.4] 2021-01-08

Added

  • Methods for generating an verifying encrypted detached signatures
(signingKeyRing *KeyRing) SignDetachedEncrypted(message *PlainMessage, encryptionKeyRing *KeyRing) (encryptedSignature *PGPMessage, err error)
(verifyingKeyRing *KeyRing) VerifyDetachedEncrypted(message *PlainMessage, encryptedSignature *PGPMessage, decryptionKeyRing *KeyRing, verifyTime int64) error

[2.1.3] 2020-12-09

Added

  • helper.FreeOSMemory() to explicitly call the GC and release the memory to the OS

Changed

  • Users of the library no longer need a replace directive for x/crypto
  • Added new calls to runtime.GC() in the low memory attachment processor
  • Reduced attachment memory allocation

[2.1.2] 2020-12-01

Added

  • SetKeyGenerationOffset to add an offset in key generation time and prevent not-yet-valid keys.

Changed

  • Improved canonicalization performance

[2.1.1] 2020-11-16

Changed

  • Session key decryption now considers multiple key packets

Fixed

  • Improved key parsing error handling

[2.1.0] 2020-11-04

Security

  • Updated underlying crypto library

Added

  • Key Armoring with custom headers
(key *Key) ArmorWithCustomHeaders(comment, version string) (string, error)
(key *Key) GetArmoredPublicKeyWithCustomHeaders(comment, version string) (string, error)
  • Message armoring with custom headers
(msg *PGPMessage) GetArmoredWithCustomHeaders(comment, version string) (string, error)
  • Extraction of encryption key IDs from a PGP message, i.e. the IDs of the keys used in the encryption of the session key
(msg *PGPMessage) GetEncryptionKeyIDs() ([]uint64, bool)
(msg *PGPMessage) GetHexEncryptionKeyIDs() ([]uint64, bool)
  • Extraction of signing key IDs from a PGP message, i.e. the IDs of the keys used in the signature of the message (of all the readable, unencrypted signature packets)
(msg *PGPMessage) GetSignatureKeyIDs() ([]uint64, bool)
(msg *PGPMessage) GetHexSignatureKeyIDs() ([]string, bool)
  • Getter for the x/crypto Entity (internal components of an OpenPGP key) from Key struct
(key *Key) GetEntity() *openpgp.Entity
  • Helpers for binary message encryption and decryption
EncryptBinaryMessageArmored(key string, data []byte) (string, error)
DecryptBinaryMessageArmored(privateKey string, passphrase []byte, ciphertext string) ([]byte, error)
  • Method to derive a public key object from a private key
(key *Key) ToPublic() (publicKey *Key, err error)
  • Helpers to handle encryption (both with armored and unarmored cipher) + encrypted detached signatures in one call.
EncryptSignArmoredDetached(
	publicKey, privateKey string,
	passphrase, plainData []byte,
) (ciphertextArmored, encryptedSignatureArmored string, err error)

DecryptVerifyArmoredDetached(
	publicKey, privateKey string,
	passphrase []byte,
	ciphertextArmored string,
	encryptedSignatureArmored string,
) (plainData []byte, err error)
EncryptSignBinaryDetached(
	publicKey, privateKey string,
	passphrase, plainData []byte,
) (encryptedData []byte, encryptedSignatureArmored string, err error)

DecryptVerifyBinaryDetached(
	publicKey, privateKey string,
	passphrase []byte,
	encryptedData []byte,
	encryptedSignatureArmored string,
) (plainData []byte, err error)
  • Wrappers for EncryptSignArmoredDetached and EncryptSignBinaryDetached helpers, to be usable with gomobile (that doesn't support multiple return values). These wrappers return custom structs instead.
type EncryptSignArmoredDetachedMobileResult struct {
	CiphertextArmored, EncryptedSignatureArmored string
}

EncryptSignArmoredDetachedMobile(
	publicKey, privateKey string,
	passphrase, plainData []byte,
) (wrappedTuple *EncryptSignArmoredDetachedMobileResult, err error)
type EncryptSignBinaryDetachedMobileResult struct {
	EncryptedData             []byte
	EncryptedSignatureArmored string
}

EncryptSignBinaryDetachedMobile(
	publicKey, privateKey string,
	passphrase, plainData []byte,
) (wrappedTuple *EncryptSignBinaryDetachedMobileResult, err error)
  • helpers to encrypt/decrypt session keys with armored keys:
EncryptSessionKey(
	publicKey string,
	sessionKey *crypto.SessionKey,
) (encryptedSessionKey []byte, err error)

DecryptSessionKey(
	privateKey string,
	passphrase, encryptedSessionKey []byte,
) (sessionKey *crypto.SessionKey, err error)
  • helpers to encrypt/decrypt binary files with armored keys:
EncryptAttachmentWithKey(
	publicKey string,
	filename string,
	plainData []byte,
) (message *crypto.PGPSplitMessage, err error)

DecryptAttachmentWithKey(
	privateKey string,
	passphrase, keyPacket, dataPacket []byte,
) (attachment []byte, err error)
  • NewPlainMessageFromFile Function to create new PlainMessages with a filename:
NewPlainMessageFromFile(data []byte, filename string, modTime int) *PlainMessage
  • GetFilename to get the filename from a message:
(msg *PlainMessage) GetFilename() string
  • GetModTime to get the modification time of a file
(msg *PlainMessage) GetModTime() uint32
  • EncryptWithCompression to encrypt specifying a compression for asymmetric and session keys
(keyRing *KeyRing) EncryptWithCompression(message *PlainMessage, privateKey *KeyRing) (*PGPMessage, error)

(sk *SessionKey) EncryptWithCompression(message *PlainMessage) ([]byte, error)

Changed

  • Improved key and message armoring testing
  • EncryptSessionKey now creates encrypted key packets for each valid encryption key in the provided keyring. Returns a byte slice with all the concatenated key packets.
  • Use aes256 cipher for password-encrypted messages.
  • The helpers EncryptSignMessageArmored, DecryptVerifyMessageArmored, DecryptVerifyAttachment, andDecryptBinaryMessageArmored now accept private keys as public keys and perform automatic casting if the keys are locked.
  • The PlainMessage struct now contains the fields Filename (string) and Time (uint32)
  • All the Decrypt* functions return the filename, type, and time specified in the encrypted message
  • Improved error wrapping and management
  • CI has been moved from travis to Actions, with automated artifacts build

Fixed

  • Public key armoring headers
  • EncryptSessionKey throws an error when invalid encryption keys are provided
  • Session keys' size is now checked against the expected value to prevent panics
  • Hex Key IDs returned from (key *Key) GetHexKeyID() string are now correctly padded
  • Avoid panics in (msg *PGPMessage) GetEncryptionKeyIDs() ([]uint64, bool) by breaking the packet.next cycle on specific packet types
  • Prevent the server time from going backwards in UpdateTime
  • Avoid panicking when messages with mixed symmetric/asymmetric key packets are decrypted with a password

[2.0.1] - 2020-05-01

Security

  • Updated underlying crypto library
  • Improved memory zeroing in helpers

Fixed

  • Fixed garbage collection issues when compiled on gomobile, by copying byte slices
  • Password encrypted binary files now have the correct flags
  • Fixed missing space in Hash header of cleartext messages
  • Fixed tests TestMultipleKeyMessageEncryption and TestSymmetricKeyPacket

Changed

  • Providing empty passphrase does no longer throw an error when unlocking an unencrypted private key
  • Improved code linter

Added

  • SHA256 fingerprint support
(key *Key) GetSHA256Fingerprints() (fingerprints []string)

// Helper
GetSHA256Fingerprints(publicKey string) ([]string, error)

// Helper, mobile only, returns fingerprints encoded as JSON
GetJsonSHA256Fingerprints(publicKey string) ([]byte, error)

[2.0.0] - 2020-01-06

Since the open-sourcing of the library in May the API has been updated, listening to internal and external feedback, in order to have a flexible library, that can be used in a simple settings, with batteries included, or by more advanced users that might want to interact directly with the inner structure of the PGP messages and keys.

It allows direct interaction with keys and keyrings, passphrases, as well as session keys. It is designed with gomobile users in mind, so that they can use the full power of the library, without having to rely on a further wrapper.

This version comes with some design improvements, in particular the introduction of keys

Security

  • Dropped the use of strings for secrets
  • New key checking functions
  • Clear memory after use, in an attempt to reduce leftover secrets in RAM.
  • Improved testing, in this and the underlying crypto library

Fixed

  • KeyRings can now only be unencrypted, removing the problem of mixed encrypted/decrypted keyring, that caused keys not to be recognised.
  • Explicit key decryption and encryption.
  • Underlying crypto library update.
  • Underlying MIME library update.
  • Fixed ECC critical bugs.
  • Removed gopenpgp/pmcrypto object as it could create multiple globals. Methods are now static on the crypto object.

Removed

  • Signature struct
  • Signature#KeyRing function
  • Signature#IsBy function
  • pmKeyObject struct
  • encodedLength function, internal and and unused
  • EncryptCore is now internal.
  • RandomTokenWith, RandomToken now takes a size
  • In the KeyRing struct:
    • KeyRing#GetEntities, entities are handled by the lib
    • KeyRing#GetSigningEntity, has been made internal
    • KeyRing#Unlock, the unlocking functionalities are on now on the key object
    • BuildKeyRingNoError, BuildKeyRingArmored, BuildKeyRing use NewKey or NewKeyFromArmored and handle errors then join them into KeyRings.
    • ReadKeyRing, ReadArmoredKeyRing, use NewKeyFromArmoredReader or NewKeyFromReader.
    • UnmarshalJSON, the interface to unmarshal JSON is not relevant to this library.

Added

  • Key struct, to store, import (unserialize) and export (serialize) keys.
// Key contains a single private or public key
type Key struct {
	// PGP entities in this keyring.
	entity *openpgp.Entity
}

// With the functions
NewKeyFromArmoredReader(r io.Reader) (key *Key, err error)
NewKeyFromReader(r io.Reader) (key *Key, err error)
NewKey(binKeys []byte) (key *Key, err error)
NewKeyFromArmored(armored string) (key *Key, err error)
GenerateKey(name, email string, keyType string, bits int) (*Key, error)
GenerateRSAKeyWithPrimes(name, email string, bits int, primeone, primetwo, primethree, primefour []byte) (*Key, error)
(key *Key) Clone() (*Key, error)
(key *Key) Lock(passphrase []byte) (*Key, error)
(key *Key) Unlock(passphrase []byte) (*Key, error)
(key *Key) Serialize() ([]byte, error)
(key *Key) Armor() (string, error)
(key *Key) GetArmoredPublicKey() (s string, err error)
(key *Key) GetPublicKey() (b []byte, err error)
(key *Key) IsExpired() bool
(key *Key) IsPrivate() bool
(key *Key) IsLocked() (bool, error)
(key *Key) IsUnlocked() (bool, error)
(key *Key) Check() (bool, error)
(key *Key) PrintFingerprints()
(key *Key) GetHexKeyID() string
(key *Key) GetKeyID() uint64
(key *Key) GetFingerprint() string
(key *Key) ClearPrivateParams() (ok bool)
  • In the KeyRing object:
NewKeyRing(key *Key) (*KeyRing, error)
(keyRing *KeyRing) AddKey(key *Key) error
(keyRing *KeyRing) GetKeys() []*Key
(keyRing *KeyRing) GetKey(n int) (*Key, error)
(keyRing *KeyRing) CountEntities() int
(keyRing *KeyRing) CountDecryptionEntities() int
(keyRing *KeyRing) GetIdentities() []*Identity
(keyRing *KeyRing) FirstKey() (*KeyRing, error)
(keyRing *KeyRing) Clone() (*KeyRing, error)
(keyRing *KeyRing) ClearPrivateParams()
  • PlainMessage struct, to store un-encrypted messages
// PlainMessage stores a plain text / unencrypted message.
type PlainMessage struct {
	// The content of the message
	Data []byte
	// if the content is text or binary
	TextType bool
}

// With the functions
NewPlainMessage(data []byte) *PlainMessage
NewPlainMessageFromString(text string) *PlainMessage
(msg *PlainMessage) GetBinary()
(msg *PlainMessage) GetString()
(msg *PlainMessage) GetBase64()
(msg *PlainMessage) NewReader()
(msg *PlainMessage) IsText()
(msg *PlainMessage) IsBinary()
  • PGPMessage struct, to store encrypted PGP messages
// PGPMessage stores a PGP-encrypted message.
type PGPMessage struct {
	// The content of the message
	Data []byte
}

// With the functions
NewPGPMessage(data []byte) *PGPMessage
NewPGPMessageFromArmored(armored string) (*PGPMessage, error)
(msg *PGPMessage) GetBinary() []byte 
(msg *PGPMessage) NewReader() io.Reader
(msg *PGPMessage) GetArmored() (string, error)
(msg *PGPMessage) SeparateKeyAndData(estimatedLength, garbageCollector int) (outSplit *PGPSplitMessage, err error)
  • PGPSignature struct, to store detached PGP signatures
// PGPSignature stores a PGP-encoded detached signature.
type PGPSignature struct {
	// The content of the message
	Data []byte
}

// With the functions
NewPGPSignature(data []byte) *PGPSignature
NewPGPSignatureFromArmored(armored string) (*PGPSignature, error) 
(msg *PGPSignature) GetBinary() []byte
(msg *PGPSignature) GetArmored() (string, error)
  • SignatureVerificationError struct, to separate signature verification errors from decryption errors
// SignatureVerificationError is returned from Decrypt and VerifyDetached functions when signature verification fails
type SignatureVerificationError struct {
	Status int
	Message string
}

Changed

  • IsKeyExpiredBin has been renamed to IsKeyExpired

  • IsKeyExpired has been renamed to IsArmoredKeyExpired

  • CheckKey has been renamed to PrintFingerprints

  • KeyRing#ArmoredPublicKeyString has been renamed to KeyRing#GetArmoredPublicKey

  • KeyRing#KeyIds has been renamed to KeyRing#GetKeyIDs

  • GetTimeUnix was renamed to GetUnixTime

  • EncryptedSplit has been changed to PGPSplitMessage

models.EncryptedSplit struct {
	DataPacket []byte
	KeyPacket  []byte
	Algo       string
}
// Is now
crypto.PGPSplitMessage struct {
	DataPacket []byte
	KeyPacket  []byte
}

// With the functions
NewPGPSplitMessage(keyPacket []byte, dataPacket []byte) *PGPSplitMessage
NewPGPSplitMessageFromArmored(encrypted string) (*PGPSplitMessage, error)
(msg *PGPSplitMessage) GetBinaryDataPacket() []byte
(msg *PGPSplitMessage) GetBinaryKeyPacket() []byte
(msg *PGPSplitMessage) GetBinary() []byte
(msg *PGPSplitMessage) GetArmored() (string, error)
  • DecryptSignedVerify has been changed to ExplicitVerifyMessage
models.DecryptSignedVerify struct {
	//clear text
	Plaintext string
	//bitmask verify status : 0
	Verify int
	//error message if verify failed
	Message string
}
// Is now
// ExplicitVerifyMessage contains explicitly the signature verification error, for gomobile users
type ExplicitVerifyMessage struct {
	Message *crypto.PlainMessage
	SignatureVerificationError *crypto.SignatureVerificationError
}
// With the new helper
DecryptExplicitVerify (pgpMessage *crypto.PGPMessage, privateKeyRing, publicKeyRing *crypto.KeyRing, verifyTime int64) (*ExplicitVerifyMessage, error)
  • SignedString has been changed to ClearTextMessage
// SignedString wraps string with Signature
type SignedString struct {
	String string
	Signed *Signature
}
// Is now
// ClearTextMessage, split signed clear text message container
type ClearTextMessage struct {
	Data []byte
	Signature []byte
}

// With the functions
NewClearTextMessage(data []byte, signature []byte) *ClearTextMessage
NewClearTextMessageFromArmored(signedMessage string) (*ClearTextMessage, error)
(msg *ClearTextMessage) GetBinary() []byte
(msg *ClearTextMessage) GetString() string
(msg *ClearTextMessage) GetBinarySignature() []byte
(msg *ClearTextMessage) GetArmored() (string, error)
  • SymmetricKey has been renamed to SessionKey
// SessionKey stores a decrypted session key.
type SessionKey struct {
	// The decrypted binary session key.
	Key []byte
	// The symmetric encryption algorithm used with this key.
	Algo string
}

// With the functions
NewSessionKeyFromToken(token []byte, algo string) *SessionKey
GenerateSessionKey() (*SessionKey, error)
GenerateSessionKeyAlgo(algo string) (sk *SessionKey, err error)
(sk *SessionKey) GetCipherFunc() packet.CipherFunction 
(sk *SessionKey) GetBase64Key() string
(sk *SessionKey) Encrypt(message *PlainMessage) ([]byte, error)
(sk *SessionKey) Decrypt(dataPacket []byte) (*PlainMessage, error)
(sk *SessionKey) Clear() (ok bool)
  • ReadClearSignedMessage moved to crypto package and renamed to NewClearTextMessageFromArmored. Changed to return ClearTextMessage.
ReadClearSignedMessage(signedMessage string) (string, error)
// Is now
NewClearTextMessageFromArmored(signedMessage string) (*ClearTextMessage, error)

// In addition, were added:
NewClearTextMessage(data []byte, signature []byte) *ClearTextMessage
(msg *ClearTextMessage) GetBinary() []byte
(msg *ClearTextMessage) GetString() string
(msg *ClearTextMessage) GetBinarySignature() []byte
(msg *ClearTextMessage) GetArmored() (string, error)

// As helpers were added:
SignCleartextMessageArmored(privateKey string, passphrase []byte, text string) (string, error)
VerifyCleartextMessageArmored(publicKey, armored string, verifyTime int64) (string, error)
SignCleartextMessage(keyRing *crypto.KeyRing, text string) (string, error)
VerifyCleartextMessage(keyRing *crypto.KeyRing, armored string, verifyTime int64) (string, error)
  • EncryptAttachment's parameters are changed to messages.
(pm *PmCrypto) EncryptAttachment(plainData []byte, fileName string, publicKey *KeyRing) (*models.EncryptedSplit, error)
// Is now
(keyRing *KeyRing) EncryptAttachment(message *PlainMessage, fileName string) (*PGPSplitMessage, error)

// As a helper was added:
EncryptSignAttachment(publicKey, privateKey string, passphrase []byte, fileName string, plainData []byte) (keyPacket, dataPacket, signature []byte, err error)
  • DecryptAttachment has been moved to KeyRing struct (like EncryptAttachment)
(pm *PmCrypto) DecryptAttachment(keyPacket []byte, dataPacket []byte, kr *KeyRing, passphrase string) ([]byte, error)
// Is now
(keyRing *KeyRing) DecryptAttachment(message *PGPSplitMessage) (*PlainMessage, error)

// As a helper was added:
DecryptVerifyAttachment(publicKey, privateKey string, passphrase, keyPacket, dataPacket []byte, armoredSignature string) (plainData []byte, err error)
  • EncryptAttachmentLowMemory was renamed to NewLowMemoryAttachmentProcessor.
(pm *PmCrypto) EncryptAttachmentLowMemory(estimatedSize int, fileName string, publicKey *KeyRing) (*AttachmentProcessor, error)
// Is now
(keyRing *KeyRing) NewLowMemoryAttachmentProcessor(estimatedSize int, fileName string) (*AttachmentProcessor, error)
  • SplitArmor was renamed to NewPGPSplitMessageFromArmored and the model changed.
SplitArmor(encrypted string) (*models.EncryptedSplit, error)
// Is now
NewPGPSplitMessageFromArmored(encrypted string) (*PGPSplitMessage, error)
  • DecryptAttKey was renamed to DecryptSessionKey and the parameter keypacket changed to []byte as it's binary, not armored.
DecryptAttKey(kr *KeyRing, keyPacket string) (key *SymmetricKey, err error):
// Is now
(keyRing *KeyRing) DecryptSessionKey(keyPacket []byte) (*SessionKey, error)
  • SetKey has been renamed to EncryptSessionKey, and the keypacket return value changed to []byte.
SetKey(kr *KeyRing, symKey *SymmetricKey) (packets string, err error):
// Is now
(keyRing *KeyRing) EncryptSessionKey(sessionSplit *SessionKey) ([]byte, error)
  • SeparateKeyAndData has been split in two different function, as it did not only separate the data, but when provided a KeyRing decrypted the session key too.
SeparateKeyAndData(kr *KeyRing, r io.Reader, estimatedLength int, garbageCollector int) (outSplit *models.EncryptedSplit, err error):

// Is now the conjunction of the following function:
// To separate key and data
(msg *PGPMessage) SeparateKeyAndData(estimatedLength, garbageCollector int) (outSplit *PGPSplitMessage, err error)
// To decrypt the SessionKey
(keyRing *KeyRing) DecryptSessionKey(keyPacket []byte) (*SessionKey, error)
  • EncryptSymmetric has been changed, now the procedure is split in two parts: Encrypt and SeparateKeyAndData
(kr *KeyRing) EncryptSymmetric(textToEncrypt string, canonicalizeText bool) (outSplit *models.EncryptedSplit, err error):
// Is now the conjunction of the following function:
// To encrypt
(keyRing *KeyRing) Encrypt(message *PlainMessage, privateKey *KeyRing) (*PGPMessage, error)
// To separate key and data
(msg *PGPMessage) SeparateKeyAndData(estimatedLength, garbageCollector int) (outSplit *PGPSplitMessage, err error)
  • GenerateKey's signature has been altered:
    • It now returns a Key struct
    • userName and domain are now joined in email, the name parameter was added (To emulate the old behaviour name = email = userName + "@" + domain).
(pm *PmCrypto) GenerateKey(userName, domain, passphrase, keyType string, bits int) (string, error) :
// Is now
GenerateKey(name, email string, keyType string, bits int) (*Key, error)

// As a helper was added:
GenerateKey(name, email string, passphrase []byte, keyType string, bits int) (string, error)
  • GenerateRSAKeyWithPrimes's signature has been altered:
    • It now returns a Key struct
    • userName and domain are now joined in email, the name parameter was added (To emulate the old behaviour name = email = userName + "@" + domain).
(pm *PmCrypto) GenerateRSAKeyWithPrimes(userName, domain, passphrase, keyType string, bits int, prime1, prime2, prime3, prime4 []byte) (string, error):
GenerateRSAKeyWithPrimes(name, email string, bits int, primeone, primetwo, primethree, primefour []byte,) (*Key, error)
  • Encrypt, EncryptArmored, EncryptString, EncryptMessage functions have been changed to return and accept messages.
(kr *KeyRing) Encrypt(w io.Writer, sign *KeyRing, filename string, canonicalizeText bool) (io.WriteCloser, error)
// Is now
(keyRing *KeyRing) Encrypt(message *PlainMessage, privateKey *KeyRing) (*PGPMessage, error)

// As a helpers were added:
EncryptMessageArmored(publicKey, plaintext string) (ciphertext string, err error)
EncryptSignMessageArmored(publicKey, privateKey string, passphrase []byte, plaintext string) (ciphertext string, err error) {
  • Decrypt, DecryptArmored, DecryptString, DecryptMessage, DecryptMessageVerify, and DecryptMessageStringKey functions have been changed to return and accept messages (Same as Encrypt*). If signature verification fails they will return a SignatureVerificationError.
(kr *KeyRing) DecryptString(encrypted string) (SignedString, error)
// Is now
(keyRing *KeyRing) Decrypt(message *PGPMessage, verifyKey *KeyRing, verifyTime int64) (*PlainMessage, error)

// As a helpers were added:
DecryptMessageArmored(privateKey string, passphrase []byte, ciphertext string) (plaintext string, err error)
DecryptVerifyMessageArmored(publicKey, privateKey string, passphrase []byte, ciphertext string) (plaintext string, err error)
DecryptExplicitVerify(pgpMessage *crypto.PGPMessage, privateKeyRing, publicKeyRing *crypto.KeyRing, verifyTime int64) (*ExplicitVerifyMessage, error) {
  • DecryptStringIfNeeded has been replaced with IsPGPMessage + Decrypt*.
(kr *KeyRing) DecryptStringIfNeeded(data string) (decrypted string, err error)
// Is now the conjunction of the following function:
// To check if the data is a PGP message
IsPGPMessage(data string) bool
// To decrypt
(keyRing *KeyRing) Decrypt(message *PGPMessage, verifyKey *KeyRing, verifyTime int64) (*PlainMessage, error)
  • SignString and DetachedSign have been replaced by signing methods.
(kr *KeyRing) SignString(message string, canonicalizeText bool) (signed string, err error)
(kr *KeyRing) DetachedSign(w io.Writer, toSign io.Reader, canonicalizeText bool, armored bool)
// Are now
(keyRing *KeyRing) SignDetached(message *PlainMessage) (*PGPSignature, error)
  • VerifyString has been altered in the same way as as signing. Returns SignatureVerificationError if the verification fails.
(kr *KeyRing) VerifyString(message, signature string, sign *KeyRing) (err error)
// Is now
(keyRing *KeyRing) VerifyDetached(message *PlainMessage, signature *PGPSignature, verifyTime int64) error
  • EncryptMessageWithPassword uses AES-256 instead of AES-128, and has a new signature.
(pm *PmCrypto) EncryptMessageWithPassword(plaintext string, password string) (string, error)
// Is now
EncryptMessageWithPassword(message *PlainMessage, password []byte) (*PGPMessage, error)

// As a helper was added:
EncryptMessageWithPassword(password []byte, plaintext string) (ciphertext string, err error)
  • DecryptMessageWithPassword accepts all symmetric algorithms known to the lib, and has a new signature
(pm *PmCrypto) DecryptMessageWithPassword(encrypted string, password string) (string, error)
// Is now
DecryptMessageWithPassword(message *PGPMessage, password []byte) (*PlainMessage, error)

// As a helper was added:
DecryptMessageWithPassword(password []byte, ciphertext string) (plaintext string, err error)
  • DecryptMIMEMessage was moved to KeyRing, and the parameters transformed to messages
(pm *PmCrypto) DecryptMIMEMessage(encryptedText string, verifierKey *KeyRing, privateKeyRing *KeyRing, passphrase string, callbacks MIMECallbacks, verifyTime int64):
// Is now
(keyRing *KeyRing) DecryptMIMEMessage(message *PGPMessage, verifyKey *KeyRing, callbacks MIMECallbacks, verifyTime int64)
  • RandomToken now takes a size
(pm *PmCrypto) RandomToken() ([]byte, error)
// Is now
RandomToken(size int) ([]byte, error)
  • GetSessionFromKeyPacket was changed to DecryptSessionKey.
(pm *PmCrypto) GetSessionFromKeyPacket(keyPackage []byte, privateKey *KeyRing, passphrase string) (*SymmetricKey, error)
// Is now
(keyRing *KeyRing) DecryptSessionKey(keyPacket []byte) (*SessionKey, error)
  • KeyPacketWithPublicKey and KeyPacketWithPublicKeyBin have been merged to EncryptSessionKey.
(pm *PmCrypto) KeyPacketWithPublicKey(sessionSplit *SymmetricKey, publicKey string) ([]byte, error)
(pm *PmCrypto) KeyPacketWithPublicKeyBin(sessionSplit *SymmetricKey, publicKey []byte) ([]byte, error)
(keyRing *KeyRing) EncryptSessionKey(sk *SessionKey) ([]byte, error)
  • GetSessionFromSymmetricPacket was renamed to DecryptSessionKeyWithPassword.
(pm *PmCrypto) GetSessionFromSymmetricPacket(keyPackage []byte, password string) (*SymmetricKey, error)
// Is now
DecryptSessionKeyWithPassword(keyPacket, password []byte) (*SessionKey, error)
  • SymmetricKeyPacketWithPassword has been renamed to EncryptSessionKeyWithPassword
(pm *PmCrypto) SymmetricKeyPacketWithPassword(sessionSplit *SymmetricKey, password string) ([]byte, error):
EncryptSessionKeyWithPassword(sk *SessionKey, password []byte]) ([]byte, error)
  • SignTextDetached and SignBinDetached have been changed to SignDetached
(pm *PmCrypto) SignTextDetached(plaintext string, privateKey *KeyRing, passphrase string, trim bool) (string, error)
(pm *PmCrypto) SignBinDetached(plainData []byte, privateKey *KeyRing, passphrase string) (string, error)
// Are now
(keyRing *KeyRing) SignDetached(message *PlainMessage) (*PGPSignature, error)

// As helpers were added:
SignCleartextMessage(keyRing *crypto.KeyRing, text string) (string, error) 
SignCleartextMessageArmored(privateKey string, passphrase []byte, text string) (string, error)
  • VerifyTextSignDetachedBinKey and VerifyBinSignDetachedBinKey have been changed to Verify.
(pm *PmCrypto) VerifyTextSignDetachedBinKey(signature string, plaintext string, publicKey *KeyRing, verifyTime int64) (bool, error):
(pm *PmCrypto) VerifyBinSignDetachedBinKey(signature string, plainData []byte, publicKey *KeyRing, verifyTime int64) (bool, error)
// Are now
(keyRing *KeyRing) VerifyDetached(message *PlainMessage, signature *PGPSignature, verifyTime int64) error

// As helpers were added:
VerifyCleartextMessage(keyRing *crypto.KeyRing, armored string, verifyTime int64) (string, error)
VerifyCleartextMessageArmored(publicKey, armored string, verifyTime int64) (string, error)

[1.0.0] - 2019-05-15

Initial release, opensourcing of the internal library PMCrypto, and subsequent renaming to gopenpgp