From 718735cfbb1d9f998ce33e1a3d6e0c8a2e6dc58b Mon Sep 17 00:00:00 2001 From: Andrew Cunliffe Date: Thu, 7 May 2026 07:42:37 -0700 Subject: [PATCH] docs(authentication): note OpenSSL 3.x requirement for Ed25519 (#1253) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary The DNS and HTTP authentication guides currently run `openssl genpkey -algorithm Ed25519 -out key.pem` without caveat. macOS ships LibreSSL as the system `openssl` binary, and LibreSSL doesn't implement Ed25519 in `genpkey` — so the very first command in the Ed25519 codepath errors out with: ``` Algorithm Ed25519 not found ``` A first-time integrator on macOS hits this immediately, with no path to a fix from the docs alone. Cost me ~5 minutes earlier today before I figured out I needed `brew install openssl@3` and an explicit binary path. This PR adds a `` callout to the **DNS Authentication** section right above the Ed25519 codepath, and a shorter cross-reference Note in the **HTTP Authentication** section since the same `openssl genpkey -algorithm Ed25519` commands appear there. The ECDSA P-384 codepath works on LibreSSL, so it's untouched. ## Test plan - [x] Verified locally that `/opt/homebrew/opt/openssl@3/bin/openssl genpkey -algorithm Ed25519 -out key.pem` works on macOS Darwin 25.4.0 - [x] Verified the system `/usr/bin/openssl genpkey -algorithm Ed25519 -out key.pem` fails with `Algorithm Ed25519 not found` on the same machine (LibreSSL 3.3.6) - [x] Verified the published `ai.ravenmcp/raven-mcp` flow end-to-end with the OpenSSL 3 binary - [ ] Markdown rendering of the `` callouts — relying on the existing `` pattern in this file (line 6) to validate the syntax Co-authored-by: Radoslav Dimitrov --- docs/modelcontextprotocol-io/authentication.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/modelcontextprotocol-io/authentication.mdx b/docs/modelcontextprotocol-io/authentication.mdx index f5af3ad..78bf23a 100644 --- a/docs/modelcontextprotocol-io/authentication.mdx +++ b/docs/modelcontextprotocol-io/authentication.mdx @@ -59,6 +59,10 @@ DNS authentication is a domain-based authentication method that relies on a DNS To perform DNS authentication using the `mcp-publisher` CLI tool, run the following commands in your server project directory to generate a TXT record based on a public/private key pair: + + The Ed25519 codepath requires **OpenSSL 3.0 or later**. macOS ships with LibreSSL by default (the system `openssl` binary), which does not implement Ed25519 in `genpkey` and fails with `Algorithm Ed25519 not found`. On macOS, install OpenSSL 3 (`brew install openssl@3`) and invoke it explicitly — for example, replace `openssl` with `/opt/homebrew/opt/openssl@3/bin/openssl` (Apple Silicon) or `/usr/local/opt/openssl@3/bin/openssl` (Intel) in the commands below. The ECDSA P-384 codepath works on LibreSSL. + + ```bash Ed25519 @@ -185,6 +189,10 @@ HTTP authentication is a domain-based authentication method that relies on a `/. To perform HTTP authentication using the `mcp-publisher` CLI tool, run the following commands in your server project directory to generate an `mcp-registry-auth` file based on a public/private key pair: + + As with DNS authentication, the Ed25519 codepath requires **OpenSSL 3.0 or later**. macOS's system LibreSSL does not support Ed25519 in `genpkey`. See the note in the [DNS Authentication](#dns-authentication) section for the macOS workaround. + + ```bash Ed25519