Crypto.Noise

Please see the README for usage information.

Types

data NoiseState c d h

This type represents the state of an entire Noise conversation, and it is used both during the handshake and for every message read and written thereafter (transport messages). It is parameterized by the Cipher, DH method, and Hash to be used.

data NoiseResult c d h

This type is used to indicate to the user the result of either writing or reading a message. In the simplest case, when processing a handshake or transport message, the (en|de)crypted message and mutated state will be available in NoiseResultMessage.

If during the course of the handshake a pre-shared key is needed, a NoiseResultNeedPSK value will be returned along with the mutated state. To continue, the user must re-issue the writeMessage or readMessage call, passing in the PSK as the payload. If no further PSKs are required, the result will be NoiseResultMessage.

If an exception is encountered at any point while processing a handshake or transport message, NoiseResultException will be returned.

Constructors

NoiseResultMessage ScrubbedBytes (NoiseState c d h)

NoiseResultNeedPSK (NoiseState c d h)

NoiseResultException SomeException

data HandshakePattern

This type represents a handshake pattern such as Noise_IK. A large set of pre-defined patterns can be found in Crypto.Noise.HandshakePatterns. Expert users are encouraged to define their own custom patterns with care.

data HandshakeRole

Represents the side of the conversation upon which a party resides.

Constructors

InitiatorRole

ResponderRole

Instances

Eq HandshakeRole

Methods

(==) :: HandshakeRole -> HandshakeRole -> Bool

(/=) :: HandshakeRole -> HandshakeRole -> Bool

Show HandshakeRole

Methods

showsPrec :: Int -> HandshakeRole -> ShowS

show :: HandshakeRole -> String

showList :: [HandshakeRole] -> ShowS

data HandshakeOpts d

Represents the various options and keys for a handshake parameterized by the DH method.

Functions

defaultHandshakeOpts :: HandshakeRole -> Plaintext -> HandshakeOpts d

defaultHandshakeOpts role prologue returns a default set of handshake options. All keys are set to Nothing.

noiseState :: (Cipher c, DH d, Hash h) => HandshakeOpts d -> HandshakePattern -> NoiseState c d h

Creates a NoiseState from the given handshake options and pattern.

writeMessage :: (Cipher c, DH d, Hash h) => ScrubbedBytes -> NoiseState c d h -> NoiseResult c d h

Creates a handshake or transport message with the provided payload. Note that the payload may not be authenticated or encrypted at all points during the handshake. Please see section 7.4 of the protocol document for details.

If a previous call to this function indicated that a pre-shared key is needed, it shall be provided as the payload. See the documentation of NoiseResult for details.

To prevent catastrophic key re-use, this function may only be used to secure 2^64 - 1 post-handshake messages.

readMessage :: (Cipher c, DH d, Hash h) => ScrubbedBytes -> NoiseState c d h -> NoiseResult c d h

Reads a handshake or transport message and returns the embedded payload. If the handshake fails, a HandshakeError will be returned. After the handshake is complete, if decryption fails a DecryptionError is returned.

If a previous call to this function indicated that a pre-shared key is needed, it shall be provided as the payload. See the documentation of NoiseResult for details.

To prevent catastrophic key re-use, this function may only be used to receive 2^64 - 1 post-handshake messages.

processPSKs :: (Cipher c, DH d, Hash h) => (ScrubbedBytes -> NoiseState c d h -> NoiseResult c d h) -> [ScrubbedBytes] -> NoiseResult c d h -> ([ScrubbedBytes], NoiseResult c d h)

Given an operation (writeMessage or readMessage), a list of PSKs, and a NoiseResult, this function will repeatedly apply PSKs to the NoiseState until no more are requested or the list of PSKs becomes empty. This is useful for patterns which require two or more PSKs, and you know exactly what they all should be ahead of time.

remoteStaticKey :: NoiseState c d h -> Maybe (PublicKey d)

