The MonoCypher encryption API is based on the Monocypher library: https://monocypher.org/. More...

Detailed Description

The MonoCypher encryption API is based on the Monocypher library: https://monocypher.org/.

The encryption uses a Chacha20 cipher and the Poly1305 one-time authenticator The asymmetric cryptography implements X25519, based on the Curve25519 elliptic curve. Hashing is done using the Blake2 algorithm, which combines the security of SHA-3 with the speed of MD5. The Key type defines a 32 byte key, used both in the case of symmetric and symmetric encryption.

To use symmetric encryption: Generate a Key with getRandomKey(), or through any other source. Then call encrypt() to encrypt, and decrypt() to decrypt.
To use asymmetric encryption: Generate a Private key using getRandomKey(), or through any other source. Get the public key using getPublicEncryptionKeyFromPrivateKey(). Encrypt the message using encryptAsymmetric() and decrypt using decryptAsymmetric().
To sign a message: Generate a Private key using getRandomKey(), or through any other source. Get the public key using getPublicSigningKeyFromPrivateKey().
Note
This is a different function from the encryption above. Do not generate and publish both types of public keys from the same private key, this has security issues!
Sign a message using: signMessage(). Verify a message using: verifySignature().

Typedefs
typedef std::array< uint8_t, 32 >	Key

typedef std::array< uint8_t, 64 >	Signature

typedef std::array< uint8_t, 64 >	Hash

Symmetric encryption
std::optional< ByteBuffer >	encrypt (const ByteBufferView &message, const Key &key)
	Encrypt message using a 32 byte key.

std::optional< ByteBuffer >	decrypt (const ByteBufferView &encryptedMessage, const Key &key)
	Decrypt message using a 32 byte key.

Key	getRandomKey ()
	Get a random 32 byte key for encryption / decryption.

bool	encryptToFile (const ByteBufferView &data, const std::string &filename, const Key &key)
	Encrypt the input buffer and write the result to a file. Returns true on success.

std::optional< ByteBuffer >	decryptFromFile (const std::string &filename, const Key &key)
	Read an encrypted file and return the decrypted data. Returns an empty optional on failure.

bool	encryptToFileAsymmetric (const ByteBufferView &data, const std::string &filename, const Key &publicKey)
	Encrypt the input buffer using a public key (generated by getPublicEncryptionKeyFromPrivateKey) and write the result to a file. Returns true on success.

std::optional< ByteBuffer >	decryptFromFileAsymmetric (const std::string &filename, const Key &privateKey)
	Read an encrypted file using a private key.

Asymmetric encryption
Key	getPublicEncryptionKeyFromPrivateKey (const Key &privateKey)
	Get public exchange key given a 32 byte private key.

Key	getSharedSecret (const Key &theirPublicKey, const Key &yourPrivateKey)
	Get shared 32 byte secret given a 32 byte public key and another 32 byte private key.

std::optional< ByteBuffer >	encryptAsymmetric (const ByteBufferView &message, const Key &publicKey)
	Encrypt data using a 32 byte public key.

std::optional< ByteBuffer >	decryptAsymmetric (const ByteBufferView &encryptedMessage, const Key &privateKey)
	Decrypt data using a 32 byte private key.

Signing API
Key	getPublicSigningKeyFromPrivateKey (const Key &privateKey)
	Get 32 byte public signing key given a 32 byte private key.

Signature	signMessage (const ByteBufferView &message, const Key &privateKey)
	Sign a message using a private key.

bool	verifySignature (const ByteBufferView &message, const Signature &signature, const Key &publicKey)
	Verify a signature with a message and public key.

Function Documentation

◆ encrypt()

std::optional< ByteBuffer > encrypt	(	const ByteBufferView &	message,
		const Key &	key )

Encrypt message using a 32 byte key.

Key can be generated using getRandomKey(); Resulting buffer will have lengh(message) + 40 bytes for nonce / authentication Returns an Optional that is empty on failure to encrypt.

◆ decrypt()

std::optional< ByteBuffer > decrypt	(	const ByteBufferView &	encryptedMessage,
		const Key &	key )

Decrypt message using a 32 byte key.

Key should be the same as was used for encryption. Returns an Optional that is empty on failure to decrypt.

◆ getRandomKey()

Key getRandomKey ( )

Get a random 32 byte key for encryption / decryption.

Use this to get a random key for symmetric or asymmetric encryption.

◆ decryptFromFileAsymmetric()

std::optional< ByteBuffer > decryptFromFileAsymmetric	(	const std::string &	filename,
		const Key &	privateKey )

Read an encrypted file using a private key.

Private key should match the public key used in encryptToFileAsymmetric. Returns the decrypted data on success, returns an empty optional on failure.

◆ getPublicEncryptionKeyFromPrivateKey()

Key getPublicEncryptionKeyFromPrivateKey ( const Key & privateKey )

Get public exchange key given a 32 byte private key.

Use these for key exchanges, do not use for the signing API!. To do that, use getPublicSigningKeyFromPrivateKey instead. Also, dont reuse the same Private key for both key exchange and signatures! Returns an empty buffer if input key is not of right size.

◆ getSharedSecret()

Key getSharedSecret	(	const Key &	theirPublicKey,
		const Key &	yourPrivateKey )

Get shared 32 byte secret given a 32 byte public key and another 32 byte private key.

Can be used to securely get a shared secret; given two key-pairs A and B, this function will return the same secret if pub(A) and priv(B) or pub(B) and priv(A) are used.. Returns an empty buffer if input keys are not of right size.

◆ encryptAsymmetric()

std::optional< ByteBuffer > encryptAsymmetric	(	const ByteBufferView &	message,
		const Key &	publicKey )

Encrypt data using a 32 byte public key.

Resulting buffer will have lengh(data) + 72 bytes for nonce / authentication + ephemeral public key. Returns an empty buffer if input keys are not of right size.

◆ decryptAsymmetric()

std::optional< ByteBuffer > decryptAsymmetric	(	const ByteBufferView &	encryptedMessage,
		const Key &	privateKey )

Decrypt data using a 32 byte private key.

Message should be created using encryptAsymmetric using matching public key. Returns an empty buffer if input keys are not of right size / decryption failed.

◆ getPublicSigningKeyFromPrivateKey()

Key getPublicSigningKeyFromPrivateKey ( const Key & privateKey )

Get 32 byte public signing key given a 32 byte private key.

Use these for public keys in the signing API, do not use for key exchanges! To do that, use getPublicEncryptionKeyFromPrivateKey instead. Also, don't reuse the same Private key for both key exchange and signatures! Returns an empty buffer if input key is not of right size.

◆ signMessage()

Signature signMessage	(	const ByteBufferView &	message,
		const Key &	privateKey )

Sign a message using a private key.

Signature will be 64 bytes long. Returns an empty buffer if input keys are not of right size / signature failed.

◆ verifySignature()

bool verifySignature	(	const ByteBufferView &	message,
		const Signature &	signature,
		const Key &	publicKey )

Verify a signature with a message and public key.

Return true if signature matches, false otherwise.