Documentation
¶
Overview ¶
Package libcipher provides cryptographic utilities for encryption, decryption, integrity verification, and key generation: AES-GCM, AES-CBC with HMAC, sealed HMAC hashes, and Ed25519 signing keys. The encryption key and integrity key must be kept secret and must be distinct.
Index ¶
- Constants
- Variables
- func CheckHash(signingKey string, salt string, shouldBe string, hash []byte) (bool, error)
- func Equal(sealedHash1, sealedHash2 []byte) bool
- func EqualSigningKey(a, b SigningPrivateKey) bool
- func FormatPublicKey(pub SigningPublicKey) string
- func FormatSigningSeed(priv SigningPrivateKey) (string, error)
- func GenerateKey(keyLength int) (string, error)
- func GenerateSigningKey() (SigningPublicKey, SigningPrivateKey, error)
- func NewHash(args GenerateHashArgs, hashfn func() hash.Hash) ([]byte, error)
- func ParseSigningSeed(s string) (SigningPublicKey, SigningPrivateKey, error)
- func Sign(priv SigningPrivateKey, message []byte) ([]byte, error)
- func Verify(pub SigningPublicKey, message, sig []byte) bool
- type CipherTextError
- type Decryptor
- type EncryptionKeyError
- type Encryptor
- type GenerateHashArgs
- type HashError
- type IntegrityKeyError
- type InvalidUsageError
- type KeyGenerationError
- type MessageError
- type SigningKeyError
- type SigningPrivateKey
- type SigningPublicKey
Constants ¶
const ( SigningSeedSize = ed25519.SeedSize SigningPublicKeySize = ed25519.PublicKeySize SigningPrivateKeySize = ed25519.PrivateKeySize SignatureSize = ed25519.SignatureSize )
Ed25519 key and signature sizes, re-exported so callers can validate lengths without importing crypto/ed25519.
const ( ErrBadPublicKey = SigningKeyError("not an ed25519 public key") ErrBadPrivateKey = SigningKeyError("not an ed25519 private key") ErrBadSeed = SigningKeyError("not an ed25519 seed") ErrKeyGeneration = SigningKeyError("error generating signing key") )
Signing-key failures.
Variables ¶
var SigningKeyEncoding = base64.StdEncoding
SigningKeyEncoding is the one encoding this package writes. Parsing is deliberately more lenient; see ParsePublicKey.
Functions ¶
func Equal ¶
Equal reports whether two sealed hashes are byte-identical, in constant time. Comparing the JSON-encoded form rather than unmarshalling first is what keeps the comparison constant-time end to end.
func EqualSigningKey ¶ added in v0.38.0
func EqualSigningKey(a, b SigningPrivateKey) bool
EqualSigningKey compares two private keys in constant time. Keys of differing length compare unequal.
func FormatPublicKey ¶ added in v0.38.0
func FormatPublicKey(pub SigningPublicKey) string
FormatPublicKey renders a public key for storage or for handing to a peer, in SigningKeyEncoding. It returns the empty string for a key of the wrong length rather than emitting text that would never parse back.
func FormatSigningSeed ¶ added in v0.38.0
func FormatSigningSeed(priv SigningPrivateKey) (string, error)
FormatSigningSeed renders the private half of a keypair as its 32-byte seed in SigningKeyEncoding. The returned string is secret material.
func GenerateKey ¶
GenerateKey generates a cryptographically random key with the specified length.
func GenerateSigningKey ¶ added in v0.38.0
func GenerateSigningKey() (SigningPublicKey, SigningPrivateKey, error)
GenerateSigningKey returns a fresh Ed25519 keypair from the system CSPRNG. Publish the public half with FormatPublicKey and store the private half with FormatSigningSeed.
func NewHash ¶
func NewHash(args GenerateHashArgs, hashfn func() hash.Hash) ([]byte, error)
NewHash computes an HMAC digest over the payload and salt in args using hashfn.
func ParseSigningSeed ¶ added in v0.38.0
func ParseSigningSeed(s string) (SigningPublicKey, SigningPrivateKey, error)
ParseSigningSeed reconstructs a keypair from a seed produced by FormatSigningSeed, accepting the same spellings ParsePublicKey does.
func Sign ¶ added in v0.38.0
func Sign(priv SigningPrivateKey, message []byte) ([]byte, error)
Sign returns a detached signature over message as given; domain separation and framing are the caller's. A key of the wrong length yields an error wrapping ErrBadPrivateKey rather than a panic.
func Verify ¶ added in v0.38.0
func Verify(pub SigningPublicKey, message, sig []byte) bool
Verify reports whether sig is a valid signature of message by pub. It never panics: malformed input yields false, which is an authentication failure and not a transient error.
Types ¶
type CipherTextError ¶
type CipherTextError string
func (CipherTextError) Error ¶
func (e CipherTextError) Error() string
type Decryptor ¶
Decryptor crypts a cipher package. Misuse may lead to a panic.
func NewCBCHMACDecryptor ¶
func NewCBCHMACDecryptor(encryptionKey []byte, integrityKey []byte, calculateMAC func() hash.Hash) (Decryptor, error)
NewCBCHMACDecryptor returns a Decryptor for data sealed by NewCBCHMACEncryptor.
func NewGCMDecryptor ¶
NewGCMDecryptor creates a new Decryptor using AES-GCM with the given key.
type EncryptionKeyError ¶
type EncryptionKeyError string
func (EncryptionKeyError) Error ¶
func (e EncryptionKeyError) Error() string
type Encryptor ¶
Encryptor crypts a message with additional data. Misuse may lead to a panic.
func NewCBCHMACEncryptor ¶
func NewCBCHMACEncryptor(encryptionKey []byte, integrityKey []byte, calculateMAC func() hash.Hash, rand io.Reader) (Encryptor, error)
NewCBCHMACEncryptor returns an Encryptor using AES-CBC with PKCS7 padding and an HMAC for integrity. The encryption key and integrity key must be distinct, both kept secret, and rotated simultaneously.
[ MAC | AD-Length | AD | Initialization Vector | Block 1 | Block 2 | ... ]
type GenerateHashArgs ¶
GenerateHashArgs contains the input parameters for generating a sealed hash. SigningKey should be kept secret.
type IntegrityKeyError ¶
type IntegrityKeyError string
func (IntegrityKeyError) Error ¶
func (e IntegrityKeyError) Error() string
type InvalidUsageError ¶
type InvalidUsageError string
func (InvalidUsageError) Error ¶
func (e InvalidUsageError) Error() string
type KeyGenerationError ¶
type KeyGenerationError string
func (KeyGenerationError) Error ¶
func (e KeyGenerationError) Error() string
type MessageError ¶
type MessageError string
func (MessageError) Error ¶
func (e MessageError) Error() string
type SigningKeyError ¶ added in v0.38.0
type SigningKeyError string
SigningKeyError represents an error while generating, parsing, or using an Ed25519 key.
func (SigningKeyError) Error ¶ added in v0.38.0
func (e SigningKeyError) Error() string
type SigningPrivateKey ¶ added in v0.38.0
type SigningPrivateKey = ed25519.PrivateKey
SigningPublicKey and SigningPrivateKey are aliases for the crypto/ed25519 key types.
type SigningPublicKey ¶ added in v0.38.0
SigningPublicKey and SigningPrivateKey are aliases for the crypto/ed25519 key types.
func ParsePublicKey ¶ added in v0.38.0
func ParsePublicKey(s string) (SigningPublicKey, error)
ParsePublicKey reads a key produced by FormatPublicKey, also accepting the unpadded and URL-safe base64 variants and lowercase hex. The result is exactly SigningPublicKeySize bytes or an error wrapping ErrBadPublicKey.
Source Files