Crypto.Saltine.Core.Box

Public-key cryptography abstraction: Crypto.Saltine.Core.Box

This module consists of functions dealing with two public-key cryptography concepts in libsodium.

The first one is an authenticated encryption scheme. In this scheme, the box function encrypts and authenticates a message ByteString using the sender's secret key, the receiver's public key, and a nonce. The boxOpen function verifies and decrypts a ciphertext ByteString using the receiver's secret key, the sender's public key, and a nonce. If the ciphertext fails verification, boxOpen returns Nothing.

The set of box functions is designed to meet the standard notions of privacy and third-party unforgeability for a public-key authenticated-encryption scheme using nonces. For formal definitions see, e.g., Jee Hea An, "Authenticated encryption in the public-key setting: security notions and analyses," http://eprint.iacr.org/2001/079.

Distinct messages between the same {sender, receiver} set are required to have distinct nonces. For example, the lexicographically smaller public key can use nonce 1 for its first message to the other key, nonce 3 for its second message, nonce 5 for its third message, etc., while the lexicographically larger public key uses nonce 2 for its first message to the other key, nonce 4 for its second message, nonce 6 for its third message, etc. Nonces are long enough that randomly generated nonces have negligible risk of collision.

There is no harm in having the same nonce for different messages if the {sender, receiver} sets are different. This is true even if the sets overlap. For example, a sender can use the same nonce for two different messages if the messages are sent to two different public keys.

The second concept is sealed boxes, which provide encryption and preservation of integrity, but not authentication. Technically, the sender of a message generates a keypair, uses the regular box mechanism, attaches the public key to the message and then immediately destroys the private key. This is useful, e.g. when the receiver cannot know the sender's public key in advance and hence cannot use the regular box functions, or when you want to send messages anonymously.

The Crypto.Saltine.Core.Box module is not meant to provide non-repudiation. On the contrary: the crypto_box function guarantees repudiability. A receiver can freely modify a boxed message, and therefore cannot convince third parties that this particular message came from the sender. The sender and receiver are nevertheless protected against forgeries by other parties. In the terminology of http://groups.google.com/group/sci.crypt/msg/ec5c18b23b11d82c, crypto_box uses "public-key authenticators" rather than "public-key signatures."

Users who want public verifiability (or receiver-assisted public verifiability) should instead use signatures (or signcryption). Signatures are documented in the Crypto.Saltine.Core.Sign module.

Crypto.Saltine.Core.Box is curve25519xsalsa20poly1305, a particular combination of Curve25519, Salsa20, and Poly1305 specified in "Cryptography in NaCl" (http://nacl.cr.yp.to/valid.html). This function is conjectured to meet the standard notions of privacy and third-party unforgeability.

This is version 2010.08.30 of the box.html web page.

Documentation

data SecretKey

An opaque box cryptographic secret key.

Instances

Eq SecretKey

Defined in Crypto.Saltine.Core.Box

Methods

(==) :: SecretKey -> SecretKey -> Bool

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

Data SecretKey

Defined in Crypto.Saltine.Core.Box

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> SecretKey -> c SecretKey

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c SecretKey

toConstr :: SecretKey -> Constr

dataTypeOf :: SecretKey -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c SecretKey)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c SecretKey)

gmapT :: (forall b. Data b => b -> b) -> SecretKey -> SecretKey

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> SecretKey -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> SecretKey -> r

gmapQ :: (forall d. Data d => d -> u) -> SecretKey -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> SecretKey -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> SecretKey -> m SecretKey

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> SecretKey -> m SecretKey

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> SecretKey -> m SecretKey

Ord SecretKey

Defined in Crypto.Saltine.Core.Box

Methods

compare :: SecretKey -> SecretKey -> Ordering

(<) :: SecretKey -> SecretKey -> Bool

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

(>) :: SecretKey -> SecretKey -> Bool

(>=) :: SecretKey -> SecretKey -> Bool

max :: SecretKey -> SecretKey -> SecretKey

min :: SecretKey -> SecretKey -> SecretKey

Generic SecretKey

Defined in Crypto.Saltine.Core.Box

Associated Types

type Rep SecretKey :: Type -> Type

Methods

from :: SecretKey -> Rep SecretKey x

to :: Rep SecretKey x -> SecretKey

Hashable SecretKey

Defined in Crypto.Saltine.Core.Box

Methods

hashWithSalt :: Int -> SecretKey -> Int

hash :: SecretKey -> Int

IsEncoding SecretKey

Defined in Crypto.Saltine.Core.Box

Methods

encode :: SecretKey -> ByteString

decode :: ByteString -> Maybe SecretKey

