NAME

Crypt::HSM::Object - A PKCS11 object

VERSION

version 0.025

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, 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 (e.g. aes).

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

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

• mechanism-type

  The mechanism object.

• 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”.

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.

cpanm Crypt::HSM

perl -MCPAN -e shell
install Crypt::HSM