Merge pull request #42 from mpretty-cyro/feature/xchacha20-functions

Added general xchacha20 encrypt/decrypt functions, doc tweaks

Author: mpretty-cyro

include/session/config/groups/info.hpp

@@ -124,7 +124,7 @@ class Info : public ConfigBase {
     ///
     /// Returns the group description, or std::nullopt if there is no group description set.
     ///
-    /// If given a description longer than `Info::DESCRIPTION_MAX_LENGTH` (2000) bytes it will be
+    /// If given a description longer than `Info::DESCRIPTION_MAX_LENGTH` bytes it will be
     /// truncated.
     ///
     /// Inputs: None

include/session/random.h

@@ -16,9 +16,10 @@ extern "C" {
 /// - `size` -- [in] number of bytes to be generated.
 ///
 /// Outputs:
-/// - `unsigned char*` -- pointer to random bytes of `size` bytes.
+/// - `unsigned char*` -- pointer to random bytes of `size` bytes.  The caller is responsible for
+/// freeing the data when done!
 LIBSESSION_EXPORT unsigned char* session_random(size_t size);
 
 #ifdef __cplusplus
 }
-#endif
+#endif

include/session/session_encrypt.h

@@ -229,6 +229,54 @@ LIBSESSION_EXPORT bool session_decrypt_push_notification(
 LIBSESSION_EXPORT bool session_compute_message_hash(
         const char* pubkey_hex_in, int16_t ns, const char* base64_data_in, char* hash_out);
 
+/// API: crypto/session_encrypt_xchacha20
+///
+/// Encrypts a value with a given key using xchacha20.
+///
+/// Inputs:
+/// - `plaintext_in` -- [in] the data to encrypt.
+/// - `plaintext_len` -- [in] the length of `plaintext_in`.
+/// - `enc_key_in` -- [in] the key to use for encryption (32 bytes).
+/// - `ciphertext_out` -- [out] Pointer-pointer to an output buffer; a new buffer is allocated, the
+///   encrypted data written to it, and then the pointer to that buffer is stored here.
+///   This buffer must be `free()`d by the caller when done with it *unless* the function returns
+///   false, in which case the buffer pointer will not be set.
+/// - `ciphertext_len` -- [out] Pointer to a size_t where the length of `ciphertext_out` is stored.
+///   Not touched if the function returns false.
+///
+/// Outputs:
+/// - `bool` -- True if the encryption was successful, false if encryption failed.
+LIBSESSION_EXPORT bool session_encrypt_xchacha20(
+        const unsigned char* plaintext_in,
+        size_t plaintext_len,
+        const unsigned char* enc_key_in, /* 32 bytes */
+        unsigned char** ciphertext_out,
+        size_t* ciphertext_len);
+
+/// API: crypto/session_decrypt_xchacha20
+///
+/// Decrypts a value that was encrypted with the `encrypt_xchacha20` function.
+///
+/// Inputs:
+/// - `ciphertext_in` -- [in] the data to decrypt.
+/// - `ciphertext_len` -- [in] the length of `ciphertext_in`.
+/// - `enc_key_in` -- [in] the key to use for decryption (32 bytes).
+/// - `plaintext_out` -- [out] Pointer-pointer to an output buffer; a new buffer is allocated, the
+///   decrypted data written to it, and then the pointer to that buffer is stored here.
+///   This buffer must be `free()`d by the caller when done with it *unless* the function returns
+///   false, in which case the buffer pointer will not be set.
+/// - `plaintext_len` -- [out] Pointer to a size_t where the length of `plaintext_out` is stored.
+///   Not touched if the function returns false.
+///
+/// Outputs:
+/// - `bool` -- True if the decryption was successful, false if decryption failed.
+LIBSESSION_EXPORT bool session_decrypt_xchacha20(
+        const unsigned char* ciphertext_in,
+        size_t ciphertext_len,
+        const unsigned char* enc_key_in, /* 32 bytes */
+        unsigned char** plaintext_out,
+        size_t* plaintext_len);
+
 #ifdef __cplusplus
 }
 #endif

include/session/session_encrypt.hpp

@@ -295,4 +295,30 @@ std::vector<unsigned char> decrypt_push_notification(
 std::string compute_message_hash(
         const std::string_view pubkey_hex, int16_t ns, std::string_view data);
 
+/// API: crypto/encrypt_xchacha20
+///
+/// Encrypts a value with a given key using xchacha20.
+///
+/// Inputs:
+/// - `plaintext` -- the data to encrypt.
+/// - `enc_key` -- the key to use for encryption (32 bytes).
+///
+/// Outputs:
+/// - `std::vector<unsigned char>` -- the resulting ciphertext.
+std::vector<unsigned char> encrypt_xchacha20(
+        std::span<const unsigned char> plaintext, std::span<const unsigned char> enc_key);
+
+/// API: crypto/decrypt_xchacha20
+///
+/// Decrypts a value that was encrypted with the `encrypt_xchacha20` function.
+///
+/// Inputs:
+/// - `ciphertext` -- the data to decrypt.
+/// - `enc_key` -- the key to use for decryption (32 bytes).
+///
+/// Outputs:
+/// - `std::vector<unsigned char>` -- the resulting plaintext.
+std::vector<unsigned char> decrypt_xchacha20(
+        std::span<const unsigned char> ciphertext, std::span<const unsigned char> enc_key);
+
 }  // namespace session

src/session_encrypt.cpp

@@ -745,8 +745,75 @@ std::string compute_message_hash(
             decoded_data);
 }
 
