box

README

cryptobox/box

This is a NaCL-like implementation of a public-key cryptographic system
using FIPS-compliant ciphers.

box provides 20-year security using ECDH with the NIST P256 curve,
and the secretbox package as the underlying symmetric encryption
system.

Documentation

Overview

box is used to authenticate and secure messages using public-key cryptography. It provides an interface similar to NaCL, but uses ECIES using ephemeral ECDH for shared keys, and secret box for securing messages.

Messages should be secured using the Seal function, and recovered using the Open function. A box (or authenticated and encrypted message) will be Overhead bytes longer than the message it came from; this package will not obscure the length of the message. Keys, if they are not generated using the GenerateKey function, should be KeySize bytes long. The KeyIsSuitable function may be used to test a key is the proper length.

This package also provides signed boxes: these digitally sign the message before sealing them, and the signature can be checked on opening. These must be opened with the OpenSigned function, and use ECDSA for signatures.

The boxes used in this package are suitable for 20-year security.

Index

• Constants
• Variables
• func BoxIsSigned(box []byte) bool
• func GenerateKey() (PrivateKey, PublicKey, bool)
• func KeyIsSuitable(key PrivateKey, pub PublicKey) bool
• func Open(box []byte, key PrivateKey) (message []byte, ok bool)
• func OpenAndVerify(box []byte, key PrivateKey, peer PublicKey) (message []byte, ok bool)
• func OpenShared(box []byte, key PrivateKey, public PublicKey) (message []byte, ok bool)
• func OpenSharedAndVerify(box []byte, key PrivateKey, public PublicKey, signer PublicKey) (message []byte, ok bool)
• func Seal(message []byte, peer PublicKey) (box []byte, ok bool)
• func SealShared(message []byte, peers []PublicKey) (box []byte, ok bool)
• func SharedKey(key PrivateKey, peer PublicKey) (secretbox.Key, bool)
• func Sign(message []byte, key PrivateKey, pub PublicKey) (signature []byte, ok bool)
• func SignAndSeal(message []byte, key PrivateKey, public PublicKey, peer PublicKey) (box []byte, ok bool)
• func SignAndSealShared(message []byte, peers []PublicKey, sigkey PrivateKey, sigpub PublicKey) (box []byte, ok bool)
• func SignKey(priv PrivateKey, pub, peer PublicKey) (sig []byte, ok bool)
• func Verify(message, signature []byte, signer PublicKey) bool
• func VerifySignedKey(pub, sigpub PublicKey, sig []byte) bool
• type PrivateKey
• type PublicKey

Constants

const (
	BoxUnsigned     byte = 1
	BoxSigned       byte = 2
	BoxShared       byte = 11
	BoxSharedSigned byte = 12
)

const (
	SharedKeySize = 48
)

const VersionString = "2.0.0"

Variables

var Overhead = publicKeySize + secretbox.Overhead + 9 // 9: two four byte lengths and type

Overhead is the number of bytes of overhead when boxing a message. This will be greater for locked and shared boxes.

var PRNG = rand.Reader

The default source for random data is the crypto/rand package's Reader.

var SignedOverhead = publicKeySize + secretbox.Overhead + sigSize

SignedOverhead is the number of bytes of overhead when signing and boxing a message.

Functions

func BoxIsSigned

func BoxIsSigned(box []byte) bool

BoxIsSigned returns true if the box is a signed box, and false otherwise.

func GenerateKey

func GenerateKey() (PrivateKey, PublicKey, bool)

GenerateKey generates an appropriate private and public keypair for use in box.

func KeyIsSuitable

func KeyIsSuitable(key PrivateKey, pub PublicKey) bool

IsKeySuitable takes a private and/or public key, and returns true if all keys passed in are valid. If no key is passed in, or any key passed in is invalid, it will return false.

func Open

func Open(box []byte, key PrivateKey) (message []byte, ok bool)

Open authenticates and decrypts a sealed message, also returning whether the message was successfully opened. If this is false, the message must be discarded. The returned message will be Overhead bytes shorter than the box.

func OpenAndVerify

func OpenAndVerify(box []byte, key PrivateKey, peer PublicKey) (message []byte, ok bool)

OpenAndVerify opens a signed box, and verifies the signature. If the box couldn't be opened or the signature is invalid, OpenAndVerify returns false, and the message value must be discarded.

func OpenShared

func OpenShared(box []byte, key PrivateKey, public PublicKey) (message []byte, ok bool)

OpenShared authenticates and decrypts a sealed shared message, also returning whether the message was successfully opened. If this is false, the message must be discarded.

func OpenSharedAndVerify

func OpenSharedAndVerify(box []byte, key PrivateKey, public PublicKey, signer PublicKey) (message []byte, ok bool)

OpenSharedAndVerify opens a signed shared box, and verifies the signature. If the box couldn't be opened or the signature is invalid, OpenSharedAndVerify returns false, and the message value must be discarded.

func Seal

func Seal(message []byte, peer PublicKey) (box []byte, ok bool)

Seal returns an authenticated and encrypted message, and a boolean indicating whether the sealing operation was successful. If it returns true, the message was successfully sealed. The box will be Overhead bytes longer than the message. These boxes are not dependent on having a private key. However, if a private key is passed in sigkey (with the corresponding public key in sigpub), the box will be signed.

func SealShared

func SealShared(message []byte, peers []PublicKey) (box []byte, ok bool)

SealShared returns an authenticated and encrypted message shared between multiple peers, and a boolean indicating whether the sealing operation was successful. If it returns true, the message was successfully sealed. These boxes are not dependent on having a private key.

func SharedKey

func SharedKey(key PrivateKey, peer PublicKey) (secretbox.Key, bool)

SharedKey precomputes a key for encrypting with secretbox.

func Sign

func Sign(message []byte, key PrivateKey, pub PublicKey) (signature []byte, ok bool)

Sign is used to certify a message with the key pair passed in. It returns a boolean indicating success; on success, the signature value returned will contain the signature.

func SignAndSeal

func SignAndSeal(message []byte, key PrivateKey, public PublicKey, peer PublicKey) (box []byte, ok bool)

SignAndSeal adds a digital signature to the message before sealing it.

func SignAndSealShared

func SignAndSealShared(message []byte, peers []PublicKey, sigkey PrivateKey, sigpub PublicKey) (box []byte, ok bool)

SignAndSealShared adds a digital signature to the shared message before sealing it.

func SignKey

func SignKey(priv PrivateKey, pub, peer PublicKey) (sig []byte, ok bool)

SignKey takes the key pair specified in priv, pub and uses that to sign the peer key. It returns a signature and true on success; if ok is false, the signature should be discarded as signing failed.

func Verify

func Verify(message, signature []byte, signer PublicKey) bool

Verify returns true if the signature is a valid signature by the signer for the message. If there is a failure (include failing to verify the signature), Verify returns false.

func VerifySignedKey

func VerifySignedKey(pub, sigpub PublicKey, sig []byte) bool

VerifySign checks the signature on the peer key with the sigpub key. It returns true if the signature is valid, or false if the signature is invalid or an error occurred.

Types

type PrivateKey

type PrivateKey []byte

type PublicKey

type PublicKey []byte