Class: Rnp::Key

Inherits:
Object
  • Object
show all
Defined in:
lib/rnp/key.rb

Overview

Class that represents a PGP key (potentially encompassing both the public and private portions).

Instance Method Summary collapse

Instance Method Details

#add_userid(userid, hash: nil, expiration_time: 0, key_flags: 0, primary: false) ⇒ void

This method returns an undefined value.

Add a userid to a key.

Parameters:

  • userid (String) —

    the userid to add

  • key_flags (Integer) (defaults to: 0)
  • primary (Boolean) (defaults to: false) —

    if true then this userid will be marked as the primary userid

  • hash (String) (defaults to: nil) —

    the hash algorithm name

  • expiration_time (Integer) (defaults to: 0) —

    the lifetime of the signature(s), as the number of seconds. The actual expiration date/time is the creation time plus this value. A value of 0 will create signatures that do not expire.



134
135
136
137
138
 
# File 'lib/rnp/key.rb', line 134

def add_userid(userid, hash: nil, expiration_time: 0, key_flags: 0,
               primary: false)
  Rnp.call_ffi(:rnp_key_add_uid, @ptr, userid, hash, expiration_time,
               key_flags, primary)
end

#bits ⇒ Integer

Get the bit length for this key.

Returns:

  • (Integer) 


351
352
353
354
355
 
# File 'lib/rnp/key.rb', line 351

def bits
  pbits = FFI::MemoryPointer.new(:uint32)
  Rnp.call_ffi(:rnp_key_get_bits, @ptr, pbits)
  pbits.read(:uint32)
end

#can?(op) ⇒ Boolean

Query whether this key can be used to perform a certain operation.

Parameters:

  • op (String, Symbol) —

    the operation to query (sign, etc)

Returns:

  • (Boolean) 


377
378
379
380
381
 
# File 'lib/rnp/key.rb', line 377

def can?(op)
  pvalue = FFI::MemoryPointer.new(:bool)
  Rnp.call_ffi(:rnp_key_allows_usage, @ptr, op.to_s, pvalue)
  pvalue.read(:bool)
end

#compromised? ⇒ Boolean

Check if this revoked key’s material was compromised.

Returns:

  • (Boolean) 


393
394
395
 
# File 'lib/rnp/key.rb', line 393

def compromised?
  bool_property(:rnp_key_is_compromised)
end

#creation_time ⇒ Time

Retrieve the creation time of the key

Returns:

  • (Time) 


421
422
423
424
425
 
# File 'lib/rnp/key.rb', line 421

def creation_time
  ptime = FFI::MemoryPointer.new(:uint32)
  Rnp.call_ffi(:rnp_key_get_creation, @ptr, ptime)
  Time.at(ptime.read(:uint32))
end

#curve ⇒ String

Get the curve of this EC key.

Returns:

  • (String) 


369
370
371
 
# File 'lib/rnp/key.rb', line 369

def curve
  string_property(:rnp_key_get_curve)
end

#each_signature(&block) ⇒ self, Enumerator

Enumerate each Signature for this key.

Returns:

  • (self, Enumerator) 


112
113
114
115
116
 
# File 'lib/rnp/key.rb', line 112

def each_signature(&block)
  block or return enum_for(:signature_iterator)
  signature_iterator(&block)
  self
end

#each_subkey(&block) ⇒ self, Enumerator

Enumerate each subkey for this key.

Returns:

  • (self, Enumerator) 


328
329
330
331
332
 
# File 'lib/rnp/key.rb', line 328

def each_subkey(&block)
  block or return enum_for(:subkey_iterator)
  subkey_iterator(&block)
  self
end

#each_uid(&block) ⇒ self, Enumerator

Enumerate each UserID for this key.

Returns:

  • (self, Enumerator) 


96
97
98
99
100
 
# File 'lib/rnp/key.rb', line 96

def each_uid(&block)
  block or return enum_for(:uid_iterator)
  uid_iterator(&block)
  self
end

#each_userid(&block) ⇒ self, Enumerator

Enumerate each userid for this key.

Returns:

  • (self, Enumerator) 


80
81
82
83
84
 
# File 'lib/rnp/key.rb', line 80

def each_userid(&block)
  block or return enum_for(:userid_iterator)
  userid_iterator(&block)
  self
