+1 -- Garrett
Darren J Moffat <[email protected]> wrote: > >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]
