RESTful API
TLS/SSL
InCommon
c/o Internet2
1000 Oakbrook Drive, Suite 300
Ann Arbor MI, 48104
Table of Contents
Version History2
[ 1 Introduction3|#_RefHeading_115495_1184992394]
[ 1.1 HTTP Methods3|#_RefHeading__Toc12780_3085879999]
[ 1.2 HTTP Status Codes3|#_RefHeading__Toc12782_3085879999]
[ 1.3 Errors3|#_RefHeading__Toc12789_3085879999]
[ 2 Authentication4|#_RefHeading_6822_1510537723]
[ 2.1 Authentication via Username and Password4|#_RefHeading_6824_1510537723]
[ 2.2 Authentication via Username and a Client Certificate4|#_RefHeading_6826_1510537723]
[ 3 API Resources (Functions)5|#_RefHeading_115497_1184992394]
[ 3.1 TLS/SSL Certificates5|#_RefHeading_115499_1184992394]
[ 3.1.1 Listing SSL Types5|#_RefHeading_115501_1184992394]
[ 3.1.1.1 Response Attributes5|#_RefHeading__Toc12791_3085879999]
[ 3.1.1.2 Example Request5|#_RefHeading_115503_1184992394]
[ 3.1.1.3 Example Response5|#_RefHeading__Toc12793_3085879999]
[ 3.1.2 TLS/SSL Enrollment6|#_RefHeading_4716_1906736158]
[ 3.1.2.1 Request Attributes6|#_RefHeading__Toc14712_3085879999]
[ 3.1.2.1.1 Server Type7|#_RefHeading__Toc14696_3085879999]
[ 3.1.2.2 Example Request9|#_RefHeading__Toc14714_3085879999]
[ 3.1.2.3 Example Response9|#_RefHeading__Toc14716_3085879999]
[ 3.1.3 Collect TLS/SSL Certificate10|#_RefHeading_49442_1042788155]
[ 3.1.3.1 Example Request10|#_RefHeading__Toc3333_3444070539]
[ 3.1.3.2 Example Response10|#_RefHeading_6645_19945470941]
[ 3.1.4 TLS/SSL Certificate Revocation10|#_RefHeading__Toc3335_3444070539]
[ 3.1.4.1 Path Parameters11|#_RefHeading__Toc3337_3444070539]
[ 3.1.4.2 Request Attributes11|#_RefHeading__Toc3339_3444070539]
[ 3.1.4.3 Example Request11|#_RefHeading_115505_1184992394]
[ 3.1.4.4 Example Response11|#_RefHeading__Toc3341_3444070539]
[ 3.1.5 TLS/SSL certificate renewal by RenewId12|#_RefHeading_115507_1184992394]
[ 3.1.5.1 Path Parameters12|#_RefHeading__Toc3414_3444070539]
[ 3.1.5.2 Example Request12|#_RefHeading_115509_1184992394]
[ 3.1.5.3 Example Response12|#_RefHeading__Toc3416_3444070539]
[ 3.1.6 TLS/SSL certificate renewal by SSL enrollment ID13|#_RefHeading__Toc3418_3444070539]
[ 3.1.6.1 Path Parameters13|#_RefHeading__Toc3420_3444070539]
[ 3.1.6.2 Example Request13|#_RefHeading__Toc3422_3444070539]
[ 3.1.6.3 Response fields13|#_RefHeading__Toc3424_3444070539]
[ 3.1.6.4 Example Response13|#_RefHeading__Toc3426_3444070539]
[ 3.1.7 TLS/SSL Certificate Replacement14|#_RefHeading_1877_1531695971]
[ 3.1.7.1 Path Parameters14|#_RefHeading_6643_199454709411]
[ 3.1.7.2 Request Attributes14|#_RefHeading_6645_199454709411]
[ 3.1.7.3 Example Request15|#_RefHeading__Toc3428_3444070539]
[ 3.1.7.4 Example Response15|#_RefHeading__Toc3430_3444070539]
Anchor | ||||
---|---|---|---|---|
|
Date | Description |
28 January 2018 | Initial Release; CCM version 6.0 |
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
InCommon Certificate Manager (CM) tries to adhere as closely as possible to standard HTTP and REST conventions in its use of of HTTP Methods (verbs).
Method | Usage |
GET | Used to retrieve a resource |
POST | Used to create a new resource |
Anchor | ||||
---|---|---|---|---|
|
InCommon Certificate Manager (CM) tries to adhere as closely as possible to standard HTTP and REST conventions in its use of of HTTP status codes.
Status Code | Usage |
200 OK | The request completed successfully |
204 No Content | An update to an existing resource has been applied successfully |
400 Bad Request | The request was malformed. The response body will include an error providing further information |
404 Not Found | The requested resource does not exist |
Anchor | ||||
---|---|---|---|---|
|
Whenever an error response (status code >=400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
...
HTTP/1.1 401 Unauthorized |
Anchor | ||||
---|---|---|---|---|
|
In order to access InCommon APIs, you will need to authenticate yourself to the InCommon CM service. You can authenticate via username/password, or via username + client certificate.
All API functions (methods) require HTTP header parameters for authorization.
Header Name | Description |
login | Privileged User's Login Name |
password | Privileged User's Password; ( if necessary ) |
CustomerUri | Customer URI part of the URL e.g.s. InCommon or InCommon_Test |
Anchor | ||
---|---|---|
|
...
|
...
|
Prerequisites
- Users should have InCommon CM login credentials.
- Web API access must be enabled for the Organization by InCommon.
- Each department department will need to be enabled by their RAO through InCommon CM.
The URI for the username/password authentication schema for InCommon CM is:
- {api-endpoint} = https://cert-manager.com/api/\{path}
...
Anchor | ||||
---|---|---|---|---|
|
Prerequisites
- Users should have InCommon CM login credentials.
- Web API access must be enabled for the Organization by InCommon.
- Each department department will need to be enabled by their RAO through InCommon CM.
- Admins should have Certificate Auth enabled.
- The authentication certificate MUST BE requested and issued through InCommon CM and active at the moment of authentication.
...
- {api-endpoint} = https://cert-manager.com/private/api/\{path}
Anchor | ||||
---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
All functions pertaining to the management of TLS/SSL certificates within InCommon CM.
Basic Auth URI endpoint – {*}{+}https://cert-manager.com/api/ssl/v1/+*{path}
Client Auth URI endpoint – {*}{+}https://cert-manager.com/private/ssl/v1+*{path}
Anchor | ||||
---|---|---|---|---|
|
Path – /ssl/v1/types
HTTP Method – GET
Anchor | ||||
---|---|---|---|---|
|
Attribute | Type | Description | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5007d85716d7c114-d29d1da8-4d3645a0-81c596a3-2f31c9434fdf1aa208ee8c0c"><ac:plain-text-body><![CDATA[ | [ ] | Array | An Array of available SSL Types | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="bc13ac2644570056-f242d8bd-416344e4-9770a8e9-0992025fb275f5fa2d070ecf"><ac:plain-text-body><![CDATA[ | [ ] id | String | The SSL Type unique identifier | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b49aa6a4a910972e-936a533d-409047ed-992fb135-b7e9edb18744987733da0a66"><ac:plain-text-body><![CDATA[ | [ ] name | String | The SSL Cert Type name | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="af43be6bff3edb7e-021ebbb1-47e444e5-822b96fb-4c168fd176498f4b1efe0791"><ac:plain-text-body><![CDATA[ | [ ] terms [ ] | Array | An array of available terms, in days, for the SSL type. | ]]></ac:plain-text-body></ac:structured-macro> |
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://cert-manager.com/api/ssl/v1/types/' -i {color} |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 200 OK |
Anchor | ||||
---|---|---|---|---|
|
Creation and submission of a request for a new TLS/SSL certificate.
Path – /ssl/v1/enroll?
HTTP Method – POST
Anchor | ||||
---|---|---|---|---|
|
Attribute | Type | Description | Constraints | ||
orgId | Integer | Organization ID; can be found within InCommon CM on the organization's and or department's General tab. | MUST BE positive & not NULL | ||
csr | String | Certificate Signing Request (Base-64 encoded, with or without the: | MUST not be empty or NULL. | ||
SubjAltNames | String | Comma-Separated list of DNS Subject Alternative Names (SANs) | A maximum of 100 SANs. | ||
certType | Integer | Certificate Type ID | Obtained from /ssl/types OR /ssl/types{orgId} function | ||
numberServers | Integer | Number of Server Licenses. Required for the Wildcard products | MUST BE positive & not NULL | ||
serverType | Integer | Server Software Identifier | MUST BE at least -1; | ||
term | Integer | Certificate validity period in number of days. | MUST BE positive. | ||
comments | String | Additional Comments/Notes for Enrollment Request | A maximum of 1024 characters accepted. | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="1c7cea3a104ce33f-633e5e96-4f9644ec-b8068844-7272f415828bb17375f54aeb"><ac:plain-text-body><![CDATA[ | customFields [] | Array | Custom fields to be applied to enrolling certificate. | MUST contain mandatory custom fields. | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="1668553ccde12c47-6829fa33-4558405b-ba77b47e-5dc40e5717147096fd7ea4ae"><ac:plain-text-body><![CDATA[ | customFields[].name | String | The name of an enabled mandatory custom field. |
| ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="45d701c0409c44a0-5d6eecf3-47ee4b0e-8bde8e4c-e5af41fffdc4fb7a59f7baea"><ac:plain-text-body><![CDATA[ | customFields[].value | String | The value of the custom field |
| ]]></ac:plain-text-body></ac:structured-macro> |
Anchor | ||||
---|---|---|---|---|
|
Server Type | Description |
---|---|
1 | AOL |
2 | Apache/ModSSL |
3 | Apache-SSL (Ben-SSL, not Stronghold) |
4 | C2Net Stronghold |
33 | Cisco 3000 Series VPN Concentrator |
34 | Citrix |
5 | Cobalt Raq |
6 | Covalent Server Software |
7 | IBM HTTP Server |
8 | IBM Internet Connection Server |
9 | iPlanet |
10 | Java Web Server (Javasoft / Sun) |
11 | Lotus Domino |
12 | Lotus Domino Go! |
13 | Microsoft IIS 1.x to 4.x |
14 | Microsoft IIS 5.x and later |
15 | Netscape Enterprise Server |
16 | Netscape FastTrack |
17 | Novell Web Server |
18 | Oracle |
19 | Quid Pro Quo |
20 | R3 SSL Server |
21 | Raven SSL |
22 | RedHat Linux |
23 | SAP Web Application Server |
24 | Tomcat |
25 | Website Professional |
26 | WebStar 4.x and later |
27 | WebTen (from Tenon) |
28 | Zeus Web Server |
29 | Ensim |
30 | Plesk |
31 | WHM/cPanel |
32 | H-Sphere |
-1 | OTHER |
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://ccm.com/api/ssl/v1/enroll/' -i -X POST {color} |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 200 OK |
Anchor | ||||
---|---|---|---|---|
|
Certificate retrieval (collection) of an issued certificate from InCommon CM
Path – /ssl/v1/collect/{sslId}/{formatType}
HTTP Method – POST
Parameter | Description |
sslId | Certificate ID; positive integer value; Minimum value = 1 |
formatType | Format Type for certificate collection.
|
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://ccm.com/api/ssl/v1/collect/582/base64' -i {color} |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 200 OK |
Anchor | ||||
---|---|---|---|---|
|
Generate a request to InCommon CM to revoke a specific TLS/SSL certificate.
Path – /ssl/v1/revoke/{sslId}
HTTP Method – POST
Anchor | ||||
---|---|---|---|---|
|
Parameter | Description |
sslId | Certificate ID; positive integer value; Minimum value = 1 |
Anchor | ||||
---|---|---|---|---|
|
Attribute | Type | Description | Constraints |
reason | String | A short comment as to why the certificate needs to be revoked. | MUST NOT be empty. |
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://ccm.com/api/ssl/v1/revoke/587' -i -X POST {color} |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 204 No Content |
Anchor | ||||
---|---|---|---|---|
|
A function to initiate the renewal of a given certificate using the same CSR and parameters of the existing certificate.
PATH – /ssl/v1/renew/{renewId}
HTTP Method – POST
Anchor | ||||
---|---|---|---|---|
|
Parameter | Type | Max. Length (chars) | Description |
---|---|---|---|
renewId | String | 20 | Returned via the enrollment API call. It is also found in every Enrollment Successful email that InCommon CM sends. |
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://ccm.com/api/ssl/v1/renew/10' -i -X POST {color} |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 204 No Content |
Anchor | ||||
---|---|---|---|---|
|
A function to initiate the renewal of a given certificate using the same CSR and parameters of the existing TLS/SSL certificate.
Path – /ssl/v1/renewById/{sslId}
HTTP Method – POST
Anchor | ||||
---|---|---|---|---|
|
Parameter | Possible value(s) |
---|---|
sslId | Certificate ID; positive integer value; Minimum value = 1 |
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://ccm.com/api/ssl/v1/renew/10' -i -X POST {color} |
Anchor | ||||
---|---|---|---|---|
|
Attribute | Type | Description |
---|---|---|
sslId | Integer | Renewed certificate's identifier. |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 200 OK |
Anchor | ||||
---|---|---|---|---|
|
A function to initiate the replacement (or re-issuance) of a given certificate, based on a unique identifier and a new CSR.
Anchor | ||||
---|---|---|---|---|
|
Parameter | Description |
---|---|
sslId | Certificate ID; positive integer value; Minimum value = 1 |
Anchor | ||||
---|---|---|---|---|
|
Attribute | Type | Description | Constraints |
---|---|---|---|
csr | String | Certificate Signing Request (Base-64 encoded, with or without the: | MUST not be empty or NULL. |
reason | String | A short comment as to why the certificate needs to be replaced (or re-issued). | MUST NOT be empty. |
Anchor | ||||
---|---|---|---|---|
|
$ curl 'https://ccm.com/api/ssl/v1/replace/586' -i -X POST {color} |
Anchor | ||||
---|---|---|---|---|
|
HTTP/1.1 204 No Content |