For handshake patterns where the remote party's static key is transmitted, this function can be used to retrieve it. This allows for the creation of public key-based access-control lists.

handshakeComplete :: NoiseState c d h -> Bool

Returns True if the handshake is complete.

handshakeHash :: Hash h => NoiseState c d h -> ScrubbedBytes

Retrieves the h value associated with the conversation's SymmetricState. This value is intended to be used for channel binding. For example, the initiator might cryptographically sign this value as part of some higher-level authentication scheme.

The value returned by this function is only meaningful after the handshake is complete.

See section 11.2 of the protocol for details.

rekeySending :: (Cipher c, DH d, Hash h) => NoiseState c d h -> NoiseState c d h

Rekeys the sending CipherState according to section 11.3 of the protocol.

rekeyReceiving :: (Cipher c, DH d, Hash h) => NoiseState c d h -> NoiseState c d h

Rekeys the receiving CipherState according to section 11.3 of the protocol.

handshakePattern :: ByteString -> MessageSequence () -> HandshakePattern

Constructs a HandshakePattern given a protocol name (such as XXpsk3) and raw pattern. Please see the README for information about creating your own custom patterns.

HandshakeOpts Setters

setLocalEphemeral :: Maybe (KeyPair d) -> HandshakeOpts d -> HandshakeOpts d

Sets the local ephemeral key.

setLocalStatic :: Maybe (KeyPair d) -> HandshakeOpts d -> HandshakeOpts d

Sets the local static key.

setRemoteEphemeral :: Maybe (PublicKey d) -> HandshakeOpts d -> HandshakeOpts d

Sets the remote ephemeral key (rarely needed).

setRemoteStatic :: Maybe (PublicKey d) -> HandshakeOpts d -> HandshakeOpts d

Sets the remote static key.

Classes

class Cipher c

Typeclass for ciphers.

Minimal complete definition

cipherName, cipherEncrypt, cipherDecrypt, cipherZeroNonce, cipherMaxNonce, cipherIncNonce, cipherNonceEq, cipherNonceCmp, cipherBytesToSym, cipherSymToBytes, cipherTextToBytes, cipherBytesToText

Instances

Cipher AESGCM

Associated Types

data Ciphertext AESGCM :: *

data SymmetricKey AESGCM :: *

data Nonce AESGCM :: *

Methods

cipherName :: proxy AESGCM -> ScrubbedBytes

cipherEncrypt :: SymmetricKey AESGCM -> Nonce AESGCM -> AssocData -> Plaintext -> Ciphertext AESGCM

cipherDecrypt :: SymmetricKey AESGCM -> Nonce AESGCM -> AssocData -> Ciphertext AESGCM -> Maybe Plaintext

cipherRekey :: SymmetricKey AESGCM -> SymmetricKey AESGCM

cipherZeroNonce :: Nonce AESGCM

cipherMaxNonce :: Nonce AESGCM

cipherIncNonce :: Nonce AESGCM -> Nonce AESGCM

cipherNonceEq :: Nonce AESGCM -> Nonce AESGCM -> Bool

cipherNonceCmp :: Nonce AESGCM -> Nonce AESGCM -> Ordering

cipherBytesToSym :: ScrubbedBytes -> SymmetricKey AESGCM

cipherSymToBytes :: SymmetricKey AESGCM -> ScrubbedBytes

cipherTextToBytes :: Ciphertext AESGCM -> ScrubbedBytes

cipherBytesToText :: ScrubbedBytes -> Ciphertext AESGCM

Cipher ChaChaPoly1305

Associated Types

data Ciphertext ChaChaPoly1305 :: *

data SymmetricKey ChaChaPoly1305 :: *

data Nonce ChaChaPoly1305 :: *

Methods

cipherName :: proxy ChaChaPoly1305 -> ScrubbedBytes

cipherEncrypt :: SymmetricKey ChaChaPoly1305 -> Nonce ChaChaPoly1305 -> AssocData -> Plaintext -> Ciphertext ChaChaPoly1305

