Credential Retriever Protocol

This section specifies the communication between a GridShib-CA credential retriever client and the GridShib-CA server.

Connection Overview


The URL for the post will be provided to the client either via its initiation mechanism from the GridShib-CA, from the user directly or some other out-of-band means.

Request Connection

A GridShib-CA credential retriever client MUST use a HTTP Post request to the GridShib-CA to request service.

The URL MUST use the https protocol. The GridShib-CA MUST reject all requests not using https.

To prevent man-in-the-middle attacks, the GridShib-CA credential retriever client SHOULD validate[ref?] that the server certificate for the GridShib-CA is appropriate for the host on which it is running and is from a trustworthy certificate authority; what a trustworthy CA is depends on the context of the deployment.

POST Headers

The following values should be set in the request header for all requests:
  • User-Agent: For future compatibility the user-agent field SHOULD contain a client version number. E.g. "GridShibCA-Python/2.0.0-preview"
  • Accept: The Accept field MUST contain "text/plain" to prevent the GridShib-CA from sending back HTML in the event of an error.
    • TODO: Verify current clients are doing this.
Response Status Code

The GridShib-CA server MUST response with a status code of 200 to indicate success.

A credential retriever client MUST consider any other status code value besides 200 as a failure. In event of an error an error message SHOULD follow the status code on the same line. Any other contents of the response SHOULD be discarded by the client.

Note: The GridShib-CA currently will not return any other 20X status codes besides 200.

Certificate Issuance Request

The following parameters MUST be set in the POST to request the issuance of a X.509 certificate.
  • command=IssueCert
    • "command" MUST be set to the literal string "IssueCert"
  • GRIDSHIBCA_SESSION_ID=<session identifier>
    • "GRIDSHIBCA_SESSION_ID" MUST be set to the session identifier provided to the client by the GridShib-CA on invocation, by the user, or some other out-of-band methed. The session identified by this value must be a Credential issuance session.
  • certificateRequest=<PEM-encoded PKCS10 certificate request>
    • "certificateRequest" MUST be set to the PEM-encoded PKCS10 certificate request [ref?] containing the public key generated by the credential retriever client. The request MUST have the "-----BEGIN CERTIFICATE REQUEST----" header line and "-----END CERTIFICATE REQUEST----" footer line as is normal for OpenSSL.
The following parameters MAY be set in the POST to request the issuance of a X.509 certificate.
  • lifetime=<value in seconds>
    • "lifetime" may specify a requested credential lifetime in seconds. The server SHOULD honor this value if within policy constraints. If the value is invalid (e.g. larger than a specific maximum), the server MUST ignore it.
Any other parameters SHOULD be ignored by the GridShib-CA.

Certificate Issuance Response

On successful certificate issuance, the response from the GridShib-CA MUST be a text/plain document containing a PEM-encoded X.509 certificate [ref?]. The document MUST have the "-----BEGIN CERTIFICATE-----" header line and the "-----END CERTIFICATE-----" footer line as is normal for OpenSSL.

Trust Roots Request

The following parameters MUST be set in the POST to request trust roots.
  • command=TrustRoots
    • "command" MUST be set to the literal string "TrustRoots"
Any other parameters SHOULD be ignored by the GridShib-CA.

Trust Roots Response

The successful response to a trust roots request will be a text/plain document containing a sequence of zero or more ASCII lines, formatted as follows:
  • SEQUENCE of 0 or more Trust Roots, each of which is a sequence of:
    • Trust Root Deliminator
      • One line starting with the literal string "-----File:" followed by the filename that should contain the subsequent trust root contents. The filename SHOULD be just the basename portion of the filename and not the full path.
    • Trust Root Contents
      • Zero or more lines containing literal content which make up the file named by the preceding Trust Roots Deliminator line.
      • The Trust Root Contents MUST NOT contain a line that could be mistaken for a Trust Root Deliminator (as it will be so mistaken).
      • The end of the Trust Root Contents MUST be indicated by a Trust Root Deliminator or end of file.