Merge branch 'poljar/pk-dekurcina' into devon/pk-pickle

.github/workflows/ci.yml

@@ -55,7 +55,7 @@ jobs:
     - uses: Swatinem/rust-cache@v2
 
     - name: Clippy
-      run: cargo clippy --all-targets -- -D warnings
+      run: cargo clippy --all-targets --all-features -- -D warnings
 
   test:
     name: ${{ matrix.target.name }} ${{ matrix.channel }}

CONTRIBUTING.md

@@ -1,16 +1,118 @@
-# Contributing to Vodozemac
+# Contributing to vodozemac
 
 Thank you for taking the time to contribute to Matrix!
 
 This is the repository for Vodozemac, a Rust implementation of Olm and Megolm.
 
-## Sign off
+# Writing changelog entries
+
+We aim to maintain clear and informative changelogs that accurately reflect the
+changes in our project. This guide will help you write useful changelog entries
+using git-cliff, which fetches changelog entries from commit messages. 
+
+## Commit Message Format
+
+Commit messages should be formatted as Conventional Commits. In addition, some
+git trailers are supported and have special meaning (see below).
+
+### Conventional Commits
+
+Conventional Commits are structured as follows:
+
+```
+<type>(<scope>): <short summary>
+```
+
+The type of changes which will be included in changelogs is one of the following:
+
+    feat: A new feature
+    fix: A bug fix
+    doc: Documentation changes
+    refactor: Code refactoring
+    perf: Performance improvements
+    ci: Changes to CI configuration files and scripts
+
+The scope is optional and can specify the area of the codebase affected (e.g.,
+olm, cipher).
+
+### Changelog Trailer
+
+In addition to the Conventional Commit format, you can use the `Changelog` git
+trailer to specify the changelog message explicitly. When that trailer is
+present, its value will be used as the changelog entry instead of the commit's
+leading line.
+
+
+#### Example Commit Message
+```
+feat: Add a method to encode Ed25519 public keys to Base64
 
-We ask that everybody who contributes to this project signs off their contributions, as explained below.
+This patch adds the Ed25519PublicKey::to_base64() method, which allows us to
+stringify Ed25519 and thus present them to users. It's also commonly used when
+Ed25519 keys need to be inserted into JSON.  
 
-We follow a simple 'inbound=outbound' model for contributions: the act of submitting an 'inbound' contribution means that the contributor agrees to license their contribution under the same terms as the project's overall 'outbound' license - in our case, this is Apache Software License v2 (see [LICENSE](./LICENSE)).
+Changelog: Added the Ed25519PublicKey::to_base64() method which can be used to
+stringify the Ed25519 public key.
+```
+
+In this commit message, the content specified in the `Changelog` trailer will be
+used for the changelog entry.
+
+### Security fixes
+
+Commits addressing security vulnerabilities must include specific trailers for
+vulnerability metadata. These commits are required to include at least the
+`Security-Impact` trailer to indicate that the commit is a security fix.
+
+Security issues have some additional git-trailers:
+
+    Security-Impact: The magnitude of harm that can be expected, i.e. low/moderate/high/critical.
+    CVE: The CVE that was assigned to this issue.
+    GitHub-Advisory: The GitHub advisory identifier.
+
+Example:
+
+```
+fix: Use a constant-time Base64 encoder for secret key material
+
+This patch fixes a security issue around a side-channel vulnerability[1]
+when decoding secret key material using Base64.
+
+In some circumstances an attacker can obtain information about secret
+secret key material via a controlled-channel and side-channel attack.
+
+This patch avoids the side-channel by switching to the base64ct crate
+for the encoding, and more importantly, the decoding of secret key
+material.
+
+Security-Impact: Low
+CVE: CVE-2024-40640
+GitHub-Advisory: GHSA-j8cm-g7r6-hfpq
+
+Changelog: Use a constant-time Base64 encoder for secret key material
+to mitigate side-channel attacks leaking secret key material.
+```
+
+## Sign off
 
