1028N/A# The contents of this file are subject to the terms of the
1028N/A# Common Development and Distribution License (the "License").
951N/A# You may not use this file except in compliance with the License.
951N/A# See the License for the specific language governing permissions
951N/A# and limitations under the License.
951N/A# When distributing Covered Code, include this CDDL HEADER in each
951N/A# If applicable, add the following below this CDDL HEADER, with the
951N/A# fields enclosed by brackets "[]" replaced with your own identifying
951N/A# information: Portions Copyright [yyyy] [name of copyright owner]
951N/A# Copyright (c) 2003, 2010, Oracle
and/or its affiliates. All rights reserved.
951N/AThis is an internal library for use only by:
951N/AThe library and the header file are installed into the proto area but
1097N/Aare not included in any pacakges.
951N/AThere are a number of common code components and general utility functions
951N/Aneeded that are shared by various userland parts of the crypto framework.
951N/AThe originally approved ARC materials (PSARC/2001/488 & PSARC/2001/553)
951N/Adidn't have a library that was included by all user land libraries,
951N/AThe solution to this is to follow what other project teams have done in the
951N/Apast and create a project private util library.
951N/AAny code that is generic enough to be shared by multiple parts of the
1097N/Auser crypto framework is eligible.
951N/A2.1 Error & Debug Functions
951N/AThese functions log debug or error information to stderr
and/or 951N/Asyslog or a file. Debug is off by default but the code is always
951N/AThe cryptodebug_init() routine allows the caller to set a message
951N/Aprefix for error and debug output.
1028N/AThe environment variable SUNW_CRYPTO_DEBUG determines wither or not
951N/Adebug output is generated at run time, valid values are "syslog" or "stderr"
951N/AFor example elfsign(1) could do:
951N/A cryptodebug_init("elfsign");
951N/A cryptoerror(LOG_STDERR, gettext("invalid number of arguments"));
951N/AThis would cause an error message on stderr thus:
951N/A "elfsign: invalid number of arguments"
951N/AThe first argument to cryptoerror is either LOG_STDERR or a syslog(3c)
951N/Apriority. All messages include the PID and are logged at LOG_USER.
951N/A cryptodebug("scmd=request opts=%s", opts);
951N/AThis would go to the location defined by $SUNW_CRYPTO_DEBUG, ie
951N/Asyslog, stderr or not be generated at all.
951N/A2.2 PKCS#11 Mechanism Type to and from Strings
951N/A pkcs11_mech2str() and pkcs11_str2mech()
951N/AThese functions use a table built at compile time from the contents of
951N/Athe
pkcs11t.h file to map mechanism numbers to the corresponding string
951N/Apkcs11_mech2str() returns a pointer to a string that should be free(3c)'d
digest(1), mac(1), encrypt(1), decrypt(1) for translating
command line args to mech numbers. They will need to
add the "CKM_" prefix before calling pkc11_str2mech()
cryptoadm(1m) for output to user, and for storing in
pkcs11.confThe "
pkcs11.conf" configuration file parsing code and data structures are
cryptoadm(1m), libpkcs11(3crypto).
#define MECH_ID_HEX_LEN 11 /* length of mechanism id in hex form */
typedef char libname_t[MAXPATHLEN];
typedef char midstr_t[MECH_ID_HEX_LEN];
/* The policy list for an entry in the config file */
typedef struct umechlist {
boolean_t flag_enabledlist; /* TRUE if an enabledlist */
umechlist_t *policylist; /* disabledlist or enabledlist */
typedef struct uentrylist {
extern int get_pkcs11conf_info(uentrylist_t **ppliblist);
Retrieve the user-level provider info from the
pkcs11.conf file.
If successful, the result is returned from the ppliblist argument.
This function returns SUCCESS if successfully done; otherwise it returns
FAILURE. The caller should use free_uentrylist() to free the space
allocated for "ppliblist".
extern umechlist_t *create_umech(char *mechname);
Create one item of type umechlist_t with the mechanism name in hex form.
A NULL is returned when the input name is NULL or the heap memory is
insufficient. The Caller should use free_umechlist() to free the space
allocated for the returning data.
extern void free_uentrylist(uentrylist_t *ptr);
Free space allocated for an pointer to the struct "uentrylist_t".
extern void free_uentry(uentry_t *ptr);
Free space allocated for an pointer to the struct "uentry_t".
extern void free_umechlist(umechlist_t *ptr);
Free space allocated for an pointer to the struct "umechlist_t".
2.4 PKCS#11 Mechanism Type to key type
This function is used to get the key type for a mechanism.
encrypt(1), decrypt(1), and libpkcs11(3crypto) for getting
the key type when creating an object for use with a
2.5 PKCS#11 return code to string
This function returns a string representation of any given PKCS11 return
encrypt(1) and decrypt(1) uses this function for reporting errors.
2.5 PKCS#11 URI parsing code
This function parses a PKCS#11 URI and fills up a pkcs11_uri_t structure. It
also reads the PIN if the PKCS#11 URI specifies a passphrase dialog. The
pkcs11_uri_t is described in
cryptoutil.h, explanation of the return codes for
the pkcs11_parse_uri() function is in the function's comment in
pk11_uri.c. The
pkcs11_parse_uri() function allocates the URI's fields and the caller is
responsible for calling pkcs11_free_uri() after it's done with the URI
SunSSH will use the functions for parsing PKCS#11 URIs.
Code for cryptographic algorithms does not belong in here. That
comes from
usr/src/common/<algorithm> since it is shared between user and
PKCS#11 header files although they are common to various parts of the
Everything in this library is Project Private or Internal. The
exported symbols will all be marked as SUNWprivate_1.0 in the library
The initial design was to only use a static archive library to avoid
exposing a new interface (even though it is all private). However while
this is fine for initial delivery it creates difficulties later with
patching. As such a Dynamic version will be build.
Libraries for lint and header files will not be shipped in any Sun packages
since this is all Project Private. Similarly the abi_ file will not be
shipped even though a spec file will be used in the source gate.
At present all of the consumers of the library are in /usr/ so the
libcryptoutil needs to move as well.