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
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
# 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 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
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
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
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 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
# File lib/gpgme/ctx.rb, line 439 def decrypt_result GPGME::gpgme_op_decrypt_result(self) end
# 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 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
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
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
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
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
# File lib/gpgme/ctx.rb, line 492 def encrypt_result GPGME::gpgme_op_encrypt_result(self) end
# 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
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
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
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
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
# File lib/gpgme/ctx.rb, line 389 def import_result GPGME::gpgme_op_import_result(self) end
# 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
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
Return the current key listing mode.
# File lib/gpgme/ctx.rb, line 149 def keylist_mode GPGME::gpgme_get_keylist_mode(self) end
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
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
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
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
Return the current offline mode.
# File lib/gpgme/ctx.rb, line 172 def offline GPGME::gpgme_get_offline(self) end
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
Return the current pinentry mode.
# File lib/gpgme/ctx.rb, line 160 def pinentry_mode GPGME::gpgme_get_pinentry_mode(self) end
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
Return the protocol
used within this context.
# File lib/gpgme/ctx.rb, line 116 def protocol GPGME::gpgme_get_protocol(self) end
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
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
Set the data pointer to the beginning.
# File lib/gpgme/compat.rb, line 26 def rewind seek(0) end
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
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
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
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
# File lib/gpgme/ctx.rb, line 479 def sign_result GPGME::gpgme_op_sign_result(self) end
# 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
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
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 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
# File lib/gpgme/ctx.rb, line 451 def verify_result GPGME::gpgme_op_verify_result(self) end