The PKCS#11 URI Scheme
draft-pechanec-pkcs11uri-02

Abstract

This memo specifies a PKCS#11 Uniform Resource Identifier (URI) Scheme for identifying PKCS#11 objects stored in PKCS#11 tokens, or for identifying PKCS#11 tokens themselves. The URI is based on how PKCS#11 objects and tokens are identified in the PKCS#11 Cryptographic Token Interface Standard.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on February 21, 2011.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  Introduction
2.  PKCS#11 URI Scheme Definition
    2.1.  PKCS#11 URI Scheme Name
    2.2.  PKCS#11 URI Scheme Status
    2.3.  PKCS#11 URI Scheme Syntax
3.  Examples of PKCS#11 URI Schemes
4.  IANA Considerations
5.  Security Considerations
6.  Normative References
§  Authors' Addresses

1.  Introduction

The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec] (RSA Laboratories, “PKCS #11: Cryptographic Token Interface Standard v2.20,” June 2004.) specifies an API, called Cryptoki, for devices which hold cryptographic information and perform cryptographic functions. Cryptoki, pronounced crypto-key and short for cryptographic token interface, follows a simple object-based approach, addressing the goals of technology independence (any kind of device may be used) and resource sharing (multiple applications may access multiple devices), presenting applications with a common, logical view of the device - a cryptographic token.

It is desirable for applications or libraries that work with PKCS#11 tokens to accept a common identifier that consumers could use to identify an existing PKCS#11 object in a PKCS#11 token, or an existing token itself, or an existing Cryptoki library. The set of object types that can be stored in a PKCS#11 token includes a public key, a private key, a certificate, a secret key, and a data object. These objects can be uniquely identifiable via the PKCS#11 URI scheme defined in this document. The set of attributes describing an object can contain an object label, its type, and its ID. The set of attributes that identifies a PKCS#11 token can contain a token label, a manufacturer name, a serial number, and a token model. Attributes that can identify a Cryptoki library are a library manufacturer, a library description, and a library version.

Note that the PKCS#11 URI is not intended to be used to create new PKCS#11 objects in tokens, or to create PKCS#11 tokens. It is solely to be used to identify existing objects or existing tokens.

2.  PKCS#11 URI Scheme Definition

In accordance with [RFC4395] (Hansen, T., Hardie, T., and L. Masinter, “Guidelines and Registration Procedures for New URI Schemes,” February 2006.), this section provides the information required to register the PKCS#11 URI scheme.

2.1.  PKCS#11 URI Scheme Name

pkcs11

2.2.  PKCS#11 URI Scheme Status

Permanent.

2.3.  PKCS#11 URI Scheme Syntax

The PKCS#11 URI scheme is a sequence of attribute value pairs. Most attributes allow for an UTF-8 string to be used as an value. In accordance with [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.), the data should first be encoded as octets according to the UTF-8 character encoding [RFC3629] (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.); then only those octets that do not correspond to characters in the unreserved set or to permitted characters from the reserved set should be percent-encoded. Rules "unreserved" and "pct-encoded" in the PKCS#11 URI specification below were imported from [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.). As a special case, note that according to [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.), a space must be percent-encoded.

A PKCS#11 URL takes the form (for explanation of Augmented BNF, see [RFC5234] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.)):

pk11-URI		= "pkcs11" ":" pk11-identifier
pk11-identifier	   	= *1(pk11-attr *(";" pk11-attr))
pk11-attr		= pk11-token / pk11-manuf / pk11-serial /
			  pk11-model / pk11-lib-manuf / pk11-lib-ver /
			  pk11-lib-desc / pk11-object /
			  pk11-objecttype / pk11-id / pk11-pinfile
; Section 2.2 of RFC 3986 specifies that all potentially reserved
; characters that do not conflict with actual delimiters of the URI
; do not have to be percent-encoded. So, we just removed ";".
pk11-reserved-avail	= ":" / "/" / "?" / "#" / "[" / "]" / "@" /
			  "!" / "$" / "&" / "'" / "(" / ")" / "*" /
			  "+" / "," / "="
pk11-value		= *(unreserved / pk11-reserved-avail /
			  pct-encoded)
; The "pk11-ck-char" rule contains a complete list of characters
; of the CK_CHAR type as defined in the PKCS#11 specification. Those
; are a-z, A-Z, 0-9, a space, and all special characters from the
; following list: !"#%&'()*+,-./:;<=>?[\]^_{|}~. Note that some
; special characters not part of the reserved and unreserved sets
; must be percent-encoded.
pk11-ck-char		= unreserved / "%20" / "!" / "%22" / "#" /
			  "%25" / "&" / "'" / "(" / ")" / "*" /
			  "+" / "," / "-" / "." / "/" / ":" / "%3B" /
			  "%3C" / "=" / "%3E" / "?" / "[" / "%5C" /
			  "]" / "%5E" / "_" / "%7B" / "%7C" / "%7D" /
			  "~"
; Corresponds to the label field of the CK_TOKEN_INFO structure.
pk11-token		= "token" "=" pk11-value
; Corresponds to the manufacturerID field of the CK_TOKEN_INFO
; structure.
pk11-manuf		= "manufacturer" "=" pk11-value
; Corresponds to the serialNumber field of the CK_TOKEN_INFO structure.
pk11-serial		= "serial" "=" *pk11-ck-char
; Corresponds to the model field of the CK_TOKEN_INFO structure.
pk11-model		= "model" "=" pk11-value
; Corresponds to the manufacturerID field of the CK_INFO structure.
pk11-lib-manuf		= "library-manufacturer" "=" pk11-value
; Corresponds to the libraryDescription field of the CK_INFO structure.
pk11-lib-desc		= "library-description" "=" pk11-value
; Corresponds to the libraryVersion field of the CK_INFO structure.
pk11-lib-ver		= "library-version" "=" 1*DIGIT *("." 1*DIGIT)
; Corresponds to the CKA_LABEL object attribute.
pk11-object		= "object" "=" pk11-value
; Corresponds to the CKA_CLASS object attribute.
pk11-objecttype	   	= "objecttype" "=" ("public" / "private" /
			  "cert" / "secretkey" / "data")
; Corresponds to the CKA_ID object attribute.
pk11-id			= "id" "=" *pct-encoded
pk11-pinfile		= "pinfile" "=" pk11-value

While the PKCS#11 specification limits the length of some fields, eg. the manufacturer label can be up to thirty-two characters long, the PKCS#11 URI does not impose such limitations. It is up to the consumer of the PKCS#11 URI to perform any necessary sanity length checks.

The attribute "token" represents a token label, the attribute "manufacturer" represents a token manufacturer ID, the attribute "serial" represents a token serial number, the attribute "model" represents a token model, the attribute "library-manufacturer" represents the Cryptoki library manufacturer, the attribute "library-description" represents the character string description of the library, the attribute "library-version" represents the Cryptoki library version, the attribute "object" represents a PKCS#11 object label, the attribute "objecttype" represents the type of the object, the attribute "id" represents the object ID, and the attribute "pinfile" specifies where the application or library should find the token PIN, if needed. Application could overload this attribute. For example, "pinfile=%7Cprog-name" could mean to read a PIN from an external application (%7C denotes a pipe '|' character). Note that an application can always ask for a PIN by any means it decides to.

3.  Examples of PKCS#11 URI Schemes

This section contains some examples of how PKCS#11 tokens or PKCS#11 token objects can be identified using the PKCS#11 URI scheme. Note that in some of the following examples, newlines and spaces were inserted for better readability which is allowed by [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.). Also note that all spaces as part of the URI are percent-encoded, as required by [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.).

An empty PKCS#11 URI might be useful to PKCS#11 consumers:

  pkcs11:

One of the simplest and most useful forms might be a PKCS#11 URI that specifies only an object label and its type. The default token is used so the URI does not specify it. Note that when specifying public objects, a token PIN might not be required.

  pkcs11:object=my-pubkey;objecttype=public

When a private key is specified either the "pinfile" attribute or an application specific method must be used:

  pkcs11:object=my-key;objecttype=private;pinfile=/etc/ssh/token_pin

The following example identifies a certificate in the software token. Note that all attributes aside from "objecttype" may have an empty value. In our case, "serial" is empty. It is up to the consumer of the URI to perform necessary checks if that is not allowed. Note the notation of the "id" attribute value which is entirely percent-encoded.

  pkcs11:token=The%20Software%20PKCS#11%20softtoken;
         manufacturer=Snake%20Oil,%20Inc.;
         serial=;
         model=1.0;
         object=my-certificate;
         objecttype=cert;
         id=%69%95%3e%5c%f4%bd%ec%91;
         pinfile=/etc/ssh/token_pin

The token alone can be identified without specifying any PKCS#11 objects. A PIN may still be needed to list all objects, for example.

  pkcs11:token=Software%20PKCS#11%20softtoken;
         manufacturer=Snake%20Oil,%20Inc.;
         pinfile=/etc/ssh/token_pin

The Cryptoki library alone can be also identified without specifying any PKCS#11 objects.

  pkcs11:library-manufacturer=Snake%20Oil,%20Inc.;
         library-description=Soft%20Token%20Library;
         library-version=2.34

The following example shows that the attribute value can contain a semicolon. In such case, it is percent-encoded. We can also have capital letters in the "id" attribute value.

  pkcs11:token=My%20token%25%20created%20by%20Joe;
         object=my-certificate;
         objecttype=cert;
         id=69:95:3E:5C:F4:BD:EC:91;
         pinfile=/etc/ssh/token_pin

And if there is any need to include literal '%;' substring, for example, we must escape both characters. The token value must be read as "The token name with a strange substring '\;'" then.

  pkcs11:token=A%20name%20with%20a%20strange%20substring%'%25%3B';
         object=my-certificate;
         objecttype=cert;
         pinfile=/etc/ssh/token_pin

The next example includes a small A with acute in the token name. We must encode it in octets according to the UTF-8 character encoding and then use the percent-encoding. Given that a small A with acute is U+225 unicode code point, the UTF-8 encoding is 195 161 in decimal, which is "%C3%A1" in the percent-encoding.

  pkcs11:token=Name%20with%20a%20small%20A%20with%20acute:%20%C3%A1;
         object=my-certificate;
         objecttype=cert;

4.  IANA Considerations

This document registers a URI scheme. The registration template can be found in Section 2 of this document.

5.  Security Considerations

There are many security considerations for URI schemes discussed in [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.).

Given that the PKCS#11 URI is also supposed to be used in command line arguments to running programs, and those arguments can be world readable on some systems, the URI intentionaly does not allow for specifying the PKCS#11 token PIN as a URI attribute.

6. Normative References

Authors' Addresses