openpgp

Documentation

Overview

Package openpgp implements high level operations on OpenPGP messages.

Index

• Variables
• func ArmoredDetachSign(w io.Writer, signer *Entity, message io.Reader) (err os.Error)
• func ArmoredDetachSignText(w io.Writer, signer *Entity, message io.Reader) os.Error
• func DetachSign(w io.Writer, signer *Entity, message io.Reader) os.Error
• func DetachSignText(w io.Writer, signer *Entity, message io.Reader) os.Error
• func NewCanonicalTextHash(h hash.Hash) hash.Hash
• func SymmetricallyEncrypt(ciphertext io.Writer, passphrase []byte, hints *FileHints) (plaintext io.WriteCloser, err os.Error)
• type Entity
  • func CheckArmoredDetachedSignature(keyring KeyRing, signed, signature io.Reader) (signer *Entity, err os.Error)
  • func CheckDetachedSignature(keyring KeyRing, signed, signature io.Reader) (signer *Entity, err os.Error)
  • func NewEntity(rand io.Reader, currentTimeSecs int64, name, comment, email string) (*Entity, os.Error)
  • func (e *Entity) SerializePrivate(w io.Writer) (err os.Error)
• type EntityList
  • func ReadArmoredKeyRing(r io.Reader) (EntityList, os.Error)
  • func ReadKeyRing(r io.Reader) (el EntityList, err os.Error)
  • func (el EntityList) DecryptionKeys() (keys []Key)
  • func (el EntityList) KeysById(id uint64) (keys []Key)
• type FileHints
• type Identity
• type Key
• type KeyRing
• type MessageDetails
  • func ReadMessage(r io.Reader, keyring KeyRing, prompt PromptFunction) (md *MessageDetails, err os.Error)
• type PromptFunction
• type Subkey

Variables

var PrivateKeyType = "PGP PRIVATE KEY BLOCK"

PrivateKeyType is the armor type for a PGP private key.

var PublicKeyType = "PGP PUBLIC KEY BLOCK"

PublicKeyType is the armor type for a PGP public key.

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) (err os.Error)

ArmoredDetachSign signs message with the private key from signer (which must already have been decrypted) and writes an armored signature to w.

func ArmoredDetachSignText

func ArmoredDetachSignText(w io.Writer, signer *Entity, message io.Reader) os.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.

func DetachSign

func DetachSign(w io.Writer, signer *Entity, message io.Reader) os.Error

DetachSign signs message with the private key from signer (which must already have been decrypted) and writes the signature to w.

func DetachSignText

func DetachSignText(w io.Writer, signer *Entity, message io.Reader) os.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.

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 SymmetricallyEncrypt

func SymmetricallyEncrypt(ciphertext io.Writer, passphrase []byte, hints *FileHints) (plaintext io.WriteCloser, err os.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.

Types

type Entity

type Entity struct {
	PrimaryKey *packet.PublicKey
	PrivateKey *packet.PrivateKey
	Identities map[string]*Identity // indexed by Identity.Name
	Subkeys    []Subkey
}

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) (signer *Entity, err os.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) (signer *Entity, err os.Error)

CheckDetachedSignature takes a signed file and a detached signature and returns the signer if the signature is valid. If the signer isn't know, UnknownIssuerError is returned.

func NewEntity

func NewEntity(rand io.Reader, currentTimeSecs int64, name, comment, email string) (*Entity, os.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".

func (*Entity) SerializePrivate

func (e *Entity) SerializePrivate(w io.Writer) (err os.Error)

SerializePrivate serializes an Entity, including private key material, to the given Writer. For now, it must only be used on an Entity returned from NewEntity.

type EntityList

type EntityList []*Entity

An EntityList contains one or more Entities.

func ReadArmoredKeyRing

func ReadArmoredKeyRing(r io.Reader) (EntityList, os.Error)

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

func ReadKeyRing

func ReadKeyRing(r io.Reader) (el EntityList, err os.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.

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
	// EpochSeconds contains the modification time of the file, or 0 if not applicable.
	EpochSeconds uint32
}

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
	Signatures    []*packet.Signature
}

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

type Key

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

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

type KeyRing

type KeyRing interface {
	// KeysById returns the set of keys that have the given key id.
	KeysById(id uint64) []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.
	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.

	SignatureError os.Error          // nil if the signature is good.
	Signature      *packet.Signature // the signature packet itself.
	// 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) (md *MessageDetails, err os.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.

type PromptFunction

type PromptFunction func(keys []Key, symmetric bool) ([]byte, os.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
}

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