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 Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(ptr, free = true) ⇒ Key

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Key.

Raises:



19
20
21
22
23
24
25
26
 
# File 'lib/rnp/key.rb', line 19

def initialize(ptr, free = true)
  raise Rnp::Error, 'NULL pointer' if ptr.null?
  if free
    @ptr = FFI::AutoPointer.new(ptr, self.class.method(:destroy))
  else
    @ptr = ptr
  end
end

Instance Attribute Details

#ptr ⇒ Object (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



16
17
18
 
# File 'lib/rnp/key.rb', line 16

def ptr
  @ptr
end

Class Method Details

.destroy(ptr) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



29
30
31
 
# File 'lib/rnp/key.rb', line 29

def self.destroy(ptr)
  LibRnp.rnp_key_handle_destroy(ptr)
end

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.



94
95
96
97
98
 
# File 'lib/rnp/key.rb', line 94

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

#each_userid(&block) ⇒ self, Enumerator

Enumerate each userid for this key.

Returns:

  • (self, Enumerator) 


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

def each_userid(&block)
  block or return enum_for(:userid_iterator)
  userid_iterator(&block)
  self
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) 


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

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) 


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

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) 


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

def fingerprint
  string_property(:rnp_key_get_fprint)
end

#grip ⇒ String

Get the grip of the key

Returns:

  • (String) 


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

def grip
  string_property(:rnp_key_get_grip)
end

#inspect ⇒ Object 



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

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) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/rnp/key.rb', line 251

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) 


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

def keyid
  string_property(:rnp_key_get_keyid)
end

#lock ⇒ self

Lock the key.

Returns:

  • (self) 


110
111
112
113
 
# File 'lib/rnp/key.rb', line 110

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

#locked? ⇒ Boolean

Returns true if the key is currently locked.

Returns:

  • (Boolean) 


103
104
105
 
# File 'lib/rnp/key.rb', line 103

def locked?
  bool_property(:rnp_key_is_locked)
end

#primary? ⇒ Boolean

Returns true if the key is a primary key.

Returns:

  • (Boolean) 


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

def primary?
  bool_property(:rnp_key_is_primary)
end

#primary_userid ⇒ String

Get the primary userid of the key

Returns:

  • (String) 


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

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) 


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

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) 


128
129
130
 
# File 'lib/rnp/key.rb', line 128

def protected?
  bool_property(:rnp_key_is_protected)
end

#public_key_data ⇒ String

Returns the raw public key data as PGP packets.

Returns:

  • (String) 


230
231
232
 
# File 'lib/rnp/key.rb', line 230

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) 


174
175
176
 
# File 'lib/rnp/key.rb', line 174

def public_key_present?
  bool_property(:rnp_key_have_public)
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) 


239
240
241
 
# File 'lib/rnp/key.rb', line 239

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) 


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

def secret_key_present?
  bool_property(:rnp_key_have_secret)
end

#sub? ⇒ Boolean

Returns true if the key is a subkey.

Returns:

  • (Boolean) 


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

def sub?
  bool_property(:rnp_key_is_sub)
end

#to_s ⇒ Object 



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

def to_s
  "#<#{self.class}:#{keyid}>"
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) 


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

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) 


152
153
154
155
 
# File 'lib/rnp/key.rb', line 152

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>) 


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

def userids
  each_userid.to_a
end