Template Version: @(#)sac_nextcase 1.70 03/30/10 SMI
This information is Copyright (c) 2010, Oracle and/or its affiliates. All
rights reserved.
1. Introduction
1.1. Project/Component Working Name:
PKCS#11 URI parser for libcryptoutil
1.2. Name of Document Author/Supplier:
Author: Jan Pechanec
1.3 Date of This Document:
21 May, 2010
4. Technical Description
Parsing the PKCS#11 URI in libcryptoutil
========================================
Overview
--------
Applications start making use of the (not just HW) PKCS#11 keystores for
storing private keys, and to a lesser extend also public keys and
certificates. OpenSSL PKCS#11 Engine already allows applications to
access PKCS#11 tokens that way (6479874) and there is also an ongoing
project to add support for X.509 certificates into SunSSH (6357779)
which also plans to use PKCS#11 keystores for storing private keys
corresponding to certificates. Basically any application that uses
private keys could benefit from having such keys in the PKCS#11
keystores.
However, so far there is no unified way of referencing such keys/certs
in the tokens. Recently we filed an Internet Draft "The PKCS#11 URI
Scheme" specifying an URI that could help with referencing the PKCS#11
objects. The PKCS#11 URI was already used in the PKCS#11 Engine
(PSARC/2009/555 OpenSSL RSA keys by reference in PKCS#11 keystores
through the PKCS11 engine) and parsing code was included directly into
the engine.
We suggest to put the PKCS#11 URI parsing code into the libcryptoutil so
that it's easily available to all consumers in ON.
PKCS#11 URI Scheme
------------------
The PKCS#11 URI is fully described in the I-D which is located here:
http://tools.ietf.org/html/draft-pechanec-pkcs11uri-01
Extension to the existing libcryptoutil API
-------------------------------------------
Given that libcryptoutil is consolidation private we can define a new
structure in cryptoutil.h, visible in ON. We also use a few new defines.
/* That's what getpassphrase(3c) supports. */
#define PK11_MAX_TOKEN_PIN_LEN 256
/*
* There is no limit for the attribute length in the spec. 256 bytes
* should be enough for the object name.
*/
#define PK11_MAX_OBJECT_LEN 256
/*
* CKA_ID is of type "byte array" which can be of arbitrary length. 256
* bytes should be sufficient though.
*/
#define PK11_MAX_ID_LEN 256
#define PK11_MAX_PASSPHRASEDIALOG_LEN (MAXPATHLEN + sizeof ("exec:"))
/* Structure for the PKCS#11 URI. */
typedef struct pkcs11_uri_t {
CK_UTF8CHAR object[PK11_MAX_OBJECT_LEN + 1];
/*
* The "objecttype" URI attribute can have a value of private,
* public, cert, seckey, or data. The "objecttype" field can
* have a value of CKO_PUBLIC_KEY, CKO_PRIVATE_KEY,
* CKO_CERTIFICATE, CKO_SECRET_KEY, or CKO_DATA.
*/
CK_ULONG objecttype;
/*
* CKO_DATA is 0 so we need this flag. Not part of the URI
* itself.
*/
boolean_t objecttype_present;
/*
* Token, manuf, serial and model are of fixed size lengths as
* defined in the specification. The +1s are for the terminating
* '\0's which are not used in the CK_TOKEN_INFO structure
* (fields are padded with spaces).
*/
/* Token label from CK_TOKEN_INFO. */
CK_UTF8CHAR token[32 + 1];
/* ManufacturerID from CK_TOKEN_INFO. */
CK_UTF8CHAR manuf[32 + 1];
/* SerialNumber from CK_TOKEN_INFO. */
CK_CHAR serial[16 + 1];
/* Model from CK_TOKEN_INFO. */
CK_UTF8CHAR model[16 + 1];
/* This is a byte array, we need a length parameter as well. */
CK_BYTE id[PK11_MAX_ID_LEN];
int id_len;
/* Passphrase dialog for getting the token PIN. */
char passphrasedialog[PK11_MAX_PASSPHRASEDIALOG_LEN + 1];
/*
* The token PIN. Not part of the URI itself. Will be filled
* when the passphrasedialog attribute is used. +1 is for the
* terminating '\0'.
*/
CK_UTF8CHAR pin[PK11_MAX_TOKEN_PIN_LEN + 1];
} pkcs11_uri_t;
We need only one function for parsing the URI, all other helper
functions are static. The function takes a string with the PKCS#11 URI
and fills up a structure allocated by the caller.
int pkcs11_parse_uri(const char *str, pkcs11_uri_t *uri);
Return codes are defined:
#define PK11_URI_OK 0
#define PK11_URI_INVALID 1
- the string begins with the "pkcs11://" prefix but the URI is
otherwise invalid. It contains an unknown attribute, for
example.
#define PK11_TOKEN_PIN_NOT_READ 2
- there might be different reasons why the PIN has not been
read. For example, the external passphrase-like command does
not exist.
#define PK11_MALLOC_ERROR 3
- internal malloc() has failed
#define PK11_URI_VALUE_OVERFLOW 4
- the PKCS#11 spec defines some limits on attributes.
#define PK11_NOT_PKCS11_URI 5
- the string does not begin with the "pkcs11://" prefix at all
#define PK11_MUTEX_ERROR 6
- getpassphrase() is not MT-safe. We use a global mutex to
protect the getpassphrase() call.
Relevant CRs
------------
6924687 teach libcryptoutil to parse a PKCS#11 URI
6953869 crypto framework STC-2 test suite needs a test for the PKCS#11
URI parsing
Doc impact
----------
We will update the README file in usr/src/lib/libcryptoutil. Since
libcryptoutil is private interface within ON it does not have its own
manual page.
Notes
-----
We asked for feedback on the following aliases:
[email protected]
- IETF Security Area Advisory Group
[email protected]
- PKCS#11 alias at RSA Security (PKCS#11 came from
there)
[email protected]
- open smart card project
Unfortunately, we haven't received any feedback. However, given that
libcryptoutil is consolidation private we believe we can implement the
current specification and make changes in the future should those be
needed.
Interface Stability
-------------------
Private.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
_______________________________________________
opensolaris-arc mailing list
[email protected]
