Module: Linzer::Key::Helper

Included in:
Linzer
Defined in:
lib/linzer/key/helper.rb

Overview

Helper methods for generating and loading cryptographic keys.

These methods provide convenient factory functions for creating Linzer::Key instances for various algorithms. They are mixed into the Linzer module and can be called directly.

Examples:

Generating keys

ed25519_key = Linzer.generate_ed25519_key("my-key")
hmac_key = Linzer.generate_hmac_sha256_key("hmac-key")
ecdsa_key = Linzer.generate_ecdsa_p256_sha256_key("ecdsa-key")

Loading keys from PEM

key = Linzer.new_ed25519_key(File.read("private.pem"), "my-key")
pubkey = Linzer.new_ed25519_public_key(File.read("public.pem"), "my-key")

See Also:

Instance Method Summary collapse

Instance Method Details

#generate_ecdsa_p256_sha256_key(key_id = nil) ⇒ ECDSA::Key

Generates a new ECDSA P-256 key pair with SHA-256 digest.

ECDSA P-256 (also known as secp256r1 or prime256v1) is widely supported and provides good security for most applications.

Uses the ecdsa-p256-sha256 algorithm identifier.

Examples:

key = Linzer.generate_ecdsa_p256_sha256_key("ecdsa-key")

Parameters:

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:

See Also:



200
201
202
203
 
# File 'lib/linzer/key/helper.rb', line 200

def generate_ecdsa_p256_sha256_key(key_id = nil)
  material = OpenSSL::PKey::EC.generate("prime256v1")
  Linzer::ECDSA::Key.new(material, id: key_id, digest: "SHA256")
end

#generate_ecdsa_p384_sha384_key(key_id = nil) ⇒ ECDSA::Key

Generates a new ECDSA P-384 key pair with SHA-384 digest.

ECDSA P-384 (also known as secp384r1) provides higher security than P-256 at the cost of larger signatures and slightly slower operations.

Uses the ecdsa-p384-sha384 algorithm identifier.

Examples:

key = Linzer.generate_ecdsa_p384_sha384_key("high-security-key")

Parameters:

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:

See Also:



229
230
231
232
 
# File 'lib/linzer/key/helper.rb', line 229

def generate_ecdsa_p384_sha384_key(key_id = nil)
  material = OpenSSL::PKey::EC.generate("secp384r1")
  Linzer::ECDSA::Key.new(material, id: key_id, digest: "SHA384")
end

#generate_ed25519_key(key_id = nil) ⇒ Ed25519::Key

Generates a new Ed25519 key pair.

Ed25519 is a modern elliptic curve signature algorithm that provides excellent security and performance. Recommended for new applications.

Uses the ed25519 algorithm identifier.

Examples:

key = Linzer.generate_ed25519_key("my-ed25519-key")

Parameters:

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



151
152
153
154
 
# File 'lib/linzer/key/helper.rb', line 151

def generate_ed25519_key(key_id = nil)
  material = OpenSSL::PKey.generate_key("ed25519")
  Linzer::Ed25519::Key.new(material, id: key_id)
end

#generate_hmac_sha256_key(key_id = nil) ⇒ HMAC::Key

Generates a new HMAC-SHA256 symmetric key.

HMAC keys are symmetric, meaning the same key is used for both signing and verification. The key material must be kept secret.

Uses the hmac-sha256 algorithm identifier.

Examples:

key = Linzer.generate_hmac_sha256_key("shared-secret")

Parameters:

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:

  • (HMAC::Key) —

    A new 64-byte random HMAC key



119
120
121
122
 
# File 'lib/linzer/key/helper.rb', line 119

def generate_hmac_sha256_key(key_id = nil)
  material = OpenSSL::Random.random_bytes(64)
  Linzer::HMAC::Key.new(material, id: key_id, digest: "SHA256")
end

#generate_jws_key(algorithm:) ⇒ JWS::Key

Generates a new JWS key for the specified algorithm.

This method generates keys compatible with JSON Web Signature (JWS) format. Currently only EdDSA (Ed25519) is supported.

Examples:

key = Linzer.generate_jws_key(algorithm: "EdDSA")

Parameters:

  • algorithm (String) —

    The JWS algorithm identifier (e.g., “EdDSA”)

