xref: /test/ontest-stc2/src/suites/security/kmf

#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#

# 
# Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
# 
# ident	"@(#)README	1.4	08/03/13 SMI"
#

#
# README file for KMF STC2 test suite.
#

1.  INTRODUCTION
2.  SYSTEM REQUIREMENTS
3.  RUNNING TESTS
    3.1  Installing Test Suite and Tools Packages
    3.2  Configuring the Test System to Run the Test Suite
    3.3  Executing Tests and Examining Results
    3.4  Building Test Binaries from Source Code
4.  TEST COVERAGE
5.  NOTES
6.  CONTACT US


1.  INTRODUCTION

This test suite is a basic functionality test of the KMF (Key Management
Framework) library, and of the pktool(1) and kmfcfg(1) utilities.

This test suite uses STF, the second generation STC harness and operates
in the standard manner implemented by STF.  Please see the "STF User's
Guide" for more information on STF.


2.  SYSTEM REQUIREMENTS

This version of the KMF test suite requires build snv_74 or later of
Nevada.  The test suite can run on all architectures supported by
Solaris.

(STC_VERSION 1.8 and earlier versions of the KMF test suite require
build snv_73 or earlier).

The test suite needs 'root' user access to the local system and may
ask for the system root password to be provided for this.

Access to an external HTTP URL (and, depending on your network
and access to an HTTP proxy server) may be required for running 
the "kmf_download_cert" and "kmf_download_crl" tests.  See the 
NOTES section for details.


3.  TEST SUITE INSTALLATION AND EXECUTION

As stated previously, this suite uses the STF harness.  The following
packages are required to run this test:
	SUNWstc-stf: the STF harness and test tools
	SUNWstc-checkenv: the checkenv environment checking tool
	SUNWstc-kmf: this test suite

In addition, the SFWexpct (expect tool) package may be optionally
installed on the system (NOTE: as of snv_84, expect is installed in
/opt/sfw/bin by default).

3.1  Installing Test Suite and Tools Packages

To install the test suite (and the tools it depends on), first remove
any existing installation of the test suite or tools from the system 
and then install the new ones.  For example,

    # pkgrm SUNWstc-stf SUNWstc-checkenv SUNWstc-kmf
    # pkgadd -d <package-location> SUNWstc-stf
    # pkgadd -d <package-location> SUNswtc-checkenv
    # pkgadd -d <package-location> SUNWstc-kmf

where <package-location> refers to the PATH where the respective
packages reside.  The packages will be installed under /opt/<package-name>.

3.2  Configuring the Test System to Run the Test Suite

Before any tests can be executed, the target test system must first be
configured to run the test suite.  To do this, add the STF tools to your
PATH, tell STF where to find the checkenv tool, and run stf_configure.
All this must be done as a non-root user.  For example,

    $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    $ export STF_CHECKENV_PATH=/opt/SUNWstc-checkenv
    $ stf_configure

If you are prompted for the system root password, it MUST be provided,
or the configuration step will not succeed.

Depending on your network, you may additionally need to set and export
all the environment variables described in the NOTES section below.
These environment variables may be set in any one of the methods
supported by stf_configure.  See the STF User's Guide for details.

3.3  Executing Tests and Examining Results

To execute the tests, the 'stf_configure' step must have passed without
error.  Once again, as a non-root user, add STF tools to your PATH, and
tell STF where to find checkenv.  Then invoke stf_execute.  For example,

    $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    $ export STF_CHECKENV_PATH=/opt/SUNWstc-checkenv
    $ stf_execute

Normally this test suite is finished in about 50 minutes on Sun-Fire-V240.

Overrideable configuration variables provided in the stf_configure phase
may be overridden using 'stf_execute -c'.  For details of the '-c'
option and more, see the STF User's Guide.

The results of test execution will be at /var/tmp/SUNWstc-kmf/results.
Detailed journaling output is placed in files named "journal.*" in the
results directory (see the STF User's Guide on how to override journal
file or results directory names.)  stf_execute also prints execution
status summary to the terminal whence it was invoked.

The stf_filter utility can be used to see a summary of test results,
like so:

    $ stf_filter <journal_file_name>

The output from stf_filter is a two column list of executed test cases
and their final result upon completion.

3.4  Building Test Binaries from Source Code

