OpenCA Guide for Versions 0.9.2+
		Next

OpenCA Guide for Versions 0.9.2+

$Id $

Table of Contents

Introduction

I. Design Guide

Preface

1. General Design

1. Basic Hierarchy

2. Interfaces

2.1. Node
2.2. CA
2.3. RA
2.4. LDAP
2.5. Pub

3. Configuration

4. Database

5. Interface

6. Life cycle of the objects

7. Sub-Ca

7.1. Example 1
7.2. Example 2

2. Recommendations

1. Hardware Issues

1.1. Time
1.2. Failing disks
1.3. Hardware monitoring

2. Physical Security

2.1. Safes and Data organization
2.2. Buildings

3. Network Issues

4. Certificate Issues

4.1. CDPs

4.2. Application specific problems

4.2.1. Mail servers
4.2.2. Netscape clients
4.2.3. OpenLDAP

5. Organizational Aspects

5.1. Dual Access Control
5.2. Privacy vs. Security
5.3. Enforcement of Access Control
5.4. Privacy Officer Integration
5.5. Enterprise Integration
5.6. Parallel use of several end user PKIs

II. Installation and Configuration Guide

Preface

3. Installation

1. Preparations

1.1. Software
1.2. Hardware

2. Configure

2.1. Host System Configuration

2.2. Host System Configuration (of the upcoming OpenCA 1.0)

2.2.1. OpenCA user and group
2.2.2. Daemon user and group

2.3. Filesystem paths

2.3.1. Common Prefixes
2.3.2. Component Prefixes
2.3.3. OpenSSL prefixes (OpenCA 1.0 only)

2.4. Webserver specific stuff

2.4.1. Common server informations
2.4.2. Filesystem Paths
2.4.3. URL Paths

2.5. Email

2.6. Compiling features

3. Installation

4. config.xml (for RPMs and DEBs too)

4.1. Configuration sections of config.xml

4.1.1. General options
4.1.2. web server configuration
4.1.3. ldap server configuration
4.1.4. database configuration
4.1.5. module configuration
4.1.6. configuration of relative paths
4.1.7. configuration of SCEP
4.1.8. Dataexchange

4.2. How to setup two management interfaces on one server?

4.2.1. Online Components
4.2.2. Offline Components
4.2.3. OPENCADIR/etc/menu.xml

4. Configuration

1. Access Control

1.1. Channel verification

1.2. Login

1.2.1. none

1.2.2. passwd

1.2.2.1. internal database
1.2.2.2. external authentication

1.2.3. x509

1.3. Session management

1.4. ACLs

2. Token and keyconfiguration

2.4.1. Introduction
2.4.2. Implementation
2.4.3. Usage
2.4.4. HSM login shell
2.4.5. OpenCA Configuration
2.4.6. Example for the setup

2.5. OpenSC

3. OpenSSL

3.1. Certificate Extensions

3.1.1. Standard Extensions

3.1.1.1. Authority Key Identifier
3.1.1.2. Subject Key Identifier
3.1.1.3. Key Usage
3.1.1.4. Private Key Usage Period
3.1.1.5. Certificate Policies
3.1.1.6. Policy Mappings
3.1.1.7. Subject Alternative Name
3.1.1.8. Issuer Alternative Name
3.1.1.9. Subject Directory Attributes
3.1.1.10. Basic Constraints
3.1.1.11. Name Constraints
3.1.1.12. Policy Constraints
3.1.1.13. Extended Key Usage
3.1.1.14. CRL Distribution Points
3.1.1.15. Inhibit Any-Policy
3.1.1.16. Freshest CRL

3.1.2. Internet Certificate Extensions

3.1.2.1. Authority Information Access
3.1.2.2. Subject Information Access

3.1.3. Vendor Specific Extensions

3.1.3.1. Microsoft
3.1.3.2. Netscape

3.2. Profiles

3.2.1. HTTPS server
3.2.2. SMTP server
3.2.3. F-Secure VPN+

4. CSRs

4.1. Additional Attributes
4.2. PKCS#10 Requests
4.3. Basic CSR
4.4. SCEP

5. Subject

5.1. Common stuff

