Cross Reference: /test/stcnv/usr/src/suites/security/kmf/README

#
# 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 2009 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.10	09/09/03 SMI"
#

#
# README file for the KMF 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 test suite requires snv_123 or newer of Nevada.
This test suite can run on all architectures supported by Solaris.

STC_VERSION 1.8 and earlier of the KMF test suite require snv_73
or earlier.  Versions 1.8 through 2.10 require snv_74 or later,
but not newer than snv_103.

Special requirements for running this test suite on systems with a TPM device,
e.g. Ultra 40 M2, T5120/5220/5140/5240, etc.:
1. STC_VERSION 2.16 or higher of the KMF test suite.
2. Snv_123 or newer of Nevada.
3. The TCG option must be enabled in the BIOS (x86) or ILOM  pre-boot
   environment (sun4v) of systems with a TPM device before installing
   OS snv_123 or newer. Moreover, for sun4v system, a latest firmware
   is required to be installed to enable TPM functionalities,
4. SUNWtpm, SUNWtss, SUNWtss-root may be installed. They can be found at:

SUNWtpm - /ws/onnv-gate/packages/$(uname -p)/snv_*{-nd}
SUNWtss & SUNWtss-root - /ws/sfwnv-gate/packages/$(uname -p)/sfwnv_*-{nd}

After installing SUNWtpm, a "reboot -- -r" may be required if /dev/tpm is
not attached.
5. After installing required packages, the 'tcsd' service must be enabled and
running. If not, enable it via "svcadm enable -s tcsd".
6. TPM device must be owned. Check via "/usr/bin/tpmadm status", if not owned,
issue the "tpmadm init" command and set the owner password to "87654321".
7. The PKCS#11 TPM token pkcs11_tpm.so must be installed. Check via
"/usr/sbin/cryptoadm list -p | grep pkcs11_tpm.so", if not installed, install
it via "cryptoadm install provider=/usr/lib/security/\$ISA/pkcs11_tpm.so"

The requirements 1, 2 & 3 are prerequisite while 4, 5, 6 & 7 are optional as
they can be done automatically during Solaris installation and stf_configure.
For step 6, if owned, before stf_configure, the variable TPM_OWNER_SECRET must
be exported and set to the TPM owner password, which was specified when the TPM
was initialized. Otherwise, it will cause execution failure due to
authentication error of incorrect owner password.

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-security-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 and by far expect is installed in /usr/bin by default).
Before snv_122, there is a bug in /usr/bin/expect that cause
$CODEMGR_WS/usr/src/suites/security/kmf/tests/pktool/pktool_077 to fail due to
timeout, see CR 6870647.


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,

    root# pkgrm SUNWstc-stf SUNWstc-checkenv SUNWstc-security-kmf
    root# pkgadd -d <package-location> SUNWstc-stf
    root# pkgadd -d <package-location> SUNWstc-checkenv
    root# pkgadd -d <package-location> SUNWstc-security-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.
But on systems with a TPM device, e.g. T5120 (sun4v), it will take about
more than 4 hours to finish executing the test suite in all modes (tpm:sparc
tpm:sparcv9 sparc sparcv9). In order to let test suite run on these systems,
we add tpm:* modes and test cases $CODEMGR_WS/usr/src/suites/security/kmf/
tests/pktool/pktool_{079, 080, 081 & 082}.ksh that only run in tpm:* modes.
The pktool_081 may take about a long time to finish in tpm:* modes so we
reset variable STF_TIMEOUT from 600s(default) to 1800s in $CODEMGR_WS/usr/src/
suites/security/kmf/config.vars in case it be killed by STF due to timeout.

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.

Test results will be placed at /var/tmp/SUNWstc-security-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.

    root# pkgrm SUNWstc-stf
    root# 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/stcnv-gate"

    $ workspace create `pwd`/kmftest
    $ workspace parent -p /gates/stcnv-gate -w `pwd`/kmftest
    $ cd kmftest
    $ bringover usr/src/suites/security/kmf

(c) Build Test Suite Binaries

    $ umask 0  # optional, recommended
    $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    $ cd usr/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
  - Initialize a PKCS11 token
  - 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 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. It's required if
		   your test system can't directly connect to URI specified
		   by KMF_CERTURI & KMF_CRLURI.
. 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=<the name of proxy server in format like www.proxy.com>
    $ 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.