Class: GPGME::Ctx

Inherits:
Object
  • Object
show all
Defined in:
lib/gpgme.rb,
lib/gpgme/compat.rb

Overview

A context within which all cryptographic operations are performed.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(options = Hash.new) ⇒ Object

Create a new instance from the given options. options is a Hash whose keys are

  • :protocol Either PROTOCOL_OpenPGP or PROTOCOL_CMS.

  • :armor If true, the output should be ASCII armored.

  • :textmode If true, inform the recipient that the input is text.

  • :keylist_mode Either KEYLIST_MODE_LOCAL, KEYLIST_MODE_EXTERN, KEYLIST_MODE_SIGS, or KEYLIST_MODE_VALIDATE.

  • :passphrase_callback A callback function.

  • :passphrase_callback_value An object passed to passphrase_callback.

  • :progress_callback A callback function.

  • :progress_callback_value An object passed to progress_callback.



894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
 
# File 'lib/gpgme.rb', line 894

def self.new(options = Hash.new)
  rctx = Array.new
  err = GPGME::gpgme_new(rctx)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  ctx = rctx[0]
  options.each_pair do |key, value|
    case key
    when :protocol
      ctx.protocol = value
    when :armor
      ctx.armor = value
    when :textmode
      ctx.textmode = value
    when :keylist_mode
      ctx.keylist_mode = value
    when :passphrase_callback
      ctx.set_passphrase_callback(value,
                                  options[:passphrase_callback_value])
    when :progress_callback
      ctx.set_progress_callback(value,
                                  options[:progress_callback_value])
    end
  end
  if block_given?
    begin
      yield ctx
    ensure
      GPGME::gpgme_release(ctx)
    end
  else
    ctx
  end
end

Instance Method Details

#add_signer(*keys) ⇒ Object

Add keys to the list of signers.



1201
1202
1203
1204
1205
1206
1207
 
# File 'lib/gpgme.rb', line 1201

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 ⇒ Object

Return true if the output is ASCII armored.



949
950
951
 
# File 'lib/gpgme.rb', line 949

def armor
  GPGME::gpgme_get_armor(self) == 1 ? true : false
end

#armor=(yes) ⇒ Object

Tell whether the output should be ASCII armored.



943
944
945
946
 
# File 'lib/gpgme.rb', line 943

def armor=(yes)
  GPGME::gpgme_set_armor(self, yes ? 1 : 0)
  yes
end

#clear_signers ⇒ Object

Remove the list of signers from this object.



1196
1197
1198
 
# File 'lib/gpgme.rb', line 1196

def clear_signers
  GPGME::gpgme_signers_clear(self)
end

#decrypt(cipher, plain = Data.new) ⇒ Object

Decrypt the ciphertext and return the plaintext.



1157
1158
1159
1160
1161
1162
 
# File 'lib/gpgme.rb', line 1157

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 ⇒ Object 



1171
1172
1173
 
# File 'lib/gpgme.rb', line 1171

def decrypt_result
  GPGME::gpgme_op_decrypt_result(self)
end

#decrypt_verify(cipher, plain = Data.new) ⇒ Object

Decrypt the ciphertext and return the plaintext.



1188
1189
1190
1191
1192
1193
 
# File 'lib/gpgme.rb', line 1188

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(key, allow_secret = false) ⇒ Object Also known as: delete

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



1132
1133
1134
1135
1136
 
# File 'lib/gpgme.rb', line 1132

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

#each_key(pattern = nil, secret_only = false, &block) ⇒ Object Also known as: each_keys

Convenient method to iterate over keys. If pattern is nil, all available keys are returned. If secret_only is true, the only secret keys are returned.



1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
 
# File 'lib/gpgme.rb', line 1051

def each_key(pattern = nil, secret_only = false, &block) # :yields: key
  keylist_start(pattern, secret_only)
  begin
	loop do
	  yield keylist_next
	end
    keys
  rescue EOFError
	# The last key in the list has already been returned.
  ensure
	keylist_end
  end
end

#edit_card_key(key, editfunc, hook_value = nil, out = Data.new) ⇒ Object Also known as: edit_card, card_edit

Edit attributes of the key on the card.



1148
1149
1150
1151
1152
 
# File 'lib/gpgme.rb', line 1148

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_key(key, editfunc, hook_value = nil, out = Data.new) ⇒ Object Also known as: edit

Edit attributes of the key in the local key ring.



1140
1141
1142
1143
1144
 
# File 'lib/gpgme.rb', line 1140

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(recp, plain, cipher = Data.new, flags = 0) ⇒ Object

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



1225
1226
1227
1228
1229
1230
 
# File 'lib/gpgme.rb', line 1225

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 ⇒ Object 



1232
1233
1234
 
# File 'lib/gpgme.rb', line 1232

def encrypt_result
  GPGME::gpgme_op_encrypt_result(self)
end

#encrypt_sign(recp, plain, cipher = Data.new, flags = 0) ⇒ Object 



1236
1237
1238
1239
1240
1241
 
# File 'lib/gpgme.rb', line 1236

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_keys(recipients, keydata = Data.new) ⇒ Object Also known as: export

Extract the public keys of the recipients.



1109
1110
1111
1112
1113
1114
 
# File 'lib/gpgme.rb', line 1109

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_key(parms, pubkey = Data.new, seckey = Data.new) ⇒ Object Also known as: genkey

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: [email protected]
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.



