openpgp

package
v1.1.0-alpha.1-proton Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 28, 2024 License: BSD-3-Clause Imports: 26 Imported by: 316

Documentation

Overview

Package openpgp implements high level operations on OpenPGP messages.

Index

Constants

This section is empty.

Variables

View Source 
var PrivateKeyType = "PGP PRIVATE KEY BLOCK"

PrivateKeyType is the armor type for a PGP private key.

View Source 
var PublicKeyType = "PGP PUBLIC KEY BLOCK"

PublicKeyType is the armor type for a PGP public key.

View Source 
var SignatureType = "PGP SIGNATURE"

SignatureType is the armor type for a PGP signature.

Functions

func ArmoredDetachSign 

func ArmoredDetachSign(w io.Writer, signer *Entity, message io.Reader, config *packet.Config) (err error)

ArmoredDetachSign signs message with the private key from signer (which must already have been decrypted) and writes an armored signature to w. If config is nil, sensible defaults will be used.

func ArmoredDetachSignText 

func ArmoredDetachSignText(w io.Writer, signer *Entity, message io.Reader, config *packet.Config) error

ArmoredDetachSignText signs message (after canonicalising the line endings) with the private key from signer (which must already have been decrypted) and writes an armored signature to w. If config is nil, sensible defaults will be used.

func DetachSign 

func DetachSign(w io.Writer, signer *Entity, message io.Reader, config *packet.Config) error

DetachSign signs message with the private key from signer (which must already have been decrypted) and writes the signature to w. If config is nil, sensible defaults will be used.

func DetachSignText 

func DetachSignText(w io.Writer, signer *Entity, message io.Reader, config *packet.Config) error

DetachSignText signs message (after canonicalising the line endings) with the private key from signer (which must already have been decrypted) and writes the signature to w. If config is nil, sensible defaults will be used.

func Encrypt 

func Encrypt(ciphertext io.Writer, to []*Entity, signed *Entity, hints *FileHints, config *packet.Config) (plaintext io.WriteCloser, err error)

Encrypt encrypts a message to a number of recipients and, optionally, signs it. hints contains optional information, that is also encrypted, that aids the recipients in processing the message. The resulting WriteCloser must be closed after the contents of the file have been written. If config is nil, sensible defaults will be used.

func EncryptSplit 

func EncryptSplit(keyWriter io.Writer, dataWriter io.Writer, to []*Entity, signed *Entity, hints *FileHints, config *packet.Config) (plaintext io.WriteCloser, err error)

EncryptSplit encrypts a message to a number of recipients and, optionally, signs it. hints contains optional information, that is also encrypted, that aids the recipients in processing the message. The resulting WriteCloser must be closed after the contents of the file have been written. If config is nil, sensible defaults will be used.

func EncryptText 

func EncryptText(ciphertext io.Writer, to []*Entity, signed *Entity, hints *FileHints, config *packet.Config) (plaintext io.WriteCloser, err error)

EncryptText encrypts a message to a number of recipients and, optionally, signs it. Optional information is contained in 'hints', also encrypted, that aids the recipients in processing the message. The resulting WriteCloser must be closed after the contents of the file have been written. If config is nil, sensible defaults will be used. The signing is done in text mode.

func EncryptTextSplit 

func EncryptTextSplit(keyWriter io.Writer, dataWriter io.Writer, to []*Entity, signed *Entity, hints *FileHints, config *packet.Config) (plaintext io.WriteCloser, err error)

EncryptTextSplit encrypts a message to a number of recipients and, optionally, signs it. hints contains optional information, that is also encrypted, that aids the recipients in processing the message. The resulting WriteCloser must be closed after the contents of the file have been written. If config is nil, sensible defaults will be used.

func HashIdToHash 

func HashIdToHash(id byte) (h crypto.Hash, ok bool)

HashIdToHash returns a crypto.Hash which corresponds to the given OpenPGP hash id.

func HashIdToString 

