[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16

Network Working Group                                        J. Pechanec
Internet-Draft                                    Sun Microsystems, Inc.
Intended status: Standards Track                               D. Moffat
Expires: September 23, 2010                           Oracle Corporation
                                                          March 22, 2010


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

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 to IETF in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   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."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on September 23, 2010.

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



Pechanec & Moffat      Expires September 23, 2010               [Page 1]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


   (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 BSD License.


Table of Contents

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






























Pechanec & Moffat      Expires September 23, 2010               [Page 2]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


1.  Introduction

   The PKCS #11: Cryptographic Token Interface Standard [pkcs11_spec]
   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.  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 that identifies a PKCS#11 token can contain a
   token label, a manufacturer name, a serial number, and a token model.

   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], 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 UTF8 string to be used as an value.  However,
   given that a semicolon is used as a delimiter of attribute value
   pairs, semicolons used in such values must be escaped with a
   backslash.  A backslash that stands for itself must be escaped, too.




Pechanec & Moffat      Expires September 23, 2010               [Page 3]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


   A PKCS#11 URL takes the form (for explanation of Augmented BNF, see
   [RFC5234]):

 semicolon               = "\%x3B"
 backslash               = "\\"
 hexa                    = 2*2( %x30-39 / %x41-46 / %x61-66 )

 ; Modified UTF8 definition rule based on UTF8-octets rule
 ; introduced in RFC3629.
 UTF8-octets-with-escapes= *( UTF8-char-with-escapes )
 UTF8-char-with-escapes  = UTF8-1-with-escapes / UTF8-2 / UTF8-3 /
                           UTF8-4
 UTF8-1-with-escapes     = %x00-3A / semicolon / %x3C-5B /
                           backslash / %x5D-7F
 UTF8-2                  = %xC2-DF UTF8-tail
 UTF8-3                  = %xE0 %xA0-BF UTF8-tail /
                           %xE1-EC 2( UTF8-tail ) /
                           %xED %x80-9F UTF8-tail /
                           %xEE-EF 2( UTF8-tail )
 UTF8-4                  = %xF0 %x90-BF 2( UTF8-tail ) /
                           %xF1-F3 3( UTF8-tail ) /
                           %xF4 %x80-8F 2( UTF8-tail )
 UTF8-tail               = %x80-BF

 ; The actual PKCS#11 URI scheme definition starts here.
 pk11-URI                = "pkcs11" ":" pk11-identifier
 pk11-identifier         = *1( pk11-attr *( "%x3B" pk11-attr ) )
 pk11-attr               = pk11-token / pk11-manufacturer /
                           pk11-serial / pk11-model /
                           pk11-object / pk11-objecttype /
                           pk11-id / pk11-passphrasedialog
 ; 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: !"#%&'()*+,-./:;<=>?[\]^_{|}~
 pk11-ck-char            = %x41-5A / %x61-7A / %x30-39 / %x20-23 /
                           %x25-2F / %x3A / semicolon / %x3C-3F /
                           %x5B / backslash / %x5D-5F / %x7B-7E
 ; Corresponds to the label field of the CK_TOKEN_INFO structure.
 pk11-token              = "token" "=" UTF8-octets-with-escapes
 ; Corresponds to the manufacturerID field of the CK_TOKEN_INFO
 ; structure.
 pk11-manufacturer       = "manufacturer" "=" UTF8-octets-with-escapes
 ; 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" "=" UTF8-octets-with-escapes
 ; Corresponds to the CKA_LABEL object attribute.



Pechanec & Moffat      Expires September 23, 2010               [Page 4]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


 pk11-object             = "object" "=" UTF8-octets-with-escapes
 ; 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" "=" *1( hexa *( ":" hexa ) )
 pk11-passphrasedialog   = "passphrasedialog" "=" "builtin" / exec
 exec                    = "exec" ":" filename
 filename                = UTF8-octets-with-escapes

   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 checks.

   The "UTF8-octets-with-escapes" rule for the UTF8 string with escaped
   ";" and "\" characters is based on the "UTF8-octets" rule defined in
   [RFC3629].

   The attribute "token" represents a token label, the attribute
   "manufacturer" represents a manufacturer ID, the attribute "serial"
   represents a token serial number, the attribute "model" represents a
   token model, 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
   "passphrasedialog" specifies how the application or library should
   ask for the token PIN, if needed.  The "builtin" value suggests that
   the application or the library should use whatever means of reading
   the PIN it can provide, and the "exec:<filename>" value specifies an
   external application whose standard output should be used as the
   token PIN.


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.

   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



Pechanec & Moffat      Expires September 23, 2010               [Page 5]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


   Specifying a private key will usually need to use the
   "passphrasedialog" attribute:

     pkcs11:object=my-key;objecttype=private;passphrasedialog=builtin

   The following example identifies a certificate in the software token.
   Note that all attributes aside from "passphrasedialog" and
   "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.  Also note that in all four of the following
   examples, newlines and spaces were inserted for better readability.
   Usage of newlines or spaces after semicolons is illegal in the
   PKCS#11 URI scheme defined above.

     pkcs11:token=Software PKCS#11 softtoken;
            manufacturer=Snake Oil, Inc.;
            serial=;
            model=1.0;
            object=my-certificate;
            objecttype=cert;
            id=69:95:3e:5c:f4:bd:ec:91;
            passphrasedialog=exec:/bin/askpass.sh

   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 PKCS#11 softtoken;
            manufacturer=Snake Oil, Inc.;
            passphrasedialog=exec:/bin/askpass.sh

   The following example shows that the attribute value can contain a
   semicolon.  In this case, it must be escaped.  We can also have
   capital letters in the "id" attribute value.

     pkcs11:token=My token\; created by Joe;
            object=my-certificate;
            objecttype=cert;
            id=69:95:3E:5C:F4:BD:EC:91;
            passphrasedialog=exec:/bin/askpass.sh

   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=The token name with a strange substring '\\\;';
            object=my-certificate;
            objecttype=cert;



Pechanec & Moffat      Expires September 23, 2010               [Page 6]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


            passphrasedialog=exec:/bin/askpass.sh


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].

   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

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", RFC 3629, STD 63, November 2003.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", RFC 3986,
              STD 66, January 2005.

   [RFC4395]  Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
              Registration Procedures for New URI Schemes", RFC 4395,
              February 2006.

   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", RFC 5234, January 2008.

   [pkcs11_spec]
              RSA Laboratories, "PKCS #11: Cryptographic Token Interface
              Standard v2.20", June 2004.












Pechanec & Moffat      Expires September 23, 2010               [Page 7]

Internet-Draft           The PKCS#11 URI Scheme               March 2010


Authors' Addresses

   Jan Pechanec
   Sun Microsystems, Inc.
   The Park, building 3
   V parku 2308/8
   Prague  14800
   CZ

   Phone: +420 233 009 380
   Email: Jan.Pechanec@Sun.COM
   URI:   http://www.sun.com


   Darren J. Moffat
   Oracle Corporation
   Guillemont Park
   Building 3
   Camberley  GU17 9QG
   UK

   Email: Darren.Moffat@Oracle.COM
   URI:   http://www.oracle.com




























Pechanec & Moffat      Expires September 23, 2010               [Page 8]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/