I am new to step-ca, and was delighted to discover we already have a module for it (thank you @mohe2015 and co)!
However, I have some questions that are so basic I can’t see them quite described anywhere in the docs.
To get step-ca up and running on NixOS, my steps so far are:
nix-shell -p step-cli
step ca init (and follow the prompts)
Copy the full output structure, from ~/.step/ to /var/lib/step-ca/ by hand.
Copy the generated password printed during the interactive setup into a secrets file (I chose /var/lib/secrets/step-ca/intermediatePasswordFile), also by hand.
Configure the module, including by referencing /var/lib/step-ca/config/ca.json, and nixos-rebuild
Now, this seems to work? But, it feels rather manual. Is this the intended flow?
Also, interacting with the running step-ca server from the cli isn’t very natural, as the STEPPATH environment variable isn’t set to point to it. Are we expected to set this ourselves as individual users, or is it something the step-ca module would do for us?
Thanks @peterhoeg, that’s actually good to know I’m not totally off track.
In fiddling around with it some more, I have a more serious question.
I only just noticed that the module places the config file in /etc/smallstep/ca.json (and passes this path to step-ca in ExecStart). However, it leaves the STEPPATH environment variable as-is (which seems to be set to /etc/step-ca by the upstream systemd service file – a location that is not used at all by this module), and further, appears to add a new HOME environment variable set to /var/lib/step-ca, which I can’t see being used anywhere.
By my reading, STEPPATH points to a nonexistent location, and, the completely-unused environment variable HOME points to our actual (I think?) desired config location.
How does this even work right now! I’m sure I’m misunderstand something. Does HOME do something? I don’t see it mentioned in the docs.
Regardless, the step-ca part does seem to work, but the problem I am seeing is that it seems impossible to use the step CLI tool properly, as you can only give it a valid STEPPATH – and /etc/smallstep is not one, because it only contains ca.json and none of the other state. Providing a STEPPATH of /var/lib/step-ca seemed to work for a minute, but only because that contained the original ca.json I started with, and when I make edits to the module config, the changes obviously don’t show up in this file, they only go into the file in /etc.
Does this all make sense? I feel like either this is quite broken, or I’m missing something important in the design.
(To further add, my particular goal right now is to adapt the provided systemd cert-renewer template, and I can’t figure out how to invoke step correctly, given my above confusion.)
The current NixOS module for step-ca doesn’t fully support interaction with the step CLI. The reason is that the step CLI is used to apply changes to an existing step-ca configuration. This approach is incompatible with the immutability of NixOS configuration.
The official way of configuring the step-ca module is through the services.step-ca.settings option. The contents of this option goes to ca.json. Users are expected to configure this manually, but it’s probably easier to generate configuration with step ca init, make adjustments to the generated ca.json, and import it into the NixOS configuration using builtins.fromJSON. This is documented in the option description.
The values of HOME and STEPPATH are implementation details of the module that aren’t exposed to users. But to clarify, HOME is set for the step-ca process so that it won’t attempt to place files in random locations in the filesystem. As for STEPPATH, it isn’t set globally for two reasons. First, it would interfere with normal uses of the step CLI. Second, there’s no reason to because using the step CLI against the NixOS-configured step-ca instance is unsupported.
Perhaps this is all a PEBKAC situation. I do see that a lot of the utility of the step CLI tool is to manage an instance of step-ca in an imperative fashion, so, not relevant to us. But I have also gotten the impression that step is also the most obvious way to use an instance of step-ca – for example, to obtain or renew certificates.
(I know it’s also possible to use an ACME client or so to do this, but, since this is for private stuff it seems a little cumbersome to set up the challenges and such.)
If I’m right, and it is reasonable to use step CLI for this purpose on the same machine as the running step-ca, should I get step-ca up and running as I already have, blow away all the “local” state made originally by step ca init, and then use step ca bootstrap, as for remote clients? Is that sort’ve canon for this?
(And, as a side question, do you have advice on the best way to add provisioners to a CA, in the situation where the use of step ca provisioner is discouraged? The fields look very fiddly to come up with on one’s own!)
But I have also gotten the impression that step is also the most obvious way to use an instance of step-ca – for example, to obtain or renew certificates.
In that case, I think you can manually specify STEPPATH and use the CLI. But you’d need to be root to use the CLI because the NixOS module enables DynamicUser for securing the systemd service, which makes STEPPATH inaccessible for regular users. If this feels inconvenient, you can override this setting if you want.
should I get step-ca up and running as I already have, blow away all the “local” state made originally by step ca init , and then use step ca bootstrap , as for remote clients?
do you have advice on the best way to add provisioners to a CA, in the situation where the use of step ca provisioner is discouraged?
I approach these issues by first creating a step-ca instance in my home directory. I then take the JSON config, make a few edits, and incorporate it into my NixOS configuration. In my case, the edits weren’t huge and I only had to fix a few paths for the certs.
If this all seems a bit tedious, you could also create an alternative STEPPATH, like /var/lib/mystep or /opt/step-ca, and create your own systemd service using the systemd.units option. With this approach, you can use step-ca like you would on other distros.
Hello, I’m just starting to work with the step-ca module and came across this topic.
Regarding the question about the manual nature of the process, you can improve the situation by updating your ca.json file to target certificates and other things in /etc. That way you can provision the given files using environment.etc.source or environment.etc.text.
However this raise an issue regarding the private key that must stay private making it incompatible with the nix store as is. For those files you can mitigate the issue using tools like agenix or sops-nix.
Anyway that could give some hint on how to improve the existing module in the long run.