Scribd
Upload
27 views6 pages

PKCS11 Wrapping With Templates - v3

This document specifies how to serialize secret and private key templates with the goal of wrapping them together with wrapped keys. Templates and keys are wrapped using authenticated encryption. The unwrapping function may then know what the values of those attributes were originally, and make appropriate security decisions accordingly.

Uploaded by

宛俊
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as ODT, PDF, TXT or read online on Scribd
27 views6 pages

PKCS11 Wrapping With Templates - v3

This document specifies how to serialize secret and private key templates with the goal of wrapping them together with wrapped keys. Templates and keys are wrapped using authenticated encryption. The unwrapping function may then know what the values of those attributes were originally, and make appropriate security decisions accordingly.

Uploaded by

宛俊
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as ODT, PDF, TXT or read online on Scribd
You are on page 1/ 6

PKCS #11 Wrapped Template

Specification (Draft v2 - 2016-05-10)


Cryptosense

[email protected]

Table of Contents
1 Introduction...........................................................................................................................................1
1.1 Terminology..................................................................................................................................2
1.2 Definitions.....................................................................................................................................2
1.4 Normative References...................................................................................................................2
2 Attributes to Wrap.................................................................................................................................2
3 Unwrapping Behavior...........................................................................................................................3
4 Payload Serialization.............................................................................................................................4
4.1 Tags...............................................................................................................................................4
4.2 Payload Structure..........................................................................................................................5
4.3 Template Structure........................................................................................................................5
4.4 Attribute Structure.........................................................................................................................5
4.5 Attribute Type Enumeration..........................................................................................................5
4.6 Attribute Values............................................................................................................................5
4.6.1 CK_BBOOL..........................................................................................................................6
4.6.2 CK_OBJECT_CLASS...........................................................................................................6
4.6.3 CK_KEY_TYPE...................................................................................................................6
4.6.4 CK_MECHANISM_TYPE...................................................................................................6
4.6.5 Byte array..............................................................................................................................6
4.6.6 RFC2279 string......................................................................................................................6
4.6.7 CK_DATE.............................................................................................................................6
4.6.8 CK_ATTRIBUTE_PTR........................................................................................................6
4.6.9 CK_MECHANISM_TYPE_PTR..........................................................................................6
Appendix A. Attribute Encoding.............................................................................................................7

1 Introduction
This document specifies how to serialize secret and private key templates with the goal of wrapping
them together with wrapped keys. Templates and keys are wrapped using authenticated encryption
mechanisms. The unwrapping function may then know what the values of those attributes were
originally, and make appropriate security decisions accordingly, such as preventing a critical attribute
from taking a value which would compromise sensitive key values.
This document does not specify which attributes should be wrapped. Some attributes have more
critical security impact than others, but we do not attempt to normalise that behaviour here.
1.1 Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
interpreted as described in [RFC2119].

1.2 Definitions
For the purposes of this standard, the following definitions apply:

Payload A pair composed of a key value and a template.


This pair is serialized and encrypted when
wrapping.

1.4 Normative References


[KMIP] OASIS, “Key Management Interoperability
Protocol Specification Version 1.2”, 19 May
2015.
URL:
http://docs.oasis-open.org/kmip/spec/v1.2/kmip-
spec-v1.2.html

[PKCS11] OASIS, “PKCS #11 Cryptographic Token


Interface Base Specification Version 2.40”, 14
April 2015.
URL: http://docs.oasis-open.org/pkcs11/pkcs11-
base/v2.40/os/pkcs11-base-v2.40-os.html

[RFC2119] Bradner, S., “Key words for use in RFCs to


Indicate Requirement Levels”, BCP 14, RFC
2119, March 1997.
URL: http://www.ietf.org/rfc/rfc2119.txt.

2 Wrapping Behavior

Wrapping using encoded attributes SHALL only be supported for mechanisms that use authenticated
encryption. If the mechanism used is GCM or CCM, token-generated Initialization Vectors (IVs)
MUST be used.

3 Unwrapping Behavior
Unwrapping can be used to duplicate a key object. The duplicate may have some different attribute
values, so unwrapping may thus also be compared to C_CopyObject and C_SetAttributeValue.
This means that the security issues which apply to C_CopyObject and C_SetAttributeValue also
apply to unwrapping. Thanks to wrapped templates, unwrapping implementations may in particular
check that changes to attribute values do not induce security breaches.
For instance, Section 4.1.2 of [PKCS11] states that CKA_SENSITIVE “can be changed from
CK_FALSE to CK_TRUE, but not the other way around”. If CKA_SENSITIVE is part of the
payload, unwrapping SHALL check that the new requested value is not CK_FALSE if the payload
value is CK_TRUE.
In general, we distinguish the following cases:
• an attribute is only specified in the payload;
• an attribute is only specified in the requested template;
• an attribute is specified both in the payload and in the requested template.
If an attribute is only specified in the payload, it SHOULD be copied as-is. Attributes CKA_LOCAL,
CKA_NEVER_EXTRACTABLE and CKA_ALWAYS_SENSITIVE are exceptions to this rule,
as those attributes SHALL always be set to CK_FALSE.
If an attribute is only specified in the requested template, the behavior SHALL be equivalent to the
behavior of C_UnwrapKey when wrapped templates are not used. Particular implementations MAY
require that some attributes are always specified in the payload.
If an attribute is specified both in the payload and in the requested template, the result SHALL be
equivalent to running C_UnwrapKey using the payload template as the requested template, followed
by C_SetAttributeValue using the requested template as the new template. Attributes such as
CKA_TOKEN and CKA_PRIVATE which are read-only but which may nevertheless change value
when copied or unwrapped are an exception to this rule; the requested value takes precedence.