Executing tests using precompiled test suite packages is the method we
strongly recommend.  However, if, for some reason, you need to build
test suite binaries from source, simply do the following:

    . Install STF
    . Obtain the test suite source
    . Invoke stf_build followed by stf_build package

(a)  Install STF

Install the precompiled STF package.

    # pkgrm SUNWstc-stf
    # pkgadd -d <package-location> SUNWstc-stf

where <package-location> is the location of the SUNWstc-stf package.
While it is possible to build STF also from source code, describing
that is beyond the scope of this README.

(b) Obtain the Test Suite Source

Obtain the test suite source using source code management commands
(TeamWare, Hg, ...) or by other methods such as extracting a tarball,
exploding a cpio file, etc.  The example below assumes that TeamWare
is used and that the test suite source code resides in a workspace 
named "/gates/onnv-stc2"

    $ workspace create `pwd`/kmftest
    $ workspace parent -p /gates/onnv-stc2 -w `pwd`/kmftest
    $ cd kmftest
    $ bringover src/suites/security/kmf

(c) Build Test Suite Binaries

    $ umask 0  # optional, recommended
    $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    $ cd src/suites/security/kmf
    $ stf_build
    ...
    ... (many lines of 'make' and shell output ensue)
    ...

The above command, if successful, will build the KMF test suite's
'proto' directory.

    $ stf_build package

This will build the package supported by the current machine's system
architecure (i.e., if building on an x64 system, packages relevant to
the "i386" architecture will be built.)

Once the test suite package has been built, install the package as
indicated in the preceding section(s) and execute tests as described.


4. TEST COVERAGE

The KMF project provides a single programming interface, a unified set
of administrative tools, and a policy enforcement system on PKCS#11, NSS
and OpenSSL keystore.

This test suite covers following KMF library tests on PKCS#11, NSS and
OpenSSL keystore:
  - Positive tests of KMF library key-, certficiate-, crl-, csr- and
    policy-related APIs.  Tests in this category are located at
    tests/kmf_api/kmf_positive
  - Multi-threaded stress tests of the KMF library.  Tests in this
    category are located at tests/kmf_api/kmf_stress
  - Negative tests of all KMF APIs.  Tests in this category are located
    at tests/kmf_api/kmf_* (i.e., all subdirectories of tests/kmf_api,
    kmf_positive and kmf_stress)

This test suite covers following usage of the pktool(1) command:
  - listing all visible PKCS#11 and NSS tokens
  - setting the passphrase to the PKCS#11 or NSS token
  - generating public keypairs and self-signed certificates
  - generating an asymmetric keypair and a CSR file
  - generating symmetric keys
  - listing certificates, keys and CRLs
  - deleting certificates, keys and CRLs
  - importing certificates, keys and CRLs
  - exporting PKCS12, pem or der files that contain certificates or keys
  - downloading certificates or CRLs from a webbased services
  - displaying help information
Tests in this category are located under tests/pktool

This test suite covers following usage of the kmfcfg(1) command:
  - listing policies
  - deleting policies
  - creating policies
  - modifying policies
  - importing policies
  - exporting policies
  - displaying help information
  - pluggability configure
Tests in this category are located under tests/kmfcfg


5. NOTES

The kmf_download_cert and kmf_download_crl tests (under tests/kmf_api)
are designed to download certificate/crl files from an external HTTP URI.
This test suite provides a default URI and a proxy server to be used by
these tests, but if these defaults are not appropriate for the system
under test, the kmf_download_cert and kmf_download_crl tests will fail.
If this happens, set the following variables and re-run stf_configure:

. KMF_CERTURI -- URI whence to download certificates
. KMF_CRLURI -- URI whence to download crls
. KMF_PROXY_SET -- whether a proxy server is required
. KMF_PROXY -- proxy server.  Makes sense only if KMF_PROXY_SET is set. 
. KMF_PROXY_PORT -- proxy port.   Makes sense only if KMF_PROXY_SET
  is set and KMF_PROXY is non-null.

For example:
    $ export KMF_PROXY_SET=1
    $ export KMF_PROXY=webcache.sfbay
    $ export KMF_PROXY_PORT=8080

These variables may also be set during the stf_execute step using the
'-c' switch.  See the STF User's Guide for details.

8. CONTACT US

If you want to contact us, please e-mail the STC_CONTACT listed in the
STC.INFO.  Your feedback is greatly appreciated.  To file a bug or an
RFE against the suite, please use the stc/security/kmf subcategory.