Class: GPGME::Key

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

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

Defined Under Namespace

Classes: Pointer

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.

    • Any other option accepted by Ctx.new

Returns:



95
96
97
98
99
100
101
102
103
104
 
# File 'lib/gpgme/key.rb', line 95

def export(pattern, options = {})
  output = Data.new(options[:output])

  GPGME::Ctx.new(options) do |ctx|
    ctx.export_keys(pattern, output)
  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



119
120
121
122
123
124
 
# File 'lib/gpgme/key.rb', line 119

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

.new_from_struct(pointer) ⇒ Object 



9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/gpgme/ffi/key.rb', line 9

def self.new_from_struct(pointer)
  instance = allocate

  instance.instance_exec do
    @ptr = Pointer.new pointer

    struct = Library::Key.new @ptr
    @keylist_mode     = struct[:keylist_mode]
    @revoked          = (struct[:flags] >> 0) & 1
    @expired          = (struct[:flags] >> 1) & 1
    @disabled         = (struct[:flags] >> 2) & 1
    @invalid          = (struct[:flags] >> 3) & 1
    @can_encrypt      = (struct[:flags] >> 4) & 1
    @can_sign         = (struct[:flags] >> 5) & 1
    @can_certify      = (struct[:flags] >> 6) & 1
    @secret           = (struct[:flags] >> 7) & 1
    @can_authenticate = (struct[:flags] >> 8) & 1
    @protocol         = struct[:protocol]
    @issuer_serial    = struct[:issuer_serial]
    @issuer_name      = struct[:issuer_name]
    @chain_id         = struct[:chain_id]
    @owner_trust      = struct[:owner_trust]

    @subkeys = []
    pointer = struct[:subkeys]
    until pointer.null?
      subkey = Library::SubKey.new pointer

      @subkeys << SubKey.new_from_struct(subkey)

      pointer = subkey[:next]
    end

    @uids = []
    pointer = struct[:uids]
    until pointer.null?
      uid = Library::UserID.new pointer

      @uids << UserID.new_from_struct(uid)

      pointer = uid[:next]
    end
  end

  instance
end

Instance Method Details

#==(another_key) ⇒ Object 



206
207
208
 
# File 'lib/gpgme/key.rb', line 206

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

#comment ⇒ Object

Returns the issuer comment for this key.



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

def comment
  primary_uid.comment
end

#context_pointer ⇒ Object 



56
57
58
 
# File 'lib/gpgme/ffi/key.rb', line 56

def context_pointer
  @ptr
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.



148
149
150
151
152
 
# File 'lib/gpgme/key.rb', line 148

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.



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

def email
  primary_uid.email
end

#expired ⇒ Object

Returns true if the key is expired



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

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

#expires ⇒ Object

Returns the expiry date for this key



156
157
158
 
# File 'lib/gpgme/key.rb', line 156

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.


141
142
143
 
# File 'lib/gpgme/key.rb', line 141

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

#fingerprint ⇒ Object

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



178
179
180
 
# File 'lib/gpgme/key.rb', line 178

def fingerprint
  primary_subkey.fingerprint
end

#inspect ⇒ Object 



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

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.



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

def name
  primary_uid.name
end

#primary_subkey ⇒ Object 



166
167
168
 
# File 'lib/gpgme/key.rb', line 166

def primary_subkey
  @primary_subkey ||= subkeys.first
end

#primary_uid ⇒ Object

Returns the main UserID for this key.



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

def primary_uid
  uids.first
end

#sha ⇒ Object

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



172
173
174
 
# File 'lib/gpgme/key.rb', line 172

def sha
  primary_subkey.sha
end

#to_s ⇒ Object 



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

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