Documentation ¶
Overview ¶
Package libdisco partially implements the Disco extension of the Noise protocol framework as specified in www.discocrypto.com/disco.html
More usage helpers are available on www.discocrypto.com ¶
Author: David Wong
Index ¶
- Constants
- func CreatePublicKeyVerifier(rootPublicKey ed25519.PublicKey) func([]byte, []byte) bool
- func CreateStaticPublicKeyProof(rootPrivateKey ed25519.PrivateKey, publicKey []byte) []byte
- func Decrypt(key, ciphertext []byte) ([]byte, error)
- func DecryptAndAuthenticate(key, ciphertext, ad []byte) ([]byte, error)
- func DeriveKeys(inputKey []byte, outputLength int) []byte
- func Dial(network, addr string, config *Config) (net.Conn, error)
- func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (net.Conn, error)
- func Encrypt(key, plaintext []byte) []byte
- func EncryptAndAuthenticate(key, plaintext, ad []byte) []byte
- func GenerateAndSaveDiscoRootKeyPair(discoRootPrivateKeyFile string, discoRootPublicKeyFile string) (err error)
- func Hash(input []byte, outputLength int) []byte
- func Initialize(handshakeType noiseHandshakeType, initiator bool, prologue []byte, ...) (hs handshakeState)
- func Listen(network, laddr string, config *Config) (net.Listener, error)
- func LoadDiscoRootPrivateKey(discoRootPrivateKey string) (rootPrivateKey ed25519.PrivateKey, err error)
- func LoadDiscoRootPublicKey(discoRootPublicKey string) (rootPublicKey ed25519.PublicKey, err error)
- func ProtectIntegrity(key, plaintext []byte) []byte
- func RecoverState(serialized []byte, psk []byte, s *KeyPair) handshakeState
- func VerifyIntegrity(key, plaintextAndTag []byte) ([]byte, error)
- type Addr
- type Config
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) Handshake() error
- func (c *Conn) IsRemoteAuthenticated() bool
- func (c *Conn) LocalAddr() net.Addr
- func (c *Conn) Read(b []byte) (n int, err error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) RemotePublicKey() (string, error)
- func (c *Conn) SetDeadline(t time.Time) error
- func (c *Conn) SetReadDeadline(t time.Time) error
- func (c *Conn) SetWriteDeadline(t time.Time) error
- func (c *Conn) Write(b []byte) (int, error)
- type DiscoHash
- type KeyPair
- type Listener
- type Signature
- type SigningKeypair
Constants ¶
const ( DiscoDraftVersion = "3" NoiseDH = "25519" )
The following constants represent the details of this implementation of the Noise specification.
const ( NoiseMessageLength = 65535 - 2 // 2-byte length NoiseTagLength = 16 NoiseMaxPlaintextSize = NoiseMessageLength - NoiseTagLength )
The following constants are taken directly from the Noise specification.
const ( // NoiseUnknown is for specifying an unknown pattern NoiseUnknown noiseHandshakeType = iota // NoiseN is a one-way pattern where a client can send // data to a server with a known static key. The server // can only receive data and cannot reply back. NoiseN // NoiseK is a one-way pattern where a client can send // data to a server with a known static key. The server // can only receive data and cannot reply back. The server // authenticates the client via a known key. NoiseK // NoiseX is a one-way pattern where a client can send // data to a server with a known static key. The server // can only receive data and cannot reply back. The server // authenticates the client via a key transmitted as part // of the handshake. NoiseX // NoiseKK is a pattern where both the client static key and the // server static key are known. NoiseKK // NoiseNX is a "HTTPS"-like pattern where the client is // not authenticated, and the static public key of the server // is transmitted during the handshake. It is the responsability of the client to validate the received key properly. NoiseNX // NoiseNK is a "Public Key Pinning"-like pattern where the client // is not authenticated, and the static public key of the server // is already known. NoiseNK // NoiseXX is a pattern where both static keys are transmitted. // It is the responsability of the server and of the client to // validate the received keys properly. NoiseXX // NoiseKX Not documented NoiseKX // NoiseXK Not documented NoiseXK // NoiseIK Not documented NoiseIK // NoiseIX Not documented NoiseIX // NoiseNNpsk2 Not documented NoiseNNpsk2 // NoiseNN Not implemented NoiseNN // NoiseKN Not implemented NoiseKN // NoiseXN Not implemented NoiseXN // NoiseIN Not implemented NoiseIN )
Variables ¶
This section is empty.
Functions ¶
func CreatePublicKeyVerifier ¶
CreatePublicKeyVerifier can be used to create the callback function PublicKeyVerifier sometimes required in a libdisco.Config for peers that are receiving a static public key at some point during the handshake
func CreateStaticPublicKeyProof ¶
func CreateStaticPublicKeyProof(rootPrivateKey ed25519.PrivateKey, publicKey []byte) []byte
CreateStaticPublicKeyProof can be used to create the proof StaticPublicKeyProof sometimes required in a libdisco.Config for peers that are sending their static public key at some point during the handshake
func Decrypt ¶
Decrypt allows you to decrypt a message that was encrypted with the Encrypt function.
func DecryptAndAuthenticate ¶
DecryptAndAuthenticate allows you to decrypt a message that was encrypted with the Encrypt function.
func DeriveKeys ¶
DeriveKeys allows you to derive keys
func Dial ¶
Dial connects to the given network address using net.Dial and then initiates a Disco handshake, returning the resulting Disco connection. Dial interprets a nil configuration as equivalent to the zero configuration; see the documentation of Config for the defaults.
func DialWithDialer ¶
DialWithDialer connects to the given network address using dialer.Dial and then initiates a Disco handshake, returning the resulting Disco connection. Any timeout or deadline given in the dialer apply to connection and Disco handshake as a whole.
DialWithDialer interprets a nil configuration as equivalent to the zero configuration; see the documentation of Config for the defaults. TODO: make sure sane defaults for time outs are set!!!
func Encrypt ¶
Encrypt allows you to encrypt a plaintext message with a key of any size greater than 128 bits (16 bytes).
func EncryptAndAuthenticate ¶
EncryptAndAuthenticate allows you to encrypt a plaintext message with a key of any size greater than 128 bits (16 bytes).
func GenerateAndSaveDiscoRootKeyPair ¶
func GenerateAndSaveDiscoRootKeyPair(discoRootPrivateKeyFile string, discoRootPublicKeyFile string) (err error)
GenerateAndSaveDiscoRootKeyPair generates an ed25519 root key pair and save the private and public parts in different files.
func Hash ¶
Hash allows you to hash an input of any length and obtain an output of length greater or equal to 256 bits (32 bytes).
func Initialize ¶
func Initialize(handshakeType noiseHandshakeType, initiator bool, prologue []byte, s, e, rs, re *KeyPair) (hs handshakeState)
Initialize allows you to initialize a peer * see `patterns` for a list of available handshakePatterns * initiator = false means the instance is for a responder * prologue is a byte string record of anything that happened prior the Noise handshakeState * s, e, rs, re are the local and remote static/ephemeral key pairs to be set (if they exist) the function returns a handshakeState object.
func Listen ¶
Listen creates a Disco listener accepting connections on the given network address using net.Listen. The configuration config must be non-nil.
func LoadDiscoRootPrivateKey ¶
func LoadDiscoRootPrivateKey(discoRootPrivateKey string) (rootPrivateKey ed25519.PrivateKey, err error)
LoadDiscoRootPrivateKey reads and parses a private Root key from a file. The file contains an 32-byte ed25519 private key in hexadecimal
func LoadDiscoRootPublicKey ¶
LoadDiscoRootPublicKey reads and parses a public Root key from a file. The file contains an 32-byte ed25519 public key in hexadecimal
func ProtectIntegrity ¶
ProtectIntegrity allows you to send a message in cleartext (not encrypted) You can later verify via the VerifyIntegrity function that the message has not been modified
func RecoverState ¶
RecoverState is a helper function to unserialize a previously serialized handshake state (via the `Serialize()` function). For security purposes, the long-term static keypair needs to be passed as argument. RecoverState will crash if the passed serializedState is malformed
func VerifyIntegrity ¶
VerifyIntegrity allows you to retrieve a message created with the ProtectIntegrity function. if it returns an error, it means that the message was altered. Otherwise it returns the original message.
Types ¶
type Addr ¶
type Addr struct {
// contains filtered or unexported fields
}
Addr represents a newtork address.
type Config ¶
type Config struct { // the type of Noise protocol that the client and the server will go through HandshakePattern noiseHandshakeType // the current peer's keyPair KeyPair *KeyPair // the other peer's public key RemoteKey []byte // any messages that the client and the server previously exchanged in clear Prologue []byte // if the chosen handshake pattern requires the current peer to send a static // public key as part of the handshake, this proof over the key is mandatory // in order for the other peer to verify the current peer's key StaticPublicKeyProof []byte // if the chosen handshake pattern requires the remote peer to send an unknown // static public key as part of the handshake, this callback is mandatory in // order to validate it PublicKeyVerifier func(publicKey, proof []byte) bool PreSharedKey []byte // by default a noise protocol is full-duplex, meaning that both the client // and the server can write on the channel at the same time. Setting this value // to true will require the peers to write and read in turns. If this requirement // is not respected by the application, the consequences could be catastrophic HalfDuplex bool // the Accept() and Dial() APIs both return a `net.Conn` interface. // Because of this, functions like `RemotePublicKey()` cannot be called // to circumvent this issue, set the following flag. After that, // `net.Conn`'s `RemoteAddress().String()` will return a tuple `ip:port:pubkey` RemoteAddrContainsRemotePubkey bool }
Config is mandatory to setup a Disco peer. It represents the configuration of the Disco handshake that the peer will go through.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
A Conn represents a secured connection. It implements the net.Conn interface.
func Client ¶
Client returns a new Disco client side connection using conn as the underlying transport. The config cannot be nil: users must set either ServerName or InsecureSkipVerify in the config.
func Server ¶
Server returns a new Disco server side connection using net.Conn as the underlying transport. The configuration config must be non-nil and must include at least one certificate or else set GetCertificate.
func (*Conn) Handshake ¶
Handshake runs the client or server handshake protocol if it has not yet been run. Most uses of this package need not call Handshake explicitly: the first Read or Write will call it automatically.
func (*Conn) IsRemoteAuthenticated ¶
IsRemoteAuthenticated can be used to check if the remote peer has been properly authenticated. It serves no real purpose for the moment as the handshake will not go through if a peer is not properly authenticated in patterns where the peer needs to be authenticated.
func (*Conn) Read ¶
Read can be made to time out and return a net.Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.
func (*Conn) RemoteAddr ¶
RemoteAddr returns the remote network address.
func (*Conn) RemotePublicKey ¶
RemotePublicKey returns the static key of the remote peer. It is useful in case the static key is only transmitted during the handshake.
func (*Conn) SetDeadline ¶
SetDeadline sets the read and write deadlines associated with the connection. A zero value for t means Read and Write will not time out. After a Write has timed out, the Disco state is corrupt and all future writes will return the same error.
func (*Conn) SetReadDeadline ¶
SetReadDeadline sets the read deadline on the underlying connection. A zero value for t means Read will not time out.
func (*Conn) SetWriteDeadline ¶
SetWriteDeadline sets the write deadline on the underlying connection. A zero value for t means Write will not time out. After a Write has timed out, the Disco state is corrupt and all future writes will return the same error.
type DiscoHash ¶
type DiscoHash struct {
// contains filtered or unexported fields
}
DiscoHash represents a strobe hash
func NewHash ¶
NewHash creates a new hashing state, allowing you to absorb data to hash via Write or WriteTuple, and to create a digest via the Sum function.
func (*DiscoHash) Sum ¶
Sum reads more output from the hash; reading affects the hash's state. (DiscoHash.Read is thus very different from Hash.Sum) It never returns an error.
func (*DiscoHash) Write ¶
Write absorbs more data into the hash's state. This function is usually called to hash contigous chunks of data. For structured data please refer to WriteTuple
func (*DiscoHash) WriteTuple ¶
WriteTuple absorbs more data to hash in a non-ambigious way. This means that data absorbed via this function is separated from the data surrounding it. Use this function instead of Write to hash structured data.
type KeyPair ¶
type KeyPair struct { PrivateKey [32]byte // must stay a [32]byte because of Serialize() PublicKey [32]byte // must stay a [32]byte because of Serialize() }
KeyPair contains a private and a public part, both of 32-byte. It can be generated via the GenerateKeyPair() function. The public part can also be extracted via the ExportPublicKey function.
func GenerateAndSaveDiscoKeyPair ¶
func GenerateAndSaveDiscoKeyPair(discoKeyPairFile string, passphrase string) (keyPair *KeyPair, err error)
GenerateAndSaveDiscoKeyPair generates a disco key pair (X25519 key pair) and saves it to a file in hexadecimal form. If a non-empty passphrase is passed, the file will be encrypted. You can use ExportPublicKey() to export the public key part.
func GenerateKeypair ¶
GenerateKeypair creates a X25519 static keyPair out of a private key. If privateKey is nil the function generates a random key pair.
func LoadDiscoKeyPair ¶
LoadDiscoKeyPair reads and parses a public/private key pair from a pair of files. You can pass a non-empty passphrase if the keys are stored encrypted.
func (KeyPair) ExportPublicKey ¶
ExportPublicKey returns the public part in hex format of a static key pair.
type Listener ¶
Listener implements a network listener (net.Listener) for Disco connections.
func ListenDisco ¶
ListenDisco creates a Disco listener accepting connections on the given network address using net.Listen. The configuration config must be non-nil.
func (*Listener) Accept ¶
Accept waits for and returns the next incoming Disco connection. The returned connection is of type *Conn.
func (*Listener) AcceptDisco ¶
AcceptDisco waits for and returns the next incoming Disco connection. The returned connection is of type *Conn.
type Signature ¶
Signature represents a schnorrkel signature
func (*Signature) Decode ¶
Decode a schnorrkel signature from a bytearray. ref: https://github.com/w3f/schnorrkel/blob/master/src/sign.rs#L100
func (*Signature) Encode ¶
Encode a signature as a bytearray. see: https://github.com/w3f/schnorrkel/blob/master/src/sign.rs#L77
type SigningKeypair ¶
SigningKeypair uses deterministic Schnorr with strobe
func GenerateSigningKeypair ¶
func GenerateSigningKeypair() (SigningKeypair, error)
GenerateSigningKeypair for schnorr signatures.
func (SigningKeypair) ExportPublicKey ¶
func (kp SigningKeypair) ExportPublicKey() string
ExportPublicKey returns a hexstring encoding of the signing keypair.
func (SigningKeypair) Sign ¶
func (kp SigningKeypair) Sign(message []byte) Signature
Sign a message using a deterministic nonce