Web Service Interface

Introduction

The JAX-WS 2.0 Web Service Interface is used to access the basic functions remotely over client authenticated HTTPS. The functionality available through the Web Service Interface is documented in the EJBCA Web Service API Reference.

There is also a CLI that can be used for scripting WS calls remotely, see Using the Web Services CLI. Note that all web service calls are not available through the CLI.

Web Services through the RA

Using a Peer Connected RA it is possible to run a subset of WS API calls through the RA, which is tried to be executed on the CA first after polling by the CA using Peer Connectors. If the RA itself has active CAs the RA tries to process the requests first local, if not marked otherwise in the list below.

Local key generation and recovery is processed on the RA in every case (see function 'keyRecover').

Role configuration for the user of the WS API is done on the CA, and WS must be enabled in the role used by the Peer Connection for the RA. On the RA it is possible to disable WS in System Configuration.

The subset of API calls available through the RA are:

  • certificateRequest

  • checkRevokationStatus (anytime tried to be processed on the CA first)

  • crmfRequest

  • customLog

  • cvcRequest

  • editUser (anytime tried to be processed on the CA first)

  • findCerts

  • findUser

  • getAvailableCAs

  • getAvailableCAsInProfile

  • getAvailableCertificateProfiles

  • getCertificate

  • getCertificatesByExpirationTime

  • getCertificatesByExpirationTimeAndIssuer

  • getCertificatesByExpirationTimeAndType

  • getLastCAChain

  • getLastCertChain

  • getLatestCRL

  • getProfile

  • getPublisherQueueLength

  • getRemainingNumberOfApprovals

  • isApproved

  • isAuthorized

  • keyRecover (local keystore generation or recovery only processed on the RA)

  • pkcs10Request

  • pkcs12Req

  • republishCertificate

  • revokeCert (anytime tried to be processed on the CA first)

  • revokeCertBackdated (anytime tried to be processed on the CA first)

  • revokeCertWithMetadata (anytime tried to be processed on the CA first)

  • revokeUser

Web Services Authentication

The Web Services interface requires client certificate authentication from administrators, in the same way as the Admin GUI does. If you have a client certificate that works on the Admin GUI, you should also be able to use it for the Web Service interface.

Configuring Web Services Behavior

The sample property file conf/jaxws.properties.sample contains more information on how to configure the behavior of the EJBCA WS. Copy this to conf/jaxws.properties, edit and redeploy.

If the end entity profile information must be used to define default values when you create a user, the flag Allow merge DN Webservices must be checked in the end entity profile.

If multiple instances of a component exist, the merge is done from end to beginning, and the remaining values of this component type will be placed at the end.

For example, if you want to merge:

dn=cn=foo,..., dc=dc1, ..., dc=dc2, ...

with

dn=..., dc=mdc1, ..., dc=mdc2, ..., dc=mdc3, ...

the result will be:

dn=cn=foo, ..., dc=mdc1, ..., dc=mdc2, ..., dc=mdc3, ...

Configuring Web Services CLI

Edit the dist/ejbca-ws-cli/ejbcawsracli.properties before running the EJBCA WS CLI. The files contain descriptions of what can be configured. Note that this directory is recreated each time you build EJBCA, so copy it to a separate location if you intend to rebuild or redeploy EJBCA and keep the configuration.

Configuration for the Web Services CLI requires a P12 or JKS keystore. You can try the WS CLI using the superadmin.p12 keystore generated during the installation or generate a new JKS using the Admin GUI.

To create a JKS for a user using the command line, and adding the new user to the superadministrator role, run the following:

bin/ejbca.sh ra addendentity <1> <2> "C=..,O=..,CN=<1>" ManagementCA 1 JKS
bin/ejbca.sh ra setclearpwd <1> <2>
bin/ejbca.sh batch <1>
bin/ejbca.sh roles addmember "Temporary Super Administrator Group" ManagementCA WITHCOMMONNAME EQUALCASEINS <1>

Using the Web Services CLI

The EJBCA Client Toolbox includes a Web Service CLI tool.

