/ 
Crypt-HSM-0.031
⭐ Starred 0 / Crypt::HSM::Object

NAME

Crypt::HSM::Object - A PKCS11 object

VERSION

version 0.031

SYNOPSIS

my ($key) = $session->find_objects({ label => $label, encrypt => 1 });
if (not $key) {
   my %attrs = { label => $label, sensitive => 1, "value-len" => 32 };
   $key = $session->generate_key('aes-key-gen', \%attrs);
}
$session->encrypt('aes-gcm', $key, $plaintext, $nonce);

DESCRIPTION

This class represents an object (usually a key) in the HSM's database. The type of the object us stored in the class attribute, this type will define what other attributes are available for it.

It's returned by Crypt::HSM::Session methods like find_object and generate_key, and used in methods such as encrypt, decrypt, sign and verify.

METHODS

copy_object($attributes = {})

Copy the object, optionally adding/modifying the given attributes.

destroy_object()

This deletes this object from the slot.

get_attribute($attribute_name)

This returns the value of the named attribute of the object.

get_attributes(@attribute_list)

This returns a hash with the attributes of the object that are asked for.

object_size()

This returns the size of this object.

set_attributes($attributes)

This sets the $attributes on this object.

ATTRIBUTES

Universal attributes

Only one attribute is present in all objects:

  • class

    This enum value van be one of data, certificate, public-key, private-key, secret-key, hw-feature, domain-parameters, mechanism, profile, validation, trust, or vendor-defined.

Storage objects

All certificate, key, en data objects are storage objects and contain the following attributes:

  • token

    True if the object is a token object, false if the object is a session object.

  • private

    If true, a user may not access the object until the user has been authenticated to the token.

  • modifiable

    If true (the default) the object can be modified.

  • label

    Description of the object (default empty).

  • copyable

    True if object can be copied using copy_object. Defaults to true. Can’t be set to true once it is set to false.

  • destroyable

    True if the object can be destroyed using destroy_object. Default is true.

  • unique-id

    The unique identifier assigned to the object.

Of these attributes, only label may be modified after the object is created.

Certificates

Several attributes are shared between all certificate types:

  • certificate-type

    This can be any of x-509, x-509-attr-cert, wtls or vendor-defined.

  • trusted

    True if the certificate can be trusted for the application that it was created. It MUST be set by a token initialization application or by the token’s SO. Trusted certificates cannot be modified.

  • certificate-category

    This can be any of unspecified, token-user, authority or other-entity.

  • check-value

    The checksum of the certificate.

  • start-date

    Start date for the certificate.

  • end-date

    End date for the certificate.

  • public-key-info

    DER-encoding of the SubjectPublicKeyInfo for the public key contained in this certificate.

X509 certificates

  • subject

    DER-encoding of the certificate subject name.

  • id

    Key identifier for public/private key pair.

  • issuer

    DER-encoding of the certificate issuer name.

  • serial-number

    DER-encoding of the certificate serial number.

  • value

    BER-encoding of the certificate. MUST be non-empty if url is empty.

  • url

    If not empty this attribute gives the URL where the complete certificate can be obtained. MUST be non-empty if value is empty.

  • hash-of-subject-public-key

    Hash of the subject public key (default empty). Hash algorithm is defined by name-hash-algorithm.

  • hash-of-issuer-public-key

    Hash of the issues public key (default empty). Hash algorithm is defined by name-hash-algorithm.

  • java-midp-security-domain

    Java MIDP security domain. This must be one of unspecified, manufacturer, operator or third-party.

  • name-hash-algorithm

    Defines the mechanism used to calculate hash-of-subject-public-key and hash-of-issues-public-key. If the attribute is not present then the type defaults to SHA-1.

WTLS certificates

  • subject

    DER-encoding of the certificate subject name.

  • issuer

    DER-encoding of the certificate issuer name.

  • value

    WTLS-encoding of the certificate. MUST be non-empty if url is empty.

  • url

    If not empty this attribute gives the URL where the complete certificate can be obtained. MUST be non-empty if value is empty.

  • hash-of-subject-public-key

    Hash of the subject public key (default empty). Hash algorithm is defined by name-hash-algorithm.

  • hash-of-issuer-public-key

    Hash of the issues public key (default empty). Hash algorithm is defined by name-hash-algorithm.

  • name-hash-algorithm

    Defines the mechanism used to calculate hash-of-subject-public-key and hash-of-issues-public-key. If the attribute is not present then the type defaults to SHA-1.

