Class: Linzer::Key Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/linzer/key.rb,
lib/linzer/key/helper.rb

Overview

This class is abstract.

Subclass and override #sign and #verify to implement a specific cryptographic algorithm.

Abstract base class for cryptographic keys used in HTTP message signatures.

This class provides the common interface for all key types supported by Linzer. Do not instantiate this class directly; use one of the concrete subclasses or the key generation/loading helper methods.

Examples:

Using a concrete key class via helper methods

# Generate a new Ed25519 key pair
key = Linzer.generate_ed25519_key("my-key-id")

# Load an existing RSA-PSS key from PEM
key = Linzer.new_rsa_pss_sha512_key(File.read("private.pem"), "rsa-key")

See Also:

Defined Under Namespace

Modules: Helper

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(material, params = {}) ⇒ Key

Creates a new Key instance.

Parameters:

  • material (OpenSSL::PKey::PKey, String) —

    The key material. For asymmetric keys, this is typically an OpenSSL key object. For HMAC, this is the raw secret bytes.

  • params (Hash) (defaults to: {}) —

    Additional key parameters

Options Hash (params):

  • :id (String) —

    The key identifier (keyid) for this key

  • :digest (String) —

    The digest algorithm (e.g., “SHA256”, “SHA512”)

Raises:

  • (Error) —

    If key material is nil or invalid



37
38
39
40
41
42
 
# File 'lib/linzer/key.rb', line 37

def initialize(material, params = {})
  @material = material
  @params   = Hash(params).clone.freeze
  validate
  freeze
end

Instance Attribute Details

#material ⇒ Object (readonly)

Returns The underlying key material.

Returns:

  • (Object) —

    The underlying key material



45
46
47
 
# File 'lib/linzer/key.rb', line 45

def material
  @material
end

Instance Method Details

#key_id ⇒ String?

Returns the key identifier.

The key ID is used in the keyid parameter of HTTP signatures to identify which key was used for signing.

Returns:

  • (String, nil) —

    The key identifier, or nil if not set



53
54
55
 
# File 'lib/linzer/key.rb', line 53

def key_id
  @params[:id]
end

#private? ⇒ Boolean

Checks if this key can be used for signing.

Returns:

  • (Boolean) —

    true if the key contains private key material



93
94
95
 
# File 'lib/linzer/key.rb', line 93

def private?
  material.private?
end

#public? ⇒ Boolean

Checks if this key can be used for signature verification.

Returns:

  • (Boolean) —

    true if the key contains public key material



86
87
88
 
# File 'lib/linzer/key.rb', line 86

def public?
  material.public?
end

#sign(*args) ⇒ String

This method is abstract.

Subclasses must override this method.

Signs data using this key.

Parameters:

  • args (Array) —

    Implementation-specific arguments (typically data to sign)

Returns:

  • (String) —

    The signature bytes

Raises:

  • (Error) —

    If called on the abstract base class

  • (SigningError) —

    If the key cannot be used for signing



65
66
67
68
 
# File 'lib/linzer/key.rb', line 65

def sign(*args)
  abstract_error = "Cannot sign data, \"#{self.class}\" is an abstract class."
  raise Error, abstract_error
end

#verify(*args) ⇒ Boolean

This method is abstract.

Subclasses must override this method.

Verifies a signature against data using this key.

Parameters:

  • args (Array) —

    Implementation-specific arguments (typically signature and data)

Returns:

  • (Boolean) —

    true if the signature is valid, false otherwise

Raises:

  • (Error) —

    If called on the abstract base class

  • (VerifyError) —

    If the key cannot be used for verification



78
79
80
81
 
# File 'lib/linzer/key.rb', line 78

def verify(*args)
  abstract_error = "Cannot verify signature, \"#{self.class}\" is an abstract class."
  raise Error, abstract_error
end