func HashIdToString(id byte) (name string, ok bool)

HashIdToString returns the name of the hash function corresponding to the given OpenPGP hash id.

func HashToHashId 

func HashToHashId(h crypto.Hash) (id byte, ok bool)

HashToHashId returns an OpenPGP hash id which corresponds the given Hash.

func NewCanonicalTextHash 

func NewCanonicalTextHash(h hash.Hash) hash.Hash

NewCanonicalTextHash reformats text written to it into the canonical form and then applies the hash h. See RFC 4880, section 5.2.1.

func Sign 

func Sign(output io.Writer, signed *Entity, hints *FileHints, config *packet.Config) (input io.WriteCloser, err error)

Sign signs a message. The resulting WriteCloser must be closed after the contents of the file have been written. hints contains optional information that aids the recipients in processing the message. If config is nil, sensible defaults will be used.

func SymmetricallyEncrypt 

func SymmetricallyEncrypt(ciphertext io.Writer, passphrase []byte, hints *FileHints, config *packet.Config) (plaintext io.WriteCloser, err error)

SymmetricallyEncrypt acts like gpg -c: it encrypts a file with a passphrase. The resulting WriteCloser must be closed after the contents of the file have been written. If config is nil, sensible defaults will be used.

Types

type Entity 

type Entity struct {
	PrimaryKey    *packet.PublicKey
	PrivateKey    *packet.PrivateKey
	Identities    map[string]*Identity // indexed by Identity.Name
	Revocations   []*packet.Signature
	Subkeys       []Subkey
	SelfSignature *packet.Signature   // Direct-key self signature of the PrimaryKey (contains primary key properties in v6)
	Signatures    []*packet.Signature // all (potentially unverified) self-signatures, revocations, and third-party signatures
}

An Entity represents the components of an OpenPGP key: a primary public key (which must be a signing key), one or more identities claimed by that key, and zero or more subkeys, which may be encryption keys.

func CheckArmoredDetachedSignature 

func CheckArmoredDetachedSignature(keyring KeyRing, signed, signature io.Reader, config *packet.Config) (signer *Entity, err error)

CheckArmoredDetachedSignature performs the same actions as CheckDetachedSignature but expects the signature to be armored.

func CheckDetachedSignature 

func CheckDetachedSignature(keyring KeyRing, signed, signature io.Reader, config *packet.Config) (signer *Entity, err error)

CheckDetachedSignature takes a signed file and a detached signature and returns the entity the signature was signed by, if any, and a possible signature verification error. If the signer isn't known, ErrUnknownIssuer is returned.

func CheckDetachedSignatureAndHash 

func CheckDetachedSignatureAndHash(keyring KeyRing, signed, signature io.Reader, expectedHashes []crypto.Hash, config *packet.Config) (signer *Entity, err error)

CheckDetachedSignatureAndHash performs the same actions as CheckDetachedSignature and checks that the expected hash functions were used.

func NewEntity 

func NewEntity(name, comment, email string, config *packet.Config) (*Entity, error)

NewEntity returns an Entity that contains a fresh RSA/RSA keypair with a single identity composed of the given full name, comment and email, any of which may be empty but must not contain any of "()<>\x00". If config is nil, sensible defaults will be used.

func ReadEntity 

func ReadEntity(packets *packet.Reader) (*Entity, error)

ReadEntity reads an entity (public key, identities, subkeys etc) from the given Reader.

func VerifyDetachedSignature 

func VerifyDetachedSignature(keyring KeyRing, signed, signature io.Reader, config *packet.Config) (sig *packet.Signature, signer *Entity, err error)

VerifyDetachedSignature takes a signed file and a detached signature and returns the signature packet and the entity the signature was signed by, if any, and a possible signature verification error. If the signer isn't known, ErrUnknownIssuer is returned.

func VerifyDetachedSignatureAndHash 

