Class: GPGME::Key

Inherits:
Object
  • Object
show all
Includes:
KeyCommon
Defined in:
lib/gpgme/key.rb,
ext/gpgme/gpgme_n.c

Overview

A ruby representation of a public or a secret key.

Every key has two instances of SubKey, accessible through #subkeys, and with a #primary_subkey where most attributes are derived from, like the fingerprint.

Also, every key has at least a UserID, accessible through #uids, with a #primary_uid, where other attributes are derived from, like email or name

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from KeyCommon

#capability, #secret?, #trust, #usable_for?

Instance Attribute Details

#chain_id ⇒ Object (readonly)

Returns the value of attribute chain_id.



17
18
19
 
# File 'lib/gpgme/key.rb', line 17

def chain_id
  @chain_id
end

#issuer_name ⇒ Object (readonly)

Returns the value of attribute issuer_name.



17
18
19
 
# File 'lib/gpgme/key.rb', line 17

def issuer_name
  @issuer_name
end

#issuer_serial ⇒ Object (readonly)

Returns the value of attribute issuer_serial.



17
18
19
 
# File 'lib/gpgme/key.rb', line 17

def issuer_serial
  @issuer_serial
end

#keylist_mode ⇒ Object (readonly)

Returns the value of attribute keylist_mode.



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

def keylist_mode
  @keylist_mode
end

#owner_trust ⇒ Object (readonly)

Returns the value of attribute owner_trust.



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

def owner_trust
  @owner_trust
end

#protocol ⇒ Object (readonly)

Returns the value of attribute protocol.



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

def protocol
  @protocol
end

#subkeys ⇒ Object (readonly)

Returns the value of attribute subkeys.



18
19
20
 
# File 'lib/gpgme/key.rb', line 18

def subkeys
  @subkeys
end

#uids ⇒ Object (readonly)

Returns the value of attribute uids.



18
19
20
 
# File 'lib/gpgme/key.rb', line 18

def uids
  @uids
end

Class Method Details

.export(pattern, options = {}) ⇒ GPGME::Data

Exports public keys

GPGME::Key.export pattern, options

Private keys cannot be exported due to GPGME restrictions.

Examples:

key = GPGME::Key.export "[email protected]"

writing to a file

out = File.open("my.key", "w+")
GPGME::Key.export "[email protected]", :output => out

Parameters:

  • pattern —

    Identifier of the key to export.

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

    • :output specify where to write the key to. It will be converted to a Data, so it could be a file, for example.

    • :minimal set to true to let the export mode be ‘minimal’.

    • Any other option accepted by Ctx.new

Returns:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/gpgme/key.rb', line 96

def export(pattern, options = {})
  output = Data.new(options[:output])
  if options.delete(:minimal) == true
    export_mode = 4
  else
    export_mode = 0
  end

  GPGME::Ctx.new(options) do |ctx|
    ctx.export_keys(pattern, output, export_mode)
  end

  output.seek(0)
  output
end

.find(secret, keys_or_names = nil, purposes = []) ⇒ Object

Returns an array of GPGME::Key objects that match the parameters.

  • secret set to :secret to get only secret keys, or to :public to get only public keys.

  • keys_or_names an array or an item that can be either GPGME::Key elements, or string identifiers like the email or the sha. Leave blank to get all.

  • purposes get only keys that are usable for any of these purposes. See GPGME::Key for a list of possible key capabilities.

Examples:

GPGME::Key.find :secret # => first secret key found
GPGME::Key.find(:public, "[email protected]")
# => return only public keys that match [email protected]
GPGME::Key.find(:public, "[email protected]", :sign)
# => return the public keys that match [email protected] and are
#    capable of signing


45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/gpgme/key.rb', line 45

def find(secret, keys_or_names = nil, purposes = [])
  secret = (secret == :secret)
  keys_or_names = [""] if keys_or_names.nil? || (keys_or_names.is_a?(Array) && keys_or_names.empty?)
  keys_or_names = [keys_or_names].flatten
  purposes      = [purposes].flatten.compact.uniq

  keys = []
  keys_or_names.each do |key_or_name|
    case key_or_name
    when Key then keys << key_or_name
    when String
      GPGME::Ctx.new do |ctx|
        keys += ctx.keys(key_or_name, secret).select do |k|
          k.usable_for?(purposes)
        end
      end
    end
  end
  keys
end

.get(fingerprint) ⇒ Object 



66
67
68
69
70
 
# File 'lib/gpgme/key.rb', line 66

def get(fingerprint)
  Ctx.new do |ctx|
    ctx.get_key(fingerprint)
  end
end

.import(keydata, options = {}) ⇒ Object

Imports a key

GPGME::Key.import keydata, options