To use the Web Service CLI client, copy the directory with all included files to the computer you want to remotely administer from. Then create a JKS or P12 file with the appropriate access rights (see Access rules required when using the Web Service API), and finally configure the file ejbcawsracli.properties. In this file you should specify the hostname of the CA server, the name of the keystore and the password to unlock it. Documentation for each setting is in the file ejbcacsracli.properties.

To list each sub-command, run ejbcaClientToolBox.sh EjbcaWsRaCli.

To view detailed help on using the CLI, run ejbcaClientToolBox.sh EjbcaWsRaCli "subcommand".

Example usage:

ejbcaClientToolBox.sh EjbcaWsRaCli pkcs12req testuser2 foo123 2048 NONE tmp
ejbcaClientToolBox.sh EjbcaWsRaCli revokeendentity testuser2 SUPERSEDED fals

Using the Web Service API for Integration

You can use the Web Service interface to integrate EJBCA from other applications.

If you are using another language than Java, start by downloading the WSDL file at http://hostname:8080/ejbca/ejbcaws/ejbcaws?wsdl. With this you can use your programming language tools to generate client stubs.

When using Java you can find the required libs in dist/ejbcawscli and its lib subdirectory.

To initialize the Web Service:

CryptoProviderTools.installBCProvider();
String urlstr = "https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl";
System.setProperty("javax.net.ssl.trustStore","p12/wstest.jks");
System.setProperty("javax.net.ssl.trustStorePassword","foo123");
System.setProperty("javax.net.ssl.keyStore","p12/wstest.jks");
System.setProperty("javax.net.ssl.keyStorePassword","foo123");
QName qname = new QName("http://ws.protocol.core.ejbca.org/", "EjbcaWSService");
EjbcaWSService service = new EjbcaWSService(new URL(urlstr),qname);
ejbcaraws = service.getEjbcaWSPort();

Example call to find all users having 'Smith' in their subject dn:

UserMatch usermatch = new UserMatch();
usermatch.setMatchwith(UserMatch.MATCH_WITH_DN);
usermatch.setMatchtype(UserMatch.MATCH_TYPE_CONTAINS);
usermatch.setMatchvalue("Smith");
List<UserDataVOWS> result = ejbcaraws.findUser(usermatch);

Example generating a certificate from a PKCS10 request:

UserDataVOWS user1 = new UserDataVOWS();
user1.setUsername("WSTESTUSER1");
user1.setSubjectDN("CN=WSTESTUSER1");
user1.setCaName("ManagementCA");
user1.setEmail(null);
user1.setSubjectAltName(null);
user1.setEndEntityProfileName("EMPTY");
user1.setCertificateProfileName("ENDUSER");
KeyPair keys = KeyTools.genKeys("2048", AlgorithmConstants.KEYALGORITHM_RSA);
PKCS10CertificationRequest pkcs10 = new PKCS10CertificationRequest("SHA256WithRSA",
CertTools.stringToBcX500Name("CN=NOUSED"), keys.getPublic(), null, keys.getPrivate());
 
CertificateResponse certenv = ejbcaraws.certificateRequest(user1,
CertificateHelper.CERT_REQ_TYPE_PKCS10,
new String(Base64.encode(pkcs10.getEncoded())),
null, CertificateHelper.RESPONSETYPE_CERTIFICATE);
X509Certificate cert = certenv.getCertificate();

Example checking the revocation status of a certificate:

RevokeStatus revokestatus = ejbcaraws.checkRevokationStatus(cert.getIssuerDN.toString,cert.getSerialNumber().toString(16));
if(revokestatus != null){
if(revokestatus.getReason() != RevokeStatus.NOT_REVOKED)){
// Certificate is revoked
}else{
// Certificate isn't revoked
}
}else{
// Certificate doesn't exist
}

Developing against the Web Service SOAP API

The SOAP API is compatible with all development languages that can handle SOAP messages. This includes programming languages such as Java, C# and PHP. The normal approach is to use your programming languages tools to generate client stubs, which are classes to be used in your client program. For Java, such stub classes are already included as part of the clientToolBox WS client provided.

Client stubs are generated from the WSDL file, which includes all information to use the WS API. The WSDL can be accessed from your installed EJBCA at https://localhost:8443/ejbca/ejbcaws/ejbcaws?wsdl. In the WSDL all methods and parameters are described, but without detailed documentation. For example, the following is described in the WSDL for the getProfile method:

