Maintainer | John Galt <jgalt@centromere.net> |
---|---|
Stability | experimental |
Portability | POSIX |
Safe Haskell | None |
Language | Haskell2010 |
Please see the README for usage information.
Synopsis
- data NoiseState c d h
- data NoiseResult c d h
- = NoiseResultMessage ScrubbedBytes (NoiseState c d h)
- | NoiseResultNeedPSK (NoiseState c d h)
- | NoiseResultException SomeException
- data HandshakePattern
- data HandshakeRole
- data HandshakeOpts d
- defaultHandshakeOpts :: HandshakeRole -> Plaintext -> HandshakeOpts d
- noiseState :: (Cipher c, DH d, Hash h) => HandshakeOpts d -> HandshakePattern -> NoiseState c d h
- writeMessage :: (Cipher c, DH d, Hash h) => ScrubbedBytes -> NoiseState c d h -> NoiseResult c d h
- readMessage :: (Cipher c, DH d, Hash h) => ScrubbedBytes -> NoiseState c d h -> NoiseResult c d h
- 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)
- remoteStaticKey :: NoiseState c d h -> Maybe (PublicKey d)
- handshakeComplete :: NoiseState c d h -> Bool
- handshakeHash :: Hash h => NoiseState c d h -> ScrubbedBytes
- rekeySending :: (Cipher c, DH d, Hash h) => NoiseState c d h -> NoiseState c d h
- rekeyReceiving :: (Cipher c, DH d, Hash h) => NoiseState c d h -> NoiseState c d h
- handshakePattern :: ByteString -> MessageSequence () -> HandshakePattern
- setLocalEphemeral :: Maybe (KeyPair d) -> HandshakeOpts d -> HandshakeOpts d
- setLocalStatic :: Maybe (KeyPair d) -> HandshakeOpts d -> HandshakeOpts d
- setRemoteEphemeral :: Maybe (PublicKey d) -> HandshakeOpts d -> HandshakeOpts d
- setRemoteStatic :: Maybe (PublicKey d) -> HandshakeOpts d -> HandshakeOpts d
- class Cipher c
- class DH d
- class Hash h
- data ScrubbedBytes
- convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout
Types
data NoiseState c d h Source #
data NoiseResult c d h Source #
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.
data HandshakePattern Source #
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 Source #
Represents the side of the conversation upon which a party resides.
Instances
Eq HandshakeRole Source # | |
Defined in Crypto.Noise.Internal.Handshake.State (==) :: HandshakeRole -> HandshakeRole -> Bool # (/=) :: HandshakeRole -> HandshakeRole -> Bool # | |
Show HandshakeRole Source # | |
Defined in Crypto.Noise.Internal.Handshake.State showsPrec :: Int -> HandshakeRole -> ShowS # show :: HandshakeRole -> String # showList :: [HandshakeRole] -> ShowS # |
data HandshakeOpts d Source #
Represents the various options and keys for a handshake parameterized by
the DH
method.
Functions
defaultHandshakeOpts :: HandshakeRole -> Plaintext -> HandshakeOpts d Source #
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 Source #
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 Source #
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 Source #
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) Source #
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) Source #
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 Source #
Returns True
if the handshake is complete.
handshakeHash :: Hash h => NoiseState c d h -> ScrubbedBytes Source #
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 Source #
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 Source #
Rekeys the receiving CipherState
according to section 11.3 of the
protocol.
handshakePattern :: ByteString -> MessageSequence () -> HandshakePattern Source #
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 Source #
Sets the local ephemeral key.
setLocalStatic :: Maybe (KeyPair d) -> HandshakeOpts d -> HandshakeOpts d Source #
Sets the local static key.
setRemoteEphemeral :: Maybe (PublicKey d) -> HandshakeOpts d -> HandshakeOpts d Source #
Sets the remote ephemeral key (rarely needed).
setRemoteStatic :: Maybe (PublicKey d) -> HandshakeOpts d -> HandshakeOpts d Source #
Sets the remote static key.
Classes
Typeclass for ciphers.
cipherName, cipherEncrypt, cipherDecrypt, cipherZeroNonce, cipherMaxNonce, cipherIncNonce, cipherNonceEq, cipherNonceCmp, cipherBytesToSym, cipherSymToBytes, cipherTextToBytes, cipherBytesToText
Instances
Typeclass for Diffie-Hellman key agreement.
dhName, dhLength, dhGenKey, dhPerform, dhPubToBytes, dhBytesToPub, dhSecToBytes, dhBytesToPair, dhPubEq
Instances
Typeclass for hashes.
Instances
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
convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout #
Convert a bytearray to another type of bytearray