Copyright | (c) Joseph Abrahamson 2013 |
---|---|
License | MIT |
Maintainer | me@jspha.com |
Stability | experimental |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
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.
Synopsis
- data SecretKey
- data PublicKey
- type Keypair = (SecretKey, PublicKey)
- data CombinedKey
- data Nonce
- newKeypair :: IO Keypair
- beforeNM :: SecretKey -> PublicKey -> CombinedKey
- newNonce :: IO Nonce
- box :: PublicKey -> SecretKey -> Nonce -> ByteString -> ByteString
- boxOpen :: PublicKey -> SecretKey -> Nonce -> ByteString -> Maybe ByteString
- boxAfterNM :: CombinedKey -> Nonce -> ByteString -> ByteString
- boxOpenAfterNM :: CombinedKey -> Nonce -> ByteString -> Maybe ByteString
- boxSeal :: PublicKey -> ByteString -> IO ByteString
- boxSealOpen :: PublicKey -> SecretKey -> ByteString -> Maybe ByteString
Documentation
An opaque box
cryptographic secret key.
Instances
Eq SecretKey Source # | |
Ord SecretKey Source # | |
Defined in Crypto.Saltine.Core.Box | |
IsEncoding SecretKey Source # | |
Defined in Crypto.Saltine.Core.Box encode :: SecretKey -> ByteString Source # decode :: ByteString -> Maybe SecretKey Source # encoded :: (Choice p, Applicative f) => p SecretKey (f SecretKey) -> p ByteString (f ByteString) Source # |
An opaque box
cryptographic public key.
Instances
Eq PublicKey Source # | |
Ord PublicKey Source # | |
Defined in Crypto.Saltine.Core.Box | |
IsEncoding PublicKey Source # | |
Defined in Crypto.Saltine.Core.Box encode :: PublicKey -> ByteString Source # decode :: ByteString -> Maybe PublicKey Source # encoded :: (Choice p, Applicative f) => p PublicKey (f PublicKey) -> p ByteString (f ByteString) Source # |
data CombinedKey Source #
An opaque boxAfterNM
cryptographic combined key.
Instances
Eq CombinedKey Source # | |
Defined in Crypto.Saltine.Core.Box (==) :: CombinedKey -> CombinedKey -> Bool # (/=) :: CombinedKey -> CombinedKey -> Bool # | |
Ord CombinedKey Source # | |
Defined in Crypto.Saltine.Core.Box compare :: CombinedKey -> CombinedKey -> Ordering # (<) :: CombinedKey -> CombinedKey -> Bool # (<=) :: CombinedKey -> CombinedKey -> Bool # (>) :: CombinedKey -> CombinedKey -> Bool # (>=) :: CombinedKey -> CombinedKey -> Bool # max :: CombinedKey -> CombinedKey -> CombinedKey # min :: CombinedKey -> CombinedKey -> CombinedKey # | |
IsEncoding CombinedKey Source # | |
Defined in Crypto.Saltine.Core.Box encode :: CombinedKey -> ByteString Source # decode :: ByteString -> Maybe CombinedKey Source # encoded :: (Choice p, Applicative f) => p CombinedKey (f CombinedKey) -> p ByteString (f ByteString) Source # |
An opaque box
nonce.
Instances
Eq Nonce Source # | |
Ord Nonce Source # | |
IsNonce Nonce Source # | |
IsEncoding Nonce Source # | |
Defined in Crypto.Saltine.Core.Box encode :: Nonce -> ByteString Source # decode :: ByteString -> Maybe Nonce Source # encoded :: (Choice p, Applicative f) => p Nonce (f Nonce) -> p ByteString (f ByteString) Source # |
newKeypair :: IO Keypair Source #
Randomly generates a secret key and a corresponding public key.
beforeNM :: SecretKey -> PublicKey -> CombinedKey Source #
Build a CombinedKey
for sending from SecretKey
to
PublicKey
. This is a precomputation step which can accelerate
later encryption calls.
:: 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.
:: 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.
:: CombinedKey | |
-> Nonce | |
-> ByteString | Message |
-> ByteString | Ciphertext (incl. authentication tag) |
box
using a CombinedKey
and thus faster.
:: CombinedKey | |
-> Nonce | |
-> ByteString | Ciphertext (incl. authentication tag) |
-> Maybe ByteString | Message |
boxOpen
using a CombinedKey
and is thus faster.
boxSeal :: PublicKey -> ByteString -> IO ByteString Source #
Encrypts a message for sending to the owner of the public key. The message is unauthenticated, but permits integrity checking.
:: 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.