class GPGME::Ctx

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+.
* +:offline+ if set to true, dirmngr will not contact external services
* +: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.
* +:status_callback+ A callback function. See {#set_status_callback}.
* +:status_callback_value+ An object passed to status_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 45
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]
  ctx.offline       = options[:offline]       if options[:offline]

  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 options[:status_callback]
    ctx.set_status_callback options[:status_callback],
      options[:status_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 518
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 461
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 127
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 121
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 456
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 425
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 439
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 432
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 396
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 305
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 412
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 404
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 485
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 492
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 496
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 373
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 358
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 329
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 382
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 389
def import_result
  GPGME::gpgme_op_import_result(self)
end
inspect() click to toggle source
# File lib/gpgme/ctx.rb, line 510
    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 292
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 149
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 143
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 281
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 272
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 319
def keys(pattern = nil, secret_only = nil)
  keys = []
  each_key(pattern, secret_only) do |key|
    keys << key
  end
  keys
end
offline() click to toggle source

Return the current offline mode.

# File lib/gpgme/ctx.rb, line 172
def offline
  GPGME::gpgme_get_offline(self)
end
offline=(mode) click to toggle source

Change the default behaviour of the dirmngr that might require connections to external services.

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

Return the current pinentry mode.

# File lib/gpgme/ctx.rb, line 160
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 154
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 116
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 108
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 98
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 226
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 241
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)
set_status_callback(statusfunc, hook_value = nil) click to toggle source

Set the status callback with given hook value. statusfunc should respond to call with 3 arguments.

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

  • keyword the name of the status message

  • args any arguments for the status message

def status_function(obj, keyword, args)
  $stderr.puts("#{keyword} #{args}")
  return 0
end
# File lib/gpgme/ctx.rb, line 258
def set_status_callback(statusfunc, hook_value = nil)
  GPGME::gpgme_set_status_cb(self, statusfunc, hook_value)
end
Also aliased as: set_status_cb
set_status_cb(statusfunc, hook_value = nil)
Alias for: set_status_callback
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 472
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 479
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 503
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 138
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 132
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 444
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 451
def verify_result
  GPGME::gpgme_op_verify_result(self)
end