HOWTO-OCSP-RESPONDER (水平有限,仅供参考,进行中.....)

This file describes how to configure ant start the OCSP responder.
本文描述如何配置ant启动OCSP响应器
Setting up external OCSP responders
===================================
构建外部OCSP响应器
Introduction
------------
You can set up separated OCSP responders in EJBCA. Using this you can isolate the CA from the Internet and still
be able to answer OCSP request. You can set up firewalls so that only outgoing traffic is allowed from the CA, and
nothing to the CA.
Separated OCSP responders is also good when you don't require high-preformance clustering for the CA, but you do
need high-performance for the OCSP responders. This should be a usual setup, if the CA only issues certificates
once every year for one million users, this does not put much pressure on the CA, but the OCSP responders can be
put under high load continuously.
See the image HOWTO-OCSP-RESPONDER.jpg for an overview of a sample setup.
   可以在EJBCA中建立一个独立的OCSP响应器.使用它就可以将CA与网络隔离依旧能够响应OCSP请求.你可以建立防火墙,从而只允许CA
向外输出,而不许任何信息与CA交互.
   当你不需要CA的高性能簇时,独立的OCSP响应器也比较好,但是OCSP响应器需要高性能.这应该是一个标准的配置,如果每年只关注
一次百万用户的证书,不会给CA带来太大的压力,但是OCSP响应器将持续的高负荷.
   可以通过HOWTO-OCSP-RESPONDER.jpg对样例进行一个总体了解.

Building and configuring EJBCA.
-------------------------------
EJBCA should be configured as for any other installation but you must also set all preferences
(ocsp-database.*) of the responder database. The responder database is the master database of all
the responders. Then EJBCA is built with the command: ant deploy
构建并配置EJBCA
    EJBCA可以配置到其他任何安装程序,但是必须设置所有响应器数据库的配置参数(ocsp-database.*).应答数据库是所有
响应器的主要数据库.EJBCA通过命令"ant deploy"构建.

When EJBCA has been started you have to add a new publisher. As a superuser you add this publisher
on the "Edit Publishers" page in the admin GUI. Use publisher type "Custom Publisher". And these
configurations (if ocsp-datasource.jndi-name=OcspDS):
Class Path:                             org.ejbca.core.model.ca.publisher.ExternalOCSPPublisher
Properties of Custom Publisher:         dataSource java:/OcspDS
All certificate profiles to certificates that should be available to the OCSP responder should
have a reference to this publisher. To configure this you must be a super user.

当EJBCA被启动后,需要添加一个新的发布者(publisher).在admin GUI界面中的"编辑发布者"页面以超级用户身份添加发布者.
使用发布者类型"自定义发布者",还有以下配置(如果 ocsp-datasource.jndi-name=OcspDS):
Class Path:                           org.ejbca.core.model.ca.publisher.ExternalOCSPPublisher
Properties of Custom Publisher:         dataSource java:/OcspDS

所有适用于该OCSP响应器的证书的证书profile都应该拥有一个该发布者的引用.这些都需要以超级用户的身份进行配置.

When all settings above have been done then all created certificates belonging to a certificate
profile that has a the ExternalOCSPPublisher as publisher should be published in the responder
database as well as in the EJBCA database. When a certificate is revoked it will be revoked in
the responder database as well.
If the publishing is not working it is important to notice this and syncronize the databases again,
see 'Error publishing to OCSP database' below.
  当以上所有配置都设置好以后,所有被创建的证书都属于一个证书profile,ExternalOCSPPublisher作为发布者应该像发布在
EJBCA数据库一样发布到响应器数据库.
   如果发布无效,应该引起足够的重视并且再次同步数据库,看下面的'OCSP 数据库错误发布':
 

