sign

README

sigtool/sign - Ed25519 signature calculation and verification

This is a small library that makes it easier to create and serialize Ed25519 keys, and sign, verify files using those keys. The library uses mmap(2) to read and process very large files.

The companion program sigtool uses this library.

License

GPL v2.0

Documentation

Overview

Package sign implements Ed25519 signing, verification on files. It builds upon golang.org/x/crypto/ed25519 by adding methods for serializing and deserializing Ed25519 private & public keys.

It can sign and verify very large files - it prehashes the files with SHA-512 and then signs the SHA-512 checksum. The keys and signatures are YAML files and so, human readable.

It can encrypt files for multiple recipients - each of whom is identified by their Ed25519 public key. The encryption by default generates ephmeral Curve25519 keys and creates pair-wise shared secret for each recipient of the encrypted file. The caller can optionally use a specific secret key during the encryption process - this has the benefit of also authenticating the sender (and the receiver can verify the sender if they possess the corresponding public key).

The sign, verify, encrypt, decrypt operations can use OpenSSH Ed25519 keys *or* the keys generated by sigtool. This means, you can send encrypted files to any recipient identified by their comment in `~/.ssh/authorized_keys`.

Index

• Constants
• Variables
• type Decryptor
  • func NewDecryptor(rd io.Reader) (*Decryptor, error)
  • func (d *Decryptor) AuthenticatedSender() bool
  • func (d *Decryptor) Decrypt(wr io.Writer) error
  • func (d *Decryptor) NewStreamReader() (io.Reader, error)
  • func (d *Decryptor) SetPrivateKey(sk *PrivateKey, senderPk *PublicKey) error
• type Encryptor
  • func NewEncryptor(sk *PrivateKey, blksize uint64) (*Encryptor, error)
  • func (e *Encryptor) AddRecipient(pk *PublicKey) error
  • func (e *Encryptor) Encrypt(rd io.Reader, wr io.WriteCloser) error
  • func (e *Encryptor) NewStreamWriter(wr io.WriteCloser) (io.WriteCloser, error)
• type Keypair
  • func NewKeypair() (*Keypair, error)
  • func (kp *Keypair) Serialize(bn, comment string, getpw func() ([]byte, error)) error
• type PrivateKey
  • func MakePrivateKey(yml []byte, pw []byte) (*PrivateKey, error)
  • func PrivateKeyFromBytes(buf []byte) (*PrivateKey, error)
  • func ReadPrivateKey(fn string, getpw func() ([]byte, error)) (*PrivateKey, error)
  • func (sk *PrivateKey) PublicKey() *PublicKey
  • func (sk *PrivateKey) SignFile(fn string) (*Signature, error)
  • func (sk *PrivateKey) SignMessage(ck []byte, comment string) (*Signature, error)
• type PublicKey
  • func MakePublicKey(yml []byte) (*PublicKey, error)
  • func ParseAuthorizedKeys(in []byte) ([]*PublicKey, error)
  • func PublicKeyFromBytes(b []byte) (*PublicKey, error)
  • func ReadPublicKey(fn string) (*PublicKey, error)
  • func (pk *PublicKey) Hash() []byte
  • func (pk *PublicKey) VerifyFile(fn string, sig *Signature) (bool, error)
  • func (pk *PublicKey) VerifyMessage(ck []byte, sig *Signature) bool
• type Signature
  • func MakeSignature(b []byte) (*Signature, error)
  • func ReadSignature(fn string) (*Signature, error)
  • func (sig *Signature) IsPKMatch(pk *PublicKey) bool
  • func (sig *Signature) Serialize(comment string) ([]byte, error)
  • func (sig *Signature) SerializeFile(fn, comment string) error

Constants

const PKHashLength = 16

Length of Ed25519 Public Key Hash

Variables

var (
	ErrIncorrectPassword = errors.New("ssh: Invalid Passphrase")
	ErrNoPEMFound        = errors.New("no PEM block found")
	ErrBadPublicKey      = errors.New("ssh: malformed public key")
	ErrKeyTooShort       = errors.New("ssh: public key too short")
	ErrBadTrailers       = errors.New("ssh: trailing junk in public key")
	ErrBadFormat         = errors.New("ssh: invalid openssh private key format")
	ErrBadLength         = errors.New("ssh: private key unexpected length")
	ErrBadPadding        = errors.New("ssh: padding not as expected")
)

Types

type Decryptor

type Decryptor struct {
	pb.Header
	// contains filtered or unexported fields
}

Decryptor holds the decryption context

func NewDecryptor

func NewDecryptor(rd io.Reader) (*Decryptor, error)

Create a new decryption context and if 'pk' is given, check that it matches the sender

func (*Decryptor) AuthenticatedSender

func (d *Decryptor) AuthenticatedSender() bool

AuthenticatedSender returns true if the sender authenticated themselves (the data-encryption key is signed).

func (*Decryptor) Decrypt

func (d *Decryptor) Decrypt(wr io.Writer) error

Decrypt the file and write to 'wr'

func (*Decryptor) NewStreamReader

func (d *Decryptor) NewStreamReader() (io.Reader, error)

NewStreamReader returns an io.Reader to read from the decrypted stream

func (*Decryptor) SetPrivateKey

func (d *Decryptor) SetPrivateKey(sk *PrivateKey, senderPk *PublicKey) error

