You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »




















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]

Version History

Date

Description

28 January 2018

Initial Release; CCM version 6.0


Introduction

HTTP Methods

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


HTTP Status Codes

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








Errors

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:

Path

Type

Description

code

Number

Error code

description

String

Error message


HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Content-Length: 41
{"code":-16,"description":"Unknown user"}


Authentication

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


Authentication via Username and Password

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:

Authentication via Username and a Client Certificate

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.

The URI for the username/client certificate authentication is:

API Resources

TLS/SSL Certificates

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}

Listing SSL Types

Path – /ssl/v1/types
HTTP Method – GET

Response Attributes

Attribute

Type

Description

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="16d7c114-1da8-45a0-96a3-1aa208ee8c0c"><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="44570056-d8bd-44e4-a8e9-f5fa2d070ecf"><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="a910972e-533d-47ed-b135-987733da0a66"><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="ff3edb7e-bbb1-44e5-96fb-8f4b1efe0791"><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>

Example Request

$ curl 'https://cert-manager.com/api/ssl/v1/types/' -i {color}
-H 'Content-Type: application/json' {color}
-H 'login: forest.gump@university.edu' {color}
-H 'password: RollTide4Jenny' {color}
-H 'customerUri: InCommon'


Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 38

[{"id":

2018,"name":"InCommon SSL"

,"terms":[

365]}]


TLS/SSL Enrollment

Creation and submission of a request for a new TLS/SSL certificate.
Path – /ssl/v1/enroll?
HTTP Method – POST

Request Attributes

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:
----BEGIN xxxxx----
and
----END xxxxx----
header and footer)

MUST not be empty or NULL.
Max size: 32767 characters.

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;
See Server Type table below for acceptable attribute values

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="104ce33f-5e96-44ec-8844-b17375f54aeb"><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="cde12c47-fa33-405b-b47e-7096fd7ea4ae"><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="409c44a0-ecf3-4b0e-8e4c-fb7a59f7baea"><ac:plain-text-body><![CDATA[

customFields[].value

String

The value of the custom field

 

]]></ac:plain-text-body></ac:structured-macro>


Server Type

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




Example Request

$ curl 'https://ccm.com/api/ssl/v1/enroll/' -i -X POST {color}
-H 'Content-Type: application/json' {color}
-H 'login: admin_customer1453' {color}
-H 'password: mLZxWzJh1+DZAPjHgnwzxaU/KVo=' {color}
-H 'customerUri: cst1453' {color}
-d

'{"orgId":766,"csr":"----BEGIN CERTIFICATE REQUEST---\nMIIC4jCCAcoCAQAwdDELMAkGA1UEBhMCVUExDTALBgNVBAgTBHRlc3QxDTALBgNV\nBAcTBHRlc3QxDTALBgNVBAoTBHRlc3QxDTALBgNVBAsTBHRlc3QxEjAQBgNVBAMT\nCWNjbXFhLmNvbTEVMBMGCSqGSIb3DQEJARYGdGVzdEB0MIIBIjANBgkqhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAul8SGkicOnrMjJDvgG8P2j1Ee5hY6ww+qSoe0oI2\ntvRcLBknPHMMAkxTjW9fy80wD8hyrnc+IGlQcq2R/tEMIJHRsJD603M+2FjAwlP9\n8xtiqv0hMyHO4fEt+HMyy8Q367aTBmnZCuAxJZJapfFW9wH5jGZxuX8mnrXVsBTD\n4ZBO4UFd9P4u8P0nJx80CiuDt4COSDl6Br4pNLciPVqfwj7LQ5/skwPkNCggk3/G\nxoQX/3FV7O4fC6WCxVP1uYjJVQjlD1Tf06hPNfonVfThVuP20OL3QAlnIF3lZiyY\nJ5etdFtu+BKcPNMdQDJOS/O4Zz0YJn6K2HdAXSc1YxYniwIDAQABoCkwJwYJKoZI\nhvcNAQkOMRowGDAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4DANBgkqhkiG9w0BAQsF\nAAOCAQEAVJVTTELGHWoRh8JZt+kx/zO0VnibBq/D6uB405L+Ir80X48Ei9hTLB11\nAqhSBE+AbEgBhRnEIDBjiXEDcWvC532Omex721kc17ZTzowuD8lOjfQkTHbAmjIi\nnCQNFAPf0D/zpi6Eync5pi2P//Uj/Yn7oDYYli1t61EZwuQyEu4mbQ1efUnU/SOl\nAAQtDPhNwATZPmfefjM8+YuzhG70dQvmFAClcFayKM92Zx9khDd/VnLT85YzDULJ\n8iiHW8dZNblaTsUjKrc73iX2hONZIxw6B3tGCFs8mH9lZlExV7Y2er3t/lO1pdxe\nSUohEELWcttIxyWnYgxvwaWX4lfx9A\u003d\u003d\n---END CERTIFICATE REQUEST----","subjAltNames":"ccmqa.com","certType":500,"numberServers":0,"serverType":-1,"term":365,"comments":"test","customFields":[{"name":"custom field","value":"custom field value"}]}'


Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 46