cipherDecrypt :: SymmetricKey ChaChaPoly1305 -> Nonce ChaChaPoly1305 -> AssocData -> Ciphertext ChaChaPoly1305 -> Maybe Plaintext

cipherRekey :: SymmetricKey ChaChaPoly1305 -> SymmetricKey ChaChaPoly1305

cipherZeroNonce :: Nonce ChaChaPoly1305

cipherMaxNonce :: Nonce ChaChaPoly1305

cipherIncNonce :: Nonce ChaChaPoly1305 -> Nonce ChaChaPoly1305

cipherNonceEq :: Nonce ChaChaPoly1305 -> Nonce ChaChaPoly1305 -> Bool

cipherNonceCmp :: Nonce ChaChaPoly1305 -> Nonce ChaChaPoly1305 -> Ordering

cipherBytesToSym :: ScrubbedBytes -> SymmetricKey ChaChaPoly1305

cipherSymToBytes :: SymmetricKey ChaChaPoly1305 -> ScrubbedBytes

cipherTextToBytes :: Ciphertext ChaChaPoly1305 -> ScrubbedBytes

cipherBytesToText :: ScrubbedBytes -> Ciphertext ChaChaPoly1305

class DH d

Typeclass for Diffie-Hellman key agreement.

Minimal complete definition

dhName, dhLength, dhGenKey, dhPerform, dhPubToBytes, dhBytesToPub, dhSecToBytes, dhBytesToPair, dhPubEq

Instances

DH Curve25519

Associated Types

data PublicKey Curve25519 :: *

data SecretKey Curve25519 :: *

Methods

dhName :: proxy Curve25519 -> ScrubbedBytes

dhLength :: proxy Curve25519 -> Int

dhGenKey :: IO (KeyPair Curve25519)

dhPerform :: SecretKey Curve25519 -> PublicKey Curve25519 -> ScrubbedBytes

dhPubToBytes :: PublicKey Curve25519 -> ScrubbedBytes

dhBytesToPub :: ScrubbedBytes -> Maybe (PublicKey Curve25519)

dhSecToBytes :: SecretKey Curve25519 -> ScrubbedBytes

dhBytesToPair :: ScrubbedBytes -> Maybe (KeyPair Curve25519)

dhPubEq :: PublicKey Curve25519 -> PublicKey Curve25519 -> Bool

DH Curve448

Associated Types

data PublicKey Curve448 :: *

data SecretKey Curve448 :: *

Methods

dhName :: proxy Curve448 -> ScrubbedBytes

dhLength :: proxy Curve448 -> Int

dhGenKey :: IO (KeyPair Curve448)

dhPerform :: SecretKey Curve448 -> PublicKey Curve448 -> ScrubbedBytes

dhPubToBytes :: PublicKey Curve448 -> ScrubbedBytes

dhBytesToPub :: ScrubbedBytes -> Maybe (PublicKey Curve448)

dhSecToBytes :: SecretKey Curve448 -> ScrubbedBytes

dhBytesToPair :: ScrubbedBytes -> Maybe (KeyPair Curve448)

dhPubEq :: PublicKey Curve448 -> PublicKey Curve448 -> Bool

class Hash h

Typeclass for hashes.

Minimal complete definition

hashName, hashLength, hash, hashHKDF, hashBytesToCK, hashCKToBytes, hashToBytes

Instances

Hash BLAKE2b

Associated Types

data ChainingKey BLAKE2b :: *

data Digest BLAKE2b :: *

Methods

hashName :: proxy BLAKE2b -> ScrubbedBytes

hashLength :: proxy BLAKE2b -> Int

hash :: ScrubbedBytes -> Digest BLAKE2b

hashHKDF :: ChainingKey BLAKE2b -> ScrubbedBytes -> Word8 -> [ScrubbedBytes]

hashBytesToCK :: ScrubbedBytes -> ChainingKey BLAKE2b

