Difference between revisions of "REST"

From Dogtag
Jump to: navigation, search
(REST Interface)
(Notes)
Line 1,262: Line 1,262:
 
| tksGetTokenInfo
 
| tksGetTokenInfo
 
|}
 
|}
 +
 +
= Current Implementation =
 +
 +
Some of the REST interface have been implemented in the following Java interfaces:
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/account/AccountResource.java Accounts]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/cert/CertResource.java Certificates]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/cert/CertRequestResource.java Certificate Resources]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/system/ConfigurationResponse.java Configuration]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/group/GroupResource.java Groups]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/group/GroupMemberResource.java Group Members]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/key/KeyResource.java Keys]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/key/KeyRequestResource.java Key Requests]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/system/KRAConnectorResource.java KRA Connector]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/system/SecurityDomainResource.java Security Domain]
 +
* [http://git.fedorahosted.org/cgit/pki.git/tree/base/common/src/com/netscape/certsrv/system/SystemConfigResource.java System Configuration]
  
 
= Notes =
 
= Notes =

Revision as of 18:44, 12 March 2013

Overview

PKI provides REST interfaces to allow clients to access services on the server. The REST services are implemented using RESTEasy.

Design

The REST interface uses regular HTTP verbs:

  • GET: Fetch data, no side effects
  • POST: create new entries in the namespace
  • PUT: Update entires in the namespace.

In general, POST will not create entries that are active, but will require a further “PUT” to approve. One exception is when agents create and approve certificates in one call. If we continue this approach, we will have to revise the security mechanisms around it, as currently it requires disabling nonces.

All HTTP calls should have return codes defined for expected success and error cases.

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Top Level GET /pki top level services; caindex kraindex; services service; ocspindex services

Controller Objects

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Controller Objects GET /pki/token/sessionKey Calculate token session key material tksSessionKey
GET /pki/token/diversifiedKey Calculate upgraded key set data for token symmetric key changeover tksCreateKeySetData
GET /pki/token/encryptedData Calculate encrypted block of data tksEncryptData
GET /pki/token/randomData Calculate random block of data of given size tksRandomData

Certificates

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"


Certificates GET /pki/certificates Get list of certificates caSrchCerts-agent; caListCerts-agent;caSrchCert; caSrchRevokeCert; caSrchCerts; caListCerts
/pki/certifcate/$id/details Get certifcate details caDisplayCertFromRequest-agent; caDisplayBySerial-agent; caDisplayCertFromRequest; caDisplayBySerial
POST-b /pki/certificate/ocsp Get OCSP response caOCSP ocspCheckCert; ocspReadCheckCertPage
GET /pki/certificate/$id Get certifcate caGetAdminCertBySerial; caGetCertChain; caGetCertChainAdmin; caGetCertFromRequest-agent;caGetBySerial-agent; caQueryBySerial; caGetBySerial; caGetAdminBySerial; caGetCAChain; caGetCertFromRequest

Certificate Status

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Certificate Status PUT /pki/certificate/$id/status Modify certificate status - revoke; unrevoke caDoUnrevoke; caDoRevoke-agent; caDoRevoke1; caDoRevoke1; caCMCRevReq; caDoUnrevoke1; caRevocation; caDoRevoke; caProxyDoRevoke
GET /pki/certificate/$id/status Get certificate status

Certificate Requests

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Cert Requests GET /pki/requests Get list of requests caListRequests; caSearchReqs
GET /pki/request/$id Get request details caqueryReq; caCheckRequest
POST-a /pki/request Add a request caProfileSubmit; caenrollment;cacertbasedenrollment; caProfileSubmitCMCSimple; profileSubmitCMCFull; caProfileSubmitSSLClient; caProxyProfileSubmit; cabulkissuance; caProxyBulkIssuance; caRenewal; caSCEP; caRASCEP
PUT /pki/request/$id Modify a request - if a request is not approved an agent can modify it before approving. caProfileProcess; caProcessCertReq; caProcessReq

Certificate Request Status

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Cert Request Status PUT /pki/request/$id/status Modify request status - approve; deny etc; caProfileProcess; caProcessCertReq; caProcessReq
GET /pki/request/$id/status Get request status caCheckRequest

Certificate Profiles

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Cert profiles GET /pki/profiles Get list of profiles caProfileList-agent; caProfileList
GET /pki/profile/$id Get profile details caProfileReview; caProfileSelect-agent; caProfileSelect; caSCEP; caRASCEP
PUT /pki/profile/$id Add or modify profile caprofile; caProfileApprove
DEL /pki/profile/$id Delete a profile caprofile

Certificate Revocation List

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Cert CRLs GET /pki/crls Get list of CRLs None
GET /pki/crl/details Get CRL details camasterCADisplayCRL ocspReadAddCRLPage
GET /pki/crl Get CRL caGetCRL
PUT /pki/crl Add a CRL ocspAddCRL
POST-b /pki/crl Modify a CRL camasterCAUpdateCRL
DEL /pki/crl Delete a CRL

CA for OCSP

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"


CAs (for OCSP) GET /pki/ocsp/cas Get list of CAs ocspListCAs
GET /pki/ocsp/ca/$id Get CA details ocspReadAddCAPage
PUT /pki/ocsp/ca/$id Add or modify a CA ocspAddCA
DEL /pki/ocsp/ca/$id Delete a CA ocspRemoveCA

Keys

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
keys GET /pki/keys Get list of keys kraSrchKey; kraKRASrchKey; kraKRASrchKeyForRecovery; kraSrchRecoverKey
GET /pki/key/$id Get key kraKRAGetPk12; kraKRAGetAsyncPk12
GET /pki/key/$id/details Get key details kraKRADisplayBySerialForRecovery; kraKRADisplayBySerial
PUT /pki/key/$id Add a key

Key Requests

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
key requests (archival; recovery; keygen) GET /pki/keyrequests Get list of key requests kraListRequests; krakraqueryReq
GET /pki/keyrequest/$id Get key request details kraKRAGetApprovalStatus; kraKRAExamineRecovery;
POST-a /pki/keyrequest/archive Add a key archival request kraConnector
POST-a /pki/keyrequest/recovery Add a key recovery request(async) kraKRARecoverBySerial; tokenKeyRecovery
POST-a /pki/keyrequest/generate Add a request to generate a key pair. Return key pair and optionally archive it. GenerateKeyPairServlet

Key Request Status

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Key request Status PUT /pki/keyrequest/$id/status Modify a key request status (approve async recovery) kraKRAGrantRecovery; kraKRAGrantAsyncRecovery; kraKRAProcessReq; kraGrantRecovery;
GET /pki/keyrequest/$id/status Get key request status
DEL /pki/keyrequest/$id Delete a key request None

Users

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
users GET /pki/users Get list of users caug kraug ocspug tksug
GET /pki/user/$id Get user details caug kraug ocspug tksug
PUT /pki/user/$id Add or modify a user caug; caRegisterUser; caRegisterRaUser; caAdminEnroll kraRegisterUser; kraug ocspug tksug; tksRegisterUser
DEL /pki/user/$id Delete a user caug kraug ocspug tksug

System

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
System GET /pki/X/status Get subsystem status caGetStatus
GET /pki/X/stats Get subsystem stats caStats
GET /pki/X/monitor Get subsystem monitor stats caMonitor
GET /pki/X/logs Get list of logs for subsystem calog kralog ocsplog tkslog
GET /pki/X/log/$id Get log contents calog kralog ocsplog tkslog

Config

"Objects" "Operation" "REST Path" "Description" "Mapped Servlets (CA)" "Mapped Servlets (KRA)" "Mapped Servlets(OCSP)" "Mapped Servlets (TKS)"
Config
GET /pki/config/X/acls Get list of acls caacl kraacl ocspacl tksacl
GET /pki/config/X/acl/$id Get acl details caacl kraacl ocspacl tksacl
PUT /pki/config/X/acl/$id Add or modify an acl caacl kraacl ocspacl tksacl
DEL /pki/config/X/acl/$id Delete an acl caacl kraacl ocspacl tksacl
GET /pki/config/X/logs Get list of logs calog kralog ocsplog tkslog
GET /pki/config/X/log/$id Get log details calog kralog ocsplog tkslog
PUT /pki/config/X/log/$id Add or modify a log configuration calog kralog ocsplog tkslog
DEL /pki/config/X/log/$id Delete an log configuration calog kralog ocsplog tkslog
GET /pki/config/ca/systems Get list of systems from security domain caGetDomainXML
GET /pki/config/ca/system/$id Get system details from sec domain None as yet
PUT /pki/config/ca/system/$id Add or modify a system in security domain caUpdateDomainXML
DEL /pki/config/ca/system/$id Delete an system from security domain caUpdateDomainXML
GET /pki/config/ca/publishers Get list of publishers capublisher
GET /pki/config/ca/publisher/$id Get publisher details capublisher
PUT /pki/config/ca/publisher/$id Add or modify a publisher capublisher
DEL /pki/config/ca/publisher/$id Delete a publisher capublisher
GET /pki/config/X/jobs Get list of jobs cajobsScheduler krajobsScheduler ocspjobsScheduler tksjobsScheduler
GET /pki/config/X/job/$id Get job details cajobsScheduler krajobsScheduler ocspjobsScheduler tksjobsScheduler
PUT /pki/config/X/job/$id Add an job cajobsScheduler krajobsScheduler ocspjobsScheduler tksjobsScheduler
DEL /pki/config/X/job/$id Delete an job cajobsScheduler krajobsScheduler ocspjobsScheduler tksjobsScheduler
GET /pki/config/X/auths Get list of authentication plugins caauths kraauths ocspauths tksauths
GET /pki/config/X/auth/$id Get authentication plugin details caauths kraauths ocspauths tksauths
PUT /pki/config/X/auth/$id Add or modify an authentication plugin caauths kraauths ocspauths tksauths
DEL /pki/config/X/auth/$id Delete an authentication plugin caauths kraauths ocspauths tksauths
GET /pki/config/X/certs Get list of system_certs caserver kraserver ocspserver tksserver
GET /pki/config/X/cert/$id Get system_cert caGetSubsystemCert kraGetTransportCert
GET /pki/config/X/cert/Y/details Get system_cert details caserver kraKRADisplayTransport; kraserver ocspserver tksserver
PUT /pki/config/X/cert/$id Add an system_cert caserver kraserver ocspserver tksserver; tksImportTransportCert
DEL /pki/config/X/cert/$id Delete an system_cert caserver kraserver ocspserver tksserver
GET /pki/config/X/serialnos/$id Get serial number range None as yet None as yet
PUT /pki/config/X/serialnos/$id Update serial number range caUpdateNumberRange kraUpdateNumberRange
GET /pki/config/X/connector/$id Get connector config kraConnector
PUT /pki/config/X/connector/$id Add or modify connector config caUpdateConnector
GET /pki/config/X/ocsp Get ocsp config caGetOCSPInfo ocspGetOCSPInfo
PUT /pki/config/X/ocsp Modify ocsp config caUpdateOCSPConfig
GET /pki/config/X/cloning Get cloning config caGetConfigEntries kraGetConfigEntries ocspGetConfigEntries tksGetConfigEntries
GET /pki/config/X/tokeninfo Get token info (for cloning) caGetTokenInfo kraGetTokenInfo ocspGetTokenInfo tksGetTokenInfo

Current Implementation

Some of the REST interface have been implemented in the following Java interfaces:

Notes

  1. Version 0.4
  2. There is still misc admin that has not yet been characterized. This is in in caca; caregistry; krakra; ocspocsp; tkstks servlets -which map to the admin servlet.
  3. Wizard and installation servlets are not covered (for the most part).
  4. We need to figure out how to handle client-auth vs. non-clientauth - which maps to ee/agent/admin. Currently we do this by filtering urls.
  5. This is just a first cut - and hopefully a useful starting point for discussions
  6. We need to revisit POST-b in CRLs

Links