{"renewId":"rqSqUt19WVhzmM6-hagZ","sslId":583}










Collect TLS/SSL Certificate

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
Displayed in InCommon CM as 'Self Enrollment Certificate ID'

formatType

Format Type for certificate collection.
Allowed values:

  • 'x509' - for X509, Base64 encoded
  • 'x509CO' - for X509 Certificate only, Base64 encoded
  • 'x509IO' - for X509 Intermediates/root only, Base64 encoded
  • 'x509IOR' - for X509 Intermediates/root only Reverse, Base64 encoded
  • 'base64' - for PKCS#7 Base64 encoded
  • 'bin' - for PKCS#7 Bin encoded

Example Request

$ curl 'https://ccm.com/api/ssl/v1/collect/582/base64' -i {color}
-H 'login: admin_customer1447' {color}
-H 'password: mLZxWzJh1+DZAPjHgnwzxaU/KVo=' {color}
-H 'customerUri: cst1447'


Example Response

HTTP/1.1 200 OK
Content-Type: application/octet-stream
content-disposition: attachment; filename=test.cert







TLS/SSL Certificate Revocation

Generate a request to InCommon CM to revoke a specific TLS/SSL certificate.
Path – /ssl/v1/revoke/{sslId}
HTTP Method – POST

Path Parameters

Parameter

Description

sslId

Certificate ID; positive integer value; Minimum value = 1
Displayed in InCommon CM as 'Self Enrollment Certificate ID'


Request Attributes

Attribute

Type

Description

Constraints

reason

String

A short comment as to why the certificate needs to be revoked.

MUST NOT be empty.
Maximum characters = 512

Example Request

$ curl 'https://ccm.com/api/ssl/v1/revoke/587' -i -X POST {color}
-H 'Content-Type: application/json' {color}
-H 'login: admin_customer1489' {color}
-H 'password: mLZxWzJh1+DZAPjHgnwzxaU/KVo=' {color}
-H 'customerUri: cst1489' {color}
-d '{"reason": "test"}'


Example Response

HTTP/1.1 204 No Content








TLS/SSL certificate renewal by RenewId

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

Path Parameters

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.

Example Request

$ curl 'https://ccm.com/api/ssl/v1/renew/10' -i -X POST {color}
-H 'Content-Type: application/json' {color}
-H 'login: admin_customer1479' {color}
-H 'password: mLZxWzJh1+DZAPjHgnwzxaU/KVo=' {color}
-H 'customerUri: cst1479' {color}
-d '{"renewId": "rqSqUt19WVhzmM6-hagZ"}'


Example Response

HTTP/1.1 204 No Content











TLS/SSL certificate renewal by SSL enrollment ID

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

Path Parameters

Parameter

Possible value(s)

sslId

Certificate ID; positive integer value; Minimum value = 1
Displayed in InCommon CM as 'Self Enrollment Certificate ID'


Example Request

