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+.
* +:pinentry_mode+ One of: +PINENTRY_MODE_DEFAULT+,
  +PINENTRY_MODE_ASK+, +PINENTRY_MODE_CANCEL+,
  +PINENTRY_MODE_ERROR+, or +PINENTRY_MODE_LOOPBACK+.
* +: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 42
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]
  ctx.pinentry_mode = options[:pinentry_mode] if options[:pinentry_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 481
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 424
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 119
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 113
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 419
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 388
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 402
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 395
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 359
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 268
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 375
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 367
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 448
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 455
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 459
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 336
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 321
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 292
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 345
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 352
def import_result
  GPGME::gpgme_op_import_result(self)
end
inspect() click to toggle source
# File lib/gpgme/ctx.rb, line 473
    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 255
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 141
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 135
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 244
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 235
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 282
def keys(pattern = nil, secret_only = nil)
  keys = []
  each_key(pattern, secret_only) do |key|
    keys << key
  end
  keys
end
pinentry_mode() click to toggle source

Return the current pinentry mode.

# File lib/gpgme/ctx.rb, line 152
def pinentry_mode
  GPGME::gpgme_get_pinentry_mode(self)
end
pinentry_mode=(mode) click to toggle source

Change the default behaviour of the pinentry invocation.

# File lib/gpgme/ctx.rb, line 146
def pinentry_mode=(mode)
  GPGME::gpgme_set_pinentry_mode(self, mode)
  mode
end
protocol() click to toggle source

Return the protocol used within this context.

# File lib/gpgme/ctx.rb, line 108
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 100
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 90
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

Note that this function doesn't work with GnuPG 2.0. You can use either GnuPG 1.x, which can be installed in parallel with GnuPG 2.0, or GnuPG 2.1, which has loopback pinentry feature (see {#pinentry_mode}).

# File lib/gpgme/ctx.rb, line 206
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 221
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 435
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 442
def sign_result
  GPGME::gpgme_op_sign_result(self)
end
spawn(file, argv, datain, dataout, dataerr, flags = 0) click to toggle source
# File lib/gpgme/ctx.rb, line 466
def spawn(file, argv, datain, dataout, dataerr, flags = 0)
  err = GPGME::gpgme_op_spawn(self, file, argv, datain, dataout, dataerr,
                              flags)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end
textmode() click to toggle source

Return true if canonical text mode is enabled.

# File lib/gpgme/ctx.rb, line 130
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 124
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 407
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 414
def verify_result
  GPGME::gpgme_op_verify_result(self)
end