ECH API problems for hybrid client-facing proxy

[yrutschle]

Version

HEAD

Description

I am having issues with the API to manipulate ECH configurations -- possibly because I can't seem to find appropriate documentation, so I am working from the source in src/ssl_ech.c.

I want to build a client-facing proxy (in so-called hybrid mode; this will end up integrated into sslh), so I need to create key pairs, export the public key to the DNS, create new key pairs and expire older ones.

My current understanding is:

• wolfSSL_CTX_GenerateEchConfig() creates a new keypair, and adds it to a list of existing keypairs.

• wolfSSL_CXT_GetEchConfigs[Base64]() extract a list (public_name + public_key), which a server can then export to a DNS

• wolfSSL_CXT_SetEchConfigs[Base64]() sets a (public_name + public_key), which clients can use to encrypt their SNI.

Which means, for a server, that:

• I can generate new keypairs, but only from the server itself, as I cannot export the private keys (I think this is an architecture problem: it means my client-facing server is responsible for generating the keys, and that there must exist a path from that exposed server to the DNS; I would prefer to have an independant process that is exposed to nothing and generates keypairs, and sends the public configuration to the DNS on one side, and the private key to the client-facing server)

• I can extract the public configuration with the wolfSSL_CTS_GetEchConfigBase64() to export to the DNS

• .... there is no way to remove older keys? IIRC ECH specification suggests changing keys every hour, surely we can't keep keys on the server forever?

Additionally, my current understanding of the RFC is that an intermediate proxy should transmit the ClientHelloInner towards the end server, rather than the ClientHelloOuter. This implies two more APIs: the proxy needs to retrieve the ClientHelloInner (to forward it), and know the size of the ClientHelloOuter, to know how much to skip before sending the rest of the TLS connection.

Am I missing something, or are these APIs missing? I am happy to collaborate on the definition of the API, and even create PRs. I am also happy with splitting this as several issues if you prefer to track them independantly.

[embhorn]

Hi @yrutschle

Thanks for contacting wolfSSL Support. I have requested a review of this by our engineers. I am flagging this as a feature request for now.

Would you please send an email to support@wolfssl.com to file a formal feature request?

Thanks,
@embhorn - wolfSSL Support

[sebastian-carpenter]

Hey @yrutschle,

As far as I know we have no documentation for ECH. I've been planning to write it for a while now, but there are a couple things to wrap up with ECH first.

---

'hybrid-mode' is not a topology I am aware of for ECH. The two topologies I know are:

• Shared-mode -> The connection is contained on one 'node'. The client will connect to a server which acts as both the client-facing server and the backend server.
• Split-mode -> Two 'nodes' will be used.
  1. The client initiates a handshake with the client-facing server
  2. Client-facing server decrypts the inner hello
  3. The inner hello is forwarded to the appropriate backend server.
  4. Ultimately, a TLS handshake is completed between the client and backend server with the client-facing server acting as a sort of router.

I guess you plan to use split-mode for sslh? Though shared-mode may work too.

---

Private-key import/export

This is certainly an issue that should be addressed. It looks like there's a PEM format for ECH configs and the private key (something like this: https://www.ietf.org/archive/id/draft-farrell-tls-pemesni-08.html).

Something like wolfSSL_CTX_ExportEchConfigs(ctx, pem) might work well. And wolfSSL_CTX_ImportEchConfigs(ctx, pem).

---

Key cycling

Yeah... there is currently no API to cycle configs. Technically, you can disable ECH on the server side to clear the keys, re-enable ECH, then generate configs. This is not ideal though.

The server should probably retain the old configs for some time before clearing them though (this way clients can be ushered to the newer configs)

on the server:

struct EchConfigCycle
{
    struct EchConfigs* new;
    struct EchConfigs* old;
}

wolfSSL_CTX_CycleEchConfigs -> clear old, move new to old (probably replace new with a list of generated configs too)

Something like this may solve the problem? The server can then decrypt with either new or old but only advertises the new configs. This way the server can manage when configs are cycled.

Putting an advertise flag on each config may work as well, though it would be hard to distinguish which to remove.

---

Additionally, my current understanding of the RFC is that an intermediate proxy should transmit the ClientHelloInner towards the end server, rather than the ClientHelloOuter. This implies two more APIs: the proxy needs to retrieve the ClientHelloInner (to forward it), and know the size of the ClientHelloOuter, to know how much to skip before sending the rest of the TLS connection.

We currently do not have support for split-mode hence the lack of API's for this.

Disregarding that, would you be able to elaborate on the API's you're thinking of for this?

• For split-mode support sending the ClientHelloInner would be the correct thing to do. In this case you probably wouldn't need to 'skip' anything, you would just be given the ClientHelloInner which should be fine to send on it's own.

---

Overall, these are great suggestions. I'll be thinking about how I want to implement these and would appreciate any feedback you have.

• Import/export
• Key cycle
• Split mode proxy
• Backend-server support?

[yrutschle]

No worries about the missing documentation -- I understand ECH is still draft and all. (I was more worried that documentation might exist and I failed to RTFM :-) ).

