Need some clarification around --dns, --address and --with-ca-url flags

[bfqrst]

Hi everybody,

I am fiddling around with the non-guided way to init that online CA in order to inspect the resulting ca.json and defaults.json. Of course, depending on what flags one passes - some mandatory, some not - , the aforementioned jsons differ somewhat. So far, so expected. Because I want to establish the step toolchain as our internal CA, I need some confirmation as for when one would want to use the three flags mentioned in the title. Here's my take:

1. --dns (multiple times) - you want x domain names for your CA to be available at
2. -- address - pin the IP to a specific address:port combo in case the box has multiple NICs??
3. --with-ca-url - this you would use, when you passed multiple DNS names and you want to pin it to a specific one?? Otherwise this would default to the first passed DNS name that came with the --dns flag plus the port from the --address flag.

With all of this asked, I might have found a validation error in --address, which would construct a erroneous defaults.json! Possibly the ca.json too.

step ca init --ssh --name 10-CA --dns "ten.example.com, tenten.example.com, 10.10.10.10" --provisioner admin --password-file pw.txt --provisioner-password-file ppw.txt --address https://10.10.20.30

Sooo, this init goes through, resulting in this defaults.json:

{
"ca-url": "https://ten.example.com://10.10.20.30",
"ca-config": "/tmp/test/config/ca.json",
"fingerprint": "e7aa7ed63a6d62e5d15ee6367e6f2076ebf0a7952ea9cc123648403e0f68c675",
"root": "/tmp/test/certs/root_ca.crt"
}

If I have to guess, everything after the colon (which normally would be the port) is filtered, so if anybody were to put in a URI, things would go sideways...

Thanks everybody!
Cheers
Ralph

[tashian]

Hi Ralph,

Yeah, that's definitely a validation error. --address is both the bind address and port number, or just the port number. So it could be something like 0.0.0.0:443 (bind to all interfaces), 127.0.0.1:443 (bind only to loopback), or :443 (all interfaces, port 443).

--dns ends up determining which DNS names are present on the internally-generated TLS leaf certificate for the CA. So, here you just need whatever DNS names your clients are going to use when accessing the CA.

--with-ca-url doesn't affect the CA configuration. It just puts whatever preferred URL you have for the CA into defaults.json, which is used by step to connect to your CA.

Does this help?

[bfqrst]

Okay, I think I finally got it! Thanks.

And then you would optionally slap the preferred dns entry in --with-ca-url to sort of make it the default entrypoint in a manner of speaking? Which in turn also means the any dns name you put in --with-ca-url also has to be in --dns, right?

[tashian]

You got it. --with-ca-url is just a shortcut for bootstrapping your local step environment to the CA.

[mmalone]

This is a great conversation. I'm sure others have questions about this. For posterity, here is how I think of these three parameters more concretely:

• --address: where step-ca should listen ([<IP>]:<port>)
• --dns: the (subject alternative) name(s) in the certificate step-ca uses for its API
• --with-ca-url: the URL that clients should use to connect to the CA

Note: for the --dns flag, these are NOT the name(s) in the root or intermediate signing certificates. Rather, they are the name(s) in the server certificate that step-ca uses for its API. When step-ca starts up it issues itself a leaf certificate so it can expose its API using TLS. The --dns flag specifies the name(s) that should appear in that certificate.

In some configurations all three of these will be the same thing.

For fun, here's a not-totally-contrived scenario where they'd all be different:

• step-ca listens on port 127.0.0.1:8443 locally
• with a TCP proxy listening on :443 and forwarding traffic to 127.0.0.1:443 (to step-ca)
• with DNS name ca.internal

In this scenario, you'd use --listen "127.0.0.1:8443" --dns "ca.internal" --with-ca-url "https://ca.internal". You need --with-ca-url here because step-ca doesn't know anything about the proxy. Without that flag it'd incorrectly tell clients to try to connect on port 8443.

This scenario comes up in Kubernetes, where you may run the CA in a pod listening on one port but expose it internally via a service or externally via an ingress with a different port.

[bfqrst]

Jackpot! The reverse-proxied or in an orchestrator use case was my gut feeling all along. For me it's Nomad. That pretty much clears it up.

Here's how I perceive implementing an internal CA! It's going to be a critical and central piece of software for pretty much everything that comes after that! I want and I think I almost need to have a deep understanding of what I am doing and what the tool does. Especially if I'm teaching other people the benefits of having something like step-ca at the cert helm, or mTLS, or zero trust or whatever good this might be used for!

Not gonna lie I was beginning to ask myself if I'm asking, well, at least unnecessary questions?! But on the other hand I'm a strong believer in learning in public, which includes the occasional dumb or additional question!

Having said that, I really appreciate you guys for taking the time. Thanks @tashian, thanks @mmalone .

PS: ...on a last bug hunting note. That validation glitch that came up in my original post... Is that implicitly on your radar, or should I go ahead and open an issue?

[mmalone]

Yea, learning in public is definitely a good thing. I wish more people did that. So please don't hesitate to ask questions. We end up with good artifacts that are google-able and will help people in the future, and it helps us refine our documentation and APIs to make them more intuitive. You're not a nuisance. You're helping. <3

Regarding the validation glitch: do you know if there's an open issue for that? If not, feel free to create one (or just lemme know and I can create one).