5.2. dc style

5.2.1. etc/servers/*.conf
5.2.2. main.html
5.2.3. certsMail.txt and expiringMail.txt
5.2.4. OpenSSL configuration
5.2.5. CA CSR

6. Subject Alternative Name

7. LDAP

7.1. Configuration of the Directory
7.2. Configuration of the online components
7.3. Writing Certificates to the Directory
7.4. Adding an attribute to the LDAP schema

8. SCEP

8.1. OPENCADIR/etc/servers/scep.conf
8.2. OPENCADIR/etc/config.xml

9. Dataexchange

9.1. Configuration

9.1.1. Configuration with simple files
9.1.2. Configuration via scp

9.2. Adding a new node

10. Databases

10.1. PostgreSQL

10.1.1. Basic Setup
10.1.2. Backup
10.1.3. Recovery

10.2. MySQL

10.3. Oracle

10.3.1. Perl database driver and Oracle OCI client libraries
10.3.2. OpenCA Oracle database configuration
10.3.3. Internal Authentication
10.3.4. External Authentication
10.3.5. Database privilege separation for the OpenCA application
10.3.6. Sample Oracle setup

10.4. DBM Files

10.4.1. Backup and Recovery

10.5. SQLite

11. Email

11.1. Sendmail with basic SMTP authentication

12. i18n

12.1. Debian 3.1 Sarge

III. User Guide

Preface

5. Features

1. 0.10
2. 0.9.2

6. Interface Descriptions

1. Public PKI Server

1.1. General

1.1.1. Logout

1.2. CA Infos

1.2.1. Policy
1.2.2. Get CA Certificate
1.2.3. Certificate Revocation Lists

1.3. User

1.3.1. Request a certificate

1.3.1.1. Request a certificate with automatic browser detection
1.3.1.2. Basic Request
1.3.1.3. Netscape's Request
1.3.1.4. IE Request
1.3.1.5. Server Request
1.3.1.6. Token Request

1.3.2. Get Requested Certificate

1.3.3. Test Certificate

1.3.4. Revoke Certificate

1.4. Certificates

1.4.1. Valid
1.4.2. Expired
1.4.3. Revoked
1.4.4. Suspended
1.4.5. Search

1.5. Requests

1.5.1. Certificate Requests List
1.5.2. Certificate Revocation Requests List

1.6. Language

2. Registration Authority

2.1. General

2.1.1. Server Management
2.1.2. LDAP Admin
2.1.3. Logout

2.2. Active CSRs

2.2.1. New

2.2.1.1. Edit Request
2.2.1.2. Approve and Sign Request
2.2.1.3. Approve Request without Signing
2.2.1.4. Delete Request

2.2.2. Renewed

2.2.3. Pending (be processed already)

2.2.4. Waiting for additional signature

2.3. Active CRRs

2.3.1. New

2.3.1.1. Approve and Sign Request
2.3.1.2. Approve Request without Signing
2.3.1.3. Delete Request

2.3.2. Pending (be processed already>

2.3.3. Waiting for additional signature

2.4. Information

2.4.1. Certificate Requests
2.4.2. Revocation Requests
2.4.3. Certificates
2.4.4. CA Certificates
2.4.5. CRLs

2.5. Utilities

2.5.1. Search Certificate
2.5.2. Search CSR
2.5.3. Warn Expiring Certificates

3. Registration Authority Node

3.1. General

3.1.1. Certificate Authority
3.1.2. Registration Authority
3.1.3. LDAP Admin
3.1.4. Public
3.1.5. Logout

3.2. Administration

3.2.1. Stop Daemons of Cryto Tokens

3.2.2. Server Init

3.2.2.1. Initialise DataBase
3.2.2.2. Import Configuration

3.2.3. Dataexchange

3.2.3.1. Enroll data to a lower level of the hierarchy

3.2.3.2. Receive data from a lower level of the hierarchy

3.2.3.3. Download data from a higher level of the hierarchy

3.2.3.3.1. All
3.2.3.3.2. Certificates
3.2.3.3.3. CRLs
3.2.3.3.4. Configuration
3.2.3.3.5. Batchprocessors

3.2.3.4. Upload data to a higher level of the hierarchy

3.2.3.4.1. All
3.2.3.4.2. Requests
3.2.3.4.3. CRRs

3.2.4. Backup and Recovery

3.2.4.1. Backup Database
3.2.4.2. Recovery Initialize Database
3.2.4.3. Restore Database
3.2.4.4. Rebuild OpenSSL's database and next serial number

3.2.5. Database

3.3. Utilites

3.3.1. E-Mail new users
3.3.2. Send a CRIN-mail
3.3.3. Cleanup sessions
3.3.4. Delete Temp Files
3.3.5. Rebuild CA Chain

3.4. Logs

3.4.1. Search
3.4.2. Recovery index database

4. LDAP Interface

4.1. Update LDAP

4.1.1. CA-Certificate
4.1.2. Certificates
4.1.3. CRL

4.2. View CA-Certificates

4.2.1. Valid

4.2.1.1. Add to LDAP
4.2.1.2. Add to LDAP with modified DN
4.2.1.3. Delete from LDAP
4.2.1.4. Delete from LDAP with modified DN

4.2.2. Certificates Expired

4.3. View Certificates

4.3.1. Valid

4.3.1.1. Add to LDAP
4.3.1.2. Add to LDAP with modified DN
4.3.1.3. Delete from LDAP
4.3.1.4. Delete from LDAP with modified DN

4.3.2. Expired

4.3.2.1. Add to LDAP
4.3.2.2. Add to LDAP with modified DN
4.3.2.3. Delete from LDAP
4.3.2.4. Delete from LDAP with modified DN

4.3.3. Suspended

4.3.3.1. Add to LDAP
4.3.3.2. Add to LDAP with modified DN
4.3.3.3. Delete from LDAP
4.3.3.4. Delete from LDAP with modified DN

4.3.4. Revoked

4.3.4.1. Add to LDAP
4.3.4.2. Add to LDAP with modified DN
4.3.4.3. Delete from LDAP
4.3.4.4. Delete from LDAP with modified DN

4.4. View CRLs

4.4.1. CRLs

4.4.1.1. Add to LDAP
4.4.1.2. Add to LDAP with modified DN

7. Functionality Descriptions

1. CA Initialization

1.1. Phase I: Initialize the Certification Authority

1.1.1. Database Setup
1.1.2. Key pair setup
1.1.3. Request setup
1.1.4. Certificate setup
1.1.5. Final setup

1.2. Phase II and III: Create the initial administrator and RA certificate

2. Node Initialization

3. CSR Handling - a request HOWTO

3.1. Ways to request a certificate

3.1.1. Microsoft client request
3.1.2. SPKAC request
3.1.3. Pregenerated PKCS#10 request handling
3.1.4. Request a centrally generated smartcard
3.1.5. Serverside key and request generation
3.1.6. Automatic browserdetection
3.1.7. Input field explanations

3.2. Edit a certificate signing requests

3.3. Approve certificate signing requests

3.4. Issue a certificate from a certificate signing request

3.5. Certificate enrollment

3.6. Delete certificate signing requests

4. Certificate Handling

4.1. Find a certificate

4.2. Download

4.2.1. Direct Download

4.2.2. Downloads from certificate page

4.2.2.1. Normal Downloads
4.2.2.2. Private Key Downloads
4.2.2.3. Certificate Installation

4.3. Start revocation

4.4. Write an email to the owner

4.5. Informational messages and their meaning

5. SCEP

5.1. SSCEP
5.2. NetScreen ScreenOS
5.3. F-Secure VPN+
5.4. Cisco PIX

8. Client Support

1. Introduction

2. Mozilla

2.1. General

2.1.1. Requesting a certificate
2.1.2. Installing a certificate

2.2. Mozilla

2.2.1. Backup a certificate

2.2.2. Signing Data

2.2.2.1. Mozilla 1.7+ and Firefox 0.9.3+
2.2.2.2. Mozilla 1.0 to 1.6, Firefox up to 0.9.2 and Netscape 6 and 7
2.2.2.3. SecClab
2.2.2.4. WaMCom

2.3. Netscape 4

2.3.1. Backup a certificate
2.3.2. Signing Data

2.4. Opera

3. Microsoft

3.1. Domaincontroller

3.1.1. OpenSSL 0.9.7
3.1.2. OpenSSL 0.9.8

3.2. Smartcard Logon

3.2.1. OpenSSL 0.9.7 (patched)
3.2.2. OpenSSL 0.9.8

3.3. Keystore

3.4. Internet Explorer

3.5. Outlook

3.6. Outlook Express

IV. Technology Guide

Preface

9. Introduction

1. Slotechnology

10. XML

11. Cryptolayer

12. Accesscontrol

13. Logging

14. Webinterfaces

1. Interfacebuilding

1.1. Technology overview

1.2. Customization capabilities

1.2.1. Statical Pages

1.2.2. cmds

1.2.2.1. New command

1.2.3. configuration files

1.2.4. configure_etc.sh

2. CSS

3. Configuration after installation

15. Hierarchy

1. Nodemanagement
2. Dataexchange

16. LDAP

1. LDAP schema specification

1.1. Used objectclasses
1.2. Supported attributes
1.3. Common definitions for distinguished names
1.4. Special definitions for user certificates

2. Sourcecodeorganization

2.1. Structure of the code
2.2. The relevant commands
2.3. export-import.lib
2.4. ldap-utils.lib
2.5. OpenCA::LDAP

17. Database

1. Tables
2. Sequences
3. Indexes

4. Database background

5. Change the workflow

6. Default workflow

7. What about the different crypto tokens?

8. Performance

8.1. PIII 850MHz, 256 MB RAM

19. Packaging

1. Common Notices

1.1. Required Perl modules

2. RPM-based system

2.1. RedHat/Feodora

2.2. SuSE

2.2.1. HOWTO
2.2.2. Dependency checking

3. Debian

4. BSD

20. Software Design (legacy from design guide)

1. Database(s)
2. Interface construction
3. openca.cgi
4. libraries
5. modules
6. commands
7. Dataexchange and Node management

A. History

1. PKI Scenario before OpenCA

2. PKI and eGovernment

3. Internet Standards

4. The Project's Purposes

5. The Project's Achievements

6. The OpenCA Project

6.1. The project start
6.2. Offering Help to Other Projects: OpenSSL
6.3. CVS and Mailing Lists
6.4. The Open Source Choice
6.5. Migrating to SourceForge

B. References

1. Universities

C. Internationalization - i18n

1. de_DE
2. it_IT
3. ja_JP
4. pl_PL
5. sl_SI

D. Authors and Contributors

1. Martin Bartosch
2. Michael Bell
3. Chris Covell
4. Massimiliano Pala
5. Ulrich Bathels
6. Ashutosh Jaiswal
7. FAQ

E. FAQ

1. General PKI Issues

1.1. What is a certificate?
1.2. Which informations does a certificate contain?
1.3. What is a request?
1.4. Which information does a CSR contain?
1.5. What is a CA?
1.6. Why should I not place the CA on the same machine like the RA?
1.7. What is an extensions?
1.8. I use Windows 2000 and Internet Explorer 6 SP1 and it don't show any CSPs.
1.9. How can I setup a sub CA?

2. General OpenCA Issues

2.1. Does it be possible to revoke a certificate without any user interaction?
2.2. I try to add a role and get the message “The role XYZ exists already!”
2.3. All cryptographic operations fail.
2.4. Apache's error_log reports a nonexistent option -subj of openssl req
2.5. Apache's error_log contains a message from IBM DB2 that the environment is not setted
2.6. What do the new features of 0.9.2 be?
2.7. I try to approve and sign a request with Mozilla and it fails.
2.8. I try to approve and sign a request with Konqueror (KDE) and it fails.
2.9. How is the format of the disc to import the CA certificate from the root CA?
2.10. OpenSSL reports entry 1: invalid expiry date
2.11. Outlook cannot encrypt mail with imported certificate
2.12. My Outlook freezes after I received a signed email
2.13. General Error 6751 during certificate issuing
2.14. What does I have to do if I create a new release?
2.15. How can I configure Mozilla for OCSP?
2.16. Error 7211021: Cannot create request!

3. Installation Issues

3.1. FreeBSD, OpenBSD and OpenCA

3.1.1. make
3.1.2. install

3.2. Solaris and OpenCA

3.2.1. make

3.3. What is a hierarchy level?

3.4. Undefined subroutine &main::xyz

3.5. Symbolic link installaton failed

3.6. After the installation all common parts are missing

3.7. Conflicting Modules

3.8. The xml path to the access control is missing

3.9. Unknown Login Type

3.10. Type Mismatch during request generation with Internet Explorer

3.11. openca(_rc) start failed

3.12. Missing modules

3.12.1. XML::Parser

3.13. Trouble with databases, database drivers and Perl DBI

4. Configuration Issues

4.1. How can I configure my httpd.conf for virtual hosts?
4.2. How can I configure virtual hosts with ./configure?
4.3. I have some users which should not be published in LDAP. Does it be possible with OpenCA?
4.4. Does it be possible to authenticate users by their certificates at the apache before they will be authenticated by OpenCA itself?
4.5. I want to update my 0.9.2 installation. Is this dangerous?
4.6. I want update to 0.9.2. How can I update my sql database?
4.7. If I run openca-ocspd then I obtain a segmentation fault.
4.8. I installed a second public interface, run configure_etc.sh and now are all the paths in the other public interface wrong.
4.9. I issue a certificate for a mailserver but sendmail doesn't work and reports an errormessage which includes “reason=unsupported certificate purpose”
4.10. My (Microsoft) client hangs after it tries to start a secured connection
4.11. Outlook freezes when receiving a signed Mail but worked already fine for some days
4.12. During the request generation OpenCA fails and reports a too short textfield
4.13. Can I place my organization's logo on the web interface?
4.14. Cannot create new OpenCA tokenobject
4.15. How can I use a Luna token with OpenCA 0.9.1
4.16. How can I include a complete certificate chain into a PKCS#12 file?
4.17. Unknown login type
4.18. Cannot initialize cryptoshell but OpenSSL path is correct
4.19. Emailaddress in subjectAltName but not in CA subject
4.20. Missing environment variables from SSL
4.21. Problems with the country name during PKCS#10 requests

5. Access Control problems

5.1. Always get a login screen - again and again
5.2. Error 6251023: Aborting connection - you are using a wrong channel
5.3. Error 6251026: Aborting connection - you are using a wrong security protocol
5.4. Error 6251029: Aborting connection - you are using the wrong computer
5.5. Error 6251033: Aborting connection - you are using a wrong asymmetric cipher
5.6. Error 6251036: Aborting connection - you are using a too short asymmetric keylength
5.7. Error 6251039: Aborting connection - you are using a wrong symmetric cipher
5.8. Error 6251043: Aborting connection - you are using a too short symmetric keylength

6. Dataexchange

6.1. I try to export something but I get error 512 “permission denied” for /dev/fd0
6.2. I try to import the CA certificate but it doesn't work.
6.3. I crashed the database of the online server and now I want to import all data again. How can I do it?
6.4. I try to export the requests to the CA but it doesn't work

7. LDAP

7.1. Errormessage: Connection refused.
7.2. Errormessage: Bind failed. Errorcode 49.
7.3. The resultcode of the nodeinsertion was 65.
7.4. How can I get more debugging messages from OpenCA's LDAP code?
7.5. How can I get more debugging messages from OpenLDAP?

8. Internationalization

8.1. How can I fix a misspelling for a language?
8.2. How can I add a new language?
8.3. The compilation/make fails on the Perl module gettext
8.4. MySQL and SET NAMES errormessages

Bibliography

Glossary

F. Strategy

1. The Strategy Behind OpenCA Development

1.1. Scalability

1.2. Command Line API to CA and RA Functions

1.3. Automation functions

1.4. On-line CA model option

1.5. High Risk Environment Mode

1.6. Audit logging

1.7. Script/environment validation

1.8. Automated CA rollover

1.8.1. External and Internal CAs

1.8.2. Request processing

1.8.3. Dispatching requests to Internal CAs

1.8.3.1. Rollover requirement 1: automatic consideration of CA validity

1.8.3.2. Rollover requirement 2: request dispatch decision

1.8.3.2.1. CRL issuance
1.8.3.2.2. Certificate issuance
1.8.3.2.3. Certificate revocation
1.8.3.2.4. Certificate renewal

1.9. Function to process signing and encryption keys in one go

1.10. Secure storage and recovery of encryption keys

1.11. Web based OpenCA configuration and management

1.12. Improved key lifecycle management

1.13. Authentication via a third party

1.14. Improved debugging support

1.15. Improved error handling

1.16. Accreditation

List of Figures

1.1. Database oriented view
1.2. Logical data view
1.3. Complete technical overview
1.4. Life cycle of objects
4.1. Passes of the accesscontrol
4.2. Passphrase based login
4.3. Tokenconcept
7.1. Phases of the CA initialization
7.2. Phase I of the CA initialization
7.3. Phase II of the CA initialization
7.4. Phase III of the CA initialization
8.1. Request a certificate
11.1. Example cryptolayer with tokens
12.1. Passes of the accesscontrol
12.2. Channel verification
12.3. Identification of the user
12.4. Access control list
16.1. LDAP source schema

List of Tables

3.1. External Perl modules
3.2. Supported parameters for host configuration
4.1. Additional attributes configuration
4.2. Generic basic CSR configuration
4.3. Common stuff configuration
16.1. Schema usage
16.2. Schema usage for user certificates
18.1. Default OpenCA workflow
18.2. 1000 User test
E.1. Texttypes for different databases

List of Examples

3.1. Module ID calculation
4.1. channel configuration
4.2. Login and Passphrase configuration
4.3. External program authentication configuration
4.4. Authentication with certificates
4.5. Session configuration
4.6. Basic ACL configuration
4.7. Permission for serverInfo
4.8. Allow all
4.9. Configuration of HSM Login/logout in menu.xml
4.10. Configuration of token.xml for nCipher
4.11. OpenSSL configuration - Authority Key Identifier
4.12. Minimal SSL client extensions
4.13. Minimal SSL server extensions
4.14. Minimal SMTP extensions for a single certificate
4.15. Additional attributes configuration
4.16. PKCS#10 configuration
4.17. Basic CSR configuration
4.18. Configuration example for a XML file based HTML-select
4.19. suffix in ldap.xml
4.20. excluded roles in ldap.xml
4.21. Schema extension for RDN uid_special
4.22. Download configuration
4.23. Export configuration
4.24. Local export configuration
4.25. OpenCA rc script that sources Oracle environment
4.26.
4.27. /etc/mail/sendmail.mc
7.1. SSCEP configuration
8.1. OpenSSL 0.9.7 key usage and extended key usage for DCs
8.2. OpenSSL 0.9.7 subjectAltName for DCs
8.3. OpenSSL 0.9.7 certificate template name for DCs
8.4. OpenSSL 0.9.8 subject alternative name section for DCs
8.5. extendedKeyUsage for clients
18.1. batch_new_user.txt
18.2. batch_new_process.txt
18.3. batch_process_data.txt
19.1. SuSE packaging
E.1. General error 6751 during certificate issueing
E.2. Bad passphrase error log during certificate issueing
E.3. Error 7211021: Cannot create request!
E.4. Full errormessage for missing functions
E.5. Already present symbolic link
E.6. Search for XML::Twig modules
E.7. Type Mismatch on Internet Explorer
E.8. Failed startup with wrong Net::Server version
E.9. failing XML parsing during configuration
E.10. failing XML parsing during configuration
E.11. empty Twig.pm files because of missing XML::Parser
E.12. Too old DBD::Pg or DBI trouble
E.13. virtual host configuration
E.14. ./configure and virtual hosts
E.15. Client authentication with mod_ssl
E.16. OCSP configuration for LDAP
E.17. OCSP configuration for http
E.18. emailaddress for subjectAltName in CA certs
E.19. Missing mod_ssl standard environment variables
E.20. SSL environment variable configuration for Apache
E.21.
E.22. Failed request upload

		Next
		Introduction