New provisioner or add to ACME provisioner for Wire™ cert enrollment

[rohan-wire]

Issue details

We would like to use Smallstep to enroll X.509 certificates for the Wire end-to-end encrypted messaging application. Wire is entirely open source and supports federation (multiple servers communicating across domains).

In Wire each user can have multiple clients (ex: desktop, iOS, Android, web). In group conversations, clients then verify the certificates of the other clients in the chat. Messages for a group are encrypted only for the active clients of the users in the group. Each certificate needs to bind:

• the identity key pair of the client (client is authoritative);
• the wire handle (ex: @alice-smith@example.com) and display name of the user as authenticated by the IdP (IdP is authoritative); and
• the client ID (Wire server is authoritative), for example SvPfLlwBQi-6oddVRrkqpw/04c7@example.com.

The resulting certificate might have the display name as a CN in the Subject, and URIs for the Wire handle (URI:im:%40alice-smith@example.com) and client ID (URI:im:SvPfLlwBQi-6oddVRrkqpw/04c7@example.com) in the SubjectAltName.

Envisioned example solution

Despite its traditional use with domain certs, I thought of modeling this with ACME because an order has to list the identifiers you want in a certificate and requires challenges to prove control over each identifier. The wire handle and display name could come from a preauthorization, and we could use a custom challenge to prove control of the client ID. (I prototyped a JWT usable for the challenge.) We also need the client to authenticate to the certificate enrollment server (for example using OAUTH/OIDC), which in ACME could be done when creating a new account.

We would like to either add this functionality to the ACME provisioner or create a new provisioner, probably using pieces of the OAUTH/OIDC provisioner and possibly the ACME provisioner.

In case you are wondering why we did not consider EAB, there is no direct relationship between the certificate server and the Wire server (which is authoritative for the client ID). The IdP has no reason to know the client IDs, which are internal identifiers, and change as new clients are added and removed.

Why is this needed?

End-to-end encryption of messaging is great, but a compromised or malicious server can still inject an extra client into communications unless there is an associated identity mechanism. There is clear way to do this using per-client X.509 certificates, providing improved privacy and confidence in encrypted messaging.

Some security properties we want:

• a malicious clients cannot impersonate another client (even for the same user)
• even collaborating with a malicious server in one domain, clients cannot impersonate a user in another domain
• an attacker needs to compromise the Wire server AND the IdP to inject a malicious client into conversations.

[maraino]

I haven't looked in detail on this, but we will soon be releasing some webhook functionality that can be used to add extra data to certificate templates. You can, for example, authenticate using OIDC, and we will call your webhook to get specific details, for example, the URIs you mentioned before. You can now build the desired certificate using templates, and we will sign that.

This solution with webhooks and OIDC might be simpler than doing a custom ACME challenge.

[rohan-wire]

I haven't looked in detail on this, but we will soon be releasing some webhook functionality that can be used to add extra data to certificate templates. You can, for example, authenticate using OIDC, and we will call your webhook to get specific details, for example, the URIs you mentioned before. You can now build the desired certificate using templates, and we will sign that.

This solution with webhooks and OIDC might be simpler than doing a custom ACME challenge.

The webhook idea is intriguing. My first observation is that what we need in the certificate subject and subjectAltName is the Wire handle and display name (available via OIDC userInfo), and the Wire client ID (available from the webhook), neither of which matches the sub claim in the token. Does the existing OIDC provisioner a) issue an OIDC UserInfo request, and b) allow templating the certificate subject/SAN from specific UserInfo claims? If so, would the webhook allow inclusion of both token claims and UserInfo claims?
Do you have anything written up describing OIDC provisioner webhooks yet?

Honestly, the custom ACME challenge didn't look that hard. I was much more worried about any assumptions that might be built into the ACME provisioner expecting a DNS certificate and the account authentication/authorization needed in that environment. The webhook idea also looks more general if it can provide what we need.

[tashian]

@rohan-wire I love this application of step-ca! If you're comfortable storing Wire handles and client IDs in your IdP, you could use custom claims in the OIDC token, and apply them to a certificate using an X.509 template. Here's a link to our docs about using custom claims (the example uses SSH certs, but the feature works with X.509 certificates as well).

But, it sounds like that only solves part of the problem (still need the enrollment server piece). For that piece, for the time being until we have webhooks in open source, you could have a program that watches the log of step-ca and sends requests toe the enrollment server. The PEM block for every issued certificate is logged there.

[maraino]

Does the existing OIDC provisioner a) issue an OIDC UserInfo request?

Not really, it does a request with the scope scope=openid+email, so the token we get back has an email address embedded. You can test this with a Google account just running:

step oauth --oidc --bare | step crypto jwt inspect --insecure

allow templating the certificate subject/SAN from specific UserInfo claims?

You can use the templates for setting the subject and SANs. For OIDC, you can use data from the OIDC token, the CSR, and user-provided data. By default, we only use data available in the token as it's the only verified thing.

In an upcoming release, before granting a certificate, we can do a request to a webhook that will return data available in the templates.

We do not use the UserInfo endpoint.

If so, would the webhook allow the inclusion of both token claims and UserInfo claims?