end

#expiration_time ⇒ Time

Retrieve the expiration time of the key

Returns:

  • (Time) 


430
431
432
433
434
 
# File 'lib/rnp/key.rb', line 430

def expiration_time
  ptime = FFI::MemoryPointer.new(:uint32)
  Rnp.call_ffi(:rnp_key_get_expiration, @ptr, ptime)
  Time.at(ptime.read(:uint32))
end

#export_public(armored: true, with_subkeys: false, output: nil) ⇒ nil, String

Export a public key.

By default, when exporting a primary key, only the primary key will be exported. When exporting a subkey, the primary key and subkey will both be exported.

Parameters:

  • output (Output) (defaults to: nil) —

    the output to write the exported key. If nil, the result will be returned directly as a String.

  • with_subkeys (Boolean) (defaults to: false) —

    when exporting a primary key, this controls whether all subkeys should also be exported. When true, the primary key and all subkeys will be exported. When false, only the primary key will be exported. This parameter is not valid when the key is a subkey.

  • armored (Boolean) (defaults to: true) —

    true if the output should be ASCII-armored, false otherwise.

Returns:

  • (nil, String) 


240
241
242
243
244
 
# File 'lib/rnp/key.rb', line 240

def export_public(armored: true, with_subkeys: false, output: nil)
  Output.default(output) do |output_|
    export(public_key: true, with_subkeys: with_subkeys, armored: armored, output: output_)
  end
end

#export_secret(armored: true, with_subkeys: false, output: nil) ⇒ nil, String

Export a secret key.

By default, when exporting a primary key, only the primary key will be exported. When exporting a subkey, the primary key and subkey will both be exported.

Parameters:

  • output (Output) (defaults to: nil) —

    the output to write the exported key. If nil, the result will be returned directly as a String.

  • with_subkeys (Boolean) (defaults to: false) —

    when exporting a primary key, this controls whether all subkeys should also be exported. When true, the primary key and all subkeys will be exported. When false, only the primary key will be exported. This parameter is not valid when the key is a subkey.

  • armored (Boolean) (defaults to: true) —

    true if the output should be ASCII-armored, false otherwise.

Returns:

  • (nil, String) 


261
262
263
264
265
 
# File 'lib/rnp/key.rb', line 261

def export_secret(armored: true, with_subkeys: false, output: nil)
  Output.default(output) do |output_|
    export(secret_key: true, with_subkeys: with_subkeys, armored: armored, output: output_)
  end
end

#fingerprint ⇒ String

Get the fingerprint of the key

Returns:

  • (String) 


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

def fingerprint
  string_property(:rnp_key_get_fprint)
end

#grip ⇒ String

Get the grip of the key

Returns:

  • (String) 


59
60
61
 
# File 'lib/rnp/key.rb', line 59

def grip
  string_property(:rnp_key_get_grip)
end

#inspect ⇒ Object 



34
35
36
 
# File 'lib/rnp/key.rb', line 34

def inspect
  Rnp.inspect_ptr(self)
end

#json(public_mpis: false, secret_mpis: false, signatures: true, signature_mpis: false) ⇒ Hash

Return a JSON representation of this key (as a Hash).

Parameters:

  • public_mpis (Boolean) (defaults to: false) —

    if true then public MPIs will be included

  • secret_mpis (Boolean) (defaults to: false) —

    if true then secret MPIs will be included

  • signatures (Boolean) (defaults to: true) —

    if true then signatures will be included

  • signature_mpis (Boolean) (defaults to: false) —

    if true then signature MPIs will be included

Returns:

  • (Hash) 


291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/rnp/key.rb', line 291

def json(public_mpis: false, secret_mpis: false, signatures: true,
         signature_mpis: false)
  flags = 0
  flags |= LibRnp::RNP_JSON_PUBLIC_MPIS if public_mpis
  flags |= LibRnp::RNP_JSON_SECRET_MPIS if secret_mpis
  flags |= LibRnp::RNP_JSON_SIGNATURES if signatures
  flags |= LibRnp::RNP_JSON_SIGNATURE_MPIS if signature_mpis
  pptr = FFI::MemoryPointer.new(:pointer)
  Rnp.call_ffi(:rnp_key_to_json, @ptr, flags, pptr)
  begin
    presult = pptr.read_pointer
    JSON.parse(presult.read_string) unless presult.null?
  ensure
    LibRnp.rnp_buffer_destroy(presult)
  end
