Name Date Size #Lines LOC

..10-Dec-2021-

amd64/H14-Feb-2021-

common/H14-Feb-2021-

i386/H14-Feb-2021-

sparc/H14-Feb-2021-

sparcv9/H14-Feb-2021-

MakefileH A D14-Feb-20211.3 KiB5217

Makefile.comH A D14-Feb-20211.4 KiB6327

READMEH A D14-Feb-20217.5 KiB248170

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
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