dynamic-ca-server

Contents

Component description

Dynamic CA server provides REST API that can be used to dynamically create certificate authorities (CAs) with CA certificates signed by the root CA. Newly created CAs can then be used to issue client certificates.

Installation

Prerequisites

  • Apache Tomcat
  • MySQL
  • Java 6

Download and Extract

Download and extract dynamic-ca-server.tar.gz package. Deploy dynamic-ca.war web application to Tomcat server.

Package structure:

/etc/contrail/dynamic-ca-server/
    * dynamic-ca-server.properties
    * rootca-cert.pem
    * rootca-key.pem
/usr/share/contrail/dynamic-ca-server/
    * dynamic-ca-server-schema.sql
/var/lib/tomcat6/webapps/
    * dynamic-ca.war

Create the Database

  1. Create dynamic_ca_server database by importing the script /usr/share/contrail/dynamic-ca-server/dynamic-ca-server-schema.sql.
  2. Create database user and give him appropriate privileges on dynamic_ca_server database.
  3. Open persistence.xml file and enter database connection string, username and password of the database user.

Configuration Files

dynamic-ca-server.properties

File location: /etc/contrail/dynamic-ca-server/dynamic-ca-server.properties

rootca.privateKeyFile=/etc/contrail/dynamic-ca-server/rootca-key.pem
rootca.privateKeyPass=contrail
rootca.certificateFile=/etc/contrail/dynamic-ca-server/rootca-cert.pem
rootca.cert.lifetimeDays=365
rootca.cert.DN=CN=%s,DC=dynamic-ca,DC=contrail-project,DC=eu
dynamicca.cert.vinagent.lifetimeDays=30

persistence.xml

File location: /var/lib/tomcat6/webapps/dynamic-ca/WEB-INF/classes/META-INF/persistence.xml

<properties>
  <property name="eclipselink.cache.shared.default" value="false"/>
  <property name="eclipselink.target-database" value="MySQL"/>
  <property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"/>
  <property name="javax.persistence.jdbc.url" value="jdbc:mysql://localhost/dynamic_ca_server"/>
  <property name="javax.persistence.jdbc.user" value="contrail"/>
  <property name="javax.persistence.jdbc.password" value="contrail"/>
</properties>

web.xml

File location: /var/lib/tomcat6/webapps/dynamic-ca/WEB-INF/web.xml

<context-param>
  <param-name>conf-file</param-name>
  <param-value>/etc/contrail/dynamic-ca-server/dynamic-ca-server.properties</param-value>
</context-param>

log4j.properties

File location: /var/lib/tomcat6/webapps/dynamic-ca/WEB-INF/classes/log4j.properties

log4j.rootCategory=ERROR, R
log4j.logger.org.ow2.contrail=TRACE

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %5p [%t] (%F:%L) - %m%n

log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=/var/log/contrail/dynamic-ca-server.log
log4j.appender.R.MaxFileSize=30MB
log4j.appender.R.MaxBackupIndex=1
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%d{ISO8601} %5p [%t] (%F:%L) - %m%n

REST API

VIN Controllers

/vins

GET

Description:
Returns a list of all registered VIN controllers.

Sample request:
GET https://contrail.xlab.si:8443/dynamic-ca/vins

Sample response:
Status Code: 200 OK
Content-Type: application/json

[
  "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin"
]

POST

Description:
Registers a new VIN controller.

Sample request:
POST https://contrail.xlab.si:8443/dynamic-ca/vins
Content-Type: application/json
{'uid':'myvin'}

Sample response:
Status Code: 201 Created
Location: https://contrail.xlab.si:8443/dynamic-ca/vins/myvin

/vins/{vinUid}

GET

Description:
Returns info about specified VIN controller.

Sample request:
GET https://contrail.xlab.si:8443/dynamic-ca/vins/myvin

Sample response:
Status Code: 200 OK
Content-Type: application/json

{
  "uid" : "myvin",
  "uri" : "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin",
  "cas" : "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas"
}

/vins/{vinUid}/cas

GET

Description:
Returns list of CAs created by the specified VIN controller.

Sample request:
GET https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas

Sample response:
Status Code: 200 OK
Content-Type: application/json

[
  "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca"
]

