step-ca REST api documentation

[arbradford]

I'm looking for more information on utilizing step-ca as a microservice behind a REST api. It appears REST is supported in the step-ca online mode according to this chart:

https://smallstep.com/docs/step-ca/certificate-authority-core-concepts#online-and-offline-x509-certificate-authority

However, when searching through nearly all of the docs I've found myself constantly hitting dead ends. I even checked the step help --http=:8000 ca command and corresponding webpage documentation. I skimmed through the content to see if I could find any lurking information on the available endpoints, payloads, request methods allowed, etc. I can't find anything.

So I have a few questions.

1. Does step-ca as a service support the ability to be a "non cli / command line" service behind a REST api that has the ability to do the following:

   • generate leaf certificates from an intermediate CA
   • verify certificate signatures
   • renew the CA
   • basically any of the step-cli / step-ca commands I suppose

2. Can step-crypto function as a REST based microservice as well? And can it support the following operations:

   • sign / encode jwt tokens
   • decode / verify jwt tokens

3. Assuming either of these are true, is the entire REST api designed to be used around curl? Or is there any information in using other libraries / utilities for requests ideally like request methods allowed, payloads, etc. I prefer pythons requests module personally (as a python based programmer) and while I don't mind getting more familiar with curl if curl was used "in mind" then I can go ahead and take the path of less friction.

4. Can you see any downside in implementing a custom REST api with whatever chosen language and framework in front of step-cli instead of attempting to use step-ca?

5. I've found these comments about the REST api docs:

https://gitter.im/smallstep/community?at=5d8402698521b34d91575237

There is a statement that the REST api is not documented. Is this still the case? Is this comment suggesting to use the step-cli in the same way I've suggested above as a workaround?

I appreciate any insight that can be provided, I've implemented a nice proof of concept using step-cli and have to say I'm glad such a tool exists and am curious to learn more implementation details.

[maraino]

Does step-ca as a service support the ability to be a "non cli / command line" service behind a REST api that has the ability to do the following:

step-ca uses a REST API using JSON for everything, so yes, you can use curl or your own implementation to talk with step-ca.

Can step-crypto function as a REST based microservice as well? And can it support the following operations:

What do you mean with step-crypto? If you mean commands like step crypto jwt sign ..., well they don't have any REST interface, but the way we sign, JWT is quite standard, so you can always sign a JWT yourself.

Assuming either of these are true, is the entire REST api designed to be used around curl? ...

Yes, we currently do not have docs, but looking at the file ca/client.go you can what endpoints and how the requests and responses are. See for example the Sign method:

certificates/ca/client.go

Lines 565 to 592 in 35ede74

	func (c *Client) Sign(req *api.SignRequest) (*api.SignResponse, error) {
	var retried bool
	body, err := json.Marshal(req)
	if err != nil {
	return nil, errs.Wrap(http.StatusInternalServerError, err, "client.Sign; error marshaling request")
	}
	u := c.endpoint.ResolveReference(&url.URL{Path: "/sign"})
	retry:
	resp, err := c.client.Post(u.String(), "application/json", bytes.NewReader(body))
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Sign; client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var sign api.SignResponse
	if err := readJSON(resp.Body, &sign); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Sign; error reading %s", u)
	}
	// Add tls.ConnectionState:
	// We'll extract the root certificate from the verified chains
	sign.TLS = resp.TLS
	return &sign, nil
	}

It does a POST request to /sign with the body api.SignRequest and the response is api.SignResponse

In that SignResponse you're probably interested in the certChain that combines both certificate (crt) and intermediate (ca), they are still there for backward compatibility.

Can you see any downside in implementing a custom REST api with whatever chosen language and framework in front of step-cli instead of attempting to use step-ca?

I think it will make more sense to use a custom REST API to talk to step-ca instead of the step-cli.

[arbradford]

Thank you for the response, exactly what I was looking for!

[maraino]

Just take into account that the renewal is a little bit more complicated:

certificates/ca/client.go

Lines 596 to 617 in 35ede74

	func (c *Client) Renew(tr http.RoundTripper) (*api.SignResponse, error) {
	var retried bool
	u := c.endpoint.ResolveReference(&url.URL{Path: "/renew"})
	client := &http.Client{Transport: tr}
	retry:
	resp, err := client.Post(u.String(), "application/json", http.NoBody)
	if err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Renew; client POST %s failed", u)
	}
	if resp.StatusCode >= 400 {
	if !retried && c.retryOnError(resp) {
	retried = true
	goto retry
	}
	return nil, readError(resp.Body)
	}
	var sign api.SignResponse
	if err := readJSON(resp.Body, &sign); err != nil {
	return nil, errs.Wrapf(http.StatusInternalServerError, err, "client.Renew; error reading %s", u)
	}
	return &sign, nil
	}

As you can see it does a POST to /renew with an empty body (http.NoBody). But it does using a client with the passed transport client := &http.Client{Transport: tr}. This client must be a regular HTTP configured with a client certificate, the one that we want to renew, and it also has to trust the root certificate of the CA.

The renewal is based on an mTLS connection, step-ca will verify the certificate of the client, it will make sure that the provisioner used to sign that certificate is still available and will sign a new certificate "cloning" the information present in the client certificate.