These functions provide an incremental interface for the Chacha20
encryption primitive.
.Pp
-Chacha20 is a low-level primitive. Consider using authenticated
-encryption, implemented by
+Chacha20 is a low-level primitive.
+Consider using authenticated encryption, implemented by
.Xr crypto_lock 3monocypher .
.Pp
.Fn crypto_chacha20_init
initialises the
.Vt crypto_chacha_ctx
-context. It needs a 32-byte secret
+context.
+It needs a 32-byte secret
.Fa key
and an 8-byte
.Fa nonce .
The nonce must be used only once per secret key (repeating them
destroys confidentiality). Counters and (unique) message numbers can
-be used as nonces. Random numbers
+be used as nonces.
+Random numbers
.Em cannot :
8-byte nonces are too small to prevent accidental reuse.
.Pp
.Fn crypto_chacha20_x_init
initialises the
.Vt crypto_chacha_ctx
-context. It needs a 32-byte secret
+context.
+It needs a 32-byte secret
.Fa key
and a 24-byte
.Fa nonce .
-The nonce is big enough to be selected at random. See
+The nonce is big enough to be selected at random.
+See
.Xr intro 3monocypher
about generating random numbers (use the operating system's random
number generator).
by XORing it with a pseudo-random stream of
numbers, seeded by the provided
.Vt crypto_chacha_ctx
-context. Once the encryption is done, the context is updated to allow
+context.
+Once the encryption is done, the context is updated to allow
subsequent calls of
.Fn crypto_chacha20_encrypt
on the rest of the message, if any.
.Fa plain_text
and
.Fa cipher_text
-may point to the same buffer for in-place encryption. If they don't,
-the buffers they point to
+may point to the same buffer for in-place encryption.
+If they don't, the buffers they point to
.Em must not overlap .
.Pp
The
(0), in which case it will be interpreted as an all zero input.
The cipher_text will then contain the raw Chacha20 stream.
.Pp
-Decryption is the same as encryption. To Decrypt the
+Decryption is the same as encryption.
+To Decrypt the
.Fa cipher_text ,
encrypt it again with the same
.Fa key
.Fa plain_text
being
.Dv NULL .
-This is useful as a user space random number generator. While
-.Sy \&this must not be used as a cryptographic random number generator ,
-it can be handy outside of a security context. Deterministic
-procedural generation and reproducible property-based tests come to
-mind.
+This is useful as a user space random number generator.
+While
+.Sy this must not be used as a cryptographic random number generator ,
+it can be handy outside of a security context.
+Deterministic procedural generation and reproducible property-based
+tests come to mind.
.Pp
.Fn crypto_chacha20_set_ctr
resets the internal counter of the
This can be used to encrypt (or decrypt) part of a long message, or to
implement some AEAD constructions such as the one described in RFC
7539 (not implemented in Monocypher because of its complexity and
-limitations). Be careful when using this not to accidentally reuse
-parts of the random stream. This would destroy confidentiality.
+limitations).
+Be careful when using this not to accidentally reuse parts of the
+random stream.
+This would destroy confidentiality.
.Sh RETURN VALUES
These functions return nothing.
They cannot fail.
uint8_t cipher_text[500]; /* Will be the encrypted message */
crypto_chacha_ctx ctx;
crypto_chacha20_x_init(&ctx, key, nonce);
-crypto_chacha20_encrypt(&ctx, cipher_text + 0, plain_text + 0, 100);
-crypto_chacha20_encrypt(&ctx, cipher_text + 100, plain_text + 100, 100);
-crypto_chacha20_encrypt(&ctx, cipher_text + 200, plain_text + 200, 100);
-crypto_chacha20_encrypt(&ctx, cipher_text + 300, plain_text + 300, 100);
-crypto_chacha20_encrypt(&ctx, cipher_text + 400, plain_text + 400, 100);
+for(int i = 0; i < 500; i += 100) {
+ crypto_chacha20_encrypt(&ctx, cipher_text+i, plain_text+i, 100);
+}
.Ed
.Pp
In place encryption (same results as simple encryption):
.Xr intro 3monocypher
.Sh STANDARDS
These functions implement Chacha20 and XChacha20.
+Chacha20 is described in rfc7539.
+XChacha20 derives from Chacha20 the same way XSalsa20 derives from
+Salsa20, and benefits from the same security reduction (proven secure
+as long as Chacha20 itself is secure).
.Sh SECURITY CONSIDERATIONS
.Sy Encryption alone is not sufficient for security .
-Chacha20 should never be used alone. It only protects against
-eavesdropping, not forgeries. To ensure the integrity of a message,
-use Blake2b in keyed mode, or authenticated encryption; see
+Chacha20 should never be used alone.
+It only protects against eavesdropping, not forgeries.
+To ensure the integrity of a message, use Blake2b in keyed mode, or
+authenticated encryption; see
.Xr crypto_blake2b 3monocypher
and
.Xr crypto_lock 3monocypher
.Pp
-When using
-.Fn crypto_chacha20_init ,
-.Pp
-Do not reuse a nonce for the same key. This would expose the XOR of
-subsequent encrypted messages, and destroy confidentiality.
+Do not reuse a nonce for the same key.
+This would expose the XOR of subsequent encrypted messages, and
+destroy confidentiality.
.Pp
.Sy do not select small nonces at random .
The
.Fn crypto_chacha20_init
nonce spans only 64 bits, which is small enough to trigger accidental
-reuses. A counter should be used instead. If multiple parties send
-out messages, Each can start with an initial nonce of 0, 1 .. n-1
-respectively, and increment them by n for each new message. (Make sure
-the counters never wrap around).
+reuses.
+A counter should be used instead.
+If multiple parties send out messages, Each can start with an initial
+nonce of 0, 1 .. n-1 respectively, and increment them by n for each
+new message (make sure the counters never wrap around).
.Pp
Do not use these functions as cryptographic random number generator.
Always use the operating system's random number generator for
projects / Monocypher.git / commitdiff