4 Payload Serialization
This section specifies how payloads SHALL be serialized. Payloads are composed of the key value,
which is serialized in the same way that C_WrapKey serializes it without wrapped templates, and of
the wrapped template, which is the list of wrapped attributes and their values.
In order to provide a bridge between PKCS #11 and KMIP, serialization uses the TTLV encoding
defined in [KMIP]. Below sections follow the format used in [KMIP].

4.1 Tags
This document defines a number of new tags which do not overlap with existing KMIP tags. Each tag
corresponds to a field of a structure defined in one of the next sections. Tag values are defined in
hexadecimal.

Object Tag Value


PKCS #11 Payload 4200D4
PKCS #11 Key Value 4200D5
PKCS #11 Template 4200D6
PKCS #11 Attribute 4200D7
PKCS #11 Attribute Type 4200D8
PKCS #11 Attribute Value 4200D9
PKCS #11 Mechanism Type 4200DA

4.2 Payload Structure


The main data structure is the Payload Structure. It is TTLV-encoded and then encrypted. It contains
the key value, encoded as a byte string, and the wrapped template. The latter MAY be omitted if there
are no attributes to wrap.

Object Encoding REQUIRED


PKCS #11 Payload Structure
PKCS #11 Key Value Byte string Yes
PKCS #11 Template Structure, see Section 4.3 No

4.3 Template Structure


The wrapped template in the payload is a structure which contains any number of attributes.

Object Encoding REQUIRED


PKCS #11 Template Structure
PKCS #11 Attribute Structure, see Section 4.4 No. MAY be repeated

4.4 Attribute Structure


Each attribute is encoded as a structure containing its type (e.g. CKA_SENSITIVE) and its value
(e.g. CKA_TRUE).

Object Encoding REQUIRED


PKCS #11 Attribute Structure
PKCS #11 Attribute Type Enumeration, see Section Yes
4.5
PKCS #11 Attribute Value Depends, see Section 4.6 Yes

4.5 Attribute Type Enumeration


Attribute types (e.g. CKA_SENSITIVE) are encoded as enumerations. The actual value of each
attribute (e.g. CKA_SENSITIVE is defined as 0x00000103 in pkcs11t.h) is used for the value in the
TTLV encoding. In particular, vendor-defined attributes always have their left-most bit set
(0x80000000). This is compatible with the “Extensions” case used in KMIP for all enumerations.
4.6 Attribute Values
The type used to encode an attribute value depends on the attribute type. The following table sums up
the conversion rules the types of attributes which can be wrapped.

PKCS #11 Type TTLV Type


CK_BBOOL Boolean, see Section 4.6.1
CK_OBJECT_CLASS Enumeration, see Section 4.6.2
CK_KEY_TYPE Enumeration, see Section 4.6.3
CK_MECHANISM_TYPE Enumeration, see Section 4.6.4
Byte array Byte String, see Section 4.6.5
RFC2279 string Text String, see Section 4.6.6
CK_DATE Date-Time, see Section 4.6.7
CK_ATTRIBUTE_PTR Structure, see Section 4.6.8 or Section 4.3
CK_MECHANISM_TYPE_PTR Structure, see Section 4.6.9
Types for CKA_VENDOR_DEFINED attributes Vendor-defined

4.6.1 CK_BBOOL
Values of type CK_BBOOL are encoded as Booleans. CK_FALSE (which is defined as 0 in
pkcs11t.h) is encoded as 0x0000000000000000 and CK_TRUE (which is defined as 1 in pkcs11t.h) is
encoded as 0x0000000000000001.

4.6.2 CK_OBJECT_CLASS
Just like attribute types (see Section 4.5), object classes are encoded as enumerations. The actual value
of each object class is used for the value in the TTLV encoding.

4.6.3 CK_KEY_TYPE
Just like attribute types (see Section 4.5), key types are encoded as enumerations. The actual value of
each key type is used for the value in the TTLV encoding.

4.6.4 CK_MECHANISM_TYPE
Just like attribute types (see Section 4.5), mechanism types are encoded as enumerations. The actual
value of each mechanism type is used for the value in the TTLV encoding.

4.6.5 Byte array


Byte arrays are encoded as Byte Strings. They are left unchanged.

4.6.6 RFC2279 string


RFC2279 strings are encoded as Text Strings. Note that Text Strings SHALL NOT be null-
terminated, as the length is given by the TTLV encoding itself.
4.6.7 CK_DATE
Dates are encoded as Date-Time. Date-Times are POSIX time values encoded as Long Integers. As
CK_DATE is a structure containing strings, a conversion MUST be made.

4.6.8 CK_ATTRIBUTE_PTR
Attributes like CKA_WRAP_TEMPLATE, CKA_UNWRAP_TEMPLATE and
CKA_DERIVE_TEMPLATE have type CKA_ATTRIBUTE_PTR: their value is a pointer to an
array of attributes. They SHALL be encoded as a PKCS #11 Template structure as defined in Section
4.3.

4.6.9 CK_MECHANISM_TYPE_PTR
Attribute CKA_ALLOWED_MECHANISM has type CK_MECHANISM_TYPE_PTR: its value
is a pointer to an array of mechanism types. It SHALL be encoded using the following structure.

Object Encoding REQUIRED


PKCS #11 Mechanism Types Structure
PKCS #11 Mechanism Enumeration, see Section No. MAY be repeated
Type 4.6.4

You might also like