Certificate Manager REST API

Middleware provides a read interface to the Certificate Manager via a REST API located at https://certs.it.vt.edu/api/v1.

REST API Client Example

The following code sample in Python provides a simple but complete usage overview that covers authentication and reading data:

import jwt
import os
import sys
import time
import requests

# Token validity period in hours
# Set to 0 to produce a token that never expires (not recommended)
VALIDITY_PERIOD=12

if len(sys.argv) < 3:
  print ("USAGE: ed-service /path/to/private.key")
  sys.exit(0)

issuer = sys.argv[1]
key_path = sys.argv[2]

with open(key_path, 'r') as f:
  key = f.read()

# Create authentication token that is valid for VALIDITY_PERIOD hours
now = int(time.time())
claims = {}
claims['iss'] = 'uusid={0},ou=services,dc=vt,dc=edu'.format(issuer)
claims['sub'] = 'uusid={0},ou=services,dc=vt,dc=edu'.format(issuer)
claims['iat'] = now
claims['exp'] = now + VALIDITY_PERIOD * 60 * 60
token = jwt.encode(claims, key, algorithm='RS256')

# Base URL to Certificate Manager Web services
base_url = 'https://certs.it.vt.edu/api/v1'

# Set up HTTP headers to pass the authentication token
# MUST pass these headers with all requests
headers = {'Authorization': 'Bearer ' + token.decode("utf-8")}

# Query for certs requested by waconley
response = requests.get(base_url + '/certs?by=username&keyword=waconley', headers=headers)
certs = response.text
print (certs)

Prequisites

There are a couple prerequisites that prospective clients need to consider before attempting to consume the REST API.

Enterprise Directory Service

An ED Service provides the security principal and credential to invoke REST API operations. An ED service is typically credentialed with an X.509 certificate issued by the Middleware CA, but may also have a password credential issued under approved circumstances (see below).

Request an ED Service.

or

Personal Digital Certificate (PDC)

A PDC may also provide the security credential to invoke the REST API endpoints.

Request a PDC.

Authorization to Invoke REST API

An authenticated user must be entitled to invoke various REST API operations. The entitlement structure is rest/search and is owned by the certs service.

Conventions

The following conventions are intended to facilitate using the API. We recommend committing these conventions, which we have found improves users’ ability to anticipate URIs and JSON document field names.

URI Naming Conventions

1. Resource URIs are named with a plural resource collection, for example, /v1/certs?[by=x&keyword=y] .

Authentication

Two authentication methods are supported:

1. HTTP Bearer token authentication via ED service signed JWT
2. HTTP Bearer token authentication via PDC signed JWT

HTTP Bearer Auth

The HTTP Bearer token authentication method provides the best balance of security and usability to clients:

1. Strong security via digital signatures
2. Excellent cross-platform support
3. Precise control over token validity period
4. Suitability for use with Javascript-based Web applications

A signed JSON Web Token (JWT) provides most of the advantages above and is simply a JSON document that is prepended with a digital signature algorithm header and to which a digital signature is appended; all parts are base-64 encoded.

Claims should mirror the following: For an ED service:

{
  "iss": "uusid=vt-service,ou=services,dc=vt,dc=edu",
  "sub": "uusid=vt-service,ou=services,dc=vt,dc=edu",
  "iat": 1476180159,
  "exp": 1476181959
}

For a PDC:

{
  "sub": "uupid=vt-username,ou=people,dc=vt,dc=edu",
  "iat": 1476180159,
  "exp": 1476181959
}

The fields of the JSON document follow an established vocabulary called claims, of which three are recognized for Certificate Manager Web services:

1. iss - REQUIRED DN of the service/person
2. sub - REQUIRED DN of the service/person
3. iat - REQUIRED creation (Issued At) date of token
4. exp - REQUIRED expiration date of token

The token MUST be signed with the private key corresponding to a valid (e.g. not expired) ED service certificate and whose service exists and is active in the Enterprise Directory. The signature MUST be produced using the RS256 algorithm.

In general JWT bearer tokens MUST NOT be shared since a bearer token is by nature a self-contained authentication token; whoever bears the token may authenticate and access services as the principal identified in the token.

Certs Resource

The certs resource provides information about a certificate and a subset of requests data for that certificate. Searches “by” cn, username, email, and serial are supported. Examples:

• by=cn&keyword=vt.edu
• by=username&keyword=waconley
• by=email&keyword=waconley@vt.edu
• by=serial&keyword=1A2B3C4D5F

# Resource URI: /v1/certs?by=x&keyword=y
[ 
   { 
      "encoded":"",
      "subject":"",
      "serial":"",
      "status":"",
      "notBefore":"",
      "notAfter":"",
      "request":{ 
         "email":"",
         "commonName":"",
         "subjectAltNames":[ 
         ]
      }
   }
]