func VerifyDetachedSignatureAndHash(keyring KeyRing, signed, signature io.Reader, expectedHashes []crypto.Hash, config *packet.Config) (sig *packet.Signature, signer *Entity, err error)

VerifyDetachedSignatureAndHash performs the same actions as VerifyDetachedSignature and checks that the expected hash functions were used.

func (*Entity) AddEncryptionSubkey 

func (e *Entity) AddEncryptionSubkey(config *packet.Config) error

AddEncryptionSubkey adds an encryption keypair as a subkey to the Entity. If config is nil, sensible defaults will be used.

func (*Entity) AddSigningSubkey 

func (e *Entity) AddSigningSubkey(config *packet.Config) error

AddSigningSubkey adds a signing keypair as a subkey to the Entity. If config is nil, sensible defaults will be used.

func (*Entity) AddUserId 

func (t *Entity) AddUserId(name, comment, email string, config *packet.Config) error

func (*Entity) CertificationKey 

func (e *Entity) CertificationKey(now time.Time) (Key, bool)

CertificationKey return the best candidate Key for certifying a key with this Entity.

func (*Entity) CertificationKeyById 

func (e *Entity) CertificationKeyById(now time.Time, id uint64) (Key, bool)

CertificationKeyById return the Key for key certification with this Entity and keyID.

func (*Entity) DecryptPrivateKeys 

func (e *Entity) DecryptPrivateKeys(passphrase []byte) error

DecryptPrivateKeys decrypts all encrypted keys in the entity with the given passphrase. Avoids recomputation of similar s2k key derivations. Public keys and dummy keys are ignored, and don't cause an error to be returned.

func (*Entity) EncryptPrivateKeys 

func (e *Entity) EncryptPrivateKeys(passphrase []byte, config *packet.Config) error

EncryptPrivateKeys encrypts all non-encrypted keys in the entity with the same key derived from the provided passphrase. Public keys and dummy keys are ignored, and don't cause an error to be returned.

func (*Entity) EncryptionKey 

func (e *Entity) EncryptionKey(now time.Time) (Key, bool)

EncryptionKey returns the best candidate Key for encrypting a message to the given Entity.

func (*Entity) NewForwardingEntity 

func (e *Entity) NewForwardingEntity(
	name, comment, email string, config *packet.Config, strict bool,
) (
	forwardeeKey *Entity, instances []packet.ForwardingInstance, err error,
)

NewForwardingEntity generates a new forwardee key and derives the proxy parameters from the entity e. If strict, it will return an error if encryption-capable non-revoked subkeys with a wrong algorithm are found, instead of ignoring them

func (*Entity) PrimaryIdentity 

func (e *Entity) PrimaryIdentity() *Identity

PrimaryIdentity returns an Identity, preferring non-revoked identities, identities marked as primary, or the latest-created identity, in that order.

func (*Entity) PrimarySelfSignature added in v1.1.0 

func (e *Entity) PrimarySelfSignature() (*packet.Signature, *Identity)

PrimarySelfSignature searches the entity for the self-signature that stores key preferences. For V4 keys, returns the self-signature of the primary identity, and the identity. For V6 keys, returns the latest valid direct-key self-signature, and no identity (nil). This self-signature is to be used to check the key expiration, algorithm preferences, and so on.

func (*Entity) RevokeKey 

func (e *Entity) RevokeKey(reason packet.ReasonForRevocation, reasonText string, config *packet.Config) error

RevokeKey generates a key revocation signature (packet.SigTypeKeyRevocation) with the specified reason code and text (RFC4880 section-5.2.3.23). If config is nil, sensible defaults will be used.

func (*Entity) RevokeSubkey 

func (e *Entity) RevokeSubkey(sk *Subkey, reason packet.ReasonForRevocation, reasonText string, config *packet.Config) error

RevokeSubkey generates a subkey revocation signature (packet.SigTypeSubkeyRevocation) for a subkey with the specified reason code and text (RFC4880 section-5.2.3.23). If config is nil, sensible defaults will be used.

