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

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


209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/rnp/key.rb', line 209

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) 


188
189
190
 
# File 'lib/rnp/key.rb', line 188

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) 


197
198
199
 
# File 'lib/rnp/key.rb', line 197

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