README
¶
go-sign - Ed25519 signature calculation and verification
What is it?
A library to generate, verify and store Ed25519 keys and signatures. It uses the extended library (golang.org/x/crypto) for the underlying operations.
The generated keys and signatures are proper YAML files and human readable.
The signature file contains a hash of the public key - so that at verification time, the right private key may be used (in situations where there are lots of keys).
Signatures on large files are calculated efficiently by reading them
in memory mapped mode (mmap(2)) and hashing the file contents
using SHA-512. The Ed25519 signature is calculated on the file-hash.
Example of Keys, Signature
Ed25519 Public Key
A serialized Ed25519 public key looks like so:
pk: uxpDh+gqXojAmxA/6vxZHzA+Uk+8wogUwvEhPBlWgvo=
Ed25519 Private Key
And, a serialized Ed25519 private key looks like so:
esk: t3vfqHbgUiA733KKPymFjWT8DdnBEkiMfsDHolPUdQWpvVn/F1Z4J6KYV3M5rGO9xgKxh5RAmqt+6LKgOiJAMQ==
salt: pPHKG55UJYtJ5wU0G9hBvNQJ0DvT0a7T4Fmj4aPB84s=
algo: scrypt-sha256
verify: JvjRjJMKhJhBmZngC3Pvq7x3KCLKt7gar1AAz7HB4qM=
Z: 131072
r: 16
p: 1
The Ed25519 private key is encrypted using Scrypt password hashing mechanism. Any user supplied passphrase to protect the private key is first pre-hashed using SHA-512 before being used in ```scrypt()``. In pseudo code, this operation looks like below:
passphrase = get_user_passphrase()
hpass = SHA512(passphrase)
salt = randombytes(32)
xorkey = Scrypt(hpass, salt, N, r, p)
verify = SHA256(salt, xorkey)
esk = ed25519_private_key ^ xorkey
Where, N, r, p are Scrypt parameters. In our
implementation:
N = 131072
r = 16
p = 1
verify is used during the decryption of the Ed25519 private
key - before actually doing the "xor" operation. The code checks to
ensure that the supplied passphrase yields the same value as
verify.
Ed25519 Signature
A generated signature looks like below after serialization:
comment: inpfile=/tmp/file.txt
pkhash: 36z9tCwTIVNwwDlExrB0SQ==
signature: ow2oBP+buDbEvlNakOrsxgB5Yc/7PYyPVZCkfyu7oahw8BakF4Qf32uswPaKGZ8RVz4uXboYHdZtfrEjCgP/Cg==
Here, ```pkhash`` is a SHA256 of the public key needed to verify this signature.
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. In addition, it works with large files - by precalculating their SHA512 checksum in mmap'd mode and sending the 64 byte signature for Ed25519 signing.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Keypair ¶
type Keypair struct {
Sec PrivateKey
Pub PublicKey
}
Ed25519 key pair
type PrivateKey ¶
type PrivateKey struct {
Sk []byte
// contains filtered or unexported fields
}
Private Ed25519 key
func MakePrivateKey ¶
func MakePrivateKey(yml []byte, pw string) (*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 ReadPrivateKey ¶
func ReadPrivateKey(fn string, pw string) (*PrivateKey, error)
Read the private key in 'fn', optionally decrypting it using password 'pw' and create new instance of PrivateKey
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
}
Public Ed25519 key
func MakePublicKey ¶
Parse a serialized public in 'yml' and return the resulting public key instance
func ReadPublicKey ¶
Read the public key from 'fn' and create new instance of PublicKey
func (*PublicKey) VerifyFile ¶
Verify a signature 'sig' for file 'fn' against public key 'pk' Return True if signature matches, False otherwise
type Signature ¶
type Signature struct {
Sig []byte // 32 byte digital signature
// contains filtered or unexported fields
}
An Ed25519 Signature
func MakeSignature ¶
Parse serialized signature from bytes 'b' and construct a Signature object
func ReadSignature ¶
Read serialized signature from file 'fn' and construct a Signature object
func (*Signature) IsPKMatch ¶
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) SerializeFile ¶
SerializeFile serializes the signature to an output file 'f'
Source Files