diff --git a/src/crypto/aead.cpp b/src/crypto/aead.cpp
index 67819d93..5913dbc2 100644
--- a/src/crypto/aead.cpp
+++ b/src/crypto/aead.cpp
@@ -1,5 +1,6 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later */
 #include "crypto/aead.hpp"
+#include "crypto/mbedtls_compat.hpp"
 
 #include <algorithm>
 #include <cstring>
@@ -44,7 +45,7 @@ public:
     {
         std::array<std::uint8_t, kBlock> block{};
         if (key.size() > kBlock) {
-            mbedtls_sha1(key.data(), key.size(), block.data());
+            (void)mbed::sha1(key.data(), key.size(), block.data());
         } else if (!key.empty()) {
             std::memcpy(block.data(), key.data(), key.size());
         }
@@ -54,7 +55,7 @@ public:
         }
         sodium_memzero(block.data(), block.size());
         mbedtls_sha1_init(&inner_);
-        ok_ = mbedtls_sha1_starts(&inner_) == 0 && mbedtls_sha1_update(&inner_, ipad_.data(), kBlock) == 0;
+        ok_ = mbed::sha1_starts(&inner_) == 0 && mbed::sha1_update(&inner_, ipad_.data(), kBlock) == 0;
     }
     ~HmacSha1()
     {
@@ -67,17 +68,17 @@ public:
 
     void update(std::span<const std::uint8_t> data) noexcept
     {
-        ok_ = ok_ && mbedtls_sha1_update(&inner_, data.data(), data.size()) == 0;
+        ok_ = ok_ && mbed::sha1_update(&inner_, data.data(), data.size()) == 0;
     }
 
     bool finish(std::uint8_t (&mac)[kSize]) noexcept
     {
         std::uint8_t inner_hash[kSize];
-        ok_ = ok_ && mbedtls_sha1_finish(&inner_, inner_hash) == 0;
+        ok_ = ok_ && mbed::sha1_finish(&inner_, inner_hash) == 0;
         mbedtls_sha1_context outer;
         mbedtls_sha1_init(&outer);
-        ok_ = ok_ && mbedtls_sha1_starts(&outer) == 0 && mbedtls_sha1_update(&outer, opad_.data(), kBlock) == 0
-              && mbedtls_sha1_update(&outer, inner_hash, kSize) == 0 && mbedtls_sha1_finish(&outer, mac) == 0;
+        ok_ = ok_ && mbed::sha1_starts(&outer) == 0 && mbed::sha1_update(&outer, opad_.data(), kBlock) == 0
+              && mbed::sha1_update(&outer, inner_hash, kSize) == 0 && mbed::sha1_finish(&outer, mac) == 0;
         mbedtls_sha1_free(&outer);
         sodium_memzero(inner_hash, sizeof(inner_hash));
         return ok_;
diff --git a/src/crypto/mbedtls_compat.hpp b/src/crypto/mbedtls_compat.hpp
new file mode 100644
index 00000000..7953ab56
--- /dev/null
+++ b/src/crypto/mbedtls_compat.hpp
@@ -0,0 +1,67 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+#ifndef SS_CRYPTO_MBEDTLS_COMPAT_HPP
+#define SS_CRYPTO_MBEDTLS_COMPAT_HPP
+
+// Mbed TLS 2.x returns void from the plain SHA-1/MD5 functions and int
+// from their _ret variants; 3.x keeps only the int-returning plain names.
+// These wrappers always return 0 on success.
+
+#include <cstddef>
+
+#include <mbedtls/md5.h>
+#include <mbedtls/sha1.h>
+#include <mbedtls/version.h>
+
+namespace ss::crypto::mbed {
+
+#if MBEDTLS_VERSION_NUMBER < 0x03000000
+inline int sha1(const unsigned char *in, std::size_t n, unsigned char out[20]) noexcept
+{
+    return mbedtls_sha1_ret(in, n, out);
+}
+inline int sha1_starts(mbedtls_sha1_context *c) noexcept { return mbedtls_sha1_starts_ret(c); }
+inline int sha1_update(mbedtls_sha1_context *c, const unsigned char *in, std::size_t n) noexcept
+{
+    return mbedtls_sha1_update_ret(c, in, n);
+}
+inline int sha1_finish(mbedtls_sha1_context *c, unsigned char out[20]) noexcept
+{
+    return mbedtls_sha1_finish_ret(c, out);
+}
+inline int md5_starts(mbedtls_md5_context *c) noexcept { return mbedtls_md5_starts_ret(c); }
+inline int md5_update(mbedtls_md5_context *c, const unsigned char *in, std::size_t n) noexcept
+{
+    return mbedtls_md5_update_ret(c, in, n);
+}
+inline int md5_finish(mbedtls_md5_context *c, unsigned char out[16]) noexcept
+{
+    return mbedtls_md5_finish_ret(c, out);
+}
+#else
+inline int sha1(const unsigned char *in, std::size_t n, unsigned char out[20]) noexcept
+{
+    return mbedtls_sha1(in, n, out);
+}
+inline int sha1_starts(mbedtls_sha1_context *c) noexcept { return mbedtls_sha1_starts(c); }
+inline int sha1_update(mbedtls_sha1_context *c, const unsigned char *in, std::size_t n) noexcept
+{
+    return mbedtls_sha1_update(c, in, n);
+}
+inline int sha1_finish(mbedtls_sha1_context *c, unsigned char out[20]) noexcept
+{
+    return mbedtls_sha1_finish(c, out);
+}
+inline int md5_starts(mbedtls_md5_context *c) noexcept { return mbedtls_md5_starts(c); }
+inline int md5_update(mbedtls_md5_context *c, const unsigned char *in, std::size_t n) noexcept
+{
+    return mbedtls_md5_update(c, in, n);
+}
+inline int md5_finish(mbedtls_md5_context *c, unsigned char out[16]) noexcept
+{
+    return mbedtls_md5_finish(c, out);
+}
+#endif
+
+} // namespace ss::crypto::mbed
+
+#endif