Hi,
Excerpts from Paul Berry's message of Tue Sep 14 19:32:07 -0400 2010:
>
> I'm working with Jesse Wolfe to design a back-end REST API for the
> features of the "puppet cert" command-line tool. This is a first cut
> at a proposed interface. I'd appreciate comments about whether this
> is a good way to go.
>
> API
> ===
>
> certificate_status and certificate_statuses
> -------------------------------------------
>
I'm not sure you need to create these two new resources given that
the certificate and certificate_request resources already exists. See
below for a proposal - I'm not sure how easy this would be to implement
within the puppet architecture though.
> To retrieve information about the status of the host called
> <hostname>, issue a GET request to
> https://<master>/<environment>/certificate_status/<hostname>. If the
> hostname is recognized, this returns a JSON hash object of the form:
>
> {'state': <state>, 'hostname': <hostname>,
> 'fingerprint': <fingerprint>, 'error_message': <error_message>}
>
> <state> is one of:
> - 'requested' if the host has sent the server a certificate request
> but no certificate has been issued.
This could be figured out by doing the following:
1. Http request:
HEAD https://<master>/<environment>/certificate/<cert_name>
Http response:
404 Not Found
2. Http request:
HEAD https://<master>/<environment>/certificate_request/<cert_name>
Http response:
200 OK
> - 'signed' if a valid certificate exists for the host.
This could be figured out by doing the following:
1. Http request:
HEAD https://<master>/<environment>/certificate/<cert_name>
Http response:
200 OK
> - 'revoked' if a certificate exists for the host but has been revoked.
This could be figured out by doing the following:
1. Http request:
HEAD https://<master>/<environment>/certificate/<cert_name>
Http response:
410 Gone
> - 'invalid' the host fails validation for some reason other than the
> certificate having been revoked.
I'm not sure what would be covered here. However the following requests
could be made:
1. Http request:
HEAD https://<master>/<environment>/certificate/<cert_name>
Http response:
404 Not Found
2. Http request:
HEAD https://<master>/<environment>/certificate_request/<cert_name>
Http response:
410 Gone
3. Http request:
GET https://<master>/<environment>/certificate_request/<cert_name>
Http response:
410 Gone
Error message.
> <fingerprint> is the fingerprint of the host's certificate or
> certificate request, as a string
> (e.g. "67:70:3E:E8:D9:75:29:F7:67:87:0E:A7:70:EE:02:80"). The default
> digest algorithm for the fingerprint is MD5. To select another
> digest, add the parameter "?digest=<digest>" to the query string. All
> digests supported by Ruby's OpenSSL::Digest class are permitted.
>
This is specific representation of the certificate resource:
1. Http request:
GET https://<master>/<environment>/certificate/<cert_name>
Accept: x-cert/fingerprint
Http response:
200 Ok
67:70:3E:E8:D9:75:29:F7:67:87:0E:A7:70:EE:02:80
For another digest:
1. Http request:
GET https://<master>/<environment>/certificate/<cert_name>
Accept: x-cert/fingerprint;digest=<digest>
Http response:
200 Ok
<DIGEST>
A media type may already exists to cover certificate fingerprints.
> <error_message> is a string saying why the host failed verification
> (if the host is in the 'revoked' or 'invalid' state). Otherwise it is
> the empty string.
>
> This takes the place of the "puppet cert" options "--verify",
> "--fingerprint", and "--digest".
>
>
> To retrieve information about the status of multiple hosts, issue a
> GET request to
> https://<master>/<environment>/certificate_statuses/<hostname_pattern>.
>
> This returns JSON list object containing JSON hashes of the form
> described above, for all known hosts that match <hostname_pattern>.
> <hostname_pattern> may be "*" to match all hosts.
To get a collection of certificates:
1. Http request:
GET https://<master>/<environment>/certificate/
Http response:
200 Ok
Content-Type: application/json
[cert1, cert2]
To restrict the list of certs:
1. Http request:
GET https://<master>/<environment>/certificate/?certname=<pattern>
Http response:
200 Ok
Content-Type: application/json
[cert1_match_pattern, cert2_match_pattern]
>
> To restrict the search to just hosts that are awaiting certificates,
> add the parameter "?restrict=waiting" to the query string. To
> restrict the search to just hosts that have signed certificates, add
> the parameter "?restrict=signed".
>
This is actually the collection of certificate requests:
1. Http request:
GET https://<master>/<environment>/certificate_requests/
Http response:
200 Ok
Content-Type: application/json
[csr1, csr2]
> This takes the place of the "puppet cert" option "--list".
>
>
> To cause the master to sign or revoke a certificate for a given host,
> issue a PUT request to
> https://<master>/<environment>/certificate_status/<hostname>, and send
> the following JSON data:
>
> {'state': <desired_state>}
>
> <desired_state> is one of:
> - 'signed': causes the master to sign a certificate for the given
> host. The host must be in the 'requested' state for this to
> succeed.
A new certificate is created:
1. Http request:
POST https://<master>/<environment>/certificate/
<cert_name>
Http response:
201 Created
Location: https://<master>/<environment>/certificate/<cert_name>
https://<master>/<environment>/certificate/<cert_name>
A side effect of the POST request on the server is to delete the CSR.
> - 'revoked': causes the master to revoke a certificate for the given
> host. The host must be in the 'signed' state for this to succeed.
A certificate is deleted:
1. Http request:
DELETE https://<master>/<environment>/certificate/<cert_name>
Http response:
204 No Content
>
> (Other hash elements, if present, are ignored).
>
> This takes the place of the "puppet cert" options "--sign" and
> "--revoke".
>
>
> To cause the master to discard certificate information for a given
> host, issue a DELETE request to
> https://<master>/<environment>/certificate_status/<hostname>.
>
> This takes the place of the "puppet cert" option "--clean".
>
Hm - I haven't a specific answer to this given that delete is already
used to revoke a certificate. I'm not sure that this method should
actually be exposed via http since important information could be
lost (revoked certificates?). It may be better to keep it as a command
line only accessible on the puppet master?
--
Mathias Gug
Ubuntu Developer http://www.ubuntu.com
--
You received this message because you are subscribed to the Google Groups
"Puppet Developers" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-dev?hl=en.