encoded :: (Choice p, Applicative f) => p SecretKey (f SecretKey) -> p ByteString (f ByteString)

type Rep SecretKey

Defined in Crypto.Saltine.Core.Box

type Rep SecretKey = D1 ('MetaData "SecretKey" "Crypto.Saltine.Core.Box" "saltine-0.1.1.1-KbVmRAcWBV25w8Dlelbdig" 'True) (C1 ('MetaCons "SK" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

data PublicKey

An opaque box cryptographic public key.

Instances

Eq PublicKey

Defined in Crypto.Saltine.Core.Box

Methods

(==) :: PublicKey -> PublicKey -> Bool

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

Data PublicKey

Defined in Crypto.Saltine.Core.Box

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> PublicKey -> c PublicKey

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c PublicKey

toConstr :: PublicKey -> Constr

dataTypeOf :: PublicKey -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c PublicKey)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c PublicKey)

gmapT :: (forall b. Data b => b -> b) -> PublicKey -> PublicKey

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> PublicKey -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> PublicKey -> r

gmapQ :: (forall d. Data d => d -> u) -> PublicKey -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> PublicKey -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> PublicKey -> m PublicKey

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> PublicKey -> m PublicKey

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> PublicKey -> m PublicKey

Ord PublicKey

Defined in Crypto.Saltine.Core.Box

Methods

compare :: PublicKey -> PublicKey -> Ordering

(<) :: PublicKey -> PublicKey -> Bool

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

(>) :: PublicKey -> PublicKey -> Bool

(>=) :: PublicKey -> PublicKey -> Bool

max :: PublicKey -> PublicKey -> PublicKey

min :: PublicKey -> PublicKey -> PublicKey

Generic PublicKey

Defined in Crypto.Saltine.Core.Box

Associated Types

type Rep PublicKey :: Type -> Type

Methods

from :: PublicKey -> Rep PublicKey x

to :: Rep PublicKey x -> PublicKey

Hashable PublicKey

Defined in Crypto.Saltine.Core.Box

Methods

hashWithSalt :: Int -> PublicKey -> Int

hash :: PublicKey -> Int

IsEncoding PublicKey

Defined in Crypto.Saltine.Core.Box

Methods

encode :: PublicKey -> ByteString

decode :: ByteString -> Maybe PublicKey

encoded :: (Choice p, Applicative f) => p PublicKey (f PublicKey) -> p ByteString (f ByteString)

type Rep PublicKey

Defined in Crypto.Saltine.Core.Box

type Rep PublicKey = D1 ('MetaData "PublicKey" "Crypto.Saltine.Core.Box" "saltine-0.1.1.1-KbVmRAcWBV25w8Dlelbdig" 'True) (C1 ('MetaCons "PK" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

type Keypair = (SecretKey, PublicKey)

A convenience type for keypairs

data CombinedKey

An opaque boxAfterNM cryptographic combined key.

Instances

Eq CombinedKey

Defined in Crypto.Saltine.Core.Box

Methods

(==) :: CombinedKey -> CombinedKey -> Bool

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

Data CombinedKey

Defined in Crypto.Saltine.Core.Box

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> CombinedKey -> c CombinedKey

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c CombinedKey

toConstr :: CombinedKey -> Constr

dataTypeOf :: CombinedKey -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c CombinedKey)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c CombinedKey)

gmapT :: (forall b. Data b => b -> b) -> CombinedKey -> CombinedKey

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> CombinedKey -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> CombinedKey -> r

gmapQ :: (forall d. Data d => d -> u) -> CombinedKey -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> CombinedKey -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> CombinedKey -> m CombinedKey

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> CombinedKey -> m CombinedKey

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> CombinedKey -> m CombinedKey

Ord CombinedKey

Defined in Crypto.Saltine.Core.Box

Methods

compare :: CombinedKey -> CombinedKey -> Ordering

(<) :: CombinedKey -> CombinedKey -> Bool

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

(>) :: CombinedKey -> CombinedKey -> Bool

(>=) :: CombinedKey -> CombinedKey -> Bool

max :: CombinedKey -> CombinedKey -> CombinedKey

min :: CombinedKey -> CombinedKey -> CombinedKey

Generic CombinedKey

Defined in Crypto.Saltine.Core.Box

Associated Types

type Rep CombinedKey :: Type -> Type

Methods

from :: CombinedKey -> Rep CombinedKey x

to :: Rep CombinedKey x -> CombinedKey

Hashable CombinedKey

Defined in Crypto.Saltine.Core.Box

Methods

hashWithSalt :: Int -> CombinedKey -> Int

hash :: CombinedKey -> Int

IsEncoding CombinedKey

Defined in Crypto.Saltine.Core.Box

Methods