<xs:complexType name="getProfile">
<xs:sequence>
<xs:element name="arg0" type="xs:int"/>
<xs:element minOccurs="0" name="arg1" type="xs:string"/>
</xs:sequence>
</xs:complexType>

There are two parameters to the method arg0 that is an integer and arg1 that is a string. The Javadoc WS API documentation contains detailed descriptions of the arguments, see WS API documentation and specifically EjbcaWS.

The API documentation covers methods for the parameters, return value, privileges needed to use the method (based on the TLS client certificate), and errors that can occur, returned as SOAP error classes. For example, the following is documented for the getProfile method:

Parameters:
profileId - ID of the profile we want to retrieve.
profileType - The type of the profile we want to retrieve. 'eep' for End Entity Profiles and 'cp' for Certificate Profiles
Returns:
a byte array containing the specified profile in XML format

Now you can use your client stubs, in your preferred programming language, to call the WS SOAP getProfile method with an integer and a string parameter, getting back a profile in XML format.

Sample Code

See the file modules/ejbca-ws/src/org/ejbca/core/protocol/ws/common/IEjbcaWS for more detailed instructions of the API. Sample code can be taken from:

Accessrules Required when Using the Web Service API

All the calls require HTTPS client authentication. The keystore used must be set up as a regular administrator and access rules according to the following:

Common for all calls (except isAuthorized, existsHardToken, isApproved that only needs a valid trusted certificate):

  • /administrator

  • /ca/'related CA'

editUser:

  • /ra_functionality/create_end_entity and/or edit_end_entity

  • /ra_functionality/'end entity profile of user'/create_end_entity and/or edit_end_entity

findUser, findCert:

  • /ra_functionality/view_end_entity

  • /ra_functionality/'end entity profile of the user'/view_end_entity

pkcs10Request, pkcs12req:

  • /ra_functionality/view_end_entity

  • /ra_functionality/edit_end_entity (only required for non key recovery)

  • /ra_functionality/keyrecovery (only required for key recovery)

  • /ra_functionality/'end entity profile of the user'/view_end_entity

  • /ra_functionality/'end entity profile of the user'/keyrecovery (only required for key recovery)

  • /ra_functionality/'end entity profile of the user'/keyrecovery (only required for non key recovery)

  • /ca_functionality/create_certificate

certificateRequest, softTokenRequest:

  • /ra_functionality/create_end_entity and/or edit_end_entity

  • /ra_functionality/'end entity profile of user'/create_end_entity and/or edit_end_entity

  • /ca_functionality/create_certificate

revokeCert, revokeToken: These calls support approvals.

  • /ra_functionality/revoke_end_entity

  • /ra_functionality/'end entity profile of the user owning the cert'/revoke_end_entity

revokeUser: This call support approvals.

  • /ra_functionality/revoke_end_entity

  • /ra_functionality/'end entity profile of the user'/revoke_end_entity

  • /ra_functionality/delete_end_entity (only if users should be deleted)

  • /ra_functionality/'end entity profile of the user'/delete_end_entity (only if users should be deleted)

fetchUserData: It is possible to turn of authorization of this call in the jaxws.properties

  • /userdatasourcesrules/'user data source'/fetch_userdata

genTokenCertificate: Important this call also supports approvals, and the default behaviour is when someone without the '/administrator' access is creating a call then will a GenerateTokenApprovalRequest be created. This behaviour can be turned off in the jaxws.properties file.

  • /ra_functionality/create_end_entity and/or edit_end_entity

  • /endentityprofilesrules/'end entity profile of user'/create_end_entity and/or edit_end_entity

  • /ra_functionality/revoke_end_entity (if overwrite flag is set)

  • /endentityprofilesrules/'end entity profile of user'/revoke_end_entity (if overwrite flag is set)

  • /ca_functionality/create_certificate

  • /ca/'ca of all requested certificates'

  • hardtoken_functionality/issue_hardtokens

