000021382 - More than OneStep Installation Guide

Document created by RSA Customer Support Employee on Jun 16, 2016Last modified by RSA Customer Support Employee on Apr 21, 2017
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000021382
Applies ToKeon Certificate Authority OneStep 6.5.1
IssueMore than OneStep Installation Guide
How to install and configure Keon OneStep
ERROR in browser during OneStep Enrollment: Unable to process request (possibly bad server parameter)

[error] Cannot open SSLSessionCache DBM file '/RSA_KeonCA/WebServer/logs/ssl_scache' for writing (store)

Resolution

What to expect from this document

This document is intended as an installation and configuration guide for BASIC OneStep configurations. As the name implies this is intended to be more detailed than the usual installation guide. As it also implies this is not simply running an installation.  Your environment may differ from these instructions as your server profile and security settings dictate. Please use this document as a reference to base your configuration.

 

It is highly recommended that you follow these instructions explicitly to get the Flat File Demo to successfully run. Once the basic configuration is confirmed via the demo, you can go on to configure and test other modules and configurations. If you follow this suggestion you will be secure in the knowledge that you have a known good reference configuration, and an understanding of the basic requirements.

 

For more information please contact RSA Security Technical Support or the support services of your 3rd party software vendor.

Before you begin

This document is written with the assumption that you have a working KCA 6.5.1 Server.

You will need to get SSL certificates from that KCA in this procedure. The OneStep program is a certificate request, generation, and distribution mechanism for the KCA

Supported System Requirement Under Windows NT or Windows 2000

? Windows NT Server 4.0 with Service Pack 6a and any critical updates, or

Windows 2000 Server Series with Service Pack 4 and any critical updates.

 

Supported System Requirement Under Solaris

? Sun Solaris 7 or 8 Operating System software.

 

Overview Of How It Works ( This Will Help Greatly! )

OneStep allows users to request a personal certificate through a web browser, the certificate is automatically approved, and retrieved in a single operation. This functionality is provided through an executable plug-in to the web server

 

The installation of OneStep is performed by either using a file/directory structure which was installed along with KCA or KRA, or that file/directory structure can be installed stand alone. A web server is required on the OneStep system since this is a web based application.

 

Files will need to be manually moved from the samples directory to the operational directories.

 

If installing stand alone, simply un-package the files to a location, which you will consider your installation directory.

 

Configure the appropriate files, and request an SSL Certificate from the CA using a command line utility on the OneStep system.

 

Approve the Certificate on the CA, and retrieve the certificate using the same command line utility on the OneStep server.

 

Configure the Web Server to point to the htmldocs directory in the OneStep, and to point to the CGI-Bin directory.  In IIS allow the index.html to be a default document.

Test your installation.

 

  

Installation And Configuration

 

There are three possible first steps.   Please select either:

1                                 In A directory pre-installed with a CA or RA

  1. Alternate A          In a different directory on a CA or RA System

1.  Alternate B   On a separate system. Using the install package from CDROM.

Installing The OneStep CGI Application

1. To install on a KCA or KRA using the pre-installed directory:

 

Locate the directory /RSAKeonCA/WebServer/OneStep  on your KCA or KRA Operating System.

 

 

1. Alternate A ? To install to a directory of your own choosing on the same system as the KCA or KRA, or to install to a separate Operating System which has an installed Web Server:

 

Copy the OneStep Subdirectory and all of its contents from the KCA or KRA to the desired location.

 

1. Alternate B ? To install to a directory of your own choosing on the same system as the KCA or KRA, or to install to a separate Operating System which has an installed Web Server:

 

      From your CDROM copy the RSAKeonOneStep-6.5.1build208r-sparc-sun-solaris.tar archive to a working directory on your system. Extracting the archive will create a directory called OneStep.

 

Bonus Note:

Please note that the default installation and  the archive do not include the Graphical Images for the default templates. To download these files, user the URL below to retrieve them.

 

ftp://ftp.rsasecurity.com/support/keon/how-to/graphics.zip

 

 

These files have no effect on operation, they are just window dressing.

 

 

2. Copy files from the OneStep/samples directory to be used with your OneStep installation.

 

Copy From

Copy To

