usr/src/lib/libcryptoutil/README

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