The webhook can return any data it wants, and it will be available in the templates. The webhook URL can be templatized with data available from the same information the template has. And it will receive the CSR and some extra data by POST too. And of course, it has a few ways to authenticate with the endpoint.

Do you have anything written up describing OIDC provisioner webhooks yet?

There's an ongoing implementation PR #1001 and ongoing docs PR smallstep/docs#141

Honestly, the custom ACME challenge didn't look that hard. I was much more worried about any assumptions that might be built into the ACME provisioner expecting a DNS certificate and the account authentication/authorization needed in that environment. The webhook idea also looks more general if it can provide what we need.

Personally, I will be more willing to implement custom challenges if there is a draft being discussed at IETF.

Without having a full understanding of your requirements, and the Wire app, I think an OIDC+Webhooks implementation sounds more appropriate.

[rohanmahy]

@rohan-wire I love this application of step-ca! If you're comfortable storing Wire handles and client IDs in your IdP, you could use custom claims in the OIDC token, and apply them to a certificate using an X.509 template.

It doesn't make any sense for us to store Wire client IDs in the IdP. They change too often and this breaks one of the security properties we like (IdP does not need to fully trust the Wire server).

But, it sounds like that only solves part of the problem (still need the enrollment server piece). For that piece, for the time being until we have webhooks in open source, you could have a program that watches the log of step-ca and sends requests toe the enrollment server. The PEM block for every issued certificate is logged there.

The Wire app being setup on a new instance already generates a client ID on the Wire server. We just need to prove control of it to Smallstep. The Wire server and Wire app also needs to keep working even if Smallstep is unavailable or someone disables certificate enrollment completely.

[rohanmahy]

You can use the templates for setting the subject and SANs. For OIDC, you can use data from the OIDC token, the CSR, and user-provided data. By default, we only use data available in the token as it's the only verified thing.
[snip]
The webhook can return any data it wants, and it will be available in the templates. The webhook URL can be templatized with data available from the same information the template has. And it will receive the CSR and some extra data by POST too. And of course, it has a few ways to authenticate with the endpoint.

Thanks for the description and the pointers. This is generally better documentation than I am accustomed to, so kudos.

I wrote up a comparison of the two approaches.

Comparing OIDC + Webhooks to ACME

OIDC + Webhooks

Webhooks are not implemented in the open source client, but if they were:

• The Wire app could include its Wire handle in the CSR. Since there is no UserInfo support, Smallstep could only verify the handle if it were convertible from the email address.
• The Wire app could include its Wire client ID in the CSR and in custom claims in OIDC.
• We would configure a webhook on Smallstep pointing at Wire server and its webhook secret. We would only allow the specific hostname of the Wire server.
• After each OIDC request to Smallstep, the webhook would call an endpoint on the Wire server which would receive the (DER encoded?) CSR and a timestamp from Smallstep. It would deep parse the CSR, validate the Wire app public key matches the one stored for the client on the Wire server, and validate the Wire client ID and Wire handle match. It then returns "allow":true"
• The template on Smallstep incorporates the (now validated via webhook) Wire client ID and Wire handle claims from the CSR into the SANs. It would need to make sure that no other SANs sneak in.

This sounds quite complicated and error-prone (especially parsing the CSR) and it assumes webhooks become available in the open source version of Smallstep.

ACME

• We would need to add support for the Wire app using OIDC authentication of ACME newAccount requests.
• We would need to add support for ACME preAuthorization using data derived from (for example) OIDC UserInfo or SCIM.
• We would need to add our custom challenge†, which proves that the Wire app has control over the Wire client ID on the Wire server.
• We might want to add persistence of ACME accounts for renewals, instead of always creating a one-time account. This would allow different treatment on the IdP (for example using a second factor for initial registration by not for a renewal).

We could implement custom challenges as a generic challenge validation callout (takes the identifier and identifier type and returns if the challenge was validated) if that would be useful.

Honestly, the custom ACME challenge didn't look that hard. I was much more worried about any assumptions that might be built into the ACME provisioner expecting a DNS certificate and the account authentication/authorization needed in that environment. The webhook idea also looks more general if it can provide what we need.

Personally, I will be more willing to implement custom challenges if there is a draft being discussed at IETF.

† I would be happy to writeup a short Internet draft describing this custom challenge. The ACME WG would almost certainly not agree to standardize it, but it would be well documented and its security properties could be vetted.

Without having a full understanding of your requirements, and the Wire app, I think an OIDC+Webhooks implementation sounds more appropriate.

I'd be happy to have a short call to clarify the requirements and then we could put the notes in this issue if that would be useful.

[maraino]

@rohan-wire Do you have a high-level design for the challenge I can take a look at?

[rohan-wire]

@maraino
we went ahead and implemented the following flow in a fork. It is working, but is based off quite an old version of smallstep. we'd like to rebase and upstream whatever we can.

https://github.com/wireapp/rusty-jwt-tools/tree/main/e2e-identity

[rohan-wire]

[rohan-wire]

We also implemented the ability to access the IdP identity claims inside the Smallstep template. This seems separable and broadly useful.