POST

Description:
Creates a new CA for the specified VIN controller with corresponding private key and certificate signed by the root CA.

Sample request:
POST https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas
Content-Type: application/json
{'uid':'myca'}

Sample response:
Status Code: 201 Created
Location: https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca

Dynamically created CAs

/vins/{vinUid}/cas/{caUid}

GET

Description:
Returns info about specified CA.

Sample request:
GET https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca

Sample response:
Status Code: 200 OK
Content-Type: application/json

{
  "uid" : "myca",
  "uri" : "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca",
  "revocation_list" : "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca/revocation_list",
  "certificate" : "https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca/cert"
}

/vins/{vinUid}/cas/{caUid}/cacert

GET

Description:
Returns certificate of the specified CA encoded in PEM format.

Sample request:
GET https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca/cacert

Sample response:
Status Code: 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE-----
MIIDoDCCAoigAwIBAgIBATANBgkqhkiG9w0BAQUFADBhMRUwEwYKCZImiZPyLGQB
GRYFdXNlcnMxEjAQBgoJkiaJk/IsZAEZFgJjYTEgMB4GCgmSJomT8ixkARkWEGNv
...
-----END CERTIFICATE-----

/vins/{vinUid}/cas/{caUid}/certs

POST

Description:
The client must first create private/public key pair, keeping the private key secret, and certificate signing request (CSR). The CSR should be given in POST body encoded in PEM format. The CA creates a certificate based on the CSR which is digitally signed with the CA private key. The service returns certificate encoded in PEM format.

Post parameters:

  • certificate signing request (CSR) encoded in PEM format

Sample request:
POST https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca/certs
Content-Type: text/plain

-----BEGIN CERTIFICATE REQUEST-----
MIICVzCCAT8CAQAwFDESMBAGA1UEAxMJdmluLWFnZW50MIIBIjANBgkqhkiG9w0B
AQEFAAOCAQ8AMIIBCgKCAQEAhMwmC9PUwpkitDbbzyVxRgkyTtz4dqKFm1XDUhIW
VXZAJ+ehsC8NMjYCzAT/zWgtt9O0lUGILcf4GugpfqsFg2t218XCdTaMYSeVyc3+
pJKp+BUcihsUe2ZI2PZKkASGKHeDJ5absPbStn8jANue3VY0rxyc0Euf2t8XBuPt
d/QsI4vqGGqZ9u4jVjX7KC/UC9NNVD7gcaCMeKuQocS1ZVkEZ4PPTJ5G2ZD43dh6
+8MnRW5cDBV3GwNL+swAUWmPqsJH758UaZeeOTcFwOtjInwNrql5w5AuD3PmbUxx
UxEbESsE+TEUyHlBSrrhBR4/HLONA1HHOcMxd2Xxumjg+wIDAQABMA0GCSqGSIb3
DQEBCwUAA4IBAQAP2cJox5yHhrD3tBkSyjETvQ1DhVRobHv6aeFcChbEHvtt7YWf
/F1EELOcnZYPvgvzRVRGkyKqd+9h9ZfUNRuWWs3nUM+3ueZ2w6MIs5DHFhTHrahn
fl62jO9vWYtun3SkIVJDS9hqn+UNviRJ5sWBvicgebbOJPM86/OmgfIFfZe+lrbJ
MnBrgtU1A7X+quyIVF2FqroZVJ0yI5ZXdysjzKpdmDKpOTAL00VbXemAmbpvEoNM
QLGc5wFAfmiFjdjUcUNIzH4pIkwQD4mHI3BFKDsUiPr9EOulM+WyKsJ/OvFAkTq1
u9bpRdeVB+Oex3bc+2lIY2wIta8lH++oC31o
-----END CERTIFICATE REQUEST-----