encode :: CombinedKey -> ByteString

decode :: ByteString -> Maybe CombinedKey

encoded :: (Choice p, Applicative f) => p CombinedKey (f CombinedKey) -> p ByteString (f ByteString)

type Rep CombinedKey

Defined in Crypto.Saltine.Core.Box

type Rep CombinedKey = D1 ('MetaData "CombinedKey" "Crypto.Saltine.Core.Box" "saltine-0.1.1.1-KbVmRAcWBV25w8Dlelbdig" 'True) (C1 ('MetaCons "CK" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

data Nonce

An opaque box nonce.

Instances

Eq Nonce

Defined in Crypto.Saltine.Core.Box

Methods

(==) :: Nonce -> Nonce -> Bool

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

Data Nonce

Defined in Crypto.Saltine.Core.Box

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Nonce -> c Nonce

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Nonce

toConstr :: Nonce -> Constr

dataTypeOf :: Nonce -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Nonce)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Nonce)

gmapT :: (forall b. Data b => b -> b) -> Nonce -> Nonce

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Nonce -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Nonce -> r

gmapQ :: (forall d. Data d => d -> u) -> Nonce -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Nonce -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Nonce -> m Nonce

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Nonce -> m Nonce

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Nonce -> m Nonce

Ord Nonce

Defined in Crypto.Saltine.Core.Box

Methods

compare :: Nonce -> Nonce -> Ordering

(<) :: Nonce -> Nonce -> Bool

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

(>) :: Nonce -> Nonce -> Bool

(>=) :: Nonce -> Nonce -> Bool

max :: Nonce -> Nonce -> Nonce

min :: Nonce -> Nonce -> Nonce

Generic Nonce

Defined in Crypto.Saltine.Core.Box

Associated Types

type Rep Nonce :: Type -> Type

Methods

from :: Nonce -> Rep Nonce x

to :: Rep Nonce x -> Nonce

Hashable Nonce

Defined in Crypto.Saltine.Core.Box

Methods

hashWithSalt :: Int -> Nonce -> Int

hash :: Nonce -> Int

IsNonce Nonce

Defined in Crypto.Saltine.Core.Box

Methods

zero :: Nonce

nudge :: Nonce -> Nonce

IsEncoding Nonce

Defined in Crypto.Saltine.Core.Box

Methods

encode :: Nonce -> ByteString

decode :: ByteString -> Maybe Nonce

encoded :: (Choice p, Applicative f) => p Nonce (f Nonce) -> p ByteString (f ByteString)

type Rep Nonce

Defined in Crypto.Saltine.Core.Box

type Rep Nonce = D1 ('MetaData "Nonce" "Crypto.Saltine.Core.Box" "saltine-0.1.1.1-KbVmRAcWBV25w8Dlelbdig" 'True) (C1 ('MetaCons "Nonce" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

newKeypair :: IO Keypair

Randomly generates a secret key and a corresponding public key.

beforeNM :: SecretKey -> PublicKey -> CombinedKey

Build a CombinedKey for sending from SecretKey to PublicKey. This is a precomputation step which can accelerate later encryption calls.

newNonce :: IO Nonce

Randomly generates a nonce for usage with box and boxOpen.

box

Arguments

:: PublicKey

-> SecretKey

-> Nonce

-> ByteString

Message

-> ByteString

Ciphertext (incl. authentication tag)

Encrypts a message for sending to the owner of the public key. They must have your public key in order to decrypt the message. It is infeasible for an attacker to decrypt the message so long as the Nonce is not repeated.

boxOpen

Arguments

:: PublicKey

-> SecretKey

-> Nonce

-> ByteString

Ciphertext (incl. authentication tag)

-> Maybe ByteString

Message

Decrypts a message sent from the owner of the public key. They must have encrypted it using your public key. Returns Nothing if the keys and message do not match.

boxAfterNM

Arguments

:: CombinedKey

-> Nonce

-> ByteString

Message

-> ByteString

Ciphertext (incl. authentication tag)

box using a CombinedKey and thus faster.

boxOpenAfterNM

Arguments

:: CombinedKey

-> Nonce

-> ByteString

Ciphertext (incl. authentication tag)

-> Maybe ByteString

Message

boxOpen using a CombinedKey and is thus faster.

boxSeal :: PublicKey -> ByteString -> IO ByteString

Encrypts a message for sending to the owner of the public key. The message is unauthenticated, but permits integrity checking.

boxSealOpen

Arguments

:: PublicKey

-> SecretKey

-> ByteString

Ciphertext

-> Maybe ByteString

Message

Decrypts a sealed box message. The message must have been encrypted using the receiver's public key. Returns Nothing if keys and message do not match or integrity is violated.