end

#keyid ⇒ String

Get the keyid of the key

Returns:

  • (String) 


52
53
54
 
# File 'lib/rnp/key.rb', line 52

def keyid
  string_property(:rnp_key_get_keyid)
end

#lock ⇒ self

Lock the key.

Returns:

  • (self) 


150
151
152
153
 
# File 'lib/rnp/key.rb', line 150

def lock
  Rnp.call_ffi(:rnp_key_lock, @ptr)
  self
end

#locked? ⇒ Boolean

Returns true if the key is currently locked.

Returns:

  • (Boolean) 


143
144
145
 
# File 'lib/rnp/key.rb', line 143

def locked?
  bool_property(:rnp_key_is_locked)
end

#primary? ⇒ Boolean

Returns true if the key is a primary key.

Returns:

  • (Boolean) 


200
201
202
 
# File 'lib/rnp/key.rb', line 200

def primary?
  bool_property(:rnp_key_is_primary)
end

#primary_grip ⇒ String

Get the primary grip of the key (for subkeys)

Returns:

  • (String) 


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

def primary_grip
  string_property(:rnp_key_get_primary_grip)
end

#primary_userid ⇒ String

Get the primary userid of the key

Returns:

  • (String) 


73
74
75
 
# File 'lib/rnp/key.rb', line 73

def primary_userid
  string_property(:rnp_key_get_primary_uid)
end

#protect(password, cipher: nil, cipher_mode: nil, s2k_hash: nil, s2k_iterations: 0) ⇒ self

Protect or re-protect the key.

Parameters:

  • password (String) —

    the password with which to encrypt the key.

  • cipher (String) (defaults to: nil) —

    the cipher algorithm to encrypt with

  • cipher_mode (String) (defaults to: nil) —

    the cipher mode

  • s2k_hash (String) (defaults to: nil) —

    the hash algorithm to use for the string-to-key key derivation.

  • s2k_iterations (Integer) (defaults to: 0) —

    the number of iterations for the string-to-key key derivation. A value of 0 will choose a default.

Returns:

  • (self) 


180
181
182
183
184
185
 
# File 'lib/rnp/key.rb', line 180

def protect(password, cipher: nil, cipher_mode: nil, s2k_hash: nil,
            s2k_iterations: 0)
  Rnp.call_ffi(:rnp_key_protect, @ptr, password, cipher, cipher_mode,
               s2k_hash, s2k_iterations)
  self
end

#protected? ⇒ Boolean

Returns true if the key is currently protected.

Returns:

  • (Boolean) 


168
169
170
 
# File 'lib/rnp/key.rb', line 168

def protected?
  bool_property(:rnp_key_is_protected)
end

#public_key_data ⇒ String

Returns the raw public key data as PGP packets.

Returns:

  • (String) 


270
271
272
 
# File 'lib/rnp/key.rb', line 270

def public_key_data
  buf_property(:rnp_get_public_key_data)
end

#public_key_present? ⇒ Boolean

Returns true if the public key packet is available.

Returns:

  • (Boolean) 


214
215
216
 
# File 'lib/rnp/key.rb', line 214

def public_key_present?
  bool_property(:rnp_key_have_public)
end

#qbits ⇒ Integer

Get the bit length for the q parameter of this DSA key.

Returns:

  • (Integer) 


360
361
362
363
364
 
# File 'lib/rnp/key.rb', line 360

def qbits
  pbits = FFI::MemoryPointer.new(:uint32)
  Rnp.call_ffi(:rnp_key_get_dsa_qbits, @ptr, pbits)
  pbits.read(:uint32)
end

#retired? ⇒ Boolean

Check if this revoked key was retired.

Returns:

  • (Boolean) 


400
401
402
 
# File 'lib/rnp/key.rb', line 400

def retired?
  bool_property(:rnp_key_is_retired)
end

#revocation_reason ⇒ String

Retrieve the reason for revoking this key, if any.

Returns:

  • (String) 


414
415
416
 
# File 'lib/rnp/key.rb', line 414