Returns:

  • (JWS::Key) —

    A new JWS-compatible key

Raises:

  • (Error) —

    If the algorithm is not supported



255
256
257
 
# File 'lib/linzer/key/helper.rb', line 255

def generate_jws_key(algorithm:)
  Linzer::JWS.generate_key(algorithm: algorithm)
end

#generate_rsa_pss_sha512_key(size, key_id = nil) ⇒ RSAPSS::Key

Generates a new RSA-PSS key pair with SHA-512 digest.

RSA-PSS (RSASSA-PSS) is the recommended RSA signature scheme. Uses the rsa-pss-sha512 algorithm identifier.

Examples:

key = Linzer.generate_rsa_pss_sha512_key(2048, "my-rsa-key")

Parameters:

  • size (Integer) —

    Key size in bits (ignored, uses OpenSSL default)

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



33
34
35
36
 
# File 'lib/linzer/key/helper.rb', line 33

def generate_rsa_pss_sha512_key(size, key_id = nil)
  material = OpenSSL::PKey.generate_key("RSASSA-PSS")
  Linzer::RSAPSS::Key.new(material, id: key_id, digest: "SHA512")
end

#generate_rsa_v1_5_sha256_key(size, key_id = nil) ⇒ RSA::Key

Note:

RSA-PSS is preferred for new applications. Use this only for compatibility with systems requiring PKCS#1 v1.5.

Generates a new RSA PKCS#1 v1.5 key pair with SHA-256 digest.

Uses the rsa-v1_5-sha256 algorithm identifier.

Examples:

key = Linzer.generate_rsa_v1_5_sha256_key(2048, "legacy-rsa")

Parameters:

  • size (Integer) —

    Key size in bits (e.g., 2048, 4096)

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



81
82
83
84
 
# File 'lib/linzer/key/helper.rb', line 81

def generate_rsa_v1_5_sha256_key(size, key_id = nil)
  material = OpenSSL::PKey::RSA.generate(size)
  Linzer::RSA::Key.new(material, id: key_id, digest: "SHA256")
end

#jwk_import(key, params = {}) ⇒ JWS::Key

Imports a key from JWK (JSON Web Key) format.

Examples:

Importing from JWK

jwk = JSON.parse(File.read("key.jwk"))
key = Linzer.jwk_import(jwk)

Parameters:

  • key (Hash) —

    The JWK as a Hash (parsed from JSON)

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

    Additional key parameters

Options Hash (params):

  • :id (String) —

    Key identifier to use (overrides JWK “kid”)

Returns:



269
270
271
 
# File 'lib/linzer/key/helper.rb', line 269

def jwk_import(key, params = {})
  Linzer::JWS.jwk_import(key, params)
end

#new_ecdsa_p256_sha256_key(material, key_id = nil) ⇒ ECDSA::Key

Loads an ECDSA P-256 key from PEM-encoded material.

Parameters:

  • material (String) —

    PEM-encoded EC key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



210
211
212
213
 
# File 'lib/linzer/key/helper.rb', line 210

def new_ecdsa_p256_sha256_key(material, key_id = nil)
  key = OpenSSL::PKey::EC.new(material)
  Linzer::ECDSA::Key.new(key, id: key_id, digest: "SHA256")
end

#new_ecdsa_p384_sha384_key(material, key_id = nil) ⇒ ECDSA::Key

Loads an ECDSA P-384 key from PEM-encoded material.

Parameters:

  • material (String) —

    PEM-encoded EC key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



239
240
241
242
 
# File 'lib/linzer/key/helper.rb', line 239

def new_ecdsa_p384_sha384_key(material, key_id = nil)
  key = OpenSSL::PKey::EC.new(material)
  Linzer::ECDSA::Key.new(key, id: key_id, digest: "SHA384")
end

#new_ed25519_key(material, key_id = nil) ⇒ Ed25519::Key

Loads an Ed25519 key from PEM-encoded material.

Can load either a private key (for signing) or public key (for verification).

Examples:

Loading a private key for signing

key = Linzer.new_ed25519_key(File.read("ed25519.pem"), "my-key")

Parameters:

  • material (String) —

    PEM-encoded Ed25519 key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