func (*Entity) Revoked 

func (e *Entity) Revoked(now time.Time) bool

Revoked returns whether the entity has any direct key revocation signatures. Note that third-party revocation signatures are not supported. Note also that Identity and Subkey revocation should be checked separately.

func (*Entity) Serialize 

func (e *Entity) Serialize(w io.Writer) error

Serialize writes the public part of the given Entity to w, including signatures from other entities. No private key material will be output.

func (*Entity) SerializePrivate 

func (e *Entity) SerializePrivate(w io.Writer, config *packet.Config) (err error)

SerializePrivate serializes an Entity, including private key material, but excluding signatures from other entities, to the given Writer. Identities and subkeys are re-signed in case they changed since NewEntry. If config is nil, sensible defaults will be used.

func (*Entity) SerializePrivateWithoutSigning 

func (e *Entity) SerializePrivateWithoutSigning(w io.Writer, config *packet.Config) (err error)

SerializePrivateWithoutSigning serializes an Entity, including private key material, but excluding signatures from other entities, to the given Writer. Self-signatures of identities and subkeys are not re-signed. This is useful when serializing GNU dummy keys, among other things. If config is nil, sensible defaults will be used.

func (*Entity) SignIdentity 

func (e *Entity) SignIdentity(identity string, signer *Entity, config *packet.Config) error

SignIdentity adds a signature to e, from signer, attesting that identity is associated with e. The provided identity must already be an element of e.Identities and the private key of signer must have been decrypted if necessary. If config is nil, sensible defaults will be used.

func (*Entity) SigningKey 

func (e *Entity) SigningKey(now time.Time) (Key, bool)

SigningKey return the best candidate Key for signing a message with this Entity.

func (*Entity) SigningKeyById 

func (e *Entity) SigningKeyById(now time.Time, id uint64) (Key, bool)

SigningKeyById return the Key for signing a message with this Entity and keyID.

type EntityList 

type EntityList []*Entity

An EntityList contains one or more Entities.

func ReadArmoredKeyRing 

func ReadArmoredKeyRing(r io.Reader) (EntityList, error)

ReadArmoredKeyRing reads one or more public/private keys from an armor keyring file.

func ReadKeyRing 

func ReadKeyRing(r io.Reader) (el EntityList, err error)

ReadKeyRing reads one or more public/private keys. Unsupported keys are ignored as long as at least a single valid key is found.

func (EntityList) DecryptionKeys 

func (el EntityList) DecryptionKeys() (keys []Key)

DecryptionKeys returns all private keys that are valid for decryption.

func (EntityList) KeysById 

func (el EntityList) KeysById(id uint64) (keys []Key)

KeysById returns the set of keys that have the given key id.

func (EntityList) KeysByIdUsage 

func (el EntityList) KeysByIdUsage(id uint64, requiredUsage byte) (keys []Key)

KeysByIdAndUsage returns the set of keys with the given id that also meet the key usage given by requiredUsage. The requiredUsage is expressed as the bitwise-OR of packet.KeyFlag* values.

type FileHints 

type FileHints struct {
	// IsBinary can be set to hint that the contents are binary data.
	IsBinary bool
	// FileName hints at the name of the file that should be written. It's
	// truncated to 255 bytes if longer. It may be empty to suggest that the
	// file should not be written to disk. It may be equal to "_CONSOLE" to
	// suggest the data should not be written to disk.
	FileName string
	// ModTime contains the modification time of the file, or the zero time if not applicable.
	ModTime time.Time
}

FileHints contains metadata about encrypted files. This metadata is, itself, encrypted.

type Identity 

type Identity struct {
	Name          string // by convention, has the form "Full Name (comment) <email@example.com>"
	UserId        *packet.UserId
	SelfSignature *packet.Signature
	Revocations   []*packet.Signature
	Signatures    []*packet.Signature // all (potentially unverified) self-signatures, revocations, and third-party signatures
}