X509 attribute certificates

  • owner

    DER-encoding of the attribute certificate's subject field. This is distinct from the subject attribute contained in X509 certificates because the ASN.1 syntax and encoding are different.

  • ac-issuer

    DER-encoding of the attribute certificate's issuer field. This is distinct from the issuer attribute contained in X509 certificates because the ASN.1 syntax and encoding are different.

  • serial-number

    DER-encoding of the certificate serial number.

  • attr-types

    BER-encoding of a sequence of object identifier values corresponding to the attribute types contained in the certificate. When present, this field offers an opportunity for applications to search for a particular attribute certificate without fetching and parsing the certificate itself. (default empty).

  • value

    BER-encoding of the certificate.

Key objects

All key types share the following attributes:

  • key-type

    The type of the key. Valid values include: rsa, dsa, dh, ec, ecdsa, x9-42-dh, kea, generic-secret, rc2, rc4, des, des2, des3, cast, cast3, cast128, cast5, rc5, idea, skipjack, baton, juniper, cdmf, aes, blowfish, twofish, securid, hotp, acti, camellia, aria, md5-hmac, sha1-hmac, ripemd128-hmac, ripemd160-hmac, sha256-hmac, sha384-hmac, sha512-hmac, sha224-hmac, seed, gostr3410, gostr3411, gost28147, chacha20, poly1305, aes-xts, sha3-224-hmac, sha3-256-hmac, sha3-384-hmac, sha3-512-hmac, blake2b-160-hmac, blake2b-256-hmac, blake2b-384-hmac, blake2b-512-hmac, salsa20, x2ratchet, ec-edwards, ec-montgomery, hkdf, sha512-224-hmac, sha512-256-hmac, sha512-t-hmac, hss, xmss, xmssmt, ml-kem, ml-dsa, slh-dsa, and vendor-defined

  • id

    Key identifier for key.

  • start-date

    Start date for the key.

  • end-date

    End date for the key.

  • derive

    True if key supports key derivation (i.e., if other keys can be derived from this one).

  • local

    True only if key was either:

    • Generated locally (i.e., on the token) with a generate_key or generate_keypair call.

    • Created with a C_CopyObject call as a copy of a key which had its local attribute set to true.

  • key-gen-mechanism

    The mechanism used to generate a new value of this key type.

  • allowed-mechanisms

    An arrayref of mechanisms that can be used with this key type.

  • parameter-set

    This represents the parameter set of a cryptographic operation. The meaning of this integer depends on the involved algorithm. For some algoritms, textual input aliases are defined:

    For ml-dsa the following parameter sets are defined: mk-dsa-44 (1), ml-dsa-65 (2), and ml-dsa-87 (3).

    For slh-dsa the following parameter sets are defined: slh-dsa-sha2-128s (1), slh-dsa-shake-128s (2), slh-dsa-sha2-128f (3), slh-dsa-shake-128f (4), slh-dsa-sha2-192s (5), slh-dsa-shake-192s (6), slh-dsa-sha2-192f (7), slh-dsa-shake-192f (8), slh-dsa-sha2-256s (9), slh-dsa-shake-256s (10), slh-dsa-sha2-256f (11), slh-dsa-shake-256f (12) are defined.

    For ml-kem the following parameter sets are defined: ml-kem-512 (1), ml-kem-768 (2), ml-kem-1024 (3)

    For xmms and xmssmt, valid values are defined by NIST SP800-208.

Public key objects

  • subject

    DER-encoding of the key subject name.

  • encrypt

    True if key supports encryption.

  • verify

    True if key supports verification where the signature is an appendix to the data.

  • verify-recover

    True if key supports verification where the data is recovered from the signature.

  • wrap

    True if key supports wrapping (i.e., can be used to wrap other keys).

  • trusted

    The key can be trusted for the application that it was created.

    The wrapping key can be used to wrap keys with wrap-with-trusted set to true.

  • wrap-template

    For wrapping keys. The attribute template to match against any keys wrapped using this wrapping key. Keys that do not match cannot be wrapped.

  • public-key-info

    DER-encoding of the SubjectPublicKeyInfo for the public key contained in this certificate.

