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