def revocation_reason
  string_property(:rnp_key_get_revocation_reason)
end

#revoked? ⇒ Boolean

Check if this has been revoked.

Returns:

  • (Boolean) 


386
387
388
 
# File 'lib/rnp/key.rb', line 386

def revoked?
  bool_property(:rnp_key_is_revoked)
end

#secret_key_data ⇒ String

Returns the raw secret key data.

The format may be either PGP packets or an s-expr/G10.

Returns:

  • (String) 


279
280
281
 
# File 'lib/rnp/key.rb', line 279

def secret_key_data
  buf_property(:rnp_get_secret_key_data)
end

#secret_key_present? ⇒ Boolean

Returns true if the secret key packet is available.

Returns:

  • (Boolean) 


221
222
223
 
# File 'lib/rnp/key.rb', line 221

def secret_key_present?
  bool_property(:rnp_key_have_secret)
end

#signatures ⇒ Array<Signature>

Get a list of Signatures for this key.

Returns:



121
122
123
 
# File 'lib/rnp/key.rb', line 121

def signatures
  each_signature.to_a
end

#sub? ⇒ Boolean

Returns true if the key is a subkey.

Returns:

  • (Boolean) 


207
208
209
 
# File 'lib/rnp/key.rb', line 207

def sub?
  bool_property(:rnp_key_is_sub)
end

#subkeys ⇒ Array<Key>

Get a list of all subkeys for this key.

Returns:



337
338
339
 
# File 'lib/rnp/key.rb', line 337

def subkeys
  each_subkey.to_a
end

#superseded? ⇒ Boolean

Check if this revoked key was superseded by another key.

Returns:

  • (Boolean) 


407
408
409
 
# File 'lib/rnp/key.rb', line 407

def superseded?
  bool_property(:rnp_key_is_superseded)
end

#to_s ⇒ Object 



38
39
40
 
# File 'lib/rnp/key.rb', line 38

def to_s
  "#<#{self.class}:#{keyid}>"
end

#type ⇒ String

Get the type of this key (RSA, etc).

Returns:

  • (String) 


344
345
346
 
# File 'lib/rnp/key.rb', line 344

def type
  string_property(:rnp_key_get_alg)
end

#uids ⇒ Array<UserID>

Get a list of UserIDs for this key.

Returns:



105
106
107
 
# File 'lib/rnp/key.rb', line 105

def uids
  each_uid.to_a
end

#unload(unload_public: true, unload_secret: true) ⇒ void

Note:

When both the public and secret portions of this key have been

This method returns an undefined value.

Unload this key.

unloaded, you should no longer interact with this object.

Parameters:

  • unload_public (Boolean) (defaults to: true) —

    if true then the public key will be unloaded

  • unload_secret (Boolean) (defaults to: true) —

    if true then the secret key will be unloaded



318
319
320
321
322
323
 
# File 'lib/rnp/key.rb', line 318

def unload(unload_public: true, unload_secret: true)
  flags = 0
  flags |= LibRnp::RNP_KEY_REMOVE_PUBLIC if unload_public
  flags |= LibRnp::RNP_KEY_REMOVE_SECRET if unload_secret
  Rnp.call_ffi(:rnp_key_remove, @ptr, flags)
end

#unlock(password = nil) ⇒ self

Unlock the key.

Parameters:

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

    the password to unlock the key. If nil, the current password provider will be used (see Rnp#password_provider=).

Returns:

  • (self) 


160
161
162
163
 
# File 'lib/rnp/key.rb', line 160

def unlock(password = nil)
  Rnp.call_ffi(:rnp_key_unlock, @ptr, password)
  self
end

#unprotect(password = nil) ⇒ self

Unprotect the key.

Parameters:

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

    the password to unlock the key. If nil, the current password provider will be used (see Rnp#password_provider=).

Returns:

  • (self) 


192
193
194
195
 
# File 'lib/rnp/key.rb', line 192

def unprotect(password = nil)
  Rnp.call_ffi(:rnp_key_unprotect, @ptr, password)
  self
end

#userids ⇒ Array<String>

Get a list of all userids for this key.

Returns:

  • (Array<String>) 


89
90
91
 
# File 'lib/rnp/key.rb', line 89

def userids
  each_userid.to_a
end