Building and configuring the Responder.
---------------------------------------
The responder is configured as EJBCA is configured. Only the preferences ocsp.* and httpsserver.*
and datasource.* and database.* are relevant to the responder but you may keep conf/*.properties
from the EJBCA setup since definitions of other properties does no harm.
Note that the External OCSP responder itself uses the configuration options database.* and not the ocsp-database.* options.
The ocsp.keys.* preferences (that has no meaning for EJBCA) has also to be configured。

构建与配置响应器
    响应器和EJBCA一样配置.只是参数ocsp.* 、httpsserver.*、datasource.* 和 database.* 与响应器相关，但是可保持EJBCA
conf/*.properties，这样对其他属性定义无害。
   注：外部OCSP响应器自身使用配置选项database.* 并不是ocsp-database.* 选项.参数ocsp.keys.*（对EJBCA无意义）也被
    配置。
   
please read description of these properties in ocsp.properties.sample, database.properties.sample and perhaps
conf/web.properties.sample (if ssl or different ports should be configured).
ocsp.usecasigningcert should be set to false. If card keys (see below) should be used then the property
'ocspHardTokenClasses' must be set to the corresponding directory of PrimeCard.
    请阅读ocsp.properties.sample、database.properties.sample和/或conf/web.properties.sample中这些属性的细节（是否
ssl或者不同端口应该被配置）。
ocsp.usecasigningcert 应该被设置为false，如果card 关键字（在下面）应该被使用，则属性‘ocspHardTokenClasses’必须
设置到相应的PrimeCard的相应目录。
  
The responder is then built and deployed with:
    ant ocsp-deploy
on the external OCSP responder.
The database that OcspDS in EJBCA points to only have to contain the CertificateData table. This table is
created automatically by JBoss when it starts on the external OCSP responder.
The keys used to sign the OCSP response could either be stored on a smart card or soft on the file system
of the host. It should be one key for each CA.

在外部OCSP响应器上，响应器使用“ant ocsp-deploy”进行编译部署
EJBCA中的OcspDS数据库仅包含证书数据表，当启动外部OCSP响应器时，该表由JBoss自动创建。
用于标记OCSP响应的密钥既可以存储在智能卡中也可以保存在主机文件系统的软件中。应该每个CA对应一个密钥。

The certificate profile could be the same for both soft and card keys.
Define a new certificate profile and use 'OCSPSIGNER (FIXED)' as template (use selected as template).
This certificate profile is like a normal end entity profile but with the following key usages:
- Key Usage: Digital Signature
- Extended Key Usage: OCSPSigner
Configure the newly created certificate profile to use the Ocsp publisher defined above.
软件与密钥卡的证书profile应该相同。
定义一个新的证书profile并使用‘OCSPSIGNER（FIXED）’作为模板（使用selected as template）。
改证书规范像一个正常的终止实体规范，但是带有下面的密钥用法：
 --- 密钥用途：数字签名
 --- 扩展密钥用途：OCSPSigner
使用上面定义的Ocsp发布者配置新创建的证书profile。

Note: the responders certificate AND the CA certificate need to be published from the CA to the
OCSP responder. For the CA you do this by setting the CRL publisher to the OCSP publisher.
You also need to create a new End Entity Profile to use the new Certificate Profile. You should set 'Batch' and TokenType=P12
if you will be issuing soft keys ot the OCSP responder.

注：证书响应者和CA证书需要从CA发布到OCSP响应器。在CA需要通过设置CRL发布者到OCSP发布者。
还需要创建一个新的终端实体。如果想让软件密钥关注OCSP响应器，需要设置'Batch' 和 TokenType=P12。

You should then create a user for each CA using this certificate profile.
Use the token type "p12" or "jks" for soft keys and "user generated" for card keys.
When a soft key has been created it should be stored in the directory defined by the ocsp.keys.dir property of ejbca.properties.
The password for each key must be the same and should be equal to the ocsp.keys.keyPassword property of ejbca.properties.

应该使用改证书profile为每个CA创建一个用户。
软件密钥使用使用token类型“p12”或“jks”，卡密钥使用“user generated”。
当软件密钥被创建之后应该保存到ejbca.properties属性文件的ocsp.keys.dir 属性指定的目录中。
每个密码的密钥必须相同并且与ejbca.properties属性文件的ocsp.keys.keyPassword属性值相同。

   Card keys are created on the card with the "create CA Token on card" tool see the HOWTO-CATokenOnCard.txt of PrimeCard.
Select the choice for one authentication code for all keys on the card. If you want several OCSP responders with same
keys then you may create several card with same keys. But note that no backup card is needed. If a card is lost or broken then
simply make another one with new keys and revoke the old signing certificates.
   The certificates for the the keys are then fetched from the enrollment page of EJBCA with certificate request. There
should be one certificate request for each key.
    'changePIN.sh createCertReqs' will create the requests, one for each key. Choose 'pem' format for
the certificates and then just store these files in the 'ocsp.keys.dir' directory.
    The property 'ocsp.keys.cardPassword' should be set to the password of the card.
   卡密钥是使用卡上的"create CA Token on card" 工具创建的，可以参看PrimeCard的HOWTO-CATokenOnCard.txt。
为卡上的所有密钥选择一个识别码。如果想要让几个OCSP响应器拥有同样的密钥，就需要使用相同的密钥创建几个卡。但是注意不需要
备份卡。如果卡丢失了或者损坏了，只需要撤销以前的签名证书并使用新密钥制作另外一个。
    密钥证书此时将从带有证书请求的EJBCA注册页取得。那里对每个密钥都有一个证书请求。
    ‘changePIN.sh createCertReqs’将创建请求，每个密钥一个。为证书选择‘pem’格式并保存这些文件到‘ocsp.keys.dir'目录.
    'ocsp.keys.cardPassword'属性设置为卡的密码.

   Re-start the application server for the external OCSP responder.
When the application server is started it should just work.
   The database connection settings on the external OCSP responder is configured and deployed in JBoss in the file
JBOSS_HOME/server/default/deploy/ejbca-ds.xml.
   重启外部OCSP响应器的应用服务.
当应用服务器启动之后就可以工作了.
   外部OCSP响应器的数据库连接配置与部署在JBoss的文件 JBOSS_HOME/server/default/deploy/ejbca-ds.xml 中.

Error publishing to OCSP database
---------------------------------
   If there is an error publishing to the OCSP database, the OCSP responder will be out of sync with the CA.
It is very important to re-synchronize the databases in that case.
   In case of failure to publish to the OCSP database the following error message will appear in the server.log:
EXTERNAL OCSP ERROR, publishing is not working
   This will be followed by more details of the error.
   The log must be monitored to discover such a fault and if such a fault is discovered an alarm should notify
the operator that he has to fix whatever is wrong and then synchronise the OCSP database with the EJBCA
database (see 'Synchronise the db of the responder').
发布OCSP数据库的错误
---------------------------------
   如果在发布OCSP数据库的时候出现错误,OCSP响应器将不再与CA保持同步.此种情况下,重新同步数据库非常的重要.
   如果发布OCSP数据库时出现错误,以下的错误信息将出现在server.log中:
EXTERNAL OCSP ERROR, publishing is not working   
之后可能跟随错误的更多细节.
   该日志必须得到监控用以发现错误,同时,如果此类错误被发现了,应该向操作者发促警告,不管是何种错误,都使他必须去修正然后
同步EJBCA和OCSP数据库(参见 'Synchronise the db of the responder').


Synchronise the db of the responder
-----------------------------------
    At the beginning and after failure in publishing to the responder the master database of the
publishers must be synchronised with the CertificateData table of the database of EJBCA.
    If there is a single certificate out of sync you can re-sync it by doing a 'Republish' from the admin-GUI.
    The following procedure may be used to synchronise the database of EJBCA with the database of the
responder:
1. Prevent any further issuing of new certificates and revocation of old certificates until the
synchronisation is finished. This might be done by simply blocking the port to the adminweb.
2. On the host of ejbca the following commands can be used to make the synchronisation:
同步响应器数据库
-----------------------------------
    在响应器开始和发布失败的时候,发布者主数据库必须与EJBCA数据库的证书数据表同步.
    如果有一个单独的证书没有同步,可以通过在admin-GUI界面进行'Republish'操作进行重新同步.
    以下操作可被用于使用响应器数据库同步EJBCA的数据库:
1.在同步结束之前,拒绝一切注册新证书和撤销旧证书的请求.可以通过锁定adminweb的端口来实现.
2.在ejbca主机,以下命令可以用于同步:

    Run on the OCSP responder machine (as root user in mysql):
mysqladmin drop ejbca_db;
mysqladmin create ejbca_db;
This drops and re-created the ejbca database to clean it. Replace ejbca_db with the database name of your database.
       Run on the CA server: 
mysqldump -u ejbca -p --compress ejbca_db CertificateData > CertificateData.dat
mysqldump -u ejbca -p --compress ejbca_db TableProtectData > TableProtectData.dat
cat CertificateData.dat | mysql -h ocspresponder ejbca_db
cat TableProtectData.dat | mysql -h ocspresponder ejbca_db
    Replace your the username ejbca with your username.
ocspResponder is the external OCSP responder host.
Note, that this can usually not be done from a windows machine, to a Linux machine, because windows is not case sensitive.

     在OCSP响应器机器运行(作为mysql根用户):
mysqladmin drop ejbca_db;
mysqladmin create ejbca_db;
删除并重新创建ejbca数据库,使用你的数据库名称替换ejbca_db.
    在CA服务器运行:
mysqldump -u ejbca -p --compress ejbca_db CertificateData > CertificateData.dat
mysqldump -u ejbca -p --compress ejbca_db TableProtectData > TableProtectData.dat
cat CertificateData.dat | mysql -h ocspresponder ejbca_db
cat TableProtectData.dat | mysql -h ocspresponder ejbca_db
    使用你的用户名替换ejbca
ocspResponder 是外部OCSP响应器主机
注意:这个通常不会在windows和Linux都奏效,因为windows大小写不敏感.



3. Check that the publishing is working before allowing issuing and revoking.
Running several responders.
--------------------------
In many case it is desirable to have several responders on different computers. This is easily
achieved if it is an mysql database that EJBCA is publishing to (see section "Building and
configuring EJBCA"). All you have to do is to set up the publishing database as a master. Then one
slave data base is created on each computer that should host a responder.
How to do it is described in the mysql documentation. Depending on which which version you are using
please read one of the followings:
http://dev.mysql.com/doc/refman/4.1/en/replication-howto.html
http://dev.mysql.com/doc/refman/5.0/en/replication-howto.html
http://dev.mysql.com/doc/refman/5.1/en/replication-howto.html

3.   在允许发布和撤销之前校验发布是否可用.
运行几个响应器/
--------------------------
在很多情况下在不同的计算机上拥有几个响应器是比较合理的.如果一个EJBCA发布到一个mysql数据库(参见章节"Building and
configuring EJBCA")这个很容易达到.所有需要做的就是将发布数据库作为主数据库.然后在每个响应器电脑创建一个从数据库.
在mysql文档中有该设置的描述.根据你所用mysql版本的不同可以参看以下文档之一:


Setting up the Unid-Fnr OCSP extension
======================================
If you don't know what a Unid-Fnr mapping is, you are probably not interested in this part.
Configuring the Unid lookup server.
-----------------------------------
The OCSP responder comes with an extension for looking up Unid-Fnr mappings.
To enable the Unid extension you configure the options
ocsp.extensionoid=2.16.578.1.16.3.2
ocsp.extensionclass=org.ejbca.core.protocol.ocsp.OCSPUnidExtension
in ejbca.properties.

配置Unid-FnrOCSP扩展
======================================
如果不知道什么是Unid-Fnr映射,你可能对这部分没有兴趣.
配置Unid查找服务.
-----------------------------------
OCSP响应器与查找Unid-Fnr映射扩展一同工作.
确保Unid扩展可用,需要在ejbca.properties文件中配置:
ocsp.extensionoid=
ocsp.extensionoid=2.16.578.1.16.3.2
ocsp.extensionclass=org.ejbca.core.protocol.ocsp.OCSPUnidExtension



All options are described in ejbca.properties.sample.
There are three options for the Unid extension itself:
- ocsp.uniddatsource:
This should be set to a datasource configured in JBoss that goes to the correct database.
the database must contain the table according to the (MySQL) definition:
CREATE TABLE UnidFnrMapping(
    unid varchar(250) NOT NULL DEFAULT '',
    fnr varchar(250) NOT NULL DEFAULT '',
    PRIMARY KEY (unid)
);
Example of ocsp.uniddatsource is java:/UnidDS, where UnidDS is configured similarly as EjbcaDS in
JBOSS_HOME/server/default/deploy/ejbca-ds.xml, but using another database.
- ocsp.unidtrustdir:
All clients that will be allowed to lookup Unid-Fnr mapping must be issued a certificate.
The issuer of the client certificates must be the same as the issuer of the server certificate for TLS
communication with the OCSP server (see below).
You should use these parameters (where differing from default) when issuing keystores to the clients:
Batch generation
PKCS#12 files
Extended key usage 'TLS client'
When a certificate has been issued for a lookup client, you must download the certificate from the admin-GUI of the CA
and place it in ocsp.unidtrustdir.
When a new certificate has been added, the EJBCA/OCSP application on the JBoss server must be re-deployed
(you can do this with the command 'touch ejbca.ear' in JBOSS_HOME/server/default/deploy).
- ocsp.unidcacert:
This is the CA certificate, in PEM format, that signed the certificates in ocsp.unidtrustdir. You can download it in
 PEM-format from EJBCA.

所有选项都在ejbca.properties.sample中描述.
Unid扩展自身有三个选项
- ocsp.uniddatsource:
  这个用于在JBoss中设置一个数据源配置来构建一个适当的数据库.该数据库必须包含以下(MySQL)表定义:
  CREATE TABLE UnidFnrMapping(
    unid varchar(250) NOT NULL DEFAULT '',
    fnr varchar(250) NOT NULL DEFAULT '',
    PRIMARY KEY (unid)
);
   ocsp.uniddatsource的样例是 java:/UnidDS,UnidDS仅是简单的在JBOSS_HOME/server/default/deploy/ejbca-ds.xml中像EjbcaDS
一样配置,但是使用其他数据库.
- ocsp.unidtrustdir:
   所有允许查找Unid-Fnr映射的客户端都需要一个证书,客户端证书发布者必须与OCSP服务器TLS(传输层安全性协议)通信的服务器证书发布者相同(看下面).
当向客户端发送keystores时,需要使用这些参数(不同于默认):
Batch generation
PKCS#12 files
扩展密钥用法'TLS client'
当一个证书已经发布给一个查找客户端,你必须从CA的admin-GUI下载该证书并将其放置到ocsp.unidtrustdir下.
   当新证书被添加,JBoss服务器上的EJBCA/OCSP应用必须重新部署(你可以在JBOSS_HOME/server/default/deploy目录下
通过命令'touch ejbca.ear'来执行).
- ocsp.unidcacert:
  这是CA证书,PEM格式的,签署ocsp.unidtrustdir目录下的证书,你可以从EJBCA以PEM格式下载它.



Configuring TLS on the Unid lookup server.
-----------------------------------------
    If you are running the OCSP server integrated with EJBCA you do not have to bother with this, as EJBCA set up TLS
    for you.
   On a stand alone OCSP server you must configure TLS with client authentication. To do this you first need a JKS
keystore for the key and certificate for the server.
You should use these parameters (where differing from default) when issuing keystores to the TLS servers:
Batch generation
JKS files
Key usage: Digital Signature, Key Encipherment
Extended key usage: 'TLS server'
   The Common Name (CN) for a TLS server should be the same as the machines fully qualified DNS name used to call the
server.
For example 'CN=ocsp.primekey.se'.The other DN components you can choose freely.
   Once the JKS keystore is issued you can configure TLS on the OCSP server in the same way as on the EJBCA server.
It is configured in the file JBOSS_HOME/server/default/deploy/jbossweb-tomcat55.sar/server.xml.
The Connectors for port 8442 and 8443 is the TLS configuration.
The keystoreFile and the keystorePass are important to get right.
It is easiest if you put the keystore for the TLS server in the file p12/tomcat.jks on the external OCSP responder.
When doing this it should be deployed correctly when using 'ant ocsp-deploy', and you don't have to change the server.xml file which is
over-written by 'ant ocsp-deploy'.
   You must create a new java trusted keystore with the commands:
bin/ejbca.sh ca getrootcert AdminCA1 ca.crt -der
keytool -import -trustcacerts -alias AdminCA1 -keystore cacerts -storepass changeit -file ca.crt
    Where AdminCA1 is replaced with the CA name of your CA that signs the TLS certificates.
    The cacerts file is then copied to (and replacing the existing) $JAVA_HOME/jre/lib/security/cacerts.
在Unid查找服务器上配置TLS(传输层安全性协议)
-----------------------------------------
    如果与EJBCA整体运行OCSP服务,不需要关注这里,EJBCA已经为你配置了TLS.略.......


Security of the lookup server.
-----------------------------
the lookup server always checks that eash client is using TLS with client authentication and that the certificate is valid and is one
of the certificates placed in the directory pointed to by 'ocsp.unidtrustdir'. If these conditions are not met, no Fnr is returned.

Logging
-------
The OCSP Unid extension logs using Log4j to the JBoss server.log. The JBoss server log is located in
JBOSS_HOME/server/default/log/server.log and the logging is configured in JBOSS_HOME/server/default/conf/log4j.xml.
If you for example want to configure so the OCSP Unid extension logging is sent to syslog, you need to know the
class patch of the OCSP Unid extension:
org.ejbca.core.protocol.ocsp.OCSPUnidExtension
and the log level:
INFO, for request logging
ERROR, for error logging

Lookup server client library
----------------------------
See Howto-Ocsp-Unid-client.txt

Using database integrity protection
===================================
Enable the basic support for database protection as described in HOWTO-logsigning.txt
(you don't have to enable log signing though).
As a property in the ExternalOCSPPublisher you add the property:
protect true

Thats all there is to it. When EJBCA publishes certificate entrys to the OCSP responder database, it will also write
antries in the TableProtectData table.
If protection is enabled also on the External OCSP responder, it will log errors
PROTECT ERROR
if verification fails when it answers OCSP queries (this will slow it down a little bit).

If protection is not enabled on the External OCSP responder, it will not verify the entries when answering OCSP queries,
a remote batch job can be used to verify the database integrity periodically instead.