Examples:

GPGME::Key.import(File.open("my.key"))

Parameters:

  • keydata —

    The key to import. It will be converted to a Data object, so could be a file, for example.

  • options (defaults to: {}) —

    Any other option accepted by Ctx.new



125
126
127
128
129
130
 
# File 'lib/gpgme/key.rb', line 125

def import(keydata, options = {})
  GPGME::Ctx.new(options) do |ctx|
    ctx.import_keys(Data.new(keydata))
    ctx.import_result
  end
end

.valid?(key) ⇒ Boolean

Checks if a key is valid

Returns:

  • (Boolean) 


133
134
135
 
# File 'lib/gpgme/key.rb', line 133

def valid?(key)
  GPGME::Key.import(key).considered == 1
end

Instance Method Details

#==(another_key) ⇒ Object 



224
225
226
 
# File 'lib/gpgme/key.rb', line 224

def ==(another_key)
  self.class === another_key and fingerprint == another_key.fingerprint
end

#comment ⇒ Object

Returns the issuer comment for this key.



220
221
222
 
# File 'lib/gpgme/key.rb', line 220

def comment
  primary_uid.comment
end

#delete!(allow_secret = false) ⇒ Object

Delete this key. If it’s public, and has a secret one it will fail unless allow_secret is specified as true.



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

def delete!(allow_secret = false)
  GPGME::Ctx.new do |ctx|
    ctx.delete_key self, allow_secret
  end
end

#email ⇒ Object

Returns the email for this key.



208
209
210
 
# File 'lib/gpgme/key.rb', line 208

def email
  primary_uid.email
end

#expired ⇒ Object

Returns true if the key is expired



180
181
182
 
# File 'lib/gpgme/key.rb', line 180

def expired
  subkeys.any?(&:expired)
end

#expires ⇒ Object

Returns the expiry date for this key



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

def expires
  primary_subkey.expires
end

#expires? ⇒ Boolean

Returns true if the key has an expiry date else false

Returns:

  • (Boolean) 


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

def expires?
  primary_subkey.expires?
end

#export(options = {}) ⇒ Object

Exports this key. Accepts the same options as Ctx.new, and options[:output], where you can specify something that can become a Data, where the output will go.

Examples:

key.export(:armor => true)
# => GPGME::Data you can read with ASCII armored format
file = File.open("key.asc", "w+")
key.export(:output => file)
# => the key will be written to the file.


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

def export(options = {})
  Key.export self.sha, options
end

#fingerprint ⇒ Object

Longer descriptive value. Can be used to identify the key.



196
197
198
 
# File 'lib/gpgme/key.rb', line 196

def fingerprint
  primary_subkey.fingerprint
end

#inspect ⇒ Object 



228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/gpgme/key.rb', line 228

def inspect
  sprintf("#<#{self.class} %s %4d%s/%s %s trust=%s, owner_trust=%s, \
capability=%s, subkeys=%s, uids=%s>",
          primary_subkey.secret? ? 'sec' : 'pub',
          primary_subkey.length,
          primary_subkey.pubkey_algo_letter,
          primary_subkey.fingerprint[-8 .. -1],
          primary_subkey.timestamp.strftime('%Y-%m-%d'),
          trust.inspect,
          VALIDITY_NAMES[@owner_trust].inspect,
          capability.inspect,
          subkeys.inspect,
          uids.inspect)
end

#name ⇒ Object

Returns the issuer name for this key.



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

def name
  primary_uid.name
end

#primary_subkey ⇒ Object 



184
185
186
 
# File 'lib/gpgme/key.rb', line 184

def primary_subkey
  @primary_subkey ||= subkeys.first
end

#primary_uid ⇒ Object

Returns the main UserID for this key.



202
203
204
 
# File 'lib/gpgme/key.rb', line 202

def primary_uid
  uids.first
end

#sha ⇒ Object

Short descriptive value. Can be used to identify the key.



190
191
192
 
# File 'lib/gpgme/key.rb', line 190

def sha
  primary_subkey.sha
end

#to_s ⇒ Object 



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/gpgme/key.rb', line 243

def to_s
  primary_subkey = subkeys[0]
  s = sprintf("%s   %4d%s/%s %s\n",
              primary_subkey.secret? ? 'sec' : 'pub',
              primary_subkey.length,
              primary_subkey.pubkey_algo_letter,
              primary_subkey.fingerprint[-8 .. -1],
              primary_subkey.timestamp.strftime('%Y-%m-%d'))
  uids.each do |user_id|
    s << "uid\t\t#{user_id.name} <#{user_id.email}>\n"
  end
  subkeys.each do |subkey|
    s << subkey.to_s
  end
  s
end