hashCKToBytes :: ChainingKey BLAKE2b -> ScrubbedBytes

hashToBytes :: Digest BLAKE2b -> ScrubbedBytes

Hash BLAKE2s

Associated Types

data ChainingKey BLAKE2s :: *

data Digest BLAKE2s :: *

Methods

hashName :: proxy BLAKE2s -> ScrubbedBytes

hashLength :: proxy BLAKE2s -> Int

hash :: ScrubbedBytes -> Digest BLAKE2s

hashHKDF :: ChainingKey BLAKE2s -> ScrubbedBytes -> Word8 -> [ScrubbedBytes]

hashBytesToCK :: ScrubbedBytes -> ChainingKey BLAKE2s

hashCKToBytes :: ChainingKey BLAKE2s -> ScrubbedBytes

hashToBytes :: Digest BLAKE2s -> ScrubbedBytes

Hash SHA256

Associated Types

data ChainingKey SHA256 :: *

data Digest SHA256 :: *

Methods

hashName :: proxy SHA256 -> ScrubbedBytes

hashLength :: proxy SHA256 -> Int

hash :: ScrubbedBytes -> Digest SHA256

hashHKDF :: ChainingKey SHA256 -> ScrubbedBytes -> Word8 -> [ScrubbedBytes]

hashBytesToCK :: ScrubbedBytes -> ChainingKey SHA256

hashCKToBytes :: ChainingKey SHA256 -> ScrubbedBytes

hashToBytes :: Digest SHA256 -> ScrubbedBytes

Hash SHA512

Associated Types

data ChainingKey SHA512 :: *

data Digest SHA512 :: *

Methods

hashName :: proxy SHA512 -> ScrubbedBytes

hashLength :: proxy SHA512 -> Int

hash :: ScrubbedBytes -> Digest SHA512

hashHKDF :: ChainingKey SHA512 -> ScrubbedBytes -> Word8 -> [ScrubbedBytes]

hashBytesToCK :: ScrubbedBytes -> ChainingKey SHA512

hashCKToBytes :: ChainingKey SHA512 -> ScrubbedBytes

hashToBytes :: Digest SHA512 -> ScrubbedBytes

Re-exports

data ScrubbedBytes :: *

ScrubbedBytes is a memory chunk which have the properties of:

• Being scrubbed after its goes out of scope.
• A Show instance that doesn't actually show any content
• A Eq instance that is constant time

Instances

Eq ScrubbedBytes

Methods

(==) :: ScrubbedBytes -> ScrubbedBytes -> Bool

(/=) :: ScrubbedBytes -> ScrubbedBytes -> Bool

Ord ScrubbedBytes

Methods

compare :: ScrubbedBytes -> ScrubbedBytes -> Ordering

(<) :: ScrubbedBytes -> ScrubbedBytes -> Bool

(<=) :: ScrubbedBytes -> ScrubbedBytes -> Bool

(>) :: ScrubbedBytes -> ScrubbedBytes -> Bool

(>=) :: ScrubbedBytes -> ScrubbedBytes -> Bool

max :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes

min :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes

Show ScrubbedBytes

Methods

showsPrec :: Int -> ScrubbedBytes -> ShowS

show :: ScrubbedBytes -> String

showList :: [ScrubbedBytes] -> ShowS

IsString ScrubbedBytes

Methods

fromString :: String -> ScrubbedBytes

Monoid ScrubbedBytes

Methods

mempty :: ScrubbedBytes

mappend :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes

mconcat :: [ScrubbedBytes] -> ScrubbedBytes

ByteArray ScrubbedBytes

Methods

allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ScrubbedBytes)

ByteArrayAccess ScrubbedBytes

Methods

length :: ScrubbedBytes -> Int

withByteArray :: ScrubbedBytes -> (Ptr p -> IO a) -> IO a

NFData ScrubbedBytes

Methods

rnf :: ScrubbedBytes -> ()

convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout

Convert a bytearray to another type of bytearray