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: s...@ietf.org - IETF Security Area Advisory Group crypt...@rsasecurity.com - PKCS#11 alias at RSA Security (PKCS#11 came from there) opensc-de...@lists.opensc-project.org - 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 opensolaris-arc@opensolaris.org