shadowsocks/shadowsocks-windows · critical · System.Exception

Cannot initialize mbed TLS cipher context

Error message

Cannot initialize mbed TLS cipher context

What it means

Thrown from AEADMbedTLSEncryptor.InitCipher when MbedTLS.cipher_setup returns non-zero, meaning the native cipher context could not be configured with the cipher_info resolved from _innerLibName. This typically means cipher_info_from_string returned null/invalid for the requested algorithm because this build of mbedTLS does not include that cipher.

Source

Thrown at shadowsocks-csharp/Encryption/AEAD/AEADMbedTLSEncryptor.cs:54

            return _ciphers;
        }

        public override void InitCipher(byte[] salt, bool isEncrypt, bool isUdp)
        {
            base.InitCipher(salt, isEncrypt, isUdp);
            IntPtr ctx = Marshal.AllocHGlobal(MbedTLS.cipher_get_size_ex());
            if (isEncrypt)
            {
                _encryptCtx = ctx;
            }
            else
            {
                _decryptCtx = ctx;
            }

            MbedTLS.cipher_init(ctx);
            if (MbedTLS.cipher_setup(ctx, MbedTLS.cipher_info_from_string(_innerLibName)) != 0)
                throw new System.Exception("Cannot initialize mbed TLS cipher context");

            DeriveSessionKey(isEncrypt ? _encryptSalt : _decryptSalt,
                _Masterkey, _sessionKey);
            CipherSetKey(isEncrypt, _sessionKey);
        }

        private void CipherSetKey(bool isEncrypt, byte[] key)
        {
            IntPtr ctx = isEncrypt ? _encryptCtx : _decryptCtx;
            int ret = MbedTLS.cipher_setkey(ctx, key, keyLen * 8,
                isEncrypt ? MbedTLS.MBEDTLS_ENCRYPT : MbedTLS.MBEDTLS_DECRYPT);
            if (ret != 0) throw new System.Exception("failed to set key");
            ret = MbedTLS.cipher_reset(ctx);
            if (ret != 0) throw new System.Exception("failed to finish preparation");
        }

        public override void cipherEncrypt(byte[] plaintext, uint plen, byte[] ciphertext, ref uint clen)
        {

View on GitHub (pinned to 891d971682)

Solutions

1. Build/ship a full mbedTLS that includes the required ciphers (MBEDTLS_GCM_C, MBEDTLS_CHACHAPOLY_C, MBEDTLS_CHACHA20_C, MBEDTLS_POLY1305_C).
2. Confirm cipher_info_from_string(_innerLibName) is non-null before calling cipher_setup and surface which name failed.
3. Fall back to the OpenSSL AEAD encryptor if mbedTLS lacks the cipher on this platform.

Example fix

// before
if (MbedTLS.cipher_setup(ctx, MbedTLS.cipher_info_from_string(_innerLibName)) != 0)
    throw new System.Exception("Cannot initialize mbed TLS cipher context");

// after: separate the lookup so the failure is specific
var info = MbedTLS.cipher_info_from_string(_innerLibName);
if (info == IntPtr.Zero)
    throw new System.Exception($"mbed TLS has no cipher for {_innerLibName}");
if (MbedTLS.cipher_setup(ctx, info) != 0)
    throw new System.Exception("Cannot initialize mbed TLS cipher context");

// Check cipher availability before setup
var info = MbedTLS.cipher_info_from_string(_innerLibName);
if (info == IntPtr.Zero) throw new System.Exception($"mbedTLS lacks {_innerLibName}");

bool MbedTLSSupportsCipher(string innerName) =>
    MbedTLS.cipher_info_from_string(innerName) != IntPtr.Zero;

try { useMbedTLS(); }
catch (Exception ex) when (ex.Message.Contains("mbed TLS cipher context"))
{ /* fall back to OpenSSL AEAD encryptor for this method */ }

When it happens

Trigger: The _innerLibName (e.g. "AES-256-GCM") is not compiled into the bundled mbedTLS binary; a method was selected that mbedTLS does not expose; the native library was swapped for a stripped build.

Common situations: Shipping a minimal mbedTLS build without AES-GCM/CHACHA20; mismatch between the cipher table (which lists the method) and the native library capabilities; platform-specific native lib that lacks the algorithm.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• openssl: cipher not found
• method not found
• failed to generate session key
• failed to set key
• failed to finish preparation

AI-assisted analysis of shadowsocks/shadowsocks-windows@891d971682 (2026-08-13). Data as JSON: /api/errors/c36c285e3c20611d. Report an issue: GitHub.