Private key objects

  • subject

    DER-encoding of certificate subject name.

  • sensitive

    True if key is sensitive.

  • decrypt

    True if key supports decrypt.

  • sign

    True if key supports sign.

  • sign-recover

    True if key supports sign_recover.

  • unwrap

    True if key supports unwrap.

  • extractable

    True if key is extractable and can be wrapped.

  • always-sensitive

    True if key has always had the sensitive attribute set to true.

  • never-extractable

    True if key has never had the extractable attribute set to true.

  • wrap-with-trusted

    True if the key can only be wrapped with a wrapping key that has trusted set to true.

  • unwrap-template

    For wrapping keys. The attribute template to apply to any keys unwrapped using this wrapping key. Any user supplied template is applied after this template as if the object has already been created.

  • always-authenticate

    If true, the user has to supply the PIN for each use (sign or decrypt) with the key. Default is false.

  • public-key-info

    DER-encoding of the SubjectPublicKeyInfo for the public key contained in this certificate.

  • c<derive-template>

    For deriving keys. The attribute template to match against any keys derived using this derivation key. Any user supplied template is applied after this template as if the object has already been created.

RSA private key objects

  • modulus

    Modulus n

  • public-exponent

    Public exponent e.

  • private-exponent

    Private exponent d.

  • prime-1

    Prime p.

  • prime-2

    Prime q.

  • exponent-1

    Private exponent d modulo p-1.

  • exponent-2

    Private exponent d modulo q-1.

  • coefficient

    CRT coefficient q-1 mod p.

Secret key objects

  • sensitive

    True if key is sensitive.

  • encrypt

    True if key supports encrypt.

  • decrypt

    True if key supports decrypt.

  • sign

    True if key supports sign.

  • verify

    True if key supports verify (i.e., of authentication codes) where the signature is an appendix to the data.

  • wrap

    True if key supports wrap (i.e., can be used to wrap other keys).

  • unwrap

    True if key supports unwrap (i.e., can be used to unwrap other keys).

  • extractable

    True if key is extractable and can be wrapped.

  • always-sensitive

    True if key has always had the sensitive attribute set to true.

  • never-extractable

    True if key has never had the extractable attribute set to true.

  • check-value

    Key checksum.

  • wrap-with-trusted

    True if the key can only be wrapped with a wrapping key that has trusted set to true.

  • trusted

    The wrapping key can be used to wrap keys with wrap-with-trusted set to true.

  • wrap-template

    For wrapping keys. The attribute template to match against any keys wrapped using this wrapping key. Keys that do not match cannot be wrapped.

  • unwrap-template

    For wrapping keys. The attribute template to apply to any keys unwrapped using this wrapping key. Any user supplied template is applied after this template as if the object has already been created.

  • c<derive-template>

    For deriving keys. The attribute template to match against any keys derived using this derivation key. Any user supplied template is applied after this template as if the object has already been created.

Data objects

  • application

    Description of the application that manages the object.

  • object-id

    DER-encoding of the object identifier indicating the data object type.

  • value

    Value of the object.

Domain parameter objects

  • key-type

    Type of key the domain parameters can be used to generate.

  • local

    True only if key was either:

    • Generated locally (i.e., on the token) with a generate_key or generate_keypair call.

    • Created with a copy-object call as a copy of a key which had its local attribute set to true.

Mechanism objects

Profile options

  • profile-id

    This can be baseline-provider, extended-provider, authentication-token, public-certificates-token, complete-provider, hkdf-tls-token, vendor-provided, or invalid-id.

Hardware objects

  • hardware-feature-type

    This can be one of monotonic-counter, clock, user-interface, vendor-defined.

Monotonic counter

  • reset-on-init

    The value of the counter will reset to a previously returned value if the token is initialized using init-token.

  • has-reset

    The value of the counter has been reset at least once at some point in time.

  • value

    The current version of the monotonic counter. The value is returned in big endian order.

Clock

  • value

    Current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved ‘0’ characters).

User Interface

  • pixel-x

    Screen resolution (in pixels) in X-axis (e.g. 1280).

  • pixel-y

    Screen resolution (in pixels) in Y-axis (e.g. 1024).

  • resolution

    DPI, pixels per inch.

  • char-rows

    For character-oriented displays; number of character rows (e.g. 24).

  • char-columns

    For character-oriented displays: number of character columns (e.g. 80). If display is of proportional-font type, this is the width of the display in “em”-s (letter “M”).

  • color

    Color support.

  • bits-per-pixel

    The number of bits of color or grayscale information per pixel.

  • char-sets

    String indicating supported character sets, as defined by IANA MIBenum sets (www.iana.org). Supported character sets are separated with “;”. E.g. a token supporting iso-8859-1 and US-ASCII would set the attribute value to “4;3”.

  • encoding-methods

    String indicating supported content transfer encoding methods, as defined by IANA (www.iana.org). Supported methods are separated with “;”. E.g. a token supporting 7bit, 8bit and base64 could set the attribute value to “7bit;8bit;base64”.

  • mime-types

    String indicating supported (presentable) MIME-types, as defined by IANA (www.iana.org). Supported types are separated with “;”. E.g. a token supporting MIME types "a/b", "a/c" and "a/d" would set the attribute value to “a/b;a/c;a/d”.

