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}.
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
# 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
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
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
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
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 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
# File lib/gpgme/ctx.rb, line 402 def decrypt_result GPGME::gpgme_op_decrypt_result(self) end
# 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 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
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
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
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
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
# File lib/gpgme/ctx.rb, line 455 def encrypt_result GPGME::gpgme_op_encrypt_result(self) end
# 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
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
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
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
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
# File lib/gpgme/ctx.rb, line 352 def import_result GPGME::gpgme_op_import_result(self) end
# 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
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
Return the current key listing mode.
# File lib/gpgme/ctx.rb, line 141 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 135 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 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
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
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
Return the current pinentry mode.
# File lib/gpgme/ctx.rb, line 152 def pinentry_mode GPGME::gpgme_get_pinentry_mode(self) end
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
Return the protocol
used within this context.
# File lib/gpgme/ctx.rb, line 108 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 100 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 90 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 206 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 221 def set_progress_callback(progfunc, hook_value = nil) GPGME::gpgme_set_progress_cb(self, progfunc, 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 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
# File lib/gpgme/ctx.rb, line 442 def sign_result GPGME::gpgme_op_sign_result(self) end
# 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
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
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 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
# File lib/gpgme/ctx.rb, line 414 def verify_result GPGME::gpgme_op_verify_result(self) end