getHardTokenData: Important this call also supports approvals, and the default behaviour is when someone without the '/administrator' access is creating a call then will a ViewHardTokenApprovalRequest be created. This behavior can be turned off in the jaxws.properties file.

  • /ra_functionality/view_hardtoken

  • /endentityprofilesrules/'end entity profile of user'/view_hardtoken

  • /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)

getHardTokenDatas:

  • /ra_functionality/view_hardtoken

  • /endentityprofilesrules/'end entity profile of user'/view_hardtoken

  • /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)

republishCertificate:

  • /ra_functionality/view_end_entity

  • /endentityprofilesrules/'end entity profile of the user'/view_end_entity

  • /endentityprofilesrules/'end entity profile of user'/view_hardtoken/puk_data (if viewPUKData = true)

customLog: No CA access rule is required.

  • /secureaudit/log_custom_events (must be configured in advanced mode when editing access rules)

deleteUserDataFromSource:

  • /userdatasourcesrules/'user data source'/remove_userdata (for all the given user data sources)

getCertificate: no requirement of the '/administrator' flag

  • /ca_functionality/view_certificate

caCertResponse, caRenewCertRequest:

  • /ca_functionality/renew_ca

createCryptoToken (Available in Enterprise Edition only):

  • /cryptotoken/modify

generateCryptoTokenKeys (Available in Enterprise Edition only):

  • /cryptotoken/keys/generate/'related CryptoToken'

createCA (Available in Enterprise Edition only):

  • /

addSubjectToRole, removeSubjectFromRole (Available with Enterprise Edition only):

  • /ca/'related CAs (All the CAs that issued the certificates of every member in the the related role)'

  • /system_functionality/edit_administrator_privileges

getCertificatesByExpirationTime, getCertificatesByExpirationTimeAndIssuer, getCertificatesByExpirationTimeAndType:

  • No other access rules are required

Error codes on Web Services

Business error code have been added in order to discriminate exception of type EjbcaException.

The following code sample shows how to use error codes :

try {
ejbcaraws.editUser(user1);
} catch(EjbcaException_Exception e) {
if(org.cesecore.ErrorCode.CERT_PROFILE_NOT_EXISTS.getInternalErrorCode().equals(e.getFaultInfo().getErrorCode().getInternalErrorCode())) {
log.error("No such certifcate profile.");
}
}

The error codes are described in org.cesecore.ErrorCode and src/test/org/ejbca/core/protocol/ws/CommonEjbcaWSTest.java.

WS Transaction Logging

WS transaction logging is performed in a similar way as the logging for the OCSP responder, see OCSP Audit and Account Logging.

Note however that different tags are used:

  • LOG_TIME: The time the call took place

  • SESSION_ID: A random 32 Byte long String generated when the OCSP-responder is started.

  • LOG_ID: An integer identifying that starts from 1 and is increased for every received request.

  • REPLY_TIME: The time it took to return from the WS method.

  • METHOD: Name of the called WS method.

  • ERROR_MESSAGE: An error message with information of the error. If the call returned successfully then 'NO_ERROR'.

  • ADMIN_DN: Subject DN for the client certificate in the call.

  • ADMIN_ISSUER_DN: Issuer DN of the client certificate in the call

The configuration is specified in conf/jaxws.properties. In the JBoss logger configuration, use org.ejbca.core.protocol.ws.logger.TransactionLogger as category name for the appender.

Example sections for a JBoss standalone.xml to enable WS transaction logging:

<size-rotating-file-handler name="WSTRANS" autoflush="true">
<formatter>
<named-formatter name="PATTERN"/>
</formatter>
<file relative-to="jboss.server.log.dir" path="wstrans.log"/>
<rotate-size value="100M"/>
<max-backup-index value="10"/>
<append value="true"/>
</size-rotating-file-handler>
 
<logger category="org.ejbca.core.protocol.ws.logger.TransactionLogger">
<level name="DEBUG"/>
<handlers>
<handler name="WSTRANS"/>
</handlers>
</logger>

WS Message Debugging

It is recommended to log the SOAP messages to facilitate debugging, by adding the following to JAVA_OPTS:

-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true

In JBoss 7/EAP6/WildFly 9 and 10, this can be done by adding the above line to JAVA_OPTS in JBOSS_HOME/bin/standalone.conf.