/RSAKeonCA/WebServer/OneStep/samples/htmldocs/*

 

For Standalone:    /OneStep/samples/htmldocs/*

 

OneStep/htmldocs/*

/RSAKeonCA/WebServer/OneStep/samples/data/*

 

For Standalone:    /OneStep/samples/data/*

 

OneStep/conf/*

/RSAKeonCA/WebServer/OneStep/samples/*.so or *.dll

 

For Standalone:    /OneStep/samples/*.so or *.dll

 

OneStep/plugins/*.so or *.dll

 

 

3. Set File permissions and Ownership of all OneStep files so that they can be accessed and executed by Web Server. Please pay special attention to this detail, as this is the most common issue encountered by RSA customers when implementing Keon OneStep.

 

On Solaris:

The OneStep files MUST have the same file owner as the Web Server docs directory and files. In addition the OneStep cgi script must have execute permissions as seen in the example below.

E.g.

/usr/iplanet/servers/docs

-rw-r--r-- 1 nobody nobody 1042 Oct 1 00:56 banner.html

-rw-r--r-- 1 nobody nobody 280 Oct 1 00:56 index.html

-rw-r--r-- 1 nobody nobody 6929 Oct 1 00:56 launch.html /opt/OneStep/cgi-bin:

-r-x------ 1 nobody nobody 5043144 Sep 30 21:03 onestep

 

To set these permissions use the following command from the directory containing the OneStep installation.

chown ?R user:group OneStep

chmod ?R 500 OneStep

 

 

 

Configuring  The SSL And Obtaining SSL Certificates

 

4. Moving to the OneStep/setup directory edit the file called setupSSL.conf. The layout of this file should be as follows. Update the values indicated in red to reflect your configuration. The Date and time acts as a high water mark and should be updated for each request made.

 

# The hostname or IP address where KCA is running

 

serverHost 192.168.131.62

 

# The non-SSL port number where KCA is running

 

serverPort 389

 

# The request-source used to identify the request at the KCA

# installation. It *MUST* be unique for each request, and it

# should have the following format:

# RSAKeonOneStep:<KCA-target-hostname>:<OneStep-server-hostname>[:<date>[,<time>]]

# It *MUST* begin with "RSAKeonOneStep".

 

ssl-RS

RSAKeonOneStep: YOUR.ONESTEP.FQDN:YOUR.CA.FQDN:9/26/2004,16:40:19

 

# Do **NOT** modify the following value. KCA requires this

# exact CN to assign correct LDAP ACL rules for OneStep SSL

# certificates.

ssl-CN OneStep Client

# The following parameters may be used to add to the subjectDN of

# the OneStep SSL certificate.

#ssl-OU Organizational Unit

#ssl-O Organization

#ssl-C 2-letter country code

# The following value specifies the certificate key size in bits.

ssl-keySize 1024

# By default, software keys are generated. Uncomment to generate

OneStep installation and Configuration Guide for iPlanet Web Server

# hardware keys. You must specify a passphrase using the -p option

# on the command line when generating a hardware key.

# The setupSSL utility only supports nFast hardware using RSA-SHA1.

#ssl-cryptoType "nFast;RSA;SHA1;"

# Do not modify the following values unless instructed to do so

# by RSA Customer Support.

ssl-keyFile ssl/private/onestep.key

ssl-certFile ssl/certs/onestep.cert

#END OF FILE EXAMPLE

 

Once this information is modified appropriately save the file as setupSSL.conf

 

 

5. From the OneStep/setup directory run the following command

setupSSL ?d2 ?request setupSSL.conf

 

This will request an administrative certificate for the OneStep installation from your KCA Server.

 

 

6. From the KCA Admin interface, approve the OneStep certificate from the Administrative Operations Workbench  Installation  request-active queue. During the approval of the certificate you will be asked to set the ACL entry for the jurisdiction that the OneStep will issue certificates from.

 

Error Note:

Error: "specified jurisdiction not found or invalid"

OneStep Internal Error displayed

OneStep is not able to connect to the Keon CA Secure Directory server.  This will happen if the OneStep SSL certificate request was approved from the Certificate Operations workbench.

The OneStep SSL certificate request must be approved from the "request-active" list in the Installation field of the Administrator Operations workbench in order for it to be applied to the Keon CA Secure Directory server's ACL rules.  Be sure to issue the request with the same jurisdiction that will be used for OneStep requests.

 

Error Note:

Keon OneStep fails with internal error while going through certificate enrollment process

Error: "error 1350-  Internal one step error" while going through Keon OneStep enrollment process

The KCA OneStep can not access the KCA backend

The KCA SSL certificates used by Keon OneStep to access the KCA needs to be issued by the proper Jurisdiction that is configured in Keon OneStep conf file. See the Keon OneStep Developer's Guide available at SecurCare Online's Documentation Center for further details.

 

 

 

7. From the OneStep/setup directory run the following command

 

setupSSL ?d2 ?retrieve setupSSL.conf

 

This will retrieve the administrative certificate from your KCA Server and place them in the appropriate directories to be used by OneStep.

 

Configuring  OneStep For Enrollment

 

8. Modify the OneStep/conf/onestep.conf file to reflect KCA information as follows.

 

# The hostname or IP address where KCA is running

# If OneStep is running on the same machine as KCA,

# and if you use the Microsoft Exchange functionality with KKRM,

# then you must specify the Fully Qualified Domain Name (FQDN)

# of the host name, or its IP address (you must not use either '127.0.0.1' or 'localhost')

 

camachine OneStep.ok.com

 

# The SSL port number where KCA is running

 

caport 636

 

# The enroll port number where KCA is running

 

enrollport 443

 

# The paths to the SSL certificate and key files, relative to

# OneStep/cgi-bin/onestep file

sslcert ../ssl/certs/onestep.cert

 

OneStep installation and Configuration Guide for iPlanet Web Server

sslkey ../ssl/private/onestep.key

 

 

Bonus Note:

Enabling the use of Profiles

1. From the CA Operations Workbench "View CA" page (of your CA) under "Jurisdiction Configuration", select the Jurisdiction you will be using and click "Configure"
2. In the Jurisdiction configuration "Extension Profiles" section, check the "Enforce Profile Definition" checkbox
 - The "Requestor Can Select" and "Vettor Can Override" checkboxes have no meaning for the OneStep CGI, only for manual enrollment & vetting
3. In the "Profile Choices" selection box, select the Profile(s) you want to be able to use for this Jurisdiction
4. In OneStep/conf/flatdemo.conf, add a "profile" parameter line. Here's an example:

  jurisdiction OneStep
  profile "S/MIMEv3 User"

This example shows certificate issued under the OneStep Jurisdiction by the OneStep CGI, will use S/MIME profile.

Notes:

1. If you specify a Profile to the OneStep CGI, but that Profile is not selected in the "Profile Choices" select box, the CGI will return KCSOSE_PROFILE
2. If the "Enforce Profile Definition" checkbox is checked, but no Profile is specified to the CGI, it will return KCSOSE_PROFILE
3. If the "Enforce Profile Definition" checkbox is NOT checked, and a Profile is specified to the CGI, behavior is undefined. In face, the Profile will NOT be enforced on the certificates.
Profiles are referenced on page 26, 41, 47, and 64 of the RSA Keon OneStep Developers Guide. The flatfile demo specifics are on page 64.

Additional Note:

If a Profile is selected and needs to be enforced, make sure the default values for the selected extensions have been set. For example, if SKI and AKI are selected, all is fine as these extension values are automatically generated when issuing certificates. However, for KeyUsage, the required values may need to be set before a certificate can be automatically issued with those values.

 

 

9. Configure your Web Server to allow access to the OneStep files.

 

For example:

 

In IIS Web server Admin, created a Virtual Directory named OneStep pointing to c:\OneStep\htmldocs folder.


Click on the OneStep Virtual Directory and create another Virtual Directory within it called cgi-bin, pointing it to c:\OneStep\cgi-bin folder

In IIS Web Server Admin allow the index.html to be a default document, by right mouse clicking the Virtual server icon for the OneStep htmldocs folder, select the documents tab, click add, type in index.html, click OK.

 

Configuring the Keon OneStep CGI Program and Web Server

1. Verify that the OneStep/conf/onestep.conf file contains the parameters needed to connect to your  Keon CA installation.

2. Depending on your setup:

a. For Keon CA or Keon RA, configure the Enrollment Server virtualhost in WebServer/conf/httpd.conf by removing the leading #s in the following lines:

###
# Keon OneStep CGI directives
###

#ScriptAlias /OneStep/cgi-bin "<installed-dir>\WebServer\OneStep\cgi-bin"

#Alias /OneStep "<installed-dir>\WebServer\OneStep\htmldocs"

#<Directory "<installed-dir>\WebServer\OneStep\cgi-bin">

# Options None

# AllowOverride None

#</Directory>

#<Directory "<installed-dir>\WebServer\OneStep\htmldocs">

# Options None

# AllowOverride None

#</Directory>

 

10. WebServer\OneStep\Conf\onestep.conf should have the proper port specifications. Verify this if not using default ports 636 and 443.

 

11. WebServer\OneStep\Conf\flatdemo.conf should have the value of the desired jurisdiction name. The file defaults to OneStep. Please note that even if you create a self-signed jurisdiction named OneStep, you will mismatch the jurisdiction by default. This occurs because the KCA appends ??s initial jurisdiction? to the end of the initial jurisdiction by default. You must then to KCA Administration Console > CA Operations > Select the desired Jurisdiction Certificate > Configure > Under General Information in red, Edit the value of Jurisdiction Name to make the jurisdiction name what you literally desire.

 

Bonus Note:

Certificates issued by Keon OneStep have default validity period of one year

By default, Keon OneStep sample code is set to issue certificates with a default validity date of one year. This validity period can be changed by modifying the source HTML of the request page in the following manner.

Within the form tag you will find several hidden input tag objects with variables assigned to them:

<FORM METHOD=POST NAME="OneStepEnroll" ACTION="/OneStep/cgi-bin/onestep">

... HTML Code & objects ...


Add the following INPUT tag to your Form to change the Validity Period of the certificates issued by Keon OneStep:

<INPUT TYPE="HIDDEN" NAME="KCSOSD_VALIDITY" VALUE="CALCULATION_VALUE">

... HTML Code ...

</FORM>


The KCSOSD_VALIDITY function determines the validity date calculated in seconds. You will have to make a calculation prior to modifying the value, then replace the CALCULATION_VALUE with the total seconds of the validity period, e.g. of calculation defining one year validity period in seconds (e.g., 365 * 24 * 60 * 60 = 3153600 = one year).

 

 Enrollment Using The Flatdemo

 

12. WebServer\OneStep\Conf\flatdemo\data contains the data used to authorize users to request certificates through OneStep. This  file acts as a simple substitution for the role which would be played by the LDAP Plugin and other Plugins.

 

 

The fields have the following format

 

UserID:Password:Locality:Jurisdiction:Name: Email Address:


 UserID is the Users login ID this must match

The default values supplied are  ajones through ejones

 

Password is the users password for authentication

The default values supplied are password1 through password 5 for the various joneses.

 

Locality is a value which is requested on the enrollment form.

The default is Sample

 

Jurisdiction Name is the Jurisdiction the enrollment is to occur to.

This must literally match the Jurisdiction you have configured OneStep to use. 

 

Email Address is the Email Address of the user.

 

Error Note:

Error: "Failed to initialize plug-in..." in KCA OneStep

One Step process fails, user certificate is not created

The flat file containing the users allowed to auto enroll via One Step contains a non-printable character such as carriage return (CR)

To correct this issue, remove non-printable characters from the flat file.



 

13. It is not necessary to enable Auto-vetting for OneStep.

 

14. Test.

Go to the URL that you have established as the OneStep URL.

For instance http://OneStep:80/OneStep

 

You will be presented with the OneStep Certificate Enrollment page.

 

Select the Flat file link.

 

Enter Username Password and Locality.

 

Select an appropriate Cryptographic Provider

For Example: Microsoft Strong Cryptographic Provider.

 

Press Accept. You should now receive a certificate.

 

The following errors occur due to an inconsistantly configured Jurisdiction Name.

ERROR in browser during OneStep Enrollment: Unable to process request (possibly bad server parameter)

Error in enrollment logs: [error] Cannot open SSLSessionCache DBM file '/RSA_KeonCA/WebServer/logs/ssl_scache' for writing (store)

 

 

Error: "Profile inconsistent with Jurisdiction, or profile enforcement failed" when issuing certificate through Keon OneStep

How to assign a default Extended Key Usage extension to certificates issued through Keon OneStep

Keon Certificate Authority 6.0.2 Build 113

Keon OneStep

Solaris 8

When "Extended Key Usage" is set to Mandatory in an extension profile, and Enforce Profile Definition is enabled for the jurisdiction, the following error shows up in the browser: "Profile inconsistent with Jurisdiction, or profile enforcement failed".



 

Legacy Article IDa23028

Attachments

    Outcomes