[Docs]: Clarify step ca init --remote-management

[udf2457]

At present it is hard to see how to correctly transpose the config shown in the docs to its step ca init --remote-management equivalent when setting up a fresh instance.

For example, can --kms-root= be left blank ? The JSON equivalent keys don't make any distinction between root and intermediate.

What would be the command syntax equivalent of the JSON config ? That's what I think ought to be clarified.

Specifically in my use-case, my root is completely offline in HSM, I only have the pub cert available. The intermediate is in AWS KMS and that's what I'll be using step ca against.

[hslatman]

Hey @udf2457, initializing step-ca with Remote Management enabled doesn't affect how the KMS is configured. It changes how provisioners are managed. Documentation for this can be found here. So for your use case you should be able to use all of the usual flags to configure the KMS settings.

[udf2457]

@hslatman I think you're missing the point. Let me try again....

The docs say "put this in your ca.json":

{
    "root": "/etc/step-ca/certs/root_ca.crt",
    "crt": "/etc/step-ca/certs/intermediate_ca.crt",
    "key": "awskms:key-id=f879f239-feb6-4596-9ed2-b1606277c7fe",
    "kms": {
        "type": "awskms",
        "uri": "awskms:region=us-east-2;profile=foo;credentials-file=/path/to/credentials"
    }
}

Meanwhile I invite you to go read the reference for the step ca init command.

As I said. It is clear as mud as to how the CLI flags match up wth the ca.json stanzas.

It is not at all clear which step ca init flags would give me the same output.

[hslatman]

The step ca init command doesn't have the flags for all configuration options, nor is it intended/designed to provide all of the options. It is provided as a way to get started quickly, and for further customization of the settings, we refer to our docs. You're free to build your own ca.json configuration with all bells and whistles applied based on the (partial) examples we provide in our docs.

As mentioned, the --remote-management setting has nothing to do with the AWS KMS settings.

[udf2457]

The problem with the line of argument you're taking is that the docs say otherwise.

I am told in the docs that if I want Remote Provisioner Management on a new CA, that the recommended way is to "pass --remote-management to step ca init"

But you're busy telling me step ca init is some sort of useless half-built tool and that if I want to do anything serious I like using AWS KMS in conjunction with Remote Provisioner Management then I should hack the ca.json manually.

It really makes no sense.

[hslatman]

The problem with the line of argument you're taking is that the docs say otherwise.

The docs also say this:

On an Existing CA

...

Update your "authority" block in ca.json to include the following:

"authority": {
  "enableAdmin": true,
  "provisioners": [
    ...
  ]
},

But you're busy telling me step ca init is some sort of useless half-built tool and that if I want to do anything serious I like using AWS KMS in conjunction with Remote Provisioner Management then I should hack the ca.json manually.

It really makes no sense.

No, that's not what I'm saying. The intention of step ca init is not to provide all of the options that are available in the CA. It is provided to get started quickly, and it has options for the options that we consider to be used most frequently. Also, it's simplifying some parts of the configuration. Take provisioner management: provisioners can't be added during step ca init (for the most part). If we'd allow that, that would make the number of step ca init flags a lot larger, and thus far more complex. So I disagree with your statement.

[udf2457]

Yeah ... "On an Existing CA".

My point is I do not have an existing CA.

Why should I be forced to play the "existing CA" game.

Is it not glaringly obvious that I should be able to set up a new CA, out of the box, with RPM and AWS KMS ?

I mean come on, its not like I'm talking about some obscure use-case here.

[hslatman]

Why should I be forced to play the "existing CA" game.

You're not forced to do anything, in my opinion. You're free to use and adapt the software.

Is it not glaringly obvious that I should be able to set up a new CA, out of the box, with RPM and AWS KMS ?

And you can do so, just not in the way you expect(ed) it to work out of the box / want it to work. Feel free to open a PR with improvements where you see fit.

[tashian]

The docs about how to set up AWS KMS are clear that you need to modify ca.json. The docs for step ca init are clear that --kms-root only supports Azure right now. It sounds like the software doesn't work the way you want it to work, but I don't see a docs issue here. Closing.