$ curl 'https://ccm.com/api/ssl/v1/renew/10' -i -X POST {color}
-H 'Content-Type: application/json' {color}
-H 'login: admin_customer1479' {color}
-H 'password: mLZxWzJh1+DZAPjHgnwzxaU/KVo=' {color}
-H 'customerUri: cst1479' {color}
-d '{"sslId":5150}'


Response fields

Attribute

Type

Description

sslId

Integer

Renewed certificate's identifier.

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 13

{"sslId":8675309}





TLS/SSL Certificate Replacement

A function to initiate the replacement (or re-issuance) of a given certificate, based on a unique identifier and a new CSR.

Path Parameters

Parameter

Description

sslId

Certificate ID; positive integer value; Minimum value = 1
Displayed in InCommon CM as 'Self Enrollment Certificate ID'

Request Attributes

Attribute

Type

Description

Constraints

csr

String

Certificate Signing Request (Base-64 encoded, with or without the:
----BEGIN xxxxx----
and
----END xxxxx----
header and footer)

MUST not be empty or NULL.
Max size: 32767 characters.

reason

String

A short comment as to why the certificate needs to be replaced (or re-issued).

MUST NOT be empty.
Maximum characters = 512











Example Request

$ curl 'https://ccm.com/api/ssl/v1/replace/586' -i -X POST {color}
-H 'Content-Type: application/json' {color}
-H 'login: admin_customer1483' {color}
-H 'password: mLZxWzJh1+DZAPjHgnwzxaU/KVo=' {color}
-H 'customerUri: cst1483' {color}
-d '{"csr":"----BEGIN CERTIFICATE REQUEST---\nMIIC4jCCAcoCAQAwdDELMAkGA1UEBhMCVUExDTALBgNVBAgTBHRlc3QxDTALBgNV\nBAcTBHRlc3QxDTALBgNVBAoTBHRlc3QxDTALBgNVBAsTBHRlc3QxEjAQBgNVBAMT\nCWNjbXFhLmNvbTEVMBMGCSqGSIb3DQEJARYGdGVzdEB0MIIBIjANBgkqhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAul8SGkicOnrMjJDvgG8P2j1Ee5hY6ww+qSoe0oI2\ntvRcLBknPHMMAkxTjW9fy80wD8hyrnc+IGlQcq2R/tEMIJHRsJD603M+2FjAwlP9\n8xtiqv0hMyHO4fEt+HMyy8Q367aTBmnZCuAxJZJapfFW9wH5jGZxuX8mnrXVsBTD\n4ZBO4UFd9P4u8P0nJx80CiuDt4COSDl6Br4pNLciPVqfwj7LQ5/skwPkNCggk3/G\nxoQX/3FV7O4fC6WCxVP1uYjJVQjlD1Tf06hPNfonVfThVuP20OL3QAlnIF3lZiyY\nJ5etdFtu+BKcPNMdQDJOS/O4Zz0YJn6K2HdAXSc1YxYniwIDAQABoCkwJwYJKoZI\nhvcNAQkOMRowGDAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4DANBgkqhkiG9w0BAQsF\nAAOCAQEAVJVTTELGHWoRh8JZt+kx/zO0VnibBq/D6uB405L+Ir80X48Ei9hTLB11\nAqhSBE+AbEgBhRnEIDBjiXEDcWvC532Omex721kc17ZTzowuD8lOjfQkTHbAmjIi\nnCQNFAPf0D/zpi6Eync5pi2P//Uj/Yn7oDYYli1t61EZwuQyEu4mbQ1efUnU/SOl\nAAQtDPhNwATZPmfefjM8+YuzhG70dQvmFAClcFayKM92Zx9khDd/VnLT85YzDULJ\n8iiHW8dZNblaTsUjKrc73iX2hONZIxw6B3tGCFs8mH9lZlExV7Y2er3t/lO1pdxe\nSUohEELWcttIxyWnYgxvwaWX4lfx9A\u003d\u003d\n---END CERTIFICATE REQUEST----","reason":"test"}'


Example Response

HTTP/1.1 204 No Content
  • No labels