1101
1102
1103
1104
1105
 
# File 'lib/gpgme.rb', line 1101

def generate_key(parms, pubkey = Data.new, seckey = Data.new)
  err = GPGME::gpgme_op_genkey(self, parms, pubkey, seckey)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end

#get_key(fingerprint, secret = false) ⇒ Object

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



1076
1077
1078
1079
1080
1081
1082
 
# File 'lib/gpgme.rb', line 1076

def get_key(fingerprint, secret = false)
  rkey = Array.new
  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_keys(keydata) ⇒ Object Also known as: import

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



1118
1119
1120
1121
1122
 
# File 'lib/gpgme.rb', line 1118

def import_keys(keydata)
  err = GPGME::gpgme_op_import(self, keydata)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end

#import_result ⇒ Object 



1125
1126
1127
 
# File 'lib/gpgme.rb', line 1125

def import_result
  GPGME::gpgme_op_import_result(self)
end

#inspect ⇒ Object 



975
976
977
978
979
 
# File 'lib/gpgme.rb', line 975

def inspect
  "#<#{self.class} protocol=#{PROTOCOL_NAMES[protocol] || protocol}, \
armor=#{armor}, textmode=#{textmode}, \
keylist_mode=#{KEYLIST_MODE_NAMES[keylist_mode]}>"
end

#keylist_end ⇒ Object

End a pending key list operation.



1041
1042
1043
1044
1045
 
# File 'lib/gpgme.rb', line 1041

def keylist_end
  err = GPGME::gpgme_op_keylist_end(self)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end

#keylist_mode ⇒ Object

Return the current key listing mode.



971
972
973
 
# File 'lib/gpgme.rb', line 971

def keylist_mode
  GPGME::gpgme_get_keylist_mode(self)
end

#keylist_mode=(mode) ⇒ Object

Change the default behaviour of the key listing functions.



965
966
967
968
 
# File 'lib/gpgme.rb', line 965

def keylist_mode=(mode)
  GPGME::gpgme_set_keylist_mode(self, mode)
  mode
end

#keylist_next ⇒ Object

Advance to the next key in the key listing operation.



1032
1033
1034
1035
1036
1037
1038
 
# File 'lib/gpgme.rb', line 1032

def keylist_next
  rkey = Array.new
  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) ⇒ Object

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



1025
1026
1027
1028
1029
 
# File 'lib/gpgme.rb', line 1025

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) ⇒ Object 



1066
1067
1068
1069
1070
1071
1072
 
# File 'lib/gpgme.rb', line 1066

def keys(pattern = nil, secret_only = nil)
  keys = Array.new
  each_key(pattern, secret_only) do |key|
    keys << key
  end
  keys
end

#protocol ⇒ Object

Return the protocol used within this context.



938
939
940
 
# File 'lib/gpgme.rb', line 938

def protocol
  GPGME::gpgme_get_protocol(self)
end

#protocol=(proto) ⇒ Object

Set the protocol used within this context.



930
931
932
933
934
935
 
# File 'lib/gpgme.rb', line 930

def protocol=(proto)
  err = GPGME::gpgme_set_protocol(self, proto)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
  proto
end

#rewind ⇒ Object

Set the data pointer to the beginning.



24
25
26
 
# File 'lib/gpgme/compat.rb', line 24

def rewind
  seek(0)
end

#set_passphrase_callback(passfunc, hook_value = nil) ⇒ Object Also known as: set_passphrase_cb

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

def passfunc(hook, 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

ctx.set_passphrase_callback(method(:passfunc))



1001
1002
1003
 
# File 'lib/gpgme.rb', line 1001

def set_passphrase_callback(passfunc, hook_value = nil)
  GPGME::gpgme_set_passphrase_cb(self, passfunc, hook_value)
end

#set_progress_callback(progfunc, hook_value = nil) ⇒ Object Also known as: set_progress_cb

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))



1016
1017
1018
 
# File 'lib/gpgme.rb', line 1016

def set_progress_callback(progfunc, hook_value = nil)
  GPGME::gpgme_set_progress_cb(self, progfunc, hook_value)
end

#sign(plain, sig = Data.new, mode = GPGME::SIG_MODE_NORMAL) ⇒ Object

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.



1212
1213
1214
1215
1216
1217
 
# File 'lib/gpgme.rb', line 1212

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 ⇒ Object 



1219
1220
1221
 
# File 'lib/gpgme.rb', line 1219

def sign_result
  GPGME::gpgme_op_sign_result(self)
end

#textmode ⇒ Object

Return true if canonical text mode is enabled.



960
961
962
 
# File 'lib/gpgme.rb', line 960

def textmode
  GPGME::gpgme_get_textmode(self) == 1 ? true : false
end

#textmode=(yes) ⇒ Object

Tell whether canonical text mode should be used.



954
955
956
957
 
# File 'lib/gpgme.rb', line 954

def textmode=(yes)
  GPGME::gpgme_set_textmode(self, yes ? 1 : 0)
  yes
end

#verify(sig, signed_text = nil, plain = Data.new) ⇒ Object

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



1176
1177
1178
1179
1180
1181
 
# File 'lib/gpgme.rb', line 1176

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 ⇒ Object 



1183
1184
1185
 
# File 'lib/gpgme.rb', line 1183

def verify_result
  GPGME::gpgme_op_verify_result(self)
end