Lijun Liao xipki

XiPKI

XiPKI (eXtensible sImple Public Key Infrastructure) is a highly scalable and high-performance open source PKI (CA and OCSP responder).

License

The Apache Software License, Version 2.0

Support

Just create issue or new discussion.

For bug-report please upload the testdata and log files, describe the version of XiPKI, OS and JRE/JDK, and the steps to reproduce the bug.

Prerequisite

OS: Linux, Windows, MacOS
JRE / JDK 8 (build 162+), 11, 17
Database: DB2, MariaDB, MySQL, Oracle, PostgreSQL, H2, HSQLDB
Hardware: Any available hardware (tested on Raspberry Pi 2 Model B with 900MHz quad-core ARM CPU and 1 GB Memory)

Tested PKCS#11 Devices

Softhsm v1 & v2
Nitrokey HSM 2 / Smartcard HSM EA+
nCipher Connect
nCipher Solo
Utimaco Se
Sansec HSM / 三未信安服务器密码机: tested SM2, ECDSA and RSA.

Get Started

JAVA_HOME

Set the environment variable JAVA_HOME to point to root directory of the to the JRE/JDK installation.

Binaries

Download the binaries xipki-ca-<version>.zip, xipki-ocsp-<version>.zip, xipki-gateway-<version>.zip, xipki-mgmt-cli-<version>.tar.gz (or xipki-mgmt-cli-jdk8-<version>.tar.gz for JDK 8), xipki-cli-<version>.tar.gz (or xipki-cli-jdk8-<version>.tar.gz for JDK 8) from releases.

Only if you want to use the development version, build it from source code as follows.

Get a copy of project code

git clone https://github.com/xipki/xipki

Build the project

In folder xipki
```
mvn clean install -DskipTests
```
Then you will find the following binaries:
- DB Tool: assemblies/xipki-dbtool/target/xipki-dbtool-<version>.zip
- CA: assemblies/xipki-ca/target/xipki-ca-<version>.zip
- OCSP: assemblies/xipki-ocsp/target/xipki-ocsp-<version>.zip
- Protocol Gateway (CMP, SCEP, REST): assemblies/xipki-gateway/target/xipki-gateway-<version>.zip
- Management CLI: assemblies/xipki-mgmt-cli/target/xipki-mgmt-cli-<version>.tar.gz (or xipki-mgmt-cli-jdk8-<version>.tar.gz for JDK 8)
- CLI: assemblies/xipki-cli/target/xipki-cli-<version>.tar.gz (or xipki-cli-jdk8-<version>.tar.gz for JDK 8)

Install DB Tool

Unpack the binary xipki-dbtool-<version>.zip.
If you use database other than PostgreSQL, MariaDB and MySQL, you need to get the JDBC driver and copy it to the directory lib/jdbc.

Install CA Server

Unpack tomcat to a new folder
Unpack the binary xipki-ca-<version>.zip and install CA as described in the unpacked README file.

Install OCSP Responder

Unpack tomcat to a new folder
Unpack the binary xipki-ocsp-<version>.zip and install OCSP responder as described in the unpacked README file.

Install Protocol Gateway

Unpack tomcat to a new folder
Unpack the binary xipki-gate-<version>.zip and install protocol gateway as described in the unpacked README file.

Install Management Command Line Interface

Unpack the binary xipki-mgmt-cli-<version>.tar.gz (or xipki-mgmt-cli-jdk8-<version>.tar.gz for JDK 8)
If you get "java.lang.ClassNotFoundException: <jdbc class>", please copy the missing JDBC driver jar to the directory lib/boot.

Install Command Line Interface

Unpack the binary xipki-cli-<version>.tar.gz (or xipki-cli-jdk8-<version>.tar.gz for JDK 8)

Configure PKCS#11 device (optional)

This step is only required if the real PKCS#11 device instead of the emulator is used. Note that this step should be applied to all components tomcat, xipki-mgmt-cli, and xipki-cli.

Copy xipki/security/example/pkcs11-hsm.json to xipki/security/pkcs11.json, and adapt the PKCS#11 configuration.

Configure how to handle SSL client certificate (optional)

This step is only required if the CA is behind a reverse proxy apache httpd.

Add the java property org.xipki.reverseproxy.mode
```
-Dorg.xipki.reverseproxy.mode=APACHE
```
configure the proxy to forward the headers via mod_proxy with the following configuration

# Require SSL Client verification
SSLVerifyClient		require

#initialize the special headers to a blank value to avoid http header forgeries 
RequestHeader set SSL_CLIENT_VERIFY  "" 
RequestHeader set SSL_CLIENT_CERT  "" 

<Location / >
 RequestHeader set SSL_CLIENT_VERIFY "%{SSL_CLIENT_VERIFY}s"
 RequestHeader set SSL_CLIENT_CERT "%{SSL_CLIENT_CERT}s"
 ...
</Location>

For more details please refer to * Jetty/Howto/Configure mod proxy * Jetty: Tricks to do client certificate authentications behind a reverse proxy * Apache Module mod_ssl

Setup CA Server

Start the servlet container
HSM devices of Thales, e.g. nCipher, can use Thales preload to manage the PKCS#11 sessions. In this case, the servlet container should be started as follows

preload <start script>

Setup CA in Management CLI (xipki-mgmt-cli)
- (If error like "Identity or Certificate with label=mylabel already exists" occurs, you need to comment the line which generate the key (e.g. dsa-p11 ec-p11, rsa-p11, sm2-p12) or delete the existing key using command delete-key-p11).
- Start Management CLI.
  
  bin/karaf
  
  HSM devices of Thales, e.g. nCipher, can use Thales preload to manage the PKCS#11 sessions. In this case, the cli should be started as follows
```
preload bin/karaf
```
- Setup CA (choose p11 if the key is saved in PKCS#11 device, p12 in PKCS#12 device.
  - In case of using new keys and certificates, in CLI:
    source xipki/ca-setup/cacert-none/setup-*-*.script where * is place holder.
  - In case of using existing keys and certificates, in CLI:
    source xipki/ca-setup/cacert-present/setup-*-*.script where * is place holder.
  - If you wish to generate the siging key and certificate for the OCSP responder, in CLI:
    source xipki/ca-setup/setup-ocsp-*.script.
  - If you wish to add the SCEP support, in CLI:
    source xipki/ca-setup/setup-scep.script.
- Verify the installation, execute the command in CLI:
  ca-info myca1

Enroll/Revoke Certificate

SCEP
Using any SCEP client. XiPKI provides also a SCEP client.

The binary xipki-cli-<version>.tar.gz (or xipki-cli-jdk8-<version>.tar.gz for JDK 8) contains an example script in the folder xipki/client-script. It can be executed in the CLI as follows:
- source xipki/client-script/scep-client.script
CMP Using any CMP client. XiPKI provides also a CMP client.

The binary xipki-cli-<version>.tar.gz (or xipki-cli-jdk8-<version>.tar.gz for JDK 8) contains an example script in the folder xipki/client-script. It can be executed in the CLI as follows:
- source xipki/client-script/cmp-client.script (use argument 'help' to print the usage)
REST API
The shell script xipki/client-script/rest.sh of the xipki-cli demonstrates the use of REST API.

The binary xipki-cli-<version>.tar.gz (or xipki-cli-jdk8-<version>.tar.gz for JDK 8) contains an example script in the folder xipki/client-script. It can be executed in the CLI as follows:
- source xipki/client-script/rest-client.script (use argument 'help' to print the usage)

Management CLI Commands

Please refer to commands.md for more details.

CLI Commands