# Summary
This is a **portable crypto library** that exposes a restricted API that is
**secure by design**, for use as a black-box building block in cryptographic
protocols.  Security and portability are emphasized over efficient (compact)
encodings, but keeping the crypto overhead reasonably minimal is still a
requirement. The API and implementation should encourage the use of best
practices, and reduce the likelihood of common protocol design errors.

# Overview
Existing cryptographic libraries available in most languages typically expose
raw crypto primitives (e.g., block ciphers with modes of operation, HMACs,
digital signatures) that are often applied incorrectly in protocol design.
While these libraries are "standards compliant", they do little or nothing to
guide the protocol designer to produce secure protocol designs. Worse still,
they leave ample room for implementations to introduce subtle security bugs
such as timing attacks.

The SecureMessage library leverages Google's protobuffer technology to provide
a simple and portable encoding for public keys and signed/encrypted data. The
exposed API consists of two main classes, and two supporting classes.

The main classes are:

* Secure Message Builder -- used to craft SecureMessage protos from the input
  data, metadata, and keys

* Secure Message Parser -- used to extract the original input data and metadata
  from a SecureMessage proto, while performing all necessary verification,
  decryption, and sanity checking in a secure fashion

The supporting classes are:

* PublicKeyProtoUtil -- provides simple protobuf based encoding/decoding for
  public keys (either EC or RSA), including appropriate security checks to
  reject maliciously crafted inputs (e.g., EC public keys that are not on the
  curve). Also assists with key generation.


* CryptoOps -- provides clean abstractions for various low-level cryptographic
  operations, making it easier to port the library to new crypto providers (and
  in the case of HKDF, providing clients of the library with access a portable
  API for that primitive too, since it is not commonly available).

In all cases, exposed APIs are carefully thought out, in order to encourage
safe use and prevent unsafe use. For example, the SecureMessageParser API will
not return the original input data unless the signature on it has been verified
first. It also requires the caller to specify exactly which signature algorithm
is expected to be used, to prevent callers from accidentally consuming messages
sent using any other (potentially deprecated / insecure) signature algorithms.

Currently supported signature algorithms are:

* EC DSA on the NIST P-256 curve, using a SHA-256 digest (ANSI X9.62)
* 2048-bit RSA signatures using a SHA-256 digest (PKCS#1)
* HMAC with SHA-256 for "symmetric key signature" (RFC 2104)

Currently supported encryption algorithms are:

* AES-256 in CBC mode for symmetric key encryption

# Features and API
The basic API for SecureMessage consists of two classes, one of which creates
SecureMessages, whereas the other parses them.  There are two basic types of
SecureMessage which these classes manipulate:

* Signed Cleartext - This is used for messages that do not require any privacy
  guarantee, but which need to be authenticated. In particular, the "signature"
  may be either a digital signature, or a MAC.

* Signcrypted - This is used when both privacy and authenticity are required.
  The body data will first be encrypted, and then "signed". (Special measures
  are taken to ensure that the original signature cannot be stripped off of the
  encrypted data and replaced by another signature from a different signer.)

Note that we use the term "signature" in a generic sense, to refer to either
digital signatures (using asymmetric keys) or Message Authentication Codes
(using symmetric keys). Currently, the encryption component of signcrypted
messages only supports symmetric key encryption schemes, but this may change in
the future.

Each SecureMessage consists of two primary components: a header and a body.
The header describes the structure of the SecureMessage as well as providing a
convenient location for metadata related to the body. The body of the
SecureMessage will contain the primary payload. Rather than using the protobuf
APIs to retrieve these components from a SecureMessage, the SecureMessageParser
must be used. The header component is always sent in the clear, and can be
extracted from the SecureMessage by calling SecureMessageParser's
getUnverifiedHeader() method without the use of any cryptographic keys. Thus,
it is possible to use the header contents to determine which key(s) must be
used to verify (and possibly decrypt) the body.  In order to retrieve the body
component, an appropriate call must be made to SecureMessageParser's
parseSignedCleartextMessage() or parseSigncryptedMessage() method, depending on
which of the two message types was sent.

To provide better support for building cryptographic protocols, we also provide
a utility class called PublicKeyProtoUtil that assists with encoding and
parsing public keys in a simple wire format, as well as generating new key
pairs. In particular, this class can be used to dramatically simplify
Diffie-Hellman key exchanges.

# Caveats
There is a some excess overhead incurred for using this library, as compared to
a more "direct" implementation of almost any of the offered functionality. The
excess overhead is the price being paid for simplicity and robustness, both in
the API and in the implementation. If saving every CPU cycle or every bit of
bandwidth is of crucial importance to you, do not use this library (for
example, it would not make for a good SSL replacement for high volume traffic).
To get a sense for magnitude of the SecureMessage overhead, a symmetric key
based HMAC SHA-256 and AES-256 CBC mode authenticated encryption incurs a
maximum of about 80 bytes of overhead with SecureMessage, as opposed to a
maximum of about 64 bytes of overhead using a direct implementation of the same
thing.

Encryption without signature is intentionally unsupported. Historically,
offering encryption-only APIs has lead to a plethora of mistakes in protocol
design and implementation, since it is frequently assumed that encrypted data
cannot be tampered with (but this is not the case in practice).

Support for public key encryption is not yet available, although it may be
added in the future. Instead, we recommend to design protocols that use
(EC)Diffie-Hellman key exchanges, and then used the exchanged symmetric key for
encryption. For instance, this approach can offer forward secrecy, and
increased efficiency when multiple messages are concerned.  Note that it is
easy to authenticate the Diffie-Hellman keys using a signature-only
SecureMessage wrapping with a public key signature scheme.

# Checkout instructions
```
git clone https://github.com/google/securemessage
cd securemessage
git submodule update --init --recursive
```

# Compilation and Use
See language specific implementation directories
