emCA API

This section provides the procedure for emCA API deployment and configuration. emCA API (emcaServices) provides an open API (Application Programming Interface) for integrating certificate services with third-party applications and devices. emCA API supports REST in JSON format. emCA APIs are light weight and flexible.

Following are the methods that are supported by emCA API. This includes:

createX509Certificate( )
createSoftTokenCert( )
getX509Certificate( )
revokeX509Cert( )
verifysignature( )
suspendCert()
reinstateCert()
rekey()

Configuration

Note: All actions required for setting up and configuring emCA should be done using administrator privileges.

Environment Variables

For Application.properties

This file is used to configure database-related properties like dialect, driver class name, URL, Username, password (database user should have full privilege to the schema created for emCA application) as well as logs.

For Windows

Configure the property file path in environment variables as shown in below figure .

Variable name: EMCA_SERVICES_CONFIGURATION_PATH

Variable value: location of property files (application.properties)

For Linux

For setting environment variable in Linux, run following command.

sudo -H gedit /etc/environment

It will open the environment folder and set the emCA and emCA Services path inside the folder.

EMCA_SERVICES_CONFIGURATION_PATH for application.properties file as shown in the below figure.

Once the Environment variable is set for application.properties, the user can open the application.properties to configure various options which includes configuring of database as well as logs.

Snapshot

Please find below is the application.properties file snapshot for reference:

#server.port=9009
# ===============================
# = DATA SOURCE
# ===============================

# Set configurations here for database connection

# Connection url for the database "netgloo_blog"
spring.datasource.url=jdbc:mysql://localhost:3306/emca
spring.datasource.username=root
spring.datasource.password= nNh0bStJeJxo3eu3taSY2Q==
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL5Dialect
#spring.datasource.hikari.jdbc-url=jdbc:mysql://localhost:3306/emca
#spring.datasource.hikari.idleTimeout=10
#spring.datasource.hikari.maximumPoolSize=10
#spring.datasource.hikari.minimumIdle=15
#spring.datasource.hikari.dataSourceClassName=com.#mysql.jdbc.jdbc2.optional.MysqlDataSource

spring.mvc.view.prefix= /WEB-INF/jsps/
spring.mvc.view.suffix= .jsp

#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL5Dialect
#spring.jpa.hibernate.ddl-auto=update
#spring.datasource.hikari.connectionTimeout=30000
#spring.datasource.hikari.idleTimeout=600000
#spring.datasource.hikari.maxLifetime=1800000
spring.datasource.type=com.zaxxer.hikari.HikariDataSource
#maximum number of milliseconds that a client will wait for a connection
spring.datasource.hikari.connection-timeout = 300000
#minimum number of idle connections maintained by HikariCP in a connection pool
spring.datasource.hikari.minimum-idle= 10
#maximum pool size
spring.datasource.hikari.maximum-pool-size= 60 
#maximum idle time for connection
spring.datasource.hikari.idle-timeout=1000
# maximum lifetime in milliseconds of a connection in the pool after it is closed.
spring.datasource.hikari.max-lifetime= 100
#default auto-commit behavior.
spring.datasource.hikari.auto-commit =true 
#
spring.datasource.hikari.leakDetectionThreshold=20000
## Naming strategy
#spring.jpa.hibernate.naming-strategy = org.hibernate.cfg.ImprovedNamingStrategy

# Allows Hibernate to generate SQL optimized for a particular DBMS
spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl

spring.jpa.properties.hibernate.current_session_context_class=org.springframework.orm.hibernate5.SpringSessionContext

#Profile location and name
#certificateProfilesPath= C:/emCA/Certificate Profiles
#profileName = User prof

#output to a temp_folder/file
logFilePath=C:/emCA/emCAProperties/log4j.xml

#SCEP Properties
#scep.certificate.create.url = http://localhost:8080/SpringBootRestApi/api/scepX509CertRequest/
#scep.certificate.profile.name = raca
#scep.registered.ext.app.name = raca
#scep.registered.ext.app.pwd = raca
#scep.registered.ext.app.credentials = raca|raca
 
soap.wsdlPath = http://localhost:8080/emCAServices/service/emcaServices.wsdl

#API Authentication time out in minutes
APIAuthenticationTimeOut = 1440

Database

Open the application.properties file and based on the type of database used; the corresponding values need to be updated. Please find below a sample Database configuration provided for MySQL database.

Example: for #MySQL database, use below mentioned values in the table:

#Hibernate properties:

Parameter

Description

Values to be replaced

spring.jpa.properties.hibernate.dialect

[DialectInfo] refers to Dialect information

org.hibernate.dialect.MySQL5Dialect

spring.datasource.driver-class-name

[DriverClassName] refers to Driver class name

com.mysql.jdbc.Driver

spring.datasource.url

[URL] refers to Database URL

jdbc:mysql://127.0.0.1:3306/emca

spring.datasource.username

