README
¶
Dist-ribut-us Crypto
Wrapper around crypto functions.
All about the types
This package wraps the nacl/box package for key exchange and symmetric encryption, the ed25519 package for signing, sha256 for hashing and provides it's own helper for managing nonce (which relies on crypto/rand).
The primary motivation of this package is to provide types for the various cryptographic primitives. The two underlying cryptographic packages use byte slices for all the data types (keys, nonce, plain-text and cipher-text). I found it easy to confuse the arguments. Giving each primitive it's own type the compiler will help enforce that the arguments to each method are correct.
Correct Use
Communication
Identity is based on a signing key. Two parties that wish to communicate must first have a way to exchange public signing keys securely. Each party then generates a one-time-use exchange key pair (XchgPair). They each sign their public exchange key and send it to the other. Each party then validates the public key they've received against public signature. If that matches, both use their private exchange key with the validated public exchange key to get the same shared secret (note that means privA.Shared(pubB) == pirvB.Shared(pubA) ). That shared secret is a Symmetric key and it can be used to safely exchange messages.
Interrupt
A handful of functions (all related to generating cryptographic random data) can encounter a rare error of running out of entropy. This is unlikely and unrecoverable. The standard Go model of bubbling the error as a return value was not useful in these cases. The error could bubble through several layers only to have the top level panic or exit.
In place of the Go model of bubbling the error, for these functions, an interrupt is used. If crypto encounters an error when generating random data it will log the error and call InterruptHandler. This can be set to another function if main needs to do some clean up before closing. The default behavior is open a new go routine and panic (so that the panic will not interact with recover in another package up the stack) and then block any further execution on the original thread.
Functions that can trigger InterruptHandler:
- GenerateKey
- RandomSymmetric
- RandomNonce
- RandInt
- RandUint32
- RandUint16
Documentation
¶
Overview ¶
Package crypto wraps many of the standard Go crypto tools. The most significant feature is providing types that distinguish XchgPublic and XchgPrivate keys, rather than using slices or arrays of bytes directly.
Crypto also provides an Un-MAC'd variant of the tools from golang.org/x/crypto/nacl/secretbox. Trusting un-MAC'd data is never a good idea, but in the Leap Frog onion routing protocol, layers of encryption are added on to MAC'd data, providing the necesary safety.
There are a number of rare and unlikely errors that all stem from not being able to generate random cryptographic data. In this case (and only this case) we do not use the idiomatic Go technique of bubbling the error up. Generally, nothing can be done, so we panic. If you don't want to panic, the error is placed on ErrChan, along with ErrConfirm. This lets the error handler read the error but keeps blocking the crypto function until it's addressed. Only when ErrConfirm is pulled can the function return. All functions that use this feature are used to generate crypto objects (keys and nonces). They will return nil if there is an error.
tl;dr: don't use unmac'd ciphers alone, only use them on top of MAC'd data. If you don't want to worry about ErrChan, just set PanicOnError to true.
Index ¶
- Constants
- Variables
- func GenerateSignPair() (*SignPub, *SignPriv)
- func RandInt(max int) int
- func RandUint16() uint16
- func RandUint32() uint32
- type Digest
- type Hasher
- type ID
- type KeyRef
- type Nonce
- type SignPriv
- type SignPub
- type Signature
- type Symmetric
- func (symmetric *Symmetric) Arr() *[KeyLength]byte
- func (symmetric *Symmetric) NonceOpen(cipher []byte, nonce *Nonce) ([]byte, error)
- func (symmetric *Symmetric) NonceSeal(msg []byte, nonce *Nonce) []byte
- func (symmetric *Symmetric) Open(cipher []byte) ([]byte, error)
- func (symmetric *Symmetric) Seal(msg []byte, nonce *Nonce) []byte
- func (symmetric *Symmetric) SealAll(msgs [][]byte, nonce *Nonce) [][]byte
- func (symmetric *Symmetric) SealPackets(tag []byte, msgs [][]byte, nonce *Nonce, trim int) [][]byte
- func (symmetric *Symmetric) Slice() []byte
- func (symmetric *Symmetric) String() string
- func (shared *Symmetric) UnmacdOpen(cipher []byte, nonce *Nonce) []byte
- func (shared *Symmetric) UnmacdSeal(message []byte, nonce *Nonce) []byte
- type XchgPair
- type XchgPriv
- func (priv *XchgPriv) AnonOpen(cipher []byte) ([]byte, error)
- func (priv *XchgPriv) AnonOpenSymmetric(cipher []byte) ([]byte, *Symmetric, error)
- func (priv *XchgPriv) Arr() *[KeyLength]byte
- func (priv *XchgPriv) GetKeyRef() *KeyRef
- func (priv *XchgPriv) Shared(pub *XchgPub) *Symmetric
- func (priv *XchgPriv) Slice() []byte
- func (priv *XchgPriv) String() string
- type XchgPub
Constants ¶
const DigestLength = 32
DigestLength is the length of a SHA 256 hash digest
const ErrBadSignature = errors.String("Signature does not match the message")
ErrBadSignature is available to indicated a process failure due to a bad signature. It is not used in this package.
const ErrDecryptionFailed = errors.String("Decryption Failed")
ErrDecryptionFailed when no other information is available
const ErrIncorrectIDSize = errors.String("Incorrect ID size")
ErrIncorrectIDSize when a byte slice length does not equal IDLength
const ErrWrongDigestLength = errors.String("Wrong Digest Length")
ErrWrongDigestLength is returned when trying to create a digest from data of the wrong length
const IDLength = 10
IDLength of array
const KeyLength = 32
KeyLength of array applies to XchgPublic, XchgPrivate and Symmetric keys.
const NonceLength = 24
NonceLength of array
const Overhead = box.Overhead
Overhead copies box.Overhead
const SignPrivLength = 64
SignPrivLength is the length of a private signature key
const SignatureLength = 64
SignatureLength is the correct length of a signature
Variables ¶
var InterruptHandler = func(err error) { go func() { panic(err) }() <-make(chan bool) }
InterruptHandler will be called in the case of a set of very rare errors. By default, the InterruptHandler will panic. Only main should change the InterruptHandler.
Functions ¶
func GenerateSignPair ¶
GenerateSignPair creates a pair of signing keys.
func RandUint16 ¶
func RandUint16() uint16
RandUint16 returns a random int generated using crypto/rand
func RandUint32 ¶
func RandUint32() uint32
RandUint32 returns a random int generated using crypto/rand
Types ¶
type Digest ¶
type Digest [DigestLength]byte
Digest wraps the output of a hash
func DigestFromHex ¶
DigestFromHex returns a digest from a hex string as would be returned by a call to Hex
func DigestFromSlice ¶
DigestFromSlice converts a byte slice to a public key. The values are copied, so the slice can be modified after.
func DigestFromString ¶
DigestFromString returns a digest from a hex string as would be returned by a call to String
type ID ¶
ID is a shorthand used to make referencing public keys easier. An ID is the first 10 bytes of the sha256 of a public key. While the chances of accidental collision should be minimal, malicious collision should not be discounted. ID can be used as to make hash tables more efficient, but should not be substituted for a full key check.
func IDFromSlice ¶
IDFromSlice returns an ID from a byte slice. The values are copied, so the slice can be modified after
func IDFromString ¶
IDFromString takes a base64 encoded ID key and returns it as *ID
type KeyRef ¶
KeyRef is similar to ID for private keys. It can be useful for managing private keys.
func KeyRefFromArr ¶
KeyRefFromArr casts an array to a KeyRef
type Nonce ¶
type Nonce [NonceLength]byte
Nonce array
func NonceFromArr ¶
func NonceFromArr(nonce *[NonceLength]byte) *Nonce
NonceFromArr casts an array to a Nonce
func NonceFromSlice ¶
NonceFromSlice casts an array to a Nonce
func NonceFromString ¶
NonceFromString takes a base64 encoded nonce and returns it as a Nonce
func RandomNonce ¶
func RandomNonce() *Nonce
RandomNonce returns a Nonce with a cryptographically random value.
func (*Nonce) Arr ¶
func (nonce *Nonce) Arr() *[NonceLength]byte
Arr returns a reference to the array underlying the Nonce
type SignPriv ¶
type SignPriv [SignPrivLength]byte
SignPriv is a private key used to sign messages
func SignPrivFromSlice ¶
SignPrivFromSlice converts a byte slice to a public key. The values are copied, so the slice can be modified after.
func SignPrivFromString ¶
SignPrivFromString takes a base64 encoded public key and returns it as a SignPriv
type SignPub ¶
type SignPub key
SignPub is a public key used to verify signatures
func SignPubFromSlice ¶
SignPubFromSlice converts a byte slice to a public key. The values are copied, so the slice can be modified after.
func SignPubFromString ¶
SignPubFromString takes a base64 encoded public key and returns it as a SignPub
type Symmetric ¶
type Symmetric key
Symmetric key. Symmetric keys are also used as symmetric keys.
func RandomSymmetric ¶
func RandomSymmetric() *Symmetric
RandomSymmetric returns a random symmetric key that can be used for symmetric ciphers
func SymmetricFromArr ¶
SymmetricFromArr casts an array to a symmetric key
func SymmetricFromSlice ¶
SymmetricFromSlice converts a byte slice to a public key. The values are copied, so the slice can be modified after.
func SymmetricFromString ¶
SymmetricFromString takes a base64 encoded public key and returns it as a Symmetric
func (*Symmetric) NonceSeal ¶
NonceSeal will seal a message but not prepend the nonce - it matches NonceOpen. If nonce is nil, a zero value nonce will be used
func (*Symmetric) Seal ¶
Seal will seal message using a symmetric key and the given nonce. If the nonce is nil, a random nonce is generated. Decyrpted with Open
func (*Symmetric) SealAll ¶
SealAll seals many messages with the same shared key. If nonce is nil, a random nonce will be generated for each message.
func (*Symmetric) SealPackets ¶
SealPackets will seal message using a symmetric key and the given nonce. If the nonce is nil, a random nonce is generated. The tag will be prepended, but not encrypted. Trim removes tags from the start of each packet.
func (*Symmetric) UnmacdOpen ¶
UnmacdOpen decrypts a box produced by UnmacdSeal and appends the message to out, which must not overlap box. The output will be Overhead bytes smaller than box. The unsealed box has not been MAC'd and the data should not be trusted unless there is an underlying MAC (as in onion routing)
func (*Symmetric) UnmacdSeal ¶
UnmacdSeal appends an encrypted copy of message to out, which must not overlap message. The key and nonce pair must be unique for each distinct message and the output will be Overhead bytes longer than message. Unlike secretbox.Seal, it does not MAC the data. It should only be use on top of a MAC'd ecnryption, as in onion routing.
type XchgPair ¶
XchgPair embeds XchgPub and XchgPriv
func GenerateXchgPair ¶
func GenerateXchgPair() *XchgPair
GenerateXchgPair returns a public and private key.
func XchgPairFromSlice ¶
XchgPairFromSlice takes a slice and returns an XchgPair
func XchgPairFromString ¶
XchgPairFromString takes a two base64 encoded strings and returns a keypair
type XchgPriv ¶
type XchgPriv key
XchgPriv key
func XchgPrivFromArr ¶
XchgPrivFromArr casts an array to a private key
func XchgPrivFromSlice ¶
XchgPrivFromSlice converts a byte slice to a public key. The values are copied, so the slice can be modified after.
func XchgPrivFromString ¶
XchgPrivFromString takes a base64 encoded public key and returns it as a XchgPriv
func (*XchgPriv) AnonOpenSymmetric ¶
AnonOpenSymmetric decrypts a cipher from AnonSeal or AnonSealSymmetric and returns the symmetric key.
type XchgPub ¶
type XchgPub key
XchgPub Key
func XchgPubFromArr ¶
XchgPubFromArr casts an array to a public key
func XchgPubFromSlice ¶
XchgPubFromSlice converts a byte slice to a public key. The values are copied, so the slice can be modified after.
func XchgPubFromString ¶
XchgPubFromString takes a base64 encoded public key and returns it as a XchgPub
func (*XchgPub) AnonSeal ¶
AnonSeal encrypts a message with a random key pair. The Nonce is always 0 and the public key is prepended to the cipher. The recipient can open the message but the sender remains anonymous.
func (*XchgPub) AnonSealSymmetric ¶
AnonSealSymmetric encrypts a message with a random key pair. The Nonce is always 0 and the public key is prepended to the cipher. The recipient can open the message but the sender remains anonymous. This method also returns the symmetric key for the message.
func (*XchgPub) TagAnonSeal ¶
TagAnonSeal encrypts a message with a random key pair and prepends a byte slice tag. The Nonce is always 0 and the public key is prepended to the cipher. The recipient can open the message but the sender remains anonymous.
Source Files