+std::vector<unsigned char> encrypt_xchacha20(
+        std::span<const unsigned char> plaintext, std::span<const unsigned char> enc_key) {
+    if (enc_key.size() != 32)
+        throw std::invalid_argument{"Invalid enc_key: expected 32 bytes"};
+
+    std::vector<unsigned char> ciphertext;
+    ciphertext.resize(
+            crypto_aead_xchacha20poly1305_ietf_NPUBBYTES + plaintext.size() +
+            crypto_aead_xchacha20poly1305_ietf_ABYTES);
+
+    // Generate random nonce, and stash it at the beginning of ciphertext:
+    randombytes_buf(ciphertext.data(), crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+
+    auto* c = reinterpret_cast<unsigned char*>(ciphertext.data()) +
+              crypto_aead_xchacha20poly1305_ietf_NPUBBYTES;
+    unsigned long long clen;
+
+    crypto_aead_xchacha20poly1305_ietf_encrypt(
+            c,
+            &clen,
+            plaintext.data(),
+            plaintext.size(),
+            nullptr,
+            0,        // additional data
+            nullptr,  // nsec (always unused)
+            reinterpret_cast<const unsigned char*>(ciphertext.data()),
+            enc_key.data());
+    assert(crypto_aead_xchacha20poly1305_ietf_NPUBBYTES + clen <= ciphertext.size());
+    ciphertext.resize(crypto_aead_xchacha20poly1305_ietf_NPUBBYTES + clen);
+    return ciphertext;
+}
+
+std::vector<unsigned char> decrypt_xchacha20(
+        std::span<const unsigned char> ciphertext, std::span<const unsigned char> enc_key) {
+    if (ciphertext.size() <
+        crypto_aead_xchacha20poly1305_ietf_NPUBBYTES + crypto_aead_xchacha20poly1305_ietf_ABYTES)
+        throw std::invalid_argument{
+                "Invalid ciphertext: too short to contain valid encrypted data"};
+    if (enc_key.size() != 32)
+        throw std::invalid_argument{"Invalid enc_key: expected 32 bytes"};
+
+    // Extract nonce from the beginning of the ciphertext:
+    auto nonce = ciphertext.subspan(0, crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    ciphertext = ciphertext.subspan(nonce.size());
+
+    std::vector<unsigned char> plaintext;
+    plaintext.resize(ciphertext.size() - crypto_aead_xchacha20poly1305_ietf_ABYTES);
+    auto* m = reinterpret_cast<unsigned char*>(plaintext.data());
+    unsigned long long mlen;
+    if (0 != crypto_aead_xchacha20poly1305_ietf_decrypt(
+                     m,
+                     &mlen,
+                     nullptr,  // nsec (always unused)
+                     ciphertext.data(),
+                     ciphertext.size(),
+                     nullptr,
+                     0,  // additional data
+                     nonce.data(),
+                     enc_key.data()))
+        throw std::runtime_error{"Could not decrypt (XChaCha20-Poly1305)"};
+    assert(mlen <= plaintext.size());
+    plaintext.resize(mlen);
+    return plaintext;
+}
+
 }  // namespace session
 
+extern "C" {
+
 using namespace session;
 
 LIBSESSION_C_API bool session_encrypt_for_recipient_deterministic(
@@ -925,3 +992,45 @@ LIBSESSION_C_API bool session_compute_message_hash(
         return false;
     }
 }
+
+LIBSESSION_C_API bool session_encrypt_xchacha20(
+        const unsigned char* plaintext_in,
+        size_t plaintext_len,
+        const unsigned char* enc_key_in,
+        unsigned char** ciphertext_out,
+        size_t* ciphertext_len) {
+    try {
+        auto ciphertext = session::encrypt_xchacha20(
+                std::span<const unsigned char>{plaintext_in, plaintext_len},
+                std::span<const unsigned char>{enc_key_in, 32});
+
+        *ciphertext_out = static_cast<unsigned char*>(malloc(ciphertext.size()));
+        *ciphertext_len = ciphertext.size();
+        std::memcpy(*ciphertext_out, ciphertext.data(), ciphertext.size());
+        return true;
+    } catch (...) {
+        return false;
+    }
+}
+
+LIBSESSION_C_API bool session_decrypt_xchacha20(
+        const unsigned char* ciphertext_in,
+        size_t ciphertext_len,
+        const unsigned char* enc_key_in,
+        unsigned char** plaintext_out,
+        size_t* plaintext_len) {
+    try {
+        auto plaintext = session::decrypt_xchacha20(
+                std::span<const unsigned char>{ciphertext_in, ciphertext_len},
+                std::span<const unsigned char>{enc_key_in, 32});
+
+        *plaintext_out = static_cast<unsigned char*>(malloc(plaintext.size()));
+        *plaintext_len = plaintext.size();
+        std::memcpy(*plaintext_out, plaintext.data(), plaintext.size());
+        return true;
+    } catch (...) {
+        return false;
+    }
+}
+
+}  // extern "C"

tests/test_session_encrypt.cpp

@@ -500,3 +500,19 @@ TEST_CASE("Session message hash", "[session][message-hash]") {
     CHECK(compute_message_hash(pubkey_hex, ns, base64_data2) ==
           "apKu8OMjrbU+YeVWpMSyrr1wHq51K3uKD8WM0F4E1cE");
 }
+
+TEST_CASE("xchacha20", "[session][xchacha20]") {
+    using namespace session;
+
+    auto payload =
+            "da74ac6e96afda1c5a07d5bde1b8b1e1c05be73cb3c84112f31f00369d67154d00ff029090b069b48c3cf603d838d4ef623d54"_hexbytes;
+    auto enc_key = "0123456789abcdef0123456789abcdeffedcba9876543210fedcba9876543210"_hexbytes;
+
+    CHECK(decrypt_xchacha20(payload, enc_key) == to_vector("TestMessage"));
+    CHECK_THROWS(decrypt_xchacha20(to_span("invalid"), enc_key));
+    CHECK_THROWS(decrypt_xchacha20(payload, to_span("invalid")));
+
+    auto ciphertext = encrypt_xchacha20(to_span("TestMessage"), enc_key);
+    CHECK(decrypt_xchacha20(ciphertext, enc_key) == to_vector("TestMessage"));
+    CHECK_THROWS(encrypt_xchacha20(payload, to_span("invalid")));
+}