[UserName] refers to UserName who has access to this schema

Root

spring.datasource.password

[Password] refers to Password for the user ( Refer Section 6)

nNh0bStJeJxo3eu3taSY2Q==

Ex:

#MySQL

DialectInfo= “org.hibernate.dialect.MySQLDialect”

DriverClassName=” com.mysql.jdbc.Driver”

URL= “jdbc:mysql://<127.0.0.1:3306>/ emca”

UserName=”root”

Password=”root”

Note: The same schema which is used for the emCA application should be used for the emCA API as well

Logs

The application uses Log4j for logging. Please specify the local server path for collecting the logs in the log4j.xml file. The local server path of the log4j.xml file needs to be provided in the application.properties file which is set in the environment variables

Log4J XML file as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">

    <!-- Logging Properties -->
    <Properties>
        <Property name="LOG_PATTERN">[%d{yyyy-MM-dd HH:mm:ss.SSS}] -- {%pid} [%p] - %m%n</Property>
        <Property name="APP_LOG_ROOT">[Local Server Path] </Property>
    </Properties>
    
    <Appenders>
    
        <!-- Console Appender -->
        <Console name="Console" target="SYSTEM_OUT" follow="true">
            <PatternLayout disableAnsi="false" pattern="${CONSOLE_LOG_PATTERN}" />
        </Console>
        
        <RollingFile name="warnLog" fileName="${APP_LOG_ROOT}/emCA-API-warn.log" filePattern="${APP_LOG_ROOT}/emCA-API-warn-%d{yyyy-MM-dd}_%i.log" immediateFlush="true" append="true">
            <LevelRangeFilter minLevel="WARN" maxLevel="WARN" onMatch="ACCEPT" onMismatch="DENY"/>
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <OnStartupTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="10MB" />
            </Policies>
            <DefaultRolloverStrategy max="30000"/>
        </RollingFile>
        
        <RollingFile name="infoLog" fileName="${APP_LOG_ROOT}/emCA-API-info.log" filePattern="${APP_LOG_ROOT}/emCA-API-info-%d{yyyy-MM-dd}_%i.log" immediateFlush="true" append="true">
            <LevelRangeFilter minLevel="INFO" maxLevel="INFO" onMatch="ACCEPT" onMismatch="DENY"/>
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <OnStartupTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="10MB" />
            </Policies>
            <DefaultRolloverStrategy max="30000"/>
        </RollingFile>
        
        <RollingFile name="errorLog" fileName="${APP_LOG_ROOT}/emCA-API-error.log" filePattern="${APP_LOG_ROOT}/emCA-API-error-%d{yyyy-MM-dd}_%i.log" immediateFlush="true" append="true">
            <LevelRangeFilter minLevel="ERROR" maxLevel="ERROR" onMatch="ACCEPT" onMismatch="DENY"/>
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <OnStartupTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="10MB" />
            </Policies>
            <DefaultRolloverStrategy max="30000"/>
        </RollingFile>
		
		<RollingFile name="debugLog" fileName="${APP_LOG_ROOT}/emCA-API-debug.log" filePattern="${APP_LOG_ROOT}/emCA-API-debug-%d{yyyy-MM-dd}_%i.log" immediateFlush="true" append="true">
            <LevelRangeFilter minLevel="DEBUG" maxLevel="DEBUG" onMatch="ACCEPT" onMismatch="DENY"/>
            <PatternLayout pattern="${LOG_PATTERN}"/>
            <Policies>
                <OnStartupTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="10MB" />
            </Policies>
            <DefaultRolloverStrategy max="30000"/>
        </RollingFile>
            
    </Appenders>

    <Loggers>
        <AsyncRoot level="debug" includeLocation="false">
            <AppenderRef ref="infoLog"  />
            <AppenderRef ref="errorLog" />
            <AppenderRef ref="warnLog" />
			 <AppenderRef ref="debugLog" />
			<AppenderRef ref="Console" /> 
        </AsyncRoot>
    </Loggers>

</Configuration>

In the above LOCAL SERVER PATH, the administrator has to provide folder path where in the log files get generated.

Deployment

The following component is required for deployment:

emCAServices.war

emCAServices comes as a war file that has to be deployed on the application server. Server provides configuration through the properties file.

Please configure and save all the properties defined in the properties file. Then deploy the configured emCAServices war file.

Please find below the steps to deploy the application:

Copy the emcaServices war inside Tomcat ->Web apps folder apache-tomcat-7.0.37\webapps.
Windows run services.msc.
Select the service Apache Tomcat and click start.

Quick Check Guide

Once deployment is completed and the server is started, Open any browser like Internet Explorer, Google Chrome, Firefox, etc. and enter the URL- https:/www.example.com/emcaServices

Example: https://www.example.com/emCAServices in the enter address field

The following message will be displayed as shown below

PreviousemCA NextOCSP Core

Last updated 7 months ago