An Identity represents an identity claimed by an Entity and zero or more assertions by other entities about that claim.

func (*Identity) Revoked 

func (i *Identity) Revoked(now time.Time) bool

Revoked returns whether the identity has been revoked by a self-signature. Note that third-party revocation signatures are not supported.

type Key 

type Key struct {
	Entity        *Entity
	PublicKey     *packet.PublicKey
	PrivateKey    *packet.PrivateKey
	SelfSignature *packet.Signature
	Revocations   []*packet.Signature
}

A Key identifies a specific public key in an Entity. This is either the Entity's primary key or a subkey.

func (*Key) Revoked 

func (key *Key) Revoked(now time.Time) bool

Revoked returns whether the key or subkey has been revoked by a self-signature. Note that third-party revocation signatures are not supported. Note also that Identity revocation should be checked separately. Normally, it's not necessary to call this function, except on keys returned by KeysById or KeysByIdUsage.

type KeyRing 

type KeyRing interface {
	// KeysById returns the set of keys that have the given key id.
	KeysById(id uint64) []Key
	// KeysByIdAndUsage returns the set of keys with the given id
	// that also meet the key usage given by requiredUsage.
	// The requiredUsage is expressed as the bitwise-OR of
	// packet.KeyFlag* values.
	KeysByIdUsage(id uint64, requiredUsage byte) []Key
	// DecryptionKeys returns all private keys that are valid for
	// decryption.
	DecryptionKeys() []Key
}

A KeyRing provides access to public and private keys.

type MessageDetails 

type MessageDetails struct {
	IsEncrypted              bool                // true if the message was encrypted.
	EncryptedToKeyIds        []uint64            // the list of recipient key ids.
	IsSymmetricallyEncrypted bool                // true if a passphrase could have decrypted the message.
	DecryptedWith            Key                 // the private key used to decrypt the message, if any.
	IsSigned                 bool                // true if the message is signed.
	SignedByKeyId            uint64              // the key id of the signer, if any.
	SignedByFingerprint      []byte              // the key fingerprint of the signer, if any.
	SignedBy                 *Key                // the key of the signer, if available.
	LiteralData              *packet.LiteralData // the metadata of the contents
	UnverifiedBody           io.Reader           // the contents of the message.

	// If IsSigned is true and SignedBy is non-zero then the signature will
	// be verified as UnverifiedBody is read. The signature cannot be
	// checked until the whole of UnverifiedBody is read so UnverifiedBody
	// must be consumed until EOF before the data can be trusted. Even if a
	// message isn't signed (or the signer is unknown) the data may contain
	// an authentication code that is only checked once UnverifiedBody has
	// been consumed. Once EOF has been seen, the following fields are
	// valid. (An authentication code failure is reported as a
	// SignatureError error when reading from UnverifiedBody.)
	Signature            *packet.Signature   // the signature packet itself.
	SignatureError       error               // nil if the signature is good.
	UnverifiedSignatures []*packet.Signature // all other unverified signature packets.
	// contains filtered or unexported fields
}

MessageDetails contains the result of parsing an OpenPGP encrypted and/or signed message.

func ReadMessage 

func ReadMessage(r io.Reader, keyring KeyRing, prompt PromptFunction, config *packet.Config) (md *MessageDetails, err error)

ReadMessage parses an OpenPGP message that may be signed and/or encrypted. The given KeyRing should contain both public keys (for signature verification) and, possibly encrypted, private keys for decrypting. If config is nil, sensible defaults will be used.

type PromptFunction 

type PromptFunction func(keys []Key, symmetric bool) ([]byte, error)

A PromptFunction is used as a callback by functions that may need to decrypt a private key, or prompt for a passphrase. It is called with a list of acceptable, encrypted private keys and a boolean that indicates whether a passphrase is usable. It should either decrypt a private key or return a passphrase to try. If the decrypted private key or given passphrase isn't correct, the function will be called again, forever. Any error returned will be passed up.