Use Private Key 'sk' to decrypt the encrypted keys in the header and optionally validate the sender

type Encryptor

type Encryptor struct {
	pb.Header
	// contains filtered or unexported fields
}

Encryptor holds the encryption context

func NewEncryptor

func NewEncryptor(sk *PrivateKey, blksize uint64) (*Encryptor, error)

Create a new Encryption context for encrypting blocks of size 'blksize'. If 'sk' is not nil, authenticate the sender to each receiver.

func (*Encryptor) AddRecipient

func (e *Encryptor) AddRecipient(pk *PublicKey) error

Add a new recipient to this encryption context.

func (*Encryptor) Encrypt

func (e *Encryptor) Encrypt(rd io.Reader, wr io.WriteCloser) error

Encrypt the input stream 'rd' and write encrypted stream to 'wr'

func (*Encryptor) NewStreamWriter

func (e *Encryptor) NewStreamWriter(wr io.WriteCloser) (io.WriteCloser, error)

NewStreamWriter begins stream encryption to an underlying destination writer 'wr'. It returns an io.WriteCloser.

type Keypair

type Keypair struct {
	Sec PrivateKey
	Pub PublicKey
}

Ed25519 key pair

func NewKeypair

func NewKeypair() (*Keypair, error)

Generate a new Ed25519 keypair

func (*Keypair) Serialize

func (kp *Keypair) Serialize(bn, comment string, getpw func() ([]byte, error)) error

Serialize the keypair to two separate files. The basename of the file is 'bn'; the public key goes in $bn.pub and the private key goes in $bn.key. If password is non-empty, then the private key is encrypted before writing to disk.

type PrivateKey

type PrivateKey struct {
	Sk []byte
	// contains filtered or unexported fields
}

Private Ed25519 key

func MakePrivateKey

func MakePrivateKey(yml []byte, pw []byte) (*PrivateKey, error)

Make a private key from bytes 'yml' and password 'pw'. The bytes are assumed to be serialized version of the private key.

func PrivateKeyFromBytes

func PrivateKeyFromBytes(buf []byte) (*PrivateKey, error)

Make a private key from 64-bytes of extended Ed25519 key

func ReadPrivateKey

func ReadPrivateKey(fn string, getpw func() ([]byte, error)) (*PrivateKey, error)

Read the private key in 'fn', optionally decrypting it using password 'pw' and create new instance of PrivateKey

func (*PrivateKey) PublicKey

func (sk *PrivateKey) PublicKey() *PublicKey

Given a secret key, return the corresponding Public Key

func (*PrivateKey) SignFile

func (sk *PrivateKey) SignFile(fn string) (*Signature, error)

Read and sign a file

We calculate the signature differently here: We first calculate the SHA-512 checksum of the file and its size. We sign the checksum.

func (*PrivateKey) SignMessage

func (sk *PrivateKey) SignMessage(ck []byte, comment string) (*Signature, error)

Sign a prehashed Message; return the signature as opaque bytes Signature is an YAML file:

Comment: source file path
Signature: Ed25519 signature

type PublicKey

type PublicKey struct {
	Pk []byte

	// Comment string
	Comment string
	// contains filtered or unexported fields
}

Public Ed25519 key

func MakePublicKey

func MakePublicKey(yml []byte) (*PublicKey, error)

Parse a serialized public in 'yml' and return the resulting public key instance

func ParseAuthorizedKeys

func ParseAuthorizedKeys(in []byte) ([]*PublicKey, error)

ParseAuthorizedKeys parses a public key from an authorized_keys file used in OpenSSH according to the sshd(8) manual page.

func PublicKeyFromBytes

func PublicKeyFromBytes(b []byte) (*PublicKey, error)

Make a public key from a byte string

func ReadPublicKey

func ReadPublicKey(fn string) (*PublicKey, error)

Read the public key from 'fn' and create new instance of PublicKey

func (*PublicKey) Hash

func (pk *PublicKey) Hash() []byte

Public Key Hash

func (*PublicKey) VerifyFile

func (pk *PublicKey) VerifyFile(fn string, sig *Signature) (bool, error)

Verify a signature 'sig' for file 'fn' against public key 'pk' Return True if signature matches, False otherwise

func (*PublicKey) VerifyMessage

func (pk *PublicKey) VerifyMessage(ck []byte, sig *Signature) bool

Verify a signature 'sig' for a pre-calculated checksum 'ck' against public key 'pk' Return True if signature matches, False otherwise

type Signature

type Signature struct {
	Sig []byte // Ed25519 sig bytes
	// contains filtered or unexported fields
}

An Ed25519 Signature

func MakeSignature

func MakeSignature(b []byte) (*Signature, error)

Parse serialized signature from bytes 'b' and construct a Signature object

func ReadSignature

func ReadSignature(fn string) (*Signature, error)

Read serialized signature from file 'fn' and construct a Signature object

func (*Signature) IsPKMatch

func (sig *Signature) IsPKMatch(pk *PublicKey) bool

IsPKMatch returns true if public key 'pk' can potentially validate the signature. It does this by comparing the hash of 'pk' against 'Pkhash' of 'sig'.

func (*Signature) Serialize

func (sig *Signature) Serialize(comment string) ([]byte, error)

Serialize a signature suitable for storing in durable media

func (*Signature) SerializeFile

func (sig *Signature) SerializeFile(fn, comment string) error

SerializeFile serializes the signature to an output file 'f'