-In order to have a concrete record that your contribution is intentional and you agree to license it under the same terms as the project's license, we've adopted the same lightweight approach used by the [Linux Kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html), [Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other projects: the [Developer Certificate of Origin](https://developercertificate.org/) (DCO). This is a simple declaration that you wrote the contribution or otherwise have the right to contribute it to Matrix:
+We ask that everybody who contributes to this project signs off their
+contributions, as explained below.
+
+We follow a simple 'inbound=outbound' model for contributions: the act of
+submitting an 'inbound' contribution means that the contributor agrees to
+license their contribution under the same terms as the project's overall
+'outbound' license - in our case, this is Apache Software License v2 (see
+[LICENSE](./LICENSE)).
+
+In order to have a concrete record that your contribution is intentional and you
+agree to license it under the same terms as the project's license, we've adopted
+the same lightweight approach used by the [Linux
+Kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html),
+[Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many
+other projects: the [Developer Certificate of
+Origin](https://developercertificate.org/) (DCO). This is a simple declaration
+that you wrote the contribution or otherwise have the right to contribute it to
+Matrix:
 
 ```
 Developer Certificate of Origin
@@ -50,10 +152,13 @@ By making a contribution to this project, I certify that:
     this project or the open source license(s) involved.
 ```
 
-If you agree to this for your contribution, then all that's needed is to include the line in your commit or pull request comment:
+If you agree to this for your contribution, then all that's needed is to include
+the line in your commit or pull request comment:
 
 ```
 Signed-off-by: Your Name <[email protected]>
 ```
 
-Git allows you to add this signoff automatically when using the `-s` flag to `git commit`, which uses the name and email set in your `user.name` and `user.email` git configs.
+Git allows you to add this signoff automatically when using the `-s` flag to
+`git commit`, which uses the name and email set in your `user.name` and
+`user.email` git configs.

Cargo.toml

@@ -24,6 +24,7 @@ default = ["libolm-compat"]
 js = ["getrandom/js"]
 strict-signatures = []
 libolm-compat = []
+insecure-pk-encryption = []
 # The low-level-api feature exposes extra APIs that are only useful in advanced
 # use cases and require extra care to use.
 low-level-api = []

README.md

@@ -1,54 +1,68 @@
-![Build Status](https://img.shields.io/github/actions/workflow/status/matrix-org/vodozemac/ci.yml?style=flat-square)
-[![codecov](https://img.shields.io/codecov/c/github/matrix-org/vodozemac/main.svg?style=flat-square)](https://codecov.io/gh/matrix-org/vodozemac)
-[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
-[![Docs - Main](https://img.shields.io/badge/docs-main-blue.svg?style=flat-square)](https://matrix-org.github.io/vodozemac/vodozemac/index.html)
-[![Docs - Stable](https://img.shields.io/crates/v/vodozemac?color=blue&label=docs&style=flat-square)](https://docs.rs/vodozemac)
+<h1 align="center">vodozemac</h1>
+<div align="center">
+    <i>vodozemac is an implementation of Olm (Double Ratchet) and Megolm</i>
+    <br/><br/>
+    <a href="https://git-cliff.org">
+        <img src="contrib/zemi.png" width="200"></a>
+    <br>
+    <hr>
+    <a href="https://github.com/matrix-org/vodozemac/releases">
+        <img src="https://img.shields.io/github/v/release/matrix-org/vodozemac?style=flat&labelColor=1C2E27&color=66845F&logo=GitHub&logoColor=white">
+    </a>
+    <a href="https://crates.io/crates/vodozemac/">
+        <img src="https://img.shields.io/crates/v/vodozemac?style=flat&labelColor=1C2E27&color=66845F&logo=Rust&logoColor=white">
+    </a>
+    <a href="https://codecov.io/gh/matrix-org/vodozemac">
+        <img src="https://img.shields.io/codecov/c/gh/matrix-org/vodozemac?style=flat&labelColor=1C2E27&color=66845F&logo=Codecov&logoColor=white">
+    </a>
+    <br>
+    <a href="https://docs.rs/vodozemac/">
+        <img src="https://img.shields.io/docsrs/vodozemac?style=flat&labelColor=1C2E27&color=66845F&logo=Rust&logoColor=white">
+    </a>
+    <a href="https://github.com/matrix-org/vodozemac/actions/workflows/ci.yml">
+        <img src="https://img.shields.io/github/actions/workflow/status/matrix-org/vodozemac/ci.yml?style=flat&labelColor=1C2E27&color=66845F&logo=GitHub%20Actions&logoColor=white">
+    </a>
+    <br>
+    <br>
+</div>
 
-A Rust implementation of Olm and Megolm
+[vodozemac] is a pure Rust implementation of the [Olm] and [Megolm]
+cryptographic ratchets, offering a high-level API for straightforward creation
+of secure communication channels using these ratchets.
 
-vodozemac is a Rust reimplementation of
-[libolm](https://gitlab.matrix.org/matrix-org/olm), a cryptographic library
-used for end-to-end encryption in [Matrix](https://matrix.org). At its core, it
-is an implementation of the [Olm][olm-docs] and [Megolm][megolm-docs] cryptographic ratchets,
-along with a high-level API to easily establish cryptographic communication
-channels employing those ratchets with other parties. It also implements some
-other miscellaneous cryptographic functionality which is useful for building
-Matrix clients, such as [SAS][sas].
+Designed as a modern alternative to the [libolm] cryptographic library, which is
+used for end-to-end encryption in [Matrix], vodozemac provides not only the
+[Olm] and [Megolm] ratchets but also additional cryptographic features useful
+for developing Matrix clients, such as [SAS] and the integrated encryption
+scheme outlined in [MSC4108].
 
-[olm-docs]:
-<https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/olm.md>
+[vodozemac]: https://hjp.znanje.hr/index.php?show=search_by_id&id=f19vXxZ%2F
+[Olm]: https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/olm.md
+[Megolm]: https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/megolm.md
+[libolm]: https://gitlab.matrix.org/matrix-org/olm
+[SAS]: https://spec.matrix.org/v1.2/client-server-api/#short-authentication-string-sas-verification
+[Matrix]: https://matrix.org
+[MSC4108]: https://github.com/matrix-org/matrix-spec-proposals/pull/4108
 
-[megolm-docs]:
-<https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/megolm.md>
+# Documentation
 
-[sas]:
-<https://spec.matrix.org/v1.2/client-server-api/#short-authentication-string-sas-verification>
+Explore how to implement end-to-end encryption in our [documentation].
 
-# Features
+[documentation]: https://docs.rs/vodozemac/latest/vodozemac/
 
-## Supported
+# Installation
 
-- [Olm](https://matrix-org.github.io/vodozemac/vodozemac/olm/index.html)
-- [Megolm](https://matrix-org.github.io/vodozemac/vodozemac/megolm/index.html)
-- libolm pickle format (read-only)
-- Modern pickle format
-- [SAS (Short Authentication Strings)](https://matrix-org.github.io/vodozemac/vodozemac/sas/index.html)
+To install add the following to your project's `Cargo.toml`:
 
-## Unsupported
+```toml
+[dependencies]
+vodozemac = "0.7.0"
+```
 
-- Creating asymmetric [server-side message key
-  backups][legacy-message-key-backup], since these have been implemented in
-  [matrix-sdk-crypto].
+# Security Notes
 
-[legacy-message-key-backup]:
-<https://spec.matrix.org/v1.2/client-server-api/#server-side-key-backups>
+This crate has received one security [audit] by [Least Authority], with no
+significant findings.
 
-[matrix-sdk-crypto]:
-<https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto/src/backups>
-
-## Planned
-
-- Primitives for the asymmetric authenticated [server-side message key backups][authenticated-message-key-backup].
-
-[authenticated-message-key-backup]:
-<https://github.com/matrix-org/matrix-spec-proposals/pull/4048>
+[audit]: https://matrix.org/media/Least%20Authority%20-%20Matrix%20vodozemac%20Final%20Audit%20Report.pdf
+[Least Authority]: https://leastauthority.com/

cliff.toml

@@ -17,7 +17,27 @@ body = """
 {% for group, commits in commits | group_by(attribute="group") %}
     ### {{ group | upper_first }}
     {% for commit in commits %}
-        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
+        {% set_global commit_message = commit.message -%}
+        {% set_global breaking = commit.breaking -%}
+        {% for footer in commit.footers -%}
+            {% if footer.token | lower  == "changelog" -%}
+                {% set_global commit_message = footer.value -%}
+            {% elif footer.token | lower == "security-impact" -%}
+                {% set_global security_impact = footer.value -%}
+            {% elif footer.token | lower == "cve" -%}
+                {% set_global cve = footer.value -%}
+            {% elif footer.token | lower == "github-advisory" -%}
+                {% set_global github_advisory = footer.value -%}
+            {% endif -%}
+        {% endfor -%}
+        - {% if breaking %}[**breaking**] {% endif %}{{ commit_message | upper_first }}
+          {% if security_impact -%}
+              (\
+              *{{ security_impact | upper_first }}*\
+              {% if cve -%}, [{{ cve | upper }}](https://www.cve.org/CVERecord?id={{ cve }}){% endif -%}\
+              {% if github_advisory -%}, [{{ github_advisory | upper }}](https://github.com/matrix-org/vodozemac/security/advisories/{{ github_advisory }}){% endif -%}
+              )
+          {% endif -%}
     {% endfor %}
 {% endfor %}\n
 """
@@ -39,16 +59,18 @@ commit_preprocessors = [
 ]
 # regex for parsing and grouping commits
 commit_parsers = [
-    { message = ".*[sS]ecurity", group = "Security"},
+    { footer = "Security-Impact:", group = "Security" },
+    { footer = "CVE:", group = "Security" },
+    { footer = "GitHub-Advisory:", group = "Security" },
     { message = "^feat", group = "Features"},
     { message = "^fix", group = "Bug Fixes"},
     { message = "^doc", group = "Documentation"},
     { message = "^perf", group = "Performance"},
     { message = "^refactor", group = "Refactor"},
-    { message = "^style", group = "Styling"},
-    { message = "^test", group = "Testing"},
     { message = "^chore\\(release\\): prepare for", skip = true},
     { message = "^chore", skip = true},
+    { message = "^style", group = "Styling", skip = true},
+    { message = "^test", skip = true},
     { message = "^ci", skip = true},
 ]
 # filter out the commits that are not matched by commit parsers

src/ecies/mod.rs

@@ -14,6 +14,8 @@
 
 #![deny(missing_docs)]
 
+//! Implementation of an integrated encryption scheme.
+//!
 //! This module implements
 //! [ECIES](https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme), the
 //! elliptic curve variant of the Integrated Encryption Scheme. This is a hybrid

src/lib.rs

@@ -217,6 +217,7 @@ pub mod ecies;
 pub mod hazmat;
 pub mod megolm;
 pub mod olm;
+#[cfg(feature = "insecure-pk-encryption")]
 pub mod pk_encryption;
 pub mod sas;
 

src/olm/messages/pre_key.rs

@@ -153,7 +153,7 @@ impl PreKeyMessage {
 
     /// Create a new pre-key message from the session keys and standard message.
     #[cfg(feature = "low-level-api")]
-    pub fn wrap(session_keys: SessionKeys, message: Message) -> Self {
+    pub const fn wrap(session_keys: SessionKeys, message: Message) -> Self {
         PreKeyMessage::new(session_keys, message)
     }
 

src/olm/session/message_key.rs

@@ -95,13 +95,13 @@ impl MessageKey {
 
     /// Get the message key's ratchet key.
     #[cfg(feature = "low-level-api")]
-    pub fn ratchet_key(&self) -> RatchetPublicKey {
+    pub const fn ratchet_key(&self) -> RatchetPublicKey {
         self.ratchet_key
     }
 
     /// Get the message key's index.
     #[cfg(feature = "low-level-api")]
-    pub fn index(&self) -> u64 {
+    pub const fn index(&self) -> u64 {
         self.index
     }
 }