This section specifies the communication between a GridShib-CA credential retriever client and the GridShib-CA server.
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.
The following values should be set in the request header for all requests:
Response Status Code
- 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.
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" 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" 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.