Sample response:
Status Code: 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE-----
MIIDWDCCAkCgAwIBAgIBATANBgkqhkiG9w0BAQUFADBhMQ0wCwYDVQQDDARteWNh
MRowGAYKCZImiZPyLGQBGRYKZHluYW1pYy1jYTEgMB4GCgmSJomT8ixkARkWEGNv
bnRyYWlsLXByb2plY3QxEjAQBgoJkiaJk/IsZAEZFgJldTAeFw0xMzA0MjMwODA3
MjVaFw0xNDA0MjMwODE3MjVaMBQxEjAQBgNVBAMMCXZpbi1hZ2VudDCCASIwDQYJ
KoZIhvcNAQEBBQADggEPADCCAQoCggEBAITMJgvT1MKZIrQ2288lcUYJMk7c+Hai
hZtVw1ISFlV2QCfnobAvDTI2AswE/81oLbfTtJVBiC3H+BroKX6rBYNrdtfFwnU2
jGEnlcnN/qSSqfgVHIobFHtmSNj2SpAEhih3gyeWm7D20rZ/IwDbnt1WNK8cnNBL
n9rfFwbj7Xf0LCOL6hhqmfbuI1Y1+ygv1AvTTVQ+4HGgjHirkKHEtWVZBGeDz0ye
RtmQ+N3YevvDJ0VuXAwVdxsDS/rMAFFpj6rCR++fFGmXnjk3BcDrYyJ8Da6pecOQ
Lg9z5m1McVMRGxErBPkxFMh5QUq64QUePxyzjQNRxznDMXdl8bpo4PsCAwEAAaNo
MGYwHwYDVR0jBBgwFoAUdTTQ75mAPR18QkkhzhtatmCtRf0wHQYDVR0OBBYEFN89
zAmjN4NXVQ3lbpWLqsH6hZNOMAwGA1UdEwEB/wQCMAAwFgYDVR0lAQH/BAwwCgYI
KwYBBQUHAwIwDQYJKoZIhvcNAQEFBQADggEBAFexwEmhxTBvCVj6f/9QR/DTwTeg
7tX8Rdc3cni5y++txXQRSw1aHy1/x375RFHfcZu/q42HxPHtKoqbUO3Uq0FzsZ7D
rEBjyfe1RSNbDI/3GIDDPY4DeRAK8BAh9yUp0alknSFxg2CU06BP6Z8Ba5q+8MZy
Hl1Ak3ZThp/b/wj18ZC/cDkeJiLvhtfqzsSDnnP2mqojJbl3KGvTp8o1t8ufibP4
Qbc/T9Z+DojUy3ohAGRZd+ozpHOQCZPIgRVA/hHXHEM9bGxAzldeXoPi18VF1jBU
zmSvWMP3AAeMr+i2/X/WkB85jLZuLtydQK4hAgPs4jyMOaPNg4t/IsPsOdE=
-----END CERTIFICATE-----

/vins/{vinUid}/cas/{caUid}/crl

GET

Description:
Returns certificate revocation list (CRL) for specified certificate authority (CA).

Sample request:
GET https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca/crl

Sample response:
Status Code: 200 OK
Content-Type: application/pkix-crl

<CRL file>

Sample CRL file:
Certificate Revocation List Information
Version: V2
Issuer: DC = eu, DC = contrail-project, DC = dynamic-ca, CN = myca
Effective date: ‎21. ‎maj ‎2013 16:51:36
Next update: ‎22. ‎maj ‎2013 16:51:36
Signature algorithm: sha1RSA
Signature hash algorithm: sha1
CRL Number: 01
Authority Key Identifier:
   KeyID=66 ca dc c6 88 a5 59 12 a9 54 c1 c0 dd 2b e5 ff c7 d3 e4 0f
   Certificate Issuer:
        Directory Address:
             DC=eu
             DC=contrail-project
             DC=ca
             DC=users
   Certificate SerialNumber=01

Revoked certificates
Serial number: 01  Revocation date: ‎21. ‎maj ‎2013 16:51:36
Serial number: 02  Revocation date: ‎21. ‎maj ‎2013 16:52:27

Certificates

/vins/{vinUid}/cas/{caUid}/certs/{sn}

DELETE

Description:
Revokes specified certificate. The revoked certificate will be listed on the certificate revocation list (CRL) of the corresponding CA.
Returns:

  • 204 No Content if the certificate has been successfully revoked
  • 304 Not Modified if the certificate is already revoked

Sample request:
DELETE https://contrail.xlab.si:8443/dynamic-ca/vins/myvin/cas/myca/certs/7

Sample response:
Status Code: 204 No Content