The topology I'm looking at for sslh is split-mode indeed. I think I saw it refered to as hybrid somewhere, but nevermind. Point is, sslh would receive the client connection, decrypt the ClientHelloOuter, retrieve the SNI, and forward the connection accordingly to the backend server.

Key management

Private-key import/export: OpenSSL uses the format you mentionned, created with

openssl ech -public_name example.com -out /etc/echkeydir/example.pem.ech                                                                                                                                                                                                                                                       

Arguably I don't need to export the private key from wolfSSL if I can create the keypair with openSSL and import the private key in wolfSSL (which there is no API for, IIRC), but obviously I'd prefer just one dependency :-)

If I am not mistaken, my final architecture would have 3 parties:

• A genkey process that creates a new keypair every hour or so. genkey exports this, presumably as PEM (new API required)

• The ECH configuration (server name + public key) is exported to the DNS, which only publishes the last configuration. (wolfSSL is not involved here)

• the client-facing proxy (sslh in my case) imports the PEM with private key + ECH configuration, and keeps "some" of the older configurations (I think I read 5 somewhere in the RFC). New APIs needed: add a new keypair (the PEM produced by genkey, and some API to throw out old ones. One possiblity would be two new API: "add keypair", and "trim older configurations to only keep the x last ones". I don't really see an application use case to individually manage the keys, but I might be short-sighted here.

With the above in mind... your suggestion would actually probably be enough, if wolfSSL_CTX_ImportEchConfigs(ctx,pem) erases all keys in the context; then genkey uses the export function, the application manages its own list of active keys, and imports the entire list every time a new key is added.

(I am not sure how you'd go about having a list of PEM... simply append them?)

Or alternatively my proposal of "add a simple keypair" and trim:

/* Retrieve a PEM of private key + ECH config of most recent                                                                                                                                                                                                                                                                   
 * key */                                                                                                                                                                                                                                                                                                                      
wolfSSL_CTX_GetEchKeypair_PEM(                                                                                                                                                                                                                                                                                                 
        WOLFSSL_CTX* ctx,  /* An existing context with the ECH configs */                                                                                                                                                                                                                                                      
        pem);                                                                                                                                                                                                                                                                                                                  
                                                                                                                                                                                                                                                                                                                               
/* Adds one keypair to the context */                                                                                                                                                                                                                                                                                          
wolfSSL_CTX_AddEchKeypair_PEM(                                                                                                                                                                                                                                                                                                 
        WOLFSSL_CTX* ctx,  /* An existing context with the ECH configs */                                                                                                                                                                                                                                                      
        pem);                                                                                                                                                                                                                                                                                                                  
                                                                                                                                                                                                                                                                                                                               
/* Drop old keys until I have that many left */                                                                                                                                                                                                                                                                                
wolfSSL_CTX_KeepEchConfigs(                                                                                                                                                                                                                                                                                                       
        WOLFSSL_CTX* ctx,  /* An existing context with the ECH configs */                                                                                                                                                                                                                                                      
        Count   /* how many are we keeping */                                                                                                                                                                                                                                                                                  
);                                                                                                                                                                                                                                                                                                                             

From an application perspective, I think I prefer the latter, as managing lists of bits of text for the various configs in PEM, in C, does not fill me with joy. Also, IIRC wolfSSL already manages the keypairs as a list, so these 3 functions should be easy to implement.

Split-mode proxy API

For split-mode support sending the ClientHelloInner would be the correct thing to do. In this case you probably wouldn't need to 'skip' anything, you would just be given the ClientHelloInner which should be fine to send on it's own.

My thinking was that if sslh forwards the ClientHelloInner in place of the ClientHelloOuter, it needs to know the size of the ClientHelloOuter. But I suppose the client does not send more data after the ClientHelloOuter, so as soon as the GetEchClientHelloInner() returns successfully, it sends the ClientHelloInner() to the backend server, and starts shoveling between client and backend server transparently.

Ideally I don't want wolfSSL to manage connections and file descriptors at all, and simply work on a buffer:

ret = wolfSSL_CTX_GetEchClientHelloInner(                                                                                                                                                                                                                                                                                      
        WOLFSSL_CTX* ctx,  /* An existing context with the ECH configs */                                                                                                                                                                                                                                                      
        byte* buffer_in,   /* Contents of the beginning of the connection, ideally a full ClientHelloOuter */                                                                                                                                                                                                                  
        word32 buffer_len  /* How many bytes in the buffer */                                                                                                                                                                                                                                                                  
       + out: decrypted ClientHelloInner                                                                                                                                                                                                                                                                                       
    );                                                                                                                                                                                                                                                                                                                         

I don't know wolfSSL culture enough, if you prefer to create the output buffer in the library, or the caller would provide a buffer + len, or a pointer to pointer that wolfSSL allocates...

And ret being:

• Negative: error; in particular, EAGAIN: not enough data to decode; EINVAL: not a TLS connection
• Positive: number of bytes in the ClientHelloOuter (if required, but I guess not)

@embhorn: I am confused by your workflow! do you still need an e-mail?