A value of 3 is recommended.
.It Fa password
the password to hash.
+You will likely want to wipe this using
+.Xr crypto_wipe 3monocypher
+after hashing it.
.It Fa password_size
the length of
.Fa password .
salt, sizeof(salt),
NULL, 0,
NULL, 0);
+crypto_wipe(password, strlen(password));
.Ed
.Sh SEE ALSO
.Xr crypto_lock 3monocypher ,
.Xr crypto_verify16 3monocypher ,
+.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh CAVEATS
Any deviation from the specified input and output length ranges results
function, you can specify the size of the hash, and use a secret key to
make the hash unpredictable \(en useful for message authentication
codes.
+Even when using a
+.Fa key ,
+you do not have to wipe the context struct with
+.Xr crypto_wipe 3monocypher .
.Ss Incremental interface
Incremental interfaces are useful to handle streams of data or large
files without using too much memory.
.Fa key
and
.Fa nonce .
+You will likely want to wipe the key and context when you are done with
+encryption or decryption.
+Use
+.Xr crypto_wipe 3monocypher
+to wipe them.
.Pp
.Fn crypto_chacha20_stream
is the same as
crypto_chacha_ctx ctx;
crypto_chacha20_x_init(&ctx, key, nonce);
crypto_chacha20_encrypt(&ctx, plain_text, cipher_text, 500);
+/* If you're done with encryption, you will want to wipe the key and
+ * context, possibly the plaintext, too.
+ */
+crypto_wipe(key, sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
+crypto_wipe(plain_text, sizeof(plain_text));
.Ed
.Pp
Encryption chunk by chunk (same as simple encryption):
for(int i = 0; i < 500; i += 100) {
crypto_chacha20_encrypt(&ctx, cipher_text+i, plain_text+i, 100);
}
+/* If you're done with decryption, you will want to wipe the key and
+ * context.
+ */
+crypto_wipe(key, sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
.Ed
.Pp
In place encryption (same results as simple encryption):
crypto_chacha_ctx ctx;
crypto_chacha20_x_init(&ctx, key, nonce);
crypto_chacha20_encrypt(&ctx, message, message, 500);
+crypto_wipe(key, sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
.Ed
.Pp
Simple encryption with a small,
crypto_chacha_ctx ctx;
crypto_chacha20_init(&ctx, key, nonce);
crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 500);
+crypto_wipe(key, sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
.Ed
.Pp
Encryption by jumping around (don't do that):
/* ...then encrypt the first part */
crypto_chacha20_set_ctr(&ctx, 0);
crypto_chacha20_encrypt(&ctx, cipher_text, plain_text, 3 * 64);
+crypto_wipe(key, sizeof(key));
+crypto_wipe(&ctx, sizeof(ctx));
.Ed
.Sh SEE ALSO
.Xr crypto_lock 3monocypher ,
+.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement Chacha20 and XChacha20.
*/
}
+/* You will want to wipe the secret key unless you specifically need
+ * it for another key exchange.
+ */
+crypto_wipe(sk, sizeof(sk));
+
/* shared_key can now be used as key, for example in
* crypto_lock/crypto_unlock.
*/
crypto_lock(mac, cipher_text, key, nonce, plain_text,
sizeof(plain_text));
+/* Once you're done with encryption, wipe the key from memory */
+crypto_wipe(key, sizeof(key));
+
/* You can now transmit over the network:
* - cipher_text
* - nonce
ret = crypto_unlock(plain_text, key, nonce, mac, cipher_text,
sizeof(cipher_text));
+/* Once you're done with decryption, wipe the key from memory */
+crypto_wipe(key, sizeof(key));
if (ret != 0) {
/* Message corrupted; possibly an attacker is interfering
* with the connection.
.Sh SEE ALSO
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock_init 3monocypher ,
+.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh IMPLEMENTATION DETAILS
These functions implement the XChacha20 (encryption) and Poly1305 (MAC)
.Fn crypto_lock_update
authenticates and encrypts the data;
.Fn crypto_lock_final
-generates the MAC.
+generates the MAC and wipes the context.
.Sy For decryption ,
.Fn crypto_unlock_update
authenticates and decrypts the data;
/* First, initialise the context */
crypto_lock_ctx ctx;
crypto_lock_init(&ctx, key, nonce);
+/* Wipe the key unless you need it for another operation. */
+crypto_wipe(key, sizeof(key));
/* Second, authenticate the additional data, if any. */
crypto_lock_auth(&ctx, ad1, ad_size1);
*/
crypto_lock_ctx ctx;
crypto_lock_init(&ctx, key, nonce);
+/* Wipe the key unless you need it for another operation. */
+crypto_wipe(key, sizeof(key));
/* Second, authenticate the additional data, if any. */
crypto_lock_auth(&ctx, ad1, ad_size1);
*/
crypto_lock_ctx ctx;
crypto_lock_init(&ctx, key, nonce);
+/* Wipe the key unless you need it for another operation. */
+crypto_wipe(key, sizeof(key));
/* Second, authenticate the additional data, if any. */
crypto_lock_auth(&ctx, ad1, ad_size1);
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_unlock 3monocypher ,
+.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh IMPLEMENTATION DETAILS
These functions implement the XChacha20 (encryption) and Poly1305 (MAC)
final, where the signature is actually verified.
.El
.Pp
+You do not have to wipe the context structs with
+.Xr crypto_wipe 3monocypher .
+.Pp
Signatures made with this interface are compatible with the direct
interface and vice-versa.
.Sh RETURN VALUES
uint8_t sig[64];
crypto_sign_ctx sctx;
crypto_sign_init_first_pass (&sctx, sk, pk);
+/* You can wipe the key from memory as early as this.
+ * Obviously, if you still need to sign more messages, do not wipe
+ * the secret key yet.
+ */
+crypto_wipe(sk, sizeof(sk));
crypto_sign_update (&sctx, msg, sizeof(msg));
crypto_sign_init_second_pass(&sctx);
crypto_sign_update (&sctx, msg, sizeof(msg));
.Xr crypto_key_exchange 3monocypher ,
.Xr crypto_lock 3monocypher ,
.Xr crypto_sign 3monocypher ,
+.Xr crypto_wipe 3monocypher ,
.Xr intro 3monocypher
.Sh CAVEATS
The same caveats as documented on
--- /dev/null
+.Dd October 20, 2017
+.Dt CRYPTO_WIPE 3MONOCYPHER
+.Os
+.Sh NAME
+.Nm crypto_wipe
+.Nd wipe data from memory
+.Sh SYNOPSIS
+.In monocypher.h
+.Ft int
+.Fn crypto_wipe "void *secret" "size_t size"
+.Sh DESCRIPTION
+Secrets and values derived from them should stay in memory for the
+shortest possible amount of time.
+.Fn crypto_wipe
+allows zeroing out contents that contain secrets.
+A secret may be a cryptographic key or a decrypted message.
+The arguments are:
+.Bl -tag -width Ds
+.It Fa secret
+the buffer to erase.
+.It Fa size
+the number of bytes to erase from the buffer.
+This will normally be the entire buffer.
+.El
+.Pp
+Monocypher will wipe its context structs when finalizing an operation
+such as signing or decrypting.
+When using direct interfaces like
+.Xr crypto_lock 3monocypher ,
+these context structs are invisible to you.
+They are exposed in incremental interfaces like
+.Xr crypto_lock_init 3monocypher .
+The original key buffer does not get automatically wiped.
+When using incremental interfaces, you may want to wipe the original key
+buffer(s) immediately after calling the respective init function.
+.Pp
+Using
+.Fn crypto_wipe
+alone may not suffice for security.
+It is recommended to lock down relevant memory regions as well.
+Refer to
+.Xr intro 3monocypher
+for instructions on how to lock down memory on common operating systems.
+.Sh RETURN VALUES
+This function returns nothing.
+It cannot fail.
+.Sh SEE ALSO
+.Xr intro 3monocypher
Disable them.
Also beware of suspend to disk (deep sleep mode), which writes all RAM
to disk regardless of swap policy, as well as virtual machine snapshots.
+It is recommended to also use
+.Xr crypto_wipe 3monocypher
+to clear secrets from memory as soon as possible to mitigate these
+dangers.
.Ss Index
Monocypher provides functions the following:
.Bl -ohang -offset indent
.It Xr crypto_verify32 3monocypher
.It Xr crypto_verify64 3monocypher
.El
+.It Utility functions
+.Bl -tag -offset indent-two -width Ds
+.It Xr crypto_wipe 3monocypher
+.El
.El
.Sh SEE ALSO
.Xr crypto_aead_lock 3monocypher ,
.Xr crypto_verify16 3monocypher ,
.Xr crypto_verify32 3monocypher ,
.Xr crypto_verify64 3monocypher ,
+.Xr crypto_wipe 3monocypher ,
.Xr crypto_x25519 3monocypher ,
.Xr crypto_x25519_public_key 3monocypher
projects / Monocypher.git / commitdiff