Home | History | Annotate | Download | only in libcryptoutil
      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, Version 1.0 only
      6 # (the "License").  You may not use this file except in compliance
      7 # with the License.
      8 #
      9 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
     10 # or http://www.opensolaris.org/os/licensing.
     11 # See the License for the specific language governing permissions
     12 # and limitations under the License.
     13 #
     14 # When distributing Covered Code, include this CDDL HEADER in each
     15 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
     16 # If applicable, add the following below this CDDL HEADER, with the
     17 # fields enclosed by brackets "[]" replaced with your own identifying
     18 # information: Portions Copyright [yyyy] [name of copyright owner]
     19 #
     20 # CDDL HEADER END
     21 #
     22 # Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
     23 # Use is subject to license terms.
     24 #
     25 # ident	"%Z%%M%	%I%	%E% SMI"
     26 
     27 This is an internal library for use only by:
     28 	usr/src/cmd/cmd-crypto
     29 	usr/src/lib/pkcs11
     30 
     31 The library and the header file are installed into the proto area but
     32 are not included in any pacakges.
     33 
     34 
     35 			libcryptoutil Design
     36 
     37 1. Introduction
     38 
     39 There are a number of common code components and general utility functions
     40 needed that are shared by various userland parts of the crypto framework.
     41 
     42 The originally approved ARC materials (PSARC/2001/488 & PSARC/2001/553)
     43 didn't have a library that was included by all user land libraries,
     44 plugins and commands.
     45 
     46 The solution to this is to follow what other project teams have done in the
     47 past and create a project private util library.
     48 
     49 2. Contents
     50 
     51 Any code that is generic enough to be shared by multiple parts of the
     52 user crypto framework is eligible.
     53 
     54 The current contents are:
     55 
     56 2.1 Error & Debug Functions
     57 
     58 	cryptodebug_init(),
     59 	cryptodebug()
     60 	cryptoerror()
     61 
     62 These functions log debug or error information to stderr and/or
     63 syslog or a file.  Debug is off by default but the code is always
     64 compiled in.
     65 
     66 The cryptodebug_init() routine allows the caller to set a message
     67 prefix for error and debug output.
     68 
     69 The environment variable SUNW_CRYPTO_DEBUG determines wither or not
     70 debug output is generated at run time, valid values are "syslog" or "stderr"
     71 
     72 For example elfsign(1) could do:
     73 
     74 	cryptodebug_init("elfsign");
     75 
     76 and later:
     77 	cryptoerror(LOG_STDERR, gettext("invalid number of arguments"));
     78 
     79 This would cause an error message on stderr thus:
     80 
     81 	"elfsign: invalid number of arguments"
     82 
     83 The first argument to cryptoerror is either LOG_STDERR or a syslog(3c)
     84 priority.  All messages include the PID and are logged at LOG_USER.
     85 
     86 for debug output:
     87 
     88 	cryptodebug("scmd=request opts=%s", opts);
     89 
     90 This would go to the location defined by $SUNW_CRYPTO_DEBUG, ie
     91 syslog, stderr or not be generated at all.
     92 
     93 2.2 PKCS#11 Mechanism Type to and from Strings
     94 
     95 	pkcs11_mech2str() and pkcs11_str2mech()
     96 
     97 These functions use a table built at compile time from the contents of
     98 the pkcs11t.h file to map mechanism numbers to the corresponding string
     99 value.
    100 
    101 pkcs11_mech2str() returns a pointer to a string that should be free(3c)'d
    102 by the caller.
    103 
    104 Consumers:  
    105 
    106 	digest(1), mac(1), encrypt(1), decrypt(1) for translating
    107 	command line args to mech numbers.  They will need to
    108 	add the "CKM_" prefix before calling pkc11_str2mech()
    109 
    110 	cryptoadm(1m) for output to user, and for storing in pkcs11.conf
    111 	file.
    112 
    113 	Debug code.
    114 
    115 2.3 The "pkcs11.conf" configuration file Parsing code.
    116 
    117 The "pkcs11.conf" configuration file parsing code and data structures are
    118 shared between:
    119 	cryptoadm(1m), libpkcs11(3crypto).
    120 
    121 2.3.1 Data Structures:
    122 
    123 	#define MECH_ID_HEX_LEN 11 /* length of mechanism id in hex form */
    124 
    125 	typedef char libname_t[MAXPATHLEN];
    126 	typedef char midstr_t[MECH_ID_HEX_LEN];
    127 
    128 	/* The policy list for an entry in the config file  */
    129 	typedef struct umechlist {
    130         	midstr_t                name;
    131 	        struct umechlist        *next;
    132 	} umechlist_t;
    133 
    134 	/* An entry in the pkcs11.conf file */
    135 	typedef struct uentry {
    136         	libname_t       name;
    137 	        boolean_t       flag_enabledlist; /* TRUE if an enabledlist */
    138         	umechlist_t     *policylist; /* disabledlist or enabledlist */
    139 	        int             count;
    140 	} uentry_t;
    141 
    142 	/* The entry list for the entire pkcs11.conf file */
    143 	typedef struct uentrylist {
    144         	uentry_t               *pent;
    145 	        struct uentrylist      *next;
    146 	} uentrylist_t;
    147 
    148 
    149 2.3.2 Functions:
    150 
    151 extern int get_pkcs11conf_info(uentrylist_t **ppliblist);
    152 $
    153     Retrieve the user-level provider info from the pkcs11.conf file.
    154     If successful, the result is returned from the ppliblist argument.
    155     This function returns SUCCESS if successfully done; otherwise it returns
    156     FAILURE.  The caller should use free_uentrylist() to free the space
    157     allocated for "ppliblist".
    158 
    159 extern umechlist_t *create_umech(char *mechname);
    160 
    161     Create one item of type umechlist_t with the mechanism name in hex form. 
    162     A NULL is returned when the input name is NULL or the heap memory is
    163     insufficient.  The Caller should use free_umechlist() to free the space
    164     allocated for the returning data.
    165 
    166 extern void free_uentrylist(uentrylist_t *ptr);
    167 
    168     Free space allocated for an pointer to the struct "uentrylist_t".
    169 
    170 extern void free_uentry(uentry_t *ptr);
    171 
    172     Free space allocated for an pointer to the struct "uentry_t".
    173 	
    174 extern void free_umechlist(umechlist_t *ptr);
    175 
    176     Free space allocated for an pointer to the struct "umechlist_t".
    177 
    178 2.4 PKCS#11 Mechanism Type to key type
    179 
    180 	pkcs11_mech2keytype()
    181 
    182 This function is used to get the key type for a mechanism.
    183 
    184 Consumers:  
    185 
    186 	encrypt(1), decrypt(1), and libpkcs11(3crypto) for getting
    187 	the key type when creating an object for use with a
    188 	specific mechanism.
    189 
    190 2.5 PKCS#11 return code to string
    191 
    192 	pkcs11_strerror()
    193 
    194 This function returnes a string representation of any given PKCS11 return
    195 code.
    196 
    197 Consumer:
    198 
    199 	encrypt(1) and decrypt(1) uses this function for reporting errors.
    200 	
    201 3. Non-Contents
    202 	
    203 Code for cryptographic algorithms does not belong in here.  That
    204 comes from usr/src/common/<algorithm> since it is shared between user and
    205 kernel.
    206 
    207 PKCS#11 header files although they are common to various parts of the
    208 user land framework come from usr/src/pkcs11/include
    209 
    210 4. Interface Taxonomy
    211 
    212 Everything in this library is Project Private or Internal.  The
    213 exported symbols will all be marked as SUNWprivate_1.0 in the library
    214 spec file.
    215 
    216 5. Static vs Dynamic
    217 
    218 The initial design was to only use a static archive library to avoid
    219 exposing a new interface (even though it is all private).  However while
    220 this is fine for initial delivery it creates difficulties later with
    221 patching.  As such a Dynamic version will be build.
    222 
    223 Libraries for lint and header files will not be shipped in any Sun packages
    224 since this is all Project Private.  Similarly the abi_ file will not be
    225 shipped even though a spec file will be used in the source gate.
    226 
    227 6. Library location
    228 
    229 At present all of the consumers of the library are in /usr/ so the
    230 library is /usr/lib/{sparcv9}/libcryptoutil.so.1.  If kcfd ever moves
    231 to /lib/crypto/kcf as a result of PSARC/2002/117 allowing it, then
    232 libcryptoutil needs to move as well.
    233