166
167
168
169
 
# File 'lib/linzer/key/helper.rb', line 166

def new_ed25519_key(material, key_id = nil)
  key = OpenSSL::PKey.read(material)
  Linzer::Ed25519::Key.new(key, id: key_id)
end

#new_ed25519_public_key(material, key_id = nil) ⇒ Ed25519::Key

Loads an Ed25519 public key from PEM-encoded material.

This is an alias for #new_ed25519_key for clarity when loading public keys specifically.

Examples:

pubkey = Linzer.new_ed25519_public_key(File.read("ed25519_pub.pem"), "my-key")

Parameters:

  • material (String) —

    PEM-encoded Ed25519 public key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



182
183
184
 
# File 'lib/linzer/key/helper.rb', line 182

def new_ed25519_public_key(material, key_id = nil)
  new_ed25519_key(material, key_id)
end

#new_hmac_sha256_key(material, key_id = nil) ⇒ HMAC::Key

Creates an HMAC-SHA256 key from existing key material.

Examples:

Loading from environment

key = Linzer.new_hmac_sha256_key(
  Base64.decode64(ENV["HMAC_SECRET"]),
  "api-key"
)

Parameters:

  • material (String) —

    The secret key bytes (should be at least 32 bytes)

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



135
136
137
 
# File 'lib/linzer/key/helper.rb', line 135

def new_hmac_sha256_key(material, key_id = nil)
  Linzer::HMAC::Key.new(material, id: key_id, digest: "SHA256")
end

#new_rsa_pss_sha512_key(material, key_id = nil) ⇒ RSAPSS::Key

Loads an RSA-PSS key from PEM-encoded material.

Can load either a private key (for signing) or public key (for verification).

Examples:

Loading a private key

key = Linzer.new_rsa_pss_sha512_key(File.read("private.pem"), "my-key")

Loading a public key

pubkey = Linzer.new_rsa_pss_sha512_key(File.read("public.pem"), "my-key")

Parameters:

  • material (String) —

    PEM-encoded RSA key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



51
52
53
54
 
# File 'lib/linzer/key/helper.rb', line 51

def new_rsa_pss_sha512_key(material, key_id = nil)
  key = OpenSSL::PKey.read(material)
  Linzer::RSAPSS::Key.new(key, id: key_id, digest: "SHA512")
end

#new_rsa_pss_sha512_public_key(material, key_id = nil) ⇒ RSAPSS::Key

Deprecated.

Use #new_rsa_pss_sha512_key instead, which handles both public and private keys.

Loads an RSA-PSS public key from PEM-encoded material.

Parameters:

  • material (String) —

    PEM-encoded RSA public key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



63
64
65
66
 
# File 'lib/linzer/key/helper.rb', line 63

def new_rsa_pss_sha512_public_key(material, key_id = nil)
  key = OpenSSL::PKey::RSA.new(material)
  Linzer::RSAPSS::Key.new(key, id: key_id, digest: "SHA512")
end

#new_rsa_v1_5_sha256_key(material, key_id = nil) ⇒ RSA::Key

Loads an RSA PKCS#1 v1.5 key from PEM-encoded material.

Parameters:

  • material (String) —

    PEM-encoded RSA key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



91
92
93
94
 
# File 'lib/linzer/key/helper.rb', line 91

def new_rsa_v1_5_sha256_key(material, key_id = nil)
  key = OpenSSL::PKey.read(material)
  Linzer::RSA::Key.new(key, id: key_id, digest: "SHA256")
end

#new_rsa_v1_5_sha256_public_key(material, key_id = nil) ⇒ RSA::Key

Deprecated.

Use #new_rsa_v1_5_sha256_key instead.

Loads an RSA PKCS#1 v1.5 public key from PEM-encoded material.

Parameters:

  • material (String) —

    PEM-encoded RSA public key

  • key_id (String, nil) (defaults to: nil) —

    Optional key identifier

Returns:



102
103
104
105
 
# File 'lib/linzer/key/helper.rb', line 102

def new_rsa_v1_5_sha256_public_key(material, key_id = nil)
  key = OpenSSL::PKey.read(material)
  Linzer::RSA::Key.new(key, id: key_id, digest: "SHA256")
end