[Pki-devel] [rhcs-dev-list] latest restful interface doc

[Ade Lee]

On Tue, 2011-10-18 at 18:13 -0700, Jack Magne wrote:
> On 10/18/2011 02:44 PM, Ade Lee wrote: 
> > Based on discussions with jmagne and ayoung, here is the latest version.
> > Please feel free to comment!
> > 
> > ayoung will post to wiki.
> > 
> > Ade
> > 
> >   
> Ade: 
> 
> A few questions:
> 
> 1. I see that for the ocsp service we have something like this:
> 
> "GET" 
> "/pki/certificate/ocsp" 
> "Get OCSP response"
> 
> 
> I see that perhaps we are trying to first get to the certificate in
> question and then drill down into the ocsp status of said certificate.
> 
> Question is, is it not true that OCSP responders respond to a common
> format (so any client can connect) as explained here:
> 
> A.1.1 Request
> 
>    HTTP based OCSP requests can use either the GET or the POST method to
>    submit their requests. To enable HTTP caching, small requests (that
>    after encoding are less than 255 bytes), MAY be submitted using GET.
>    If HTTP caching is not important, or the request is greater than 255
>    bytes, the request SHOULD be submitted using POST.  Where privacy is
>    a requirement, OCSP transactions exchanged using HTTP MAY be
>    protected using either TLS/SSL or some other lower layer protocol.
> 
>    An OCSP request using the GET method is constructed as follows:
> 
>    GET {url}/{url-encoding of base-64 encoding of the DER encoding of
>    the OCSPRequest}
> 
>    where {url} may be derived from the value of AuthorityInfoAccess or
>    other local configuration of the OCSP client.
> 
>    An OCSP request using the POST method is constructed as follows: The
>    Content-Type header has the value "application/ocsp-request" while
>    the body of the message is the binary value of the DER encoding of
>    the OCSPRequest.
> 
> I wonder if instead of drilling down to a cert and proceeding, it would make more sense to have a top level url ending with perhaps "ocsp", that is then passed the 
> certificate info in the standard way? I don't know if this is in fact restful.
> 
I was actually thinking of /pki/certificate/ocsp as kind of a top level
request -- that is -- I did not specify /pki/certificate/ocsp/$id.  It
may make it more clear to specify this as /pki/ocsp or some such.  I did
not use /pki/ocsp because that would conflict with the
system /pki/ocsp. 

Its a good point though that the standard expects the OCSP request to be
submitted using POST.  I think we should do that.

> 2. I was curious as to what the following does:
> 
> 
> 
> 
> 
> 
> 
> "PUT" 
> "/pki/certificate" 
> "Add a
> certificate" 
> "None",,, 
> Is this actually for submitting a certificate request? I realize there is a section below dealing with requests.
> Is this perhaps something that is referenced by some other piece of the server itself? Like approving a request would trigger this?
> 
Are you looking at the right version?  In the latest, this is POST-a ..

Actually - I had put this in for completeness but in the interest of
clarity, we should remove it.  This operation - as well as the ones for
DELETE for keys, certs and cert requests should be removed from the doc.

> 3. I notice proceeding below there is a whole section devoted to profiles. I assume the bulk of the requests are agent and adminy type actions in managing profiles. 
> I was just wondering if we have a handle on how to actually USE a profile, that is have the standalone client be able to apply for a certificate using one of these profiles we have?
> 
> 
> Is it absorbed into the act of creating "requests" further down into the API? One of the payload params would be a profile? Or perhaps a portion of the url itself would be
> for the profile used?
> 
Yes -requests are done using profiles.  We may in fact end up doing
something like this : POST /pki/request/${profile_id}  for example.
This would act like a factory URL that would end up generating a request
as /pki/request/0xfeed

The payload would need to include the relevant inputs as specified by
the profile.

The profile URLs that change the profile are agent/admin operations.  It
is possible for a client to GET a list of profiles (/pki/profiles) or
the details (including inputs, outputs and constraints) of a specific
profile (GET /pki/profile/$profile_id ) and craft a request accordingly
and parse the response accordingly.

> 
> . Also in some of the online doco they express the requests with
> possibly some sort of templated param at the end like this: GET
> pki/certificate/{cert_serial_no} or some such. Is this convention kind
> of implied by the API or would it be filled in later?

Its implied - but I think you are looking at the wrong version.  In this
last version, I did explicitly say -- GET /pki/certificate/$id
> 
> Looks like it is shaping up as we continue to discuss.
> 
> thanks,
> jack
> _______________________________________________
> Pki-devel mailing list
> Pki-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/pki-devel