Module: PQCrypto::PKCS8

Defined in:
lib/pq_crypto/pkcs8.rb

Constant Summary collapse

PEM_LABEL = 
"PRIVATE KEY"
PEM_BEGIN = 
"-----BEGIN #{PEM_LABEL}-----"
PEM_END = 
"-----END #{PEM_LABEL}-----"
ENCRYPTED_PEM_LABEL = 
"ENCRYPTED PRIVATE KEY"
ENCRYPTED_PEM_BEGIN = 
"-----BEGIN #{ENCRYPTED_PEM_LABEL}-----"
ENCRYPTED_PEM_END = 
"-----END #{ENCRYPTED_PEM_LABEL}-----"
ML_KEM_SEED_BYTES = 
64
ML_DSA_SEED_BYTES = 
32
PBES2_OID = 
"1.2.840.113549.1.5.13"
PBKDF2_OID = 
"1.2.840.113549.1.5.12"
HMAC_SHA256_OID = 
"1.2.840.113549.2.9"
AES_256_CBC_OID = 
"2.16.840.1.101.3.4.1.42"
ENCRYPTED_PKCS8_DEFAULT_ITERATIONS = 
200_000
PRIVATE_KEY_CHOICES = 
{
  ml_kem_512: {
    seed_bytes: ML_KEM_SEED_BYTES,
    expanded_bytes: PQCrypto::ML_KEM_512_SECRET_KEY_BYTES,
    supported_formats: %i[seed expanded both],
  }.freeze,
  ml_kem_768: {
    seed_bytes: ML_KEM_SEED_BYTES,
    expanded_bytes: PQCrypto::ML_KEM_SECRET_KEY_BYTES,
    supported_formats: %i[seed expanded both],
  }.freeze,
  ml_kem_1024: {
    seed_bytes: ML_KEM_SEED_BYTES,
    expanded_bytes: PQCrypto::ML_KEM_1024_SECRET_KEY_BYTES,
    supported_formats: %i[seed expanded both],
  }.freeze,
  ml_dsa_44: {
    seed_bytes: ML_DSA_SEED_BYTES,
    expanded_bytes: PQCrypto::SIGN_44_SECRET_KEY_BYTES,
    supported_formats: %i[seed expanded both],
  }.freeze,
  ml_dsa_65: {
    seed_bytes: ML_DSA_SEED_BYTES,
    expanded_bytes: PQCrypto::SIGN_SECRET_KEY_BYTES,
    supported_formats: %i[seed expanded both],
  }.freeze,
  ml_dsa_87: {
    seed_bytes: ML_DSA_SEED_BYTES,
    expanded_bytes: PQCrypto::SIGN_87_SECRET_KEY_BYTES,
    supported_formats: %i[seed expanded both],
  }.freeze,
}.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.allow_ml_dsa_seed_format ⇒ Object

Returns the value of attribute allow_ml_dsa_seed_format.



57
58
59
 
# File 'lib/pq_crypto/pkcs8.rb', line 57

def allow_ml_dsa_seed_format
  @allow_ml_dsa_seed_format
end

Class Method Details

.decode_der(der, passphrase: nil) ⇒ Object

Raises:



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/pq_crypto/pkcs8.rb', line 103

def decode_der(der, passphrase: nil)
  input = String(der).b
  outer = decode_asn1(input)
  raise SerializationError, "PKCS#8 DER contains trailing data" unless outer.to_der.b == input
  raise SerializationError, "PKCS#8 must be an ASN.1 SEQUENCE" unless outer.is_a?(OpenSSL::ASN1::Sequence)

  if encrypted_private_key_info?(outer)
    raise SerializationError, "Encrypted PKCS#8 requires passphrase" if passphrase.nil?

    plain_der = decrypt_der(outer, passphrase: passphrase)
    begin
      return decode_der(plain_der)
    ensure
      safe_wipe(plain_der)
    end
  end

  raise SerializationError, "PKCS#8 OneAsymmetricKey must contain exactly 3 elements" unless outer.value.size == 3

  version, algorithm_identifier, private_key = outer.value
  decode_version(version)
  algorithm = decode_algorithm_identifier(algorithm_identifier)
  entry = AlgorithmRegistry.fetch(algorithm)
  validate_secret_key_algorithm!(algorithm, entry)

  unless private_key.is_a?(OpenSSL::ASN1::OctetString)
    raise SerializationError, "PKCS#8 privateKey must be an OCTET STRING"
  end

  decode_private_key_choice(algorithm, String(private_key.value).b)
end

.decode_pem(pem, passphrase: nil) ⇒ Object 



135
136
137
138
 
# File 'lib/pq_crypto/pkcs8.rb', line 135

def decode_pem(pem, passphrase: nil)
  der = der_from_pem(pem)
  decode_der(der, passphrase: passphrase)
end

.encode_der(algorithm_symbol, secret_material, format:, passphrase: nil, iterations: ENCRYPTED_PKCS8_DEFAULT_ITERATIONS) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/pq_crypto/pkcs8.rb', line 59

def encode_der(algorithm_symbol, secret_material, format:, passphrase: nil, iterations: ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
  entry = AlgorithmRegistry.fetch(algorithm_symbol)
  validate_secret_key_algorithm!(algorithm_symbol, entry)
  ensure_format_supported!(algorithm_symbol, format)

  choice_der = case format
               when :seed
                 encode_seed_choice(secret_material, algorithm_symbol)
               when :expanded
                 encode_expanded_key_choice(secret_material, algorithm_symbol)
               when :both
                 encode_both_choice(secret_material, algorithm_symbol)
               else
                 raise SerializationError, "Unsupported PKCS#8 private key format: #{format.inspect}"
               end

  der = OpenSSL::ASN1::Sequence.new([
    OpenSSL::ASN1::Integer.new(0),
    OpenSSL::ASN1::Sequence.new([
      OpenSSL::ASN1::ObjectId.new(AlgorithmRegistry.standard_oid(algorithm_symbol)),
    ]),
    OpenSSL::ASN1::OctetString.new(choice_der),
  ]).to_der.b

  return der if passphrase.nil?

  encrypt_der(der, passphrase: passphrase, iterations: iterations)
rescue OpenSSL::ASN1::ASN1Error => e
  raise SerializationError, e.message
ensure
  safe_wipe(choice_der) if defined?(choice_der)
  safe_wipe(der) if passphrase && defined?(der)
end

.encode_pem(algorithm_symbol, secret_material, format:, passphrase: nil, iterations: ENCRYPTED_PKCS8_DEFAULT_ITERATIONS) ⇒ Object 



93
94
95
96
97
98
99
100
101
 
# File 'lib/pq_crypto/pkcs8.rb', line 93

def encode_pem(algorithm_symbol, secret_material, format:, passphrase: nil, iterations: ENCRYPTED_PKCS8_DEFAULT_ITERATIONS)
  der = encode_der(algorithm_symbol, secret_material, format: format, passphrase: passphrase, iterations: iterations)
  body = encode_base64(der).scan(/.{1,64}/).join("\n")
  if passphrase.nil?
    "#{PEM_BEGIN}\n#{body}\n#{PEM_END}\n"
  else
    "#{ENCRYPTED_PEM_BEGIN}\n#{body}\n#{ENCRYPTED_PEM_END}\n"
  end
end