type Subkey 

type Subkey struct {
	PublicKey   *packet.PublicKey
	PrivateKey  *packet.PrivateKey
	Sig         *packet.Signature
	Revocations []*packet.Signature
}

A Subkey is an additional public key in an Entity. Subkeys can be used for encryption.

func (*Subkey) Revoked 

func (s *Subkey) Revoked(now time.Time) bool

Revoked returns whether the subkey has been revoked by a self-signature. Note that third-party revocation signatures are not supported.

Source Files

View all Source files

Directories

Path Synopsis
aes
keywrap
Package keywrap is an implementation of the RFC 3394 AES key wrapping algorithm.
 Package keywrap is an implementation of the RFC 3394 AES key wrapping algorithm.
Package armor implements OpenPGP ASCII Armor, see RFC 4880.
 Package armor implements OpenPGP ASCII Armor, see RFC 4880.
Package clearsign generates and processes OpenPGP, clear-signed data.
 Package clearsign generates and processes OpenPGP, clear-signed data.
Package ecdh implements ECDH encryption, suitable for OpenPGP, as specified in RFC 6637, section 8.
 Package ecdh implements ECDH encryption, suitable for OpenPGP, as specified in RFC 6637, section 8.
Package ecdsa implements ECDSA signature, suitable for OpenPGP, as specified in RFC 6637, section 5.
 Package ecdsa implements ECDSA signature, suitable for OpenPGP, as specified in RFC 6637, section 5.
Package ed25519 implements the ed25519 signature algorithm for OpenPGP as defined in the Open PGP crypto refresh.
 Package ed25519 implements the ed25519 signature algorithm for OpenPGP as defined in the Open PGP crypto refresh.
Package ed448 implements the ed448 signature algorithm for OpenPGP as defined in the Open PGP crypto refresh.
 Package ed448 implements the ed448 signature algorithm for OpenPGP as defined in the Open PGP crypto refresh.
Package eddsa implements EdDSA signature, suitable for OpenPGP, as specified in https://datatracker.ietf.org/doc/html/draft-ietf-openpgp-crypto-refresh-06#section-13.7
 Package eddsa implements EdDSA signature, suitable for OpenPGP, as specified in https://datatracker.ietf.org/doc/html/draft-ietf-openpgp-crypto-refresh-06#section-13.7
Package elgamal implements ElGamal encryption, suitable for OpenPGP, as specified in "A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms," IEEE Transactions on Information Theory, v.
 Package elgamal implements ElGamal encryption, suitable for OpenPGP, as specified in "A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms," IEEE Transactions on Information Theory, v.
Package errors contains common error types for the OpenPGP packages.
 Package errors contains common error types for the OpenPGP packages.
internal
algorithm
ecc
Package ecc implements a generic interface for ECDH, ECDSA, and EdDSA.
 Package ecc implements a generic interface for ECDH, ECDSA, and EdDSA.
ecc/curve25519
Package curve25519 implements custom field operations without clamping for forwarding.
 Package curve25519 implements custom field operations without clamping for forwarding.
ecc/curve25519/field
Package field implements fast arithmetic modulo 2^255-19.
 Package field implements fast arithmetic modulo 2^255-19.
encoding
Package encoding implements openpgp packet field encodings as specified in RFC 4880 and 6637.
 Package encoding implements openpgp packet field encodings as specified in RFC 4880 and 6637.
Package packet implements parsing and serialization of OpenPGP packets, as specified in RFC 4880.
 Package packet implements parsing and serialization of OpenPGP packets, as specified in RFC 4880.
Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1, and Argon2 specified in draft-ietf-openpgp-crypto-refresh-08 section 3.7.1.4.
 Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1, and Argon2 specified in draft-ietf-openpgp-crypto-refresh-08 section 3.7.1.4.
Package openpgp implements high level operations on OpenPGP messages.
 Package openpgp implements high level operations on OpenPGP messages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.