Home | History | Annotate | Download | only in kmf
      1 #
      2 # CDDL HEADER START
      3 #
      4 # The contents of this file are subject to the terms of the
      5 # Common Development and Distribution License (the "License").
      6 # You may not use this file except in compliance with the License.
      7 #
      8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
      9 # or http://www.opensolaris.org/os/licensing.
     10 # See the License for the specific language governing permissions
     11 # and limitations under the License.
     12 #
     13 # When distributing Covered Code, include this CDDL HEADER in each
     14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
     15 # If applicable, add the following below this CDDL HEADER, with the
     16 # fields enclosed by brackets "[]" replaced with your own identifying
     17 # information: Portions Copyright [yyyy] [name of copyright owner]
     18 #
     19 # CDDL HEADER END
     20 #
     21 
     22 # 
     23 # Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
     24 # Use is subject to license terms.
     25 # 
     26 # ident	"@(#)README	1.4	08/03/13 SMI"
     27 #
     28 
     29 #
     30 # README file for KMF STC2 test suite.
     31 #
     32 
     33 1.  INTRODUCTION
     34 2.  SYSTEM REQUIREMENTS
     35 3.  RUNNING TESTS
     36     3.1  Installing Test Suite and Tools Packages
     37     3.2  Configuring the Test System to Run the Test Suite
     38     3.3  Executing Tests and Examining Results
     39     3.4  Building Test Binaries from Source Code
     40 4.  TEST COVERAGE
     41 5.  NOTES
     42 6.  CONTACT US
     43 
     44 
     45 1.  INTRODUCTION
     46 
     47 This test suite is a basic functionality test of the KMF (Key Management
     48 Framework) library, and of the pktool(1) and kmfcfg(1) utilities.
     49 
     50 This test suite uses STF, the second generation STC harness and operates
     51 in the standard manner implemented by STF.  Please see the "STF User's
     52 Guide" for more information on STF.
     53 
     54 
     55 2.  SYSTEM REQUIREMENTS
     56 
     57 This version of the KMF test suite requires build snv_74 or later of
     58 Nevada.  The test suite can run on all architectures supported by
     59 Solaris.
     60 
     61 (STC_VERSION 1.8 and earlier versions of the KMF test suite require
     62 build snv_73 or earlier).
     63 
     64 The test suite needs 'root' user access to the local system and may
     65 ask for the system root password to be provided for this.
     66 
     67 Access to an external HTTP URL (and, depending on your network
     68 and access to an HTTP proxy server) may be required for running 
     69 the "kmf_download_cert" and "kmf_download_crl" tests.  See the 
     70 NOTES section for details.
     71 
     72 
     73 3.  TEST SUITE INSTALLATION AND EXECUTION
     74 
     75 As stated previously, this suite uses the STF harness.  The following
     76 packages are required to run this test:
     77 	SUNWstc-stf: the STF harness and test tools
     78 	SUNWstc-checkenv: the checkenv environment checking tool
     79 	SUNWstc-kmf: this test suite
     80 
     81 In addition, the SFWexpct (expect tool) package may be optionally
     82 installed on the system (NOTE: as of snv_84, expect is installed in
     83 /opt/sfw/bin by default).
     84 
     85 3.1  Installing Test Suite and Tools Packages
     86 
     87 To install the test suite (and the tools it depends on), first remove
     88 any existing installation of the test suite or tools from the system 
     89 and then install the new ones.  For example,
     90 
     91     # pkgrm SUNWstc-stf SUNWstc-checkenv SUNWstc-kmf
     92     # pkgadd -d <package-location> SUNWstc-stf
     93     # pkgadd -d <package-location> SUNswtc-checkenv
     94     # pkgadd -d <package-location> SUNWstc-kmf
     95 
     96 where <package-location> refers to the PATH where the respective
     97 packages reside.  The packages will be installed under /opt/<package-name>.
     98 
     99 3.2  Configuring the Test System to Run the Test Suite
    100 
    101 Before any tests can be executed, the target test system must first be
    102 configured to run the test suite.  To do this, add the STF tools to your
    103 PATH, tell STF where to find the checkenv tool, and run stf_configure.
    104 All this must be done as a non-root user.  For example,
    105 
    106     $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    107     $ export STF_CHECKENV_PATH=/opt/SUNWstc-checkenv
    108     $ stf_configure
    109 
    110 If you are prompted for the system root password, it MUST be provided,
    111 or the configuration step will not succeed.
    112 
    113 Depending on your network, you may additionally need to set and export
    114 all the environment variables described in the NOTES section below.
    115 These environment variables may be set in any one of the methods
    116 supported by stf_configure.  See the STF User's Guide for details.
    117 
    118 3.3  Executing Tests and Examining Results
    119 
    120 To execute the tests, the 'stf_configure' step must have passed without
    121 error.  Once again, as a non-root user, add STF tools to your PATH, and
    122 tell STF where to find checkenv.  Then invoke stf_execute.  For example,
    123 
    124     $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    125     $ export STF_CHECKENV_PATH=/opt/SUNWstc-checkenv
    126     $ stf_execute
    127 
    128 Normally this test suite is finished in about 50 minutes on Sun-Fire-V240.
    129 
    130 Overrideable configuration variables provided in the stf_configure phase
    131 may be overridden using 'stf_execute -c'.  For details of the '-c'
    132 option and more, see the STF User's Guide.
    133 
    134 The results of test execution will be at /var/tmp/SUNWstc-kmf/results.
    135 Detailed journaling output is placed in files named "journal.*" in the
    136 results directory (see the STF User's Guide on how to override journal
    137 file or results directory names.)  stf_execute also prints execution
    138 status summary to the terminal whence it was invoked.
    139 
    140 The stf_filter utility can be used to see a summary of test results,
    141 like so:
    142 
    143     $ stf_filter <journal_file_name>
    144 
    145 The output from stf_filter is a two column list of executed test cases
    146 and their final result upon completion.
    147 
    148 3.4  Building Test Binaries from Source Code
    149 
    150 Executing tests using precompiled test suite packages is the method we
    151 strongly recommend.  However, if, for some reason, you need to build
    152 test suite binaries from source, simply do the following:
    153 
    154     . Install STF
    155     . Obtain the test suite source
    156     . Invoke stf_build followed by stf_build package
    157 
    158 (a)  Install STF
    159 
    160 Install the precompiled STF package.
    161 
    162     # pkgrm SUNWstc-stf
    163     # pkgadd -d <package-location> SUNWstc-stf
    164 
    165 where <package-location> is the location of the SUNWstc-stf package.
    166 While it is possible to build STF also from source code, describing
    167 that is beyond the scope of this README.
    168 
    169 (b) Obtain the Test Suite Source
    170 
    171 Obtain the test suite source using source code management commands
    172 (TeamWare, Hg, ...) or by other methods such as extracting a tarball,
    173 exploding a cpio file, etc.  The example below assumes that TeamWare
    174 is used and that the test suite source code resides in a workspace 
    175 named "/gates/onnv-stc2"
    176 
    177     $ workspace create `pwd`/kmftest
    178     $ workspace parent -p /gates/onnv-stc2 -w `pwd`/kmftest
    179     $ cd kmftest
    180     $ bringover src/suites/security/kmf
    181 
    182 (c) Build Test Suite Binaries
    183 
    184     $ umask 0  # optional, recommended
    185     $ export PATH=/opt/SUNWstc-stf/bin/`uname -p`:$PATH
    186     $ cd src/suites/security/kmf
    187     $ stf_build
    188     ...
    189     ... (many lines of 'make' and shell output ensue)
    190     ...
    191 
    192 The above command, if successful, will build the KMF test suite's
    193 'proto' directory.
    194 
    195     $ stf_build package
    196 
    197 This will build the package supported by the current machine's system
    198 architecure (i.e., if building on an x64 system, packages relevant to
    199 the "i386" architecture will be built.)
    200 
    201 Once the test suite package has been built, install the package as
    202 indicated in the preceding section(s) and execute tests as described.
    203 
    204 
    205 4. TEST COVERAGE
    206 
    207 The KMF project provides a single programming interface, a unified set
    208 of administrative tools, and a policy enforcement system on PKCS#11, NSS
    209 and OpenSSL keystore.
    210 
    211 This test suite covers following KMF library tests on PKCS#11, NSS and
    212 OpenSSL keystore:
    213   - Positive tests of KMF library key-, certficiate-, crl-, csr- and
    214     policy-related APIs.  Tests in this category are located at
    215     tests/kmf_api/kmf_positive
    216   - Multi-threaded stress tests of the KMF library.  Tests in this
    217     category are located at tests/kmf_api/kmf_stress
    218   - Negative tests of all KMF APIs.  Tests in this category are located
    219     at tests/kmf_api/kmf_* (i.e., all subdirectories of tests/kmf_api,
    220     kmf_positive and kmf_stress)
    221 
    222 This test suite covers following usage of the pktool(1) command:
    223   - listing all visible PKCS#11 and NSS tokens
    224   - setting the passphrase to the PKCS#11 or NSS token
    225   - generating public keypairs and self-signed certificates
    226   - generating an asymmetric keypair and a CSR file
    227   - generating symmetric keys
    228   - listing certificates, keys and CRLs
    229   - deleting certificates, keys and CRLs
    230   - importing certificates, keys and CRLs
    231   - exporting PKCS12, pem or der files that contain certificates or keys
    232   - downloading certificates or CRLs from a webbased services
    233   - displaying help information
    234 Tests in this category are located under tests/pktool
    235 
    236 This test suite covers following usage of the kmfcfg(1) command:
    237   - listing policies
    238   - deleting policies
    239   - creating policies
    240   - modifying policies
    241   - importing policies
    242   - exporting policies
    243   - displaying help information
    244   - pluggability configure
    245 Tests in this category are located under tests/kmfcfg
    246 
    247 
    248 5. NOTES
    249 
    250 The kmf_download_cert and kmf_download_crl tests (under tests/kmf_api)
    251 are designed to download certificate/crl files from an external HTTP URI.
    252 This test suite provides a default URI and a proxy server to be used by
    253 these tests, but if these defaults are not appropriate for the system
    254 under test, the kmf_download_cert and kmf_download_crl tests will fail.
    255 If this happens, set the following variables and re-run stf_configure:
    256 
    257 . KMF_CERTURI -- URI whence to download certificates
    258 . KMF_CRLURI -- URI whence to download crls
    259 . KMF_PROXY_SET -- whether a proxy server is required
    260 . KMF_PROXY -- proxy server.  Makes sense only if KMF_PROXY_SET is set. 
    261 . KMF_PROXY_PORT -- proxy port.   Makes sense only if KMF_PROXY_SET
    262   is set and KMF_PROXY is non-null.
    263 
    264 For example:
    265     $ export KMF_PROXY_SET=1
    266     $ export KMF_PROXY=webcache.sfbay
    267     $ export KMF_PROXY_PORT=8080
    268 
    269 These variables may also be set during the stf_execute step using the
    270 '-c' switch.  See the STF User's Guide for details.
    271 
    272 8. CONTACT US
    273 
    274 If you want to contact us, please e-mail the STC_CONTACT listed in the
    275 STC.INFO.  Your feedback is greatly appreciated.  To file a bug or an
    276 RFE against the suite, please use the stc/security/kmf subcategory.
    277