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 24This 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 29The library and the header file are installed into the proto area but 30are not included in any pacakges. 31 32 33 libcryptoutil Design 34 351. Introduction 36 37There are a number of common code components and general utility functions 38needed that are shared by various userland parts of the crypto framework. 39 40The originally approved ARC materials (PSARC/2001/488 & PSARC/2001/553) 41didn't have a library that was included by all user land libraries, 42plugins and commands. 43 44The solution to this is to follow what other project teams have done in the 45past and create a project private util library. 46 472. Contents 48 49Any code that is generic enough to be shared by multiple parts of the 50user crypto framework is eligible. 51 52The current contents are: 53 542.1 Error & Debug Functions 55 56 cryptodebug_init(), 57 cryptodebug() 58 cryptoerror() 59 60These functions log debug or error information to stderr and/or 61syslog or a file. Debug is off by default but the code is always 62compiled in. 63 64The cryptodebug_init() routine allows the caller to set a message 65prefix for error and debug output. 66 67The environment variable SUNW_CRYPTO_DEBUG determines wither or not 68debug output is generated at run time, valid values are "syslog" or "stderr" 69 70For example elfsign(1) could do: 71 72 cryptodebug_init("elfsign"); 73 74and later: 75 cryptoerror(LOG_STDERR, gettext("invalid number of arguments")); 76 77This would cause an error message on stderr thus: 78 79 "elfsign: invalid number of arguments" 80 81The first argument to cryptoerror is either LOG_STDERR or a syslog(3c) 82priority. All messages include the PID and are logged at LOG_USER. 83 84for debug output: 85 86 cryptodebug("scmd=request opts=%s", opts); 87 88This would go to the location defined by $SUNW_CRYPTO_DEBUG, ie 89syslog, stderr or not be generated at all. 90 912.2 PKCS#11 Mechanism Type to and from Strings 92 93 pkcs11_mech2str() and pkcs11_str2mech() 94 95These functions use a table built at compile time from the contents of 96the pkcs11t.h file to map mechanism numbers to the corresponding string 97value. 98 99pkcs11_mech2str() returns a pointer to a string that should be free(3c)'d 100by the caller. 101 102Consumers: 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 1132.3 The "pkcs11.conf" configuration file Parsing code. 114 115The "pkcs11.conf" configuration file parsing code and data structures are 116shared between: 117 cryptoadm(1m), libpkcs11(3crypto). 118 1192.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 1472.3.2 Functions: 148 149extern 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 157extern 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 164extern void free_uentrylist(uentrylist_t *ptr); 165 166 Free space allocated for an pointer to the struct "uentrylist_t". 167 168extern void free_uentry(uentry_t *ptr); 169 170 Free space allocated for an pointer to the struct "uentry_t". 171 172extern void free_umechlist(umechlist_t *ptr); 173 174 Free space allocated for an pointer to the struct "umechlist_t". 175 1762.4 PKCS#11 Mechanism Type to key type 177 178 pkcs11_mech2keytype() 179 180This function is used to get the key type for a mechanism. 181 182Consumers: 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 1882.5 PKCS#11 return code to string 189 190 pkcs11_strerror() 191 192This function returns a string representation of any given PKCS11 return 193code. 194 195Consumer: 196 197 encrypt(1) and decrypt(1) uses this function for reporting errors. 198 1992.5 PKCS#11 URI parsing code 200 201 pkcs11_parse_uri() 202 pkcs11_free_uri() 203 204This function parses a PKCS#11 URI and fills up a pkcs11_uri_t structure. It 205also reads the PIN if the PKCS#11 URI specifies a passphrase dialog. The 206pkcs11_uri_t is described in cryptoutil.h, explanation of the return codes for 207the pkcs11_parse_uri() function is in the function's comment in pk11_uri.c. The 208pkcs11_parse_uri() function allocates the URI's fields and the caller is 209responsible for calling pkcs11_free_uri() after it's done with the URI 210structure. 211 212Consumer: 213 214 SunSSH will use the functions for parsing PKCS#11 URIs. 215 2163. Non-Contents 217 218Code for cryptographic algorithms does not belong in here. That 219comes from usr/src/common/<algorithm> since it is shared between user and 220kernel. 221 222PKCS#11 header files although they are common to various parts of the 223user land framework come from usr/src/pkcs11/include 224 2254. Interface Taxonomy 226 227Everything in this library is Project Private or Internal. The 228exported symbols will all be marked as SUNWprivate_1.0 in the library 229spec file. 230 2315. Static vs Dynamic 232 233The initial design was to only use a static archive library to avoid 234exposing a new interface (even though it is all private). However while 235this is fine for initial delivery it creates difficulties later with 236patching. As such a Dynamic version will be build. 237 238Libraries for lint and header files will not be shipped in any Sun packages 239since this is all Project Private. Similarly the abi_ file will not be 240shipped even though a spec file will be used in the source gate. 241 2426. Library location 243 244At present all of the consumers of the library are in /usr/ so the 245library is /usr/lib/{sparcv9}/libcryptoutil.so.1. If kcfd ever moves 246to /lib/crypto/kcf as a result of PSARC/2002/117 allowing it, then 247libcryptoutil needs to move as well. 248