########################################################################
#
# PKCS #11 attribute definitions.
#
# The architecture of PKCS #11 is heavily based on an n-level-deep
# object inheritance hierarcy. Concrete object types inherit
# attribute definitions, default values, usage constraints etc from
# abstract types. Fine if one happens to be writing in a language
# that supports this, but C doesn't, and C++ is an abomination.
#
# So we handle all this inheritance-related fun here, by specifying
# object types and attributes in a (relatively) readable way and using
# a Python script to translate from this into "descriptors" (read-only
# C tables) we can use to automate some of the most tedious attribute
# checking in the C code.
#
# A secondary goal is to provide enough of a machine-readable
# description of the PKCS #11 object hierarchy that we can use it to
# drive automated test scripts, but that's not implemented yet.
#
# The base language here is YAML, with a somewhat ad-hoc data layout
# on top of it. The exact semantics are a bit of a moving target, but
# the overall layout is:
#
# - The top-level data object is a YAML sequence (indicated in YAML by
# the leading "- " marker, converts to Python list).
#
# - Each entry in the sequence describes one object, represented as a
# YAML mapping (converts to Python dict). Each object description
# has at least one required field ("name"), several optional fields,
# and one or more attribute descriptions.
#
# - An attribute description is a YAML mapping (Python dict)
# containing one or more fields describing the attribute.
#
# So the overall structure is a sequence of maps of maps.
#
# Attribute definitions within the hierarchy are combined, so that,
# eg, the "rsa_public_key" type inherits the CKA_CLASS definition from
# the the root object type, the CKA_KEY_TYPE definition from the "key"
# type, a value of CKO_PUBLIC_KEY for the CKA_CLASS from the
# "public_key" type, and provides its own value of CKK_RSA for the
# CKA_KEY_TYPE.
#
# No doubt the error checking in the Python script could become much
# more rigorous than it is now.
#
########################################################################
#
# Currently-defined object fields:
#
# - "name": String, required. Name of this object class. For
# concrete object types, this controls the name of the corresponding
# C descriptor.
#
# - "concrete": Boolean, optional, default false. If true, this
# object type should generate a C descriptor.
#
# - "superclass": String, optional but present for all but one type.
# Contains name of parent type.
#
# New object fields may be defined at a later date as needed.
#
# Any entry in an object mapping whose key starts with "CKA_" is
# assumed to be an attribute description.
#
# Keys in an object mapping which do not start with CKA_ and are not
# known object fields should result in an error during parsing.
#
########################################################################
#
# Currently-defined attribute fields:
#
# - "type": a PKCS #11 type name (CK_*) or one of a few other types
# described in the PKCS #11 specification: "rfc2279string",
# "biginteger", or "bytearray".
#
# - "default": data-value (see below) to be used as default if neither
# the application template nor the PKCS #11 software itself
# supplies an explicit value. As a special case, the null string
# ("") means that the default value of the attribute is empty (this
# is allowed for a few rfc2279string attributes such as CKA_LABEL).
#
# - "value": data-value (see below) for this field. If the
# application specifies a value for this attribute, it must match;
# otherwise, behaves like default. The special handling of the null
# string ("") used with default does not apply here.
#
# - "footnotes": Sequence (Python list) of integers in the range 1-12.
# If present, this indicates that the attribute's definition in the
# PKCS #11 specification has been tagged with the listed footnote
# numbers from the "common footnotes" in "Table 15" of the
# specification. These footnotes specify various constraints on the
# attributes behavior, and the Python script translates them into
# flags with more meaningful names, but since the specification
# itself is written in terms of these silly footnote numbers, using
# the footnote numbers in the YAML makes it easier to check the
# attribute descriptions in the YAML against the specification.
#
# - "unimplemented": boolean, default false. If true, the attribute
# is known to be in the specification but is not (yet?) supported by
# the Python script and the C code. This flag is set on a small
# number of relatively obscure attributes whose internal structure
# makes them tedious to represent in the attribute database; this is
# a placeholder for attributes which should be implemented
# eventually but which were not deemed to be on the critical path.
#
# As with object mappings, attribute mappings with unrecognized keys
# should result in an error during parsing.
#
# "data-value" fields ("default" and "value") in an attribute can take
# one of several forms:
#
# - A string value naming a PKCS #11 constant (eg, CK_TRUE);
#
# - A sequence of eight bit unsigned numeric values (ie, bytes)
# specifying a literal value; or
#
# - An integer (Python long) specifying a numeric value for a
# biginteger field, to be converted into a literal value using the
# smallest possible number of bytes.
#
########################################################################
#
# Author: Rob Austein
# Copyright (c) 2015, SUNET
#
# Redistribution and use in source and binary forms, with or
# without modification, are permitted provided that the following
# conditions are met:
#
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in
# the documentation and/or other materials provided with the
# distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
########################################################################
###
# Root of the object tree
###
- name: object
CKA_CLASS:
footnotes: [1]
type: CK_OBJECT_CLASS
###
# Storage objects
###
- name: storage
superclass: object
CKA_TOKEN:
type: CK_BBOOL
default: CK_FALSE
CKA_PRIVATE:
type: CK_BBOOL
default: CK_TRUE
CKA_MODIFIABLE:
type: CK_BBOOL
default: CK_TRUE
CKA_LABEL:
type: rfc2279string
default: ""
###
# Data objects
###
- name: data
superclass: storage
CKA_CLASS:
value: CKO_DATA
CKA_APPLICATION:
type: rfc2279string
default: ""
CKA_OBJECT_ID:
type: bytearray
default: ""
CKA_VALUE:
type: bytearray
default: ""
###
# Certificate objects
###
- name: certificate
superclass: storage
CKA_CLASS:
value: CKO_CERTIFICATE
CKA_CERTIFICATE_TYPE:
footnotes: [1]
type: CK_CERTIFICATE_TYPE
CKA_TRUSTED:
footnotes: [10]
type: CK_BBOOL
default: CK_FALSE
CKA_CERTIFICATE_CATEGORY:
type: CK_ULONG
default: 0
CKA_CHECK_VALUE:
type: bytearray
CKA_START_DATE:
type: CK_DATE
default: ""
CKA_END_DATE:
type: CK_DATE
default: ""
###
# X.509 public key certificate objects
###
# NB: For some reason, numeric footnotes in the table describing X.509
# certificate attributes are NOT the common attribute footnotes
# from Table 15. Be careful!
- name: x509_public_key_certificate
superclass: certificate
CKA_SUBJECT:
type: bytearray
CKA_ID:
type: bytearray
default: ""
CKA_ISSUER:
type: bytearray
default: ""
CKA_SERIAL_NUMBER:
type: bytearray
default: ""
CKA_VALUE:
type: bytearray
CKA_URL:
type: rfc2279string
default: ""
CKA_HASH_OF_SUBJECT_PUBLIC_KEY:
type: bytearray
default: ""
CKA_HASH_OF_ISSUER_PUBLIC_KEY:
type: bytearray
default: ""
CKA_JAVA_MIDP_SECURITY_DOMAIN:
type: CK_ULONG
default: 0
###
# Key objects
###
- name: key
superclass: storage
CKA_KEY_TYPE:
footnotes: [1, 5]
type: CK_KEY_TYPE
CKA_ID:
footnotes: [8]
type: bytearray
default: ""
CKA_START_DATE:
footnotes: [8]
type: CK_DATE
default: ""
CKA_END_DATE:
footnotes: [8]
type: CK_DATE
default: ""
CKA_DERIVE:
footnotes: [8]
type: CK_BBOOL
default: CK_FALSE
CKA_LOCAL:
footnotes: [2, 4, 6]
type: CK_BBOOL
default: CK_FALSE
CKA_KEY_GEN_MECHANISM:
footnotes: [2, 4, 6]
type: CK_MECHANISM_TYPE
default: CK_UNAVAILABLE_INFORMATION
CKA_ALLOWED_MECHANISMS:
unimplemented: true
###
# Public key objects
###
- name: public_key
superclass: key
CKA_CLASS:
value: CKO_PUBLIC_KEY
CKA_SUBJECT:
footnotes: [8]
type: bytearray
default: ""
CKA_ENCRYPT:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_VERIFY:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_VERIFY_RECOVER:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_WRAP:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_TRUSTED:
footnotes: [10]
type: CK_BBOOL
default: CK_FALSE
CKA_WRAP_TEMPLATE:
unimplemented: true
###
# Private key objects
###
- name: private_key
superclass: key
CKA_CLASS:
value: CKO_PRIVATE_KEY
CKA_SUBJECT:
footnotes: [8]
type: bytearray
default: ""
CKA_SENSITIVE:
footnotes: [8, 9, 11]
type: CK_BBOOL
default: CK_TRUE
CKA_DECRYPT:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_SIGN:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_SIGN_RECOVER:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_UNWRAP:
footnotes: [8, 9]
type: CK_BBOOL
default: CK_FALSE
CKA_EXTRACTABLE:
footnotes: [8, 9, 12]
type: CK_BBOOL
default: CK_FALSE
CKA_ALWAYS_SENSITIVE:
footnotes: [2, 4, 6]
type: CK_BBOOL
CKA_NEVER_EXTRACTABLE:
footnotes: [2, 4, 6]
type: CK_BBOOL
CKA_WRAP_WITH_TRUSTED:
footnotes: [11]
type: CK_BBOOL
default: CK_FALSE
CKA_UNWRAP_TEMPLATE:
unimplemented: true
###
# Secret key objects
###
- name: secret_key
superclass: key
CKA_CLASS:
value: CKO_SECRET_KEY
CKA_SENSITIVE:
footnotes: [8, 11]
type: CK_BBOOL
default: CK_FALSE
CKA_ENCRYPT:
footnotes: [8, 9]
type: CK_BBOOL
CKA_DECRYPT:
footnotes: [8, 9]
type: CK_BBOOL
CKA_SIGN:
footnotes: [8, 9]
type: CK_BBOOL
CKA_VERIFY:
footnotes: [8, 9]
type: CK_BBOOL
CKA_WRAP:
footnotes: [8, 9]
type: CK_BBOOL
CKA_UNWRAP:
footnotes: [8, 9]
type: CK_BBOOL
CKA_EXTRACTABLE:
footnotes: [8, 9, 12]
type: CK_BBOOL
CKA_ALWAYS_SENSITIVE:
footnotes: [2, 4, 6]
type: CK_BBOOL
CKA_NEVER_EXTRACTABLE:
footnotes: [2, 4, 6]
type: CK_BBOOL
CKA_CHECK_VALUE:
type: bytearray
CKA_WRAP_WITH_TRUSTED:
footnotes: [11]
type: CK_BBOOL
default: CK_FALSE
CKA_TRUSTED:
footnotes: [10]
type: CK_BBOOL
default: CK_FALSE
CKA_WRAP_TEMPLATE:
unimplemented: true
CKA_UNWRAP_TEMPLATE:
unimplemented: true
###
# Domain parameter objects
###
- name: domain_parameters
superclass: storage
CKA_CLASS:
value: CKO_DOMAIN_PARAMETERS
CKA_KEY_TYPE:
footnotes: [1]
type: CK_KEY_TYPE
CKA_LOCAL:
footnotes: [2, 4]
type: CK_BBOOL
###
# Mechanism objects
###
- name: mechanism
superclass: object
CKA_CLASS:
value: CKO_MECHANISM_INFO
CKA_MECHANISM_TYPE:
type: CK_MECHANISM_TYPE
###
# RSA public key objects
###
- name: rsa_public_key
superclass: public_key
concrete: true
CKA_KEY_TYPE:
value: CKK_RSA
CKA_MODULUS:
footnotes: [1, 4]
type: biginteger
CKA_MODULUS_BITS:
footnotes: [2, 3]
type: CK_ULONG
CKA_PUBLIC_EXPONENT:
footnotes: [1]
type: biginteger
value: 0x10001 # We only allow F4 as public exponent
###
# RSA private key objects
###
- name: rsa_private_key
superclass: private_key
concrete: true
CKA_KEY_TYPE:
value: CKK_RSA
CKA_MODULUS:
footnotes: [1, 4, 6]
type: biginteger
CKA_PUBLIC_EXPONENT:
footnotes: [4, 6]
type: biginteger
value: 0x10001 # We only allow F4 as public exponent
CKA_PRIVATE_EXPONENT:
footnotes: [1, 4, 6, 7]
type: biginteger
CKA_PRIME_1:
footnotes: [4, 6, 7]
type: biginteger
CKA_PRIME_2:
footnotes: [4, 6, 7]
type: biginteger
CKA_EXPONENT_1:
footnotes: [4, 6, 7]
type: biginteger
CKA_EXPONENT_2:
footnotes: [4, 6, 7]
type: biginteger
CKA_COEFFICIENT:
footnotes: [4, 6, 7]
type: biginteger
###
# Eliptic curve public key objects
###
- name: ec_public_key
superclass: public_key
concrete: true
CKA_KEY_TYPE:
value: CKK_EC
CKA_EC_PARAMS:
footnotes: [1, 3]
type: bytearray
CKA_EC_POINT:
footnotes: [1, 4]
type: bytearray
###
# Elliptic curve private key objects
###
- name: ec_private_key
superclass: private_key
concrete: true
CKA_KEY_TYPE:
value: CKK_EC
CKA_EC_PARAMS:
footnotes: [1, 4, 6]
type: bytearray
CKA_VALUE:
footnotes: [1, 4, 6, 7]
type: biginteger
