class GPGME::GpgmeCtx

A context within which all cryptographic operations are performed.

More operations can be done which are not available in the higher level API. Note how to create a new instance of this class in {GPGME::Ctx.new}.

Public Class Methods

new(options = {}) { |ctx| ... } click to toggle source

Create a new instance from the given options. Must be released either executing the operations inside a block, or executing {GPGME::Ctx#release} afterwards.

@param [Hash] options

The optional parameters are as follows:
* +:protocol+ Either +PROTOCOL_OpenPGP+ or +PROTOCOL_CMS+.
* +:armor+ will return ASCII armored outputs if specified true.
* +:textmode+ if +true+, inform the recipient that the input is text.
* +:keylist_mode+ One of: +KEYLIST_MODE_LOCAL+, +KEYLIST_MODE_EXTERN+,
  +KEYLIST_MODE_SIGS+ or +KEYLIST_MODE_VALIDATE+.
* +:password+ password of the passphrased password being used.
* +:passphrase_callback+ A callback function. See {#set_passphrase_callback}.
* +:passphrase_callback_value+ An object passed to passphrase_callback.
* +:progress_callback+  A callback function. See {#set_progress_callback}.
* +:progress_callback_value+ An object passed to progress_callback.

@example

ctx = GPGME::Ctx.new
# operate on ctx
ctx.release

@example

GPGME::Ctx.new do |ctx|
  # operate on ctx
end
# File lib/gpgme/ctx.rb, line 39
def self.new(options = {})
  rctx = []
  err = GPGME::gpgme_new(rctx)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  ctx = rctx[0]

  ctx.protocol     = options[:protocol]     if options[:protocol]
  ctx.armor        = options[:armor]        if options[:armor]
  ctx.textmode     = options[:textmode]     if options[:textmode]
  ctx.keylist_mode = options[:keylist_mode] if options[:keylist_mode]

  if options[:password]
    ctx.set_passphrase_callback GPGME::Ctx.method(:pass_function),
      options[:password]
  else
    if options[:passphrase_callback]
      ctx.set_passphrase_callback options[:passphrase_callback],
        options[:passphrase_callback_value]
    end
  end
  if options[:progress_callback]
    ctx.set_progress_callback options[:progress_callback],
      options[:progress_callback_value]
  end

  if block_given?
    begin
      yield ctx
    ensure
      GPGME::gpgme_release(ctx)
    end
  else
    ctx
  end
end

Private Class Methods

pass_function(pass, uid_hint, passphrase_info, prev_was_bad, fd) click to toggle source
# File lib/gpgme/ctx.rb, line 455
def self.pass_function(pass, uid_hint, passphrase_info, prev_was_bad, fd)
  io = IO.for_fd(fd, 'w')
  io.puts pass
  io.flush
end

Public Instance Methods

add_signer(*keys) click to toggle source

Add keys to the list of signers.

# File lib/gpgme/ctx.rb, line 405
def add_signer(*keys)
  keys.each do |key|
    err = GPGME::gpgme_signers_add(self, key)
    exc = GPGME::error_to_exception(err)
    raise exc if exc
  end
end
armor() click to toggle source

Return true if the output is ASCII armored.

# File lib/gpgme/ctx.rb, line 115
def armor
  GPGME::gpgme_get_armor(self) == 1 ? true : false
end
armor=(yes) click to toggle source

Tell whether the output should be ASCII armored.

# File lib/gpgme/ctx.rb, line 109
def armor=(yes)
  GPGME::gpgme_set_armor(self, yes ? 1 : 0)
  yes
end
card_edit(key, editfunc, hook_value = nil, out = Data.new)
Alias for: edit_card_key
clear_signers() click to toggle source

Remove the list of signers from this object.

# File lib/gpgme/ctx.rb, line 400
def clear_signers
  GPGME::gpgme_signers_clear(self)
end
decrypt(cipher, plain = Data.new) click to toggle source

Decrypt the ciphertext and return the plaintext.

# File lib/gpgme/ctx.rb, line 369
def decrypt(cipher, plain = Data.new)
  err = GPGME::gpgme_op_decrypt(self, cipher, plain)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  plain
end
decrypt_result() click to toggle source
# File lib/gpgme/ctx.rb, line 383
def decrypt_result
  GPGME::gpgme_op_decrypt_result(self)
end
decrypt_verify(cipher, plain = Data.new) click to toggle source
# File lib/gpgme/ctx.rb, line 376
def decrypt_verify(cipher, plain = Data.new)
  err = GPGME::gpgme_op_decrypt_verify(self, cipher, plain)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  plain
end
delete(key, allow_secret = false)
Alias for: delete_key
delete_key(key, allow_secret = false) click to toggle source

Delete the key from the key ring. If allow_secret is false, only public keys are deleted, otherwise secret keys are deleted as well.

# File lib/gpgme/ctx.rb, line 340
def delete_key(key, allow_secret = false)
  err = GPGME::gpgme_op_delete(self, key, allow_secret ? 1 : 0)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
Also aliased as: delete
each_key(pattern = nil, secret_only = false) { |keylist_next| ... } click to toggle source

Convenient method to iterate over keys.

If pattern is nil, all available keys are returned. If secret_only is true, only secret keys are returned.

See {GPGME::Key.find} for an example of how to use, or for an easier way to use.

# File lib/gpgme/ctx.rb, line 249
def each_key(pattern = nil, secret_only = false, &block)
  keylist_start(pattern, secret_only)
  begin
    loop { yield keylist_next }
  rescue EOFError
    # The last key in the list has already been returned.
  ensure
    keylist_end
  end
end
Also aliased as: each_keys
each_keys(pattern = nil, secret_only = false, &block)
Alias for: each_key
edit(key, editfunc, hook_value = nil, out = Data.new)
Alias for: edit_key
edit_card(key, editfunc, hook_value = nil, out = Data.new)
Alias for: edit_card_key
edit_card_key(key, editfunc, hook_value = nil, out = Data.new) click to toggle source

Edit attributes of the key on the card.

# File lib/gpgme/ctx.rb, line 356
def edit_card_key(key, editfunc, hook_value = nil, out = Data.new)
  err = GPGME::gpgme_op_card_edit(self, key, editfunc, hook_value, out)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
Also aliased as: edit_card, card_edit
edit_key(key, editfunc, hook_value = nil, out = Data.new) click to toggle source

Edit attributes of the key in the local key ring.

# File lib/gpgme/ctx.rb, line 348
def edit_key(key, editfunc, hook_value = nil, out = Data.new)
  err = GPGME::gpgme_op_edit(self, key, editfunc, hook_value, out)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
Also aliased as: edit
encrypt(recp, plain, cipher = Data.new, flags = 0) click to toggle source

Encrypt the plaintext in the data object for the recipients and return the ciphertext.

# File lib/gpgme/ctx.rb, line 429
def encrypt(recp, plain, cipher = Data.new, flags = 0)
  err = GPGME::gpgme_op_encrypt(self, recp, flags, plain, cipher)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  cipher
end
encrypt_result() click to toggle source
# File lib/gpgme/ctx.rb, line 436
def encrypt_result
  GPGME::gpgme_op_encrypt_result(self)
end
encrypt_sign(recp, plain, cipher = Data.new, flags = 0) click to toggle source
# File lib/gpgme/ctx.rb, line 440
def encrypt_sign(recp, plain, cipher = Data.new, flags = 0)
  err = GPGME::gpgme_op_encrypt_sign(self, recp, flags, plain, cipher)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  cipher
end
export(recipients, keydata = Data.new)
Alias for: export_keys
export_keys(recipients, keydata = Data.new) click to toggle source

Extract the public keys that match the recipients. Returns a {GPGME::Data} object which is not rewinded (should do +seek(0)+ before reading).

Private keys cannot be exported due to GPGME restrictions.

If passed, the key will be exported to keydata, which must be a {GPGME::Data} object.

# File lib/gpgme/ctx.rb, line 317
def export_keys(recipients, keydata = Data.new)
  err = GPGME::gpgme_op_export(self, recipients, 0, keydata)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  keydata
end
Also aliased as: export
generate_key(parms, pubkey = nil, seckey = nil) click to toggle source

Generate a new key pair. parms is a string which looks like

<GnupgKeyParms format="internal">
Key-Type: DSA
Key-Length: 1024
Subkey-Type: ELG-E
Subkey-Length: 1024
Name-Real: Joe Tester
Name-Comment: with stupid passphrase
Name-Email: joe@foo.bar
Expire-Date: 0
Passphrase: abc
</GnupgKeyParms>

If pubkey and seckey are both set to nil, it stores the generated key pair into your key ring.

# File lib/gpgme/ctx.rb, line 302
def generate_key(parms, pubkey = nil, seckey = nil)
  err = GPGME::gpgme_op_genkey(self, parms, pubkey, seckey)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
Also aliased as: genkey
genkey(parms, pubkey = nil, seckey = nil)
Alias for: generate_key
get_key(fingerprint, secret = false) click to toggle source

Get the key with the fingerprint. If secret is true, secret key is returned.

# File lib/gpgme/ctx.rb, line 273
def get_key(fingerprint, secret = false)
  rkey = []
  err = GPGME::gpgme_get_key(self, fingerprint, rkey, secret ? 1 : 0)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  rkey[0]
end
import(keydata)
Alias for: import_keys
import_keys(keydata) click to toggle source

Add the keys in the data buffer to the key ring.

# File lib/gpgme/ctx.rb, line 326
def import_keys(keydata)
  err = GPGME::gpgme_op_import(self, keydata)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
Also aliased as: import
import_result() click to toggle source
# File lib/gpgme/ctx.rb, line 333
def import_result
  GPGME::gpgme_op_import_result(self)
end
inspect() click to toggle source
# File lib/gpgme/ctx.rb, line 447
    def inspect
      "#<#{self.class} protocol=#{PROTOCOL_NAMES[protocol] || protocol}, \
armor=#{armor}, textmode=#{textmode}, \
keylist_mode=#{KEYLIST_MODE_NAMES[keylist_mode]}>"
    end
keylist_end() click to toggle source

End a pending key list operation.

Used by {GPGME::Ctx#each_key}

# File lib/gpgme/ctx.rb, line 236
def keylist_end
  err = GPGME::gpgme_op_keylist_end(self)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
keylist_mode() click to toggle source

Return the current key listing mode.

# File lib/gpgme/ctx.rb, line 137
def keylist_mode
  GPGME::gpgme_get_keylist_mode(self)
end
keylist_mode=(mode) click to toggle source

Change the default behaviour of the key listing functions.

# File lib/gpgme/ctx.rb, line 131
def keylist_mode=(mode)
  GPGME::gpgme_set_keylist_mode(self, mode)
  mode
end
keylist_next() click to toggle source

Advance to the next key in the key listing operation.

Used by {GPGME::Ctx#each_key}

# File lib/gpgme/ctx.rb, line 225
def keylist_next
  rkey = []
  err = GPGME::gpgme_op_keylist_next(self, rkey)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  rkey[0]
end
keylist_start(pattern = nil, secret_only = false) click to toggle source

Initiate a key listing operation for given pattern. If pattern is nil, all available keys are returned. If secret_only< is true, only secret keys are returned.

Used by {GPGME::Ctx#each_key}

# File lib/gpgme/ctx.rb, line 216
def keylist_start(pattern = nil, secret_only = false)
  err = GPGME::gpgme_op_keylist_start(self, pattern, secret_only ? 1 : 0)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
keys(pattern = nil, secret_only = nil) click to toggle source

Returns the keys that match the pattern, or all if pattern is nil. Returns only secret keys if secret_only is true.

# File lib/gpgme/ctx.rb, line 263
def keys(pattern = nil, secret_only = nil)
  keys = []
  each_key(pattern, secret_only) do |key|
    keys << key
  end
  keys
end
protocol() click to toggle source

Return the protocol used within this context.

# File lib/gpgme/ctx.rb, line 104
def protocol
  GPGME::gpgme_get_protocol(self)
end
protocol=(proto) click to toggle source

Set the protocol used within this context. See {GPGME::Ctx.new} for possible values.

# File lib/gpgme/ctx.rb, line 96
def protocol=(proto)
  err = GPGME::gpgme_set_protocol(self, proto)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  proto
end
release() click to toggle source

Releases the Ctx instance. Must be called if it was initialized without a block.

@example

ctx = GPGME::Ctx.new
# operate on ctx
ctx.release
# File lib/gpgme/ctx.rb, line 86
def release
  GPGME::gpgme_release(self)
end
rewind() click to toggle source

Set the data pointer to the beginning.

# File lib/gpgme/compat.rb, line 26
def rewind
  seek(0)
end
set_passphrase_callback(passfunc, hook_value = nil) click to toggle source

Set the passphrase callback with given hook value. passfunc should respond to call with 5 arguments.

  • obj the parameter :passphrase_callback_value passed when creating the {GPGME::Ctx} object.

  • uid_hint hint as to what key are we asking the password for. Ex:

    +CFB3294A50C2CFD7 Albert Llop <mrsimo@example.com>+

  • passphrase_info

  • prev_was_bad 0 if it's the first time the password is being asked, 1 otherwise.

  • fd file descriptor where the password must be written too.

Expects a Method object which can be obtained by the method method (really..).

ctx.set_passphrase_callback(MyModule.method(:passfunc))

@example this method will simply return maria as password.

def pass_function(obj, uid_hint, passphrase_info, prev_was_bad, fd)
  io = IO.for_fd(fd, 'w')
  io.puts "maria"
  io.flush
end

@example this will interactively ask for the password

def passfunc(obj, uid_hint, passphrase_info, prev_was_bad, fd)
  $stderr.write("Passphrase for #{uid_hint}: ")
  $stderr.flush
  begin
    system('stty -echo')
    io = IO.for_fd(fd, 'w')
    io.puts(gets)
    io.flush
  ensure
    (0 ... $_.length).each do |i| $_[i] = 0 end if $_
    system('stty echo')
  end
  $stderr.puts
end
# File lib/gpgme/ctx.rb, line 187
def set_passphrase_callback(passfunc, hook_value = nil)
  GPGME::gpgme_set_passphrase_cb(self, passfunc, hook_value)
end
Also aliased as: set_passphrase_cb
set_passphrase_cb(passfunc, hook_value = nil)
set_progress_callback(progfunc, hook_value = nil) click to toggle source

Set the progress callback with given hook value. progfunc should respond to call with 5 arguments.

def progfunc(hook, what, type, current, total)
  $stderr.write("#{what}: #{current}/#{total}\r")
  $stderr.flush
end

ctx.set_progress_callback(method(:progfunc))
# File lib/gpgme/ctx.rb, line 202
def set_progress_callback(progfunc, hook_value = nil)
  GPGME::gpgme_set_progress_cb(self, progfunc, hook_value)
end
Also aliased as: set_progress_cb
set_progress_cb(progfunc, hook_value = nil)
sign(plain, sig = Data.new, mode = GPGME::SIG_MODE_NORMAL) click to toggle source

Create a signature for the text. plain is a data object which contains the text. sig is a data object where the generated signature is stored.

# File lib/gpgme/ctx.rb, line 416
def sign(plain, sig = Data.new, mode = GPGME::SIG_MODE_NORMAL)
  err = GPGME::gpgme_op_sign(self, plain, sig, mode)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  sig
end
sign_result() click to toggle source
# File lib/gpgme/ctx.rb, line 423
def sign_result
  GPGME::gpgme_op_sign_result(self)
end
textmode() click to toggle source

Return true if canonical text mode is enabled.

# File lib/gpgme/ctx.rb, line 126
def textmode
  GPGME::gpgme_get_textmode(self) == 1 ? true : false
end
textmode=(yes) click to toggle source

Tell whether canonical text mode should be used.

# File lib/gpgme/ctx.rb, line 120
def textmode=(yes)
  GPGME::gpgme_set_textmode(self, yes ? 1 : 0)
  yes
end
verify(sig, signed_text = nil, plain = Data.new) click to toggle source

Verify that the signature in the data object is a valid signature.

# File lib/gpgme/ctx.rb, line 388
def verify(sig, signed_text = nil, plain = Data.new)
  err = GPGME::gpgme_op_verify(self, sig, signed_text, plain)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  plain
end
verify_result() click to toggle source
# File lib/gpgme/ctx.rb, line 395
def verify_result
  GPGME::gpgme_op_verify_result(self)
end