path: root/attributes.yaml

########################################################################
#
# 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

  CKA_NAME_HASH_ALGORITHM:
    type: CK_MECHANISM_TYPE
    default: CKM_SHA_1

###
# 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