#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License (the "License").

# You may not use this file except in compliance with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

#

# Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.

#

This is an internal library for use only by:

usr/closed/cmd/cmd-crypto

usr/src/cmd/cmd-crypto

usr/src/cmd/lofiadm

usr/src/lib/pkcs11

usr/src/lib/libkmf

usr/src/lib/libsoftcrypto

libcryptoutil Design

1. Introduction

There are a number of common code components and general utility functions

needed that are shared by various userland parts of the crypto framework.

The originally approved ARC materials (PSARC/2001/488 & PSARC/2001/553)

didn't have a library that was included by all user land libraries,

plugins and commands.

The solution to this is to follow what other project teams have done in the

past and create a project private util library.

2. Contents

Any code that is generic enough to be shared by multiple parts of the

user crypto framework is eligible.

The current contents are:

2.1 Error & Debug Functions

cryptodebug_init(),

cryptodebug()

cryptoerror()

These functions log debug or error information to stderr and/or

syslog or a file. Debug is off by default but the code is always

compiled in.

The cryptodebug_init() routine allows the caller to set a message

prefix for error and debug output.

The environment variable SUNW_CRYPTO_DEBUG determines wither or not

debug output is generated at run time, valid values are "syslog" or "stderr"

For example elfsign(1) could do:

cryptodebug_init("elfsign");

and later:

cryptoerror(LOG_STDERR, gettext("invalid number of arguments"));

This would cause an error message on stderr thus:

"elfsign: invalid number of arguments"

The first argument to cryptoerror is either LOG_STDERR or a syslog(3c)

priority. All messages include the PID and are logged at LOG_USER.

for debug output:

cryptodebug("scmd=request opts=%s", opts);

This would go to the location defined by $SUNW_CRYPTO_DEBUG, ie

syslog, stderr or not be generated at all.

2.2 PKCS#11 Mechanism Type to and from Strings

pkcs11_mech2str() and pkcs11_str2mech()

These functions use a table built at compile time from the contents of

the pkcs11t.h file to map mechanism numbers to the corresponding string

value.

pkcs11_mech2str() returns a pointer to a string that should be free(3c)'d

by the caller.

Consumers:

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 pkcs11_str2mech()

cryptoadm(1m) for output to user, and for storing in pkcs11.conf

file.

Debug code.

2.3 The "pkcs11.conf" configuration file Parsing code.

The "pkcs11.conf" configuration file parsing code and data structures are

shared between:

cryptoadm(1m), libpkcs11(3crypto).

2.3.1 Data Structures:

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

midstr_t name;

struct umechlist *next;

} umechlist_t;

/* An entry in the pkcs11.conf file */

typedef struct uentry {

libname_t name;

boolean_t flag_enabledlist; /* TRUE if an enabledlist */

umechlist_t *policylist; /* disabledlist or enabledlist */

int count;

} uentry_t;

/* The entry list for the entire pkcs11.conf file */

typedef struct uentrylist {

uentry_t *pent;

struct uentrylist *next;

} uentrylist_t;

2.3.2 Functions:

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

pkcs11_mech2keytype()

This function is used to get the key type for a mechanism.

Consumers:

encrypt(1), decrypt(1), and libpkcs11(3crypto) for getting

the key type when creating an object for use with a

specific mechanism.

2.5 PKCS#11 return code to string

pkcs11_strerror()

This function returns a string representation of any given PKCS#11 return

code.

Consumer:

encrypt(1), decrypt(1), digest(1), pktool(1), and lofiadm(1M)

use this function for reporting errors.

2.6 PKCS#11 URI parsing code

pkcs11_parse_uri()

pkcs11_free_uri()

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

structure.

Consumer:

SunSSH will use the functions for parsing PKCS#11 URIs.

2.7 Random data from /dev/random and /dev/urandom

int pkcs11_seed_random(void *sbuf, size_t slen)

int pkcs11_seed_urandom(void *sbuf, size_t slen)

void pkcs11_close_random_seed(void)

void pkcs11_close_urandom_seed(void)

int pkcs11_get_random(void *dbuf, size_t dlen)

int pkcs11_get_urandom(void *dbuf, size_t dlen)

void pkcs11_close_random(void)

void pkcs11_close_urandom(void)

int pkcs11_get_nzero_urandom(void *dbuf, size_t dlen)

These functions get random data from /dev/random and /dev/urandom,

respectively. They also support seeding the devices, assuming the

caller has sufficient privilege. A specialized function to get

non-zero data from /dev/urandom is also included. Exactly the number

of bytes requested will be read from the random devices. Return

values are 0 on success and -1 on failure.

Consumers:

lib/libzfs, lib/libsmbns, lib/pkcs11, common/crypto,

lofiadm(1M), encrypt(1), decrypt(1)

2.8 Insulated file I/O system calls

int open_nointr(const char *path, int oflag, ...)

ssize_t readn_nointr(int fd, void *dbuf, size_t dlen)

ssize_t writen_nointr(int fd, void *dbuf, size_t dlen)

These functions are equivalent to the system calls open(2), read(2)

and write(2) except that EINTR causes the functions to be retried

until success or another error occurs. For readn_nointr/writen_nointr,

the functions keep reading/writing until the exact number of bytes

requested is reached.

Consumers:

lib/pkcs11

2.9 Read data from file into buffer

int pkcs11_read_data(char *filename, void **dbuf, size_t *dlen)

Reads a file into buffer allocated by this function. Used to read raw

key data or initialization vector data. Buffer must be freed by caller

using free().

If file is a regular file, entire file is read and dlen is set to the

number of bytes read. Otherwise, dlen should first be set to the number

of bytes requested and will be reset to actual number of bytes returned.

Consumers:

lib/libzfs, encrypt(1), decrypt(1), digest(1), lofiadm(1M)

2.10 Passphrase utilities

int pkcs11_get_pass(char *token_name, char **pdata, size_t *psize,

size_t min_psize, boolean_t with_confirmation)

This function prompts the user for a passphrase or the PIN for a token.

An optional minimum length can be enforced. Caller can optionally also

reprompt for the passphrase/PIN to confirm it was entered correctly.

The caller must free the buffer containing the passphrase/PIN with free().

0 returned for success, -1 for failure with the first passphrase/PIN,

-2 for failure with the optional second passphrase/PIN used to confirm.

Consumers:

encrypt(1), decrypt(1), digest(1), lofiadm(1M)

3. Non-Contents

Code for cryptographic algorithms does not belong in here. That

comes from usr/src/common/<algorithm> since it is shared between user and

kernel.

PKCS#11 header files although they are common to various parts of the

user land framework come from usr/src/pkcs11/include

4. Interface Taxonomy

Everything in this library is Project Private or Internal. The

exported symbols will all be marked as SUNWprivate_1.0 in the library

spec file.

5. Static vs Dynamic

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 created difficulties later with

patching. As such a Dynamic version is now built.

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.

6. Library location

The library is at /lib/{,amd64,sparcv9}/libcryptoutil.so.1.

See PSARC/2007/674.