Crate secure_serialisation

Secure Serialisation

Given a remote nacl box PublicKey this lib will securely serialise and encrypt messages destined for that node. These will use authenticated encryption.

Authenticated encryption

Using public-key authenticated encryption, Bob can encrypt a confidential message specifically for Alice, using Alice's public key.

Using Bob's public key, Alice can verify that the encrypted message was actually created by Bob and was not tampered with, before eventually decrypting it.

Alice only needs Bob's public key, the nonce and the ciphertext. Bob should never ever share his secret key, even with Alice. And in order to send messages to Alice, Bob only needs Alice's public key. Alice should never ever share her secret key either, even with Bob.

Alice can reply to Bob using the same system, without having to generate a distinct key pair. The nonce doesn't have to be confidential, but it should be used with just one invocation of crypto_box_open_easy() for a particular pair of public and secret keys.

One easy way to generate a nonce is to use randombytes_buf(); considering the size of nonces the risk of any random collisions is negligible. For some applications, if you wish to use nonces to detect missing messages or to ignore replayed messages, it is also OK to use a simple incrementing counter as a nonce. In this crate we use a random nonce wrapped into the message.

This implementation will encrypt data with a nonce and then serialise the payload. The nonce is then prepended to the message and pulled off first at the remote end. This provides a clean, secure mechanism for sending data between entities who have session-based keypairs. It SHOULD NOT be used for permanent keys.

Where possible the precompute_* functions will lessen any CPU overhead in sending messages and should be preferred. This is not enforced to allow occasional sending of messages between parties using a simpler, although slower, method.

These functions are not meant to provide non-repudiation. On the contrary: they guarantee repudiability. A receiver can freely modify a 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, this crate uses "public-key authenticators" rather than "public-key signatures."

Anonymous encryption

Sealed boxes are designed to anonymously send messages to a recipient given its public key.

Only the recipient can decrypt these messages, using its private key. While the recipient can verify the integrity of the message, it cannot verify the identity of the sender. A message is encrypted using an ephemeral key pair, whose secret part is destroyed right after the encryption process. Without knowing the secret key used for a given message, the sender cannot decrypt its own message later. And without additional data, a message cannot be correlated with the identity of its sender.

Structs

PrecomputedKey	Applications that send several messages to the same receiver can gain speed by splitting seal() into two steps, precompute() and seal_precomputed(). Similarly, applications that receive several messages from the same sender can gain speed by splitting open() into two steps, precompute() and open_precomputed().
PublicKey	PublicKey for asymmetric authenticated encryption
SecretKey	SecretKey for asymmetric authenticated encryption

Enums

Error

Error types.

Functions

anonymous_deserialise	Parse a tuple data type from an encoded message from a sender whose public key we do not know. Success does not provide any guarantee of correlation between the expected and actual identity of the message sender.
anonymous_serialise	Prepare an encodable data element for transmission to another process, whose public key we know, that does not know our public key.
deserialise	Parse a data type from an encoded message from a sender whose public key we know. Success ensures the message was from the holder of the private key related to the public key we know of the sender.
gen_keypair	gen_keypair() randomly generates a secret key and a corresponding public key.
pre_computed_deserialise	Parse a data type from an encoded message from a sender whose public key we know, and which is pre-computed. This is less CPU-intensive than deserialise() which can be useful if many messages are to be transferred. Success ensures the message was from the holder of the private key related to the public key we know of the sender.
pre_computed_serialise	Prepare an encodable data element for transmission to another process whose public key we know, and which is pre-computed. This is less CPU-intensive than serialise() which can be useful if many messages are to be transferred.
precompute	precompute() computes an intermediate key that can be used by seal_precomputed() and open_precomputed()
serialise	Prepare an encodable data element for transmission to another process whose public key we know.