Using the smallstep/step-ca container

[marioja]

In the documentation for the container at https://hub.docker.com/r/smallstep/step-ca I do not understand the information in the quickstart section vs the manual installation.

In the section "Initialize your PKI" in Quickstart there is a docker run command with which will keep the docker command in the foreground. What is the purpose of this foreground command? Where is the root ca stored? Should it not be run using -d instead of -it?

In the section Bootstrap step clients in Quickstart, what is the text in the box with the two commands? Is that meant to be a bash shell script? Why the {}? What is the purpose of running those commands? Does that work on Windows?

How does the information in the Manual installation section compare to the information in the Quickstart section? Which one should be used for what scenarios?

[hslatman]

In the documentation for the container at https://hub.docker.com/r/smallstep/step-ca I do not understand the information in the quickstart section vs the manual installation.

In the section "Initialize your PKI" in Quickstart there is a docker run command with which will keep the docker command in the foreground. What is the purpose of this foreground command? Where is the root ca stored? Should it not be run using -d instead of -it?

This is an illustrative example of running the container. You can adapt it to your needs. You're right that usually you would run the CA "in the background" using a container orchestrator.

The root CA (and other files) are stored in /home/step in the container. This is mounted as step locally.

In the section Bootstrap step clients in Quickstart, what is the text in the box with the two commands? Is that meant to be a bash shell script? Why the {}? What is the purpose of running those commands? Does that work on Windows?

The {} seems to some leftover formatting that isn't showing correctly on the Docker hub page. We need to fix that. The purpose of the commands is to bootstrap trust with your new CA on the host system (or any other system that you want to issue certs to). It also works on Windows.

How does the information in the Manual installation section compare to the information in the Quickstart section? Which one should be used for what scenarios?

The manual installation is more of a step by step instruction for initializing the CA when running in Docker. The quickstart is for a quick start, omitting some details and customization options, and doing it in a single command. The instructions for bootstrapping trust apply to both: these are not specific to initializing and running the CA in Docker; they apply to any deployment option. Both only show the surface of what's possible when running the CA, as there are ample of options for initializing a CA with different settings and signing chains.

[tashian]

The curly braces are a Bash scoping construct.
For Windows, you'd need to adapt the commands for your environment.
I've added a note to the Docker Hub README, saying that these commands have been tested in Bash on Linux.

[marioja]

Ok, now I understand better. I am running step-ca on a Synology NAS and I would like to be able to issue certificate on other devices on my network since I do not want to install step on it. When I run step ca certificate on the step-ca container, all works ok. When I try to run this command on a remote device where step is installed here is what I get:

step ca certificate localhost s.crt s.key
No admin credentials found. You must login to execute admin commands.
✔ Please enter admin name/subject (e.g., name@example.com): step
✔ Provisioner: admin (JWK) [kid: (snip)]
Please enter the password to decrypt the provisioner key: ☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺☺
The request lacked necessary authorization to be completed. Please see the certificate authority logs for more info.
Re-run with STEPDEBUG=1 for more info.

In the step-ca logs I get this error:

time="2023-07-23T02:18:43Z" level=warning duration="720.048µs" duration-ns=720048 error="authority.Authorize: authority.authorizeSign: provisioner not found or invalid audience (https://synology-nas-host:9000/1.0/sign)" fields.time="2023-07-23T02:18:43Z" method=POST name=ca ott=(snip) path=/sign protocol=HTTP/2.0 referer= remote-address=x.x.x.x request-id=ciu8s0rpu3cg00bs7qng size=144 status=401 user-agent="Smallstep CLI/0.24.1 (windows/amd64)" user-id=

I know that this is a provisioner issue but for the life of me, I read everything I could on this page and I cannot figure out 1) if this allowed and 2) how to do it.

[hslatman]

You'll need to verify that 1) the provisioner you're using exists (I think it does, because you're using the CLI UI to select the right one from the ones available) and 2) verify that you're running your CA with the synology-nas-host included as one of its DNS names (in the dnsNames config property).

When using step to get a certificate, a JWT token is created with an audience destined for your CA. If you CA isn't configured with the same audience (which includes the CA hostname), then the CA assumes the token wasn't destined for itself, and will not authorize the request.

What may have happened is that you initialized the CA on your NAS with a DNS name like localhost or 127.0.0.1. Those would work for the case where you run step on the NAS itself. But if you then try to access the CA from somewhere on your network, you need the CA to respond to synology-nas-host too.

[marioja]

Maybe the docker readme doc should explain what each sections are for and I would change the docker run -it to a docker run -d and tell users to check their logs for the important initialization information.

[marioja]

Also, a lot of service require the certificate that gets created to be combined with the intermediate CA so how can I get the intermediate CA especially in PEM format?

[tk-nguyen]

If you're using docker, it should print the intermediate cert path in the beginning of the logs:

$ docker logs <step-ca container name>
...
✔ Root certificate: /home/step/certs/root_ca.crt
✔ Root private key: /home/step/secrets/root_ca_key
✔ Root fingerprint: 1c5b19a2cbe2cb65793085ecf712e51d6cd901bddf70399c63c90cb8b6ff3dd7
✔ Intermediate certificate: /home/step/certs/intermediate_ca.crt
✔ Intermediate private key: /home/step/secrets/intermediate_ca_key
...

To get the cert you can use either docker cp <step-ca container name>:/home/step/certs/intermediate_ca.crt . to copy it out to local directory or docker exec <step-ca container name> cat /home/step/certs/intermediate_ca.crt to print it to stdout.

[hslatman]

By default the CA includes the intermediate certificate with any leaf certificate it issues. So generally there's no need for additional steps to get the intermediate certificate, unless the service you're using it with doesn't understand multiple certificates in a file.