Validation objects

Validation objects describe which third party validations the module conforms to. Validation objects are read only, token objects.

The have the following attributes:

  • validation-type

    Identifier indicating the validation type. This must be one of: unspecified, software, hardware, firmware or hybrid

  • validation-version

    Version of the validation standard or specification

  • validation-level

    Validation level, Meaning is Validation type specific

  • validation-module-id

    How the module is identified in the validation documentation

  • validation-flag

    Flags identifying this validation in sessions and objects

  • validation-authority-type

    Identifies the authority that issues the validation. This must be one of: unspecified, nist-cmvp or common-criteria.

  • validation-country

    2 letter ISO country code

  • validation-certificate-identifier

    Identifier of the validation certificate

  • validation-certificate-uri

    Validation authority URI from which information related to the validation is available. If the Validation Certificate URI is not provided, the validation object SHOULD include a Validation Vendor URI.

  • validation-vendor-uri

    Validation Vendor URI from which information related to the validation is available.

  • validation-profile

    Profile used for validation

Trust objects

Trust objects bind trusted usages to individual certificates. Trust objects for a given certificate are accessed using the issuer and serial-number attributes, and may be confirmed by comparing hash-of-certificate with a recomputed hash value. The corresponding certificate does not necessarily have to exist in the same token as its trust object. Multiple trust objects for the same certificate can exist in different tokens, but each token should have no more than one trust object for a given certificate.

The have the following attributes:

  • issuer

    DER-encoding of the certificate issuer name (default empty)

  • serial-number

    DER-encoding of the certificate serial number (default empty)

  • hash-of-certificate

    Cryptographic hash of the certificate computed by name-hash-algorithm (default empty)

  • name-hash-algorithm

    Mechanism used to calculate hash-of-certificate (defaults to SHA-1 if not present)

  • trust-server-auth

    Trust for authenticating the server in a client/server interaction (as in TLS/SSL/SSH)

  • trust-client-auth

    Trust for authenticating the client in a client/server interaction (as in TLS/SSL/SSH)

  • trust-code-signing

    Trust for authenticating a code fragment

  • trust-email-protection

    Trust for authenticating an email user

  • trust-ipsec-ike

    Trust for IPSEC

  • trust-time-stamping

    Trust for timestamping

  • trust-ocsp-signing

    Trust for OCSP Signing

The trust- values

  • trusted

    The certificate is trusted for the associated operation.

  • trust-anchor

    The certificate is trusted as a root signing certificate for chain validation of a cert that is trusted for the associate operation; this applies even when the certificate is not self-signed and when the certificate does not have the proper attributes to be CA certificate.

  • not-trusted

    The certificate is explicitly not trusted for the associated operation, nor can trust chain through the certificate to an otherwise trusted root; this attribute can be used to ‘revoke’ intermediate CA certificates that have been compromised without removing trust from the parent certificate.

  • trust-must-verify-trust

    The certificate is neither trusted nor untrusted for the associated operation.

  • trust-unknown

    The certificate is neither trusted nor untrusted for the associated operation.

To obtain the effective trust attributes for a given certificate, the typical application will first:

1. identify the tokens containing a Trust object with matching CKA_ISSUER and CKA_SERIAL_NUMBER (and optionally check that CKA_HASH_OF_CERTIFICATE agrees with the hash of the certificate computed using CKA_NAME_HASH_ALGORITHM),
2. determine which of those Trust objects should be processed (presumably according to an established security policy), and
3. arrange the selected Trust objects in a list sorted in order of increasing priority.

Now, taking the first Trust object in the list as the initial working Trust object (WTO) with all omitted attributes assumed to have the value trust-unknown, the remaining Trust objects in the list are iteratively merged into it as follows:

1. if the value of a trust attribute in the current object is CKT_TRUST_UNKNOWN, that attribute is left unchanged in the WTO,
2. otherwise, the current attribute value replaces the attribute value in the WTO .

Note that at any step of this process, an attribute value of CKT_TRUST_MUST_VERIFY_TRUST in the current Trust object resets any trust or distrust assigned to that attribute in the WTO by a lower priority token.

When the process is complete, the final (“effective”) trust attribute values are to be interpreted as follows:

AUTHOR

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.