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.



884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
 
# File 'lib/gpgme.rb', line 884

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
  ctx
end

Instance Method Details

#add_signer(*keys) ⇒ Object

Add keys to the list of signers.



1166
1167
1168
1169
1170
1171
1172
 
# File 'lib/gpgme.rb', line 1166

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.



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

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

#armor=(yes) ⇒ Object

Tell whether the output should be ASCII armored.



925
926
927
928
 
# File 'lib/gpgme.rb', line 925

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

#clear_signers ⇒ Object

Remove the list of signers from this object.



1161
1162
1163
 
# File 'lib/gpgme.rb', line 1161

def clear_signers
  GPGME::gpgme_signers_clear(self)
end

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

Decrypt the ciphertext and return the plaintext.



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

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 



1136
1137
1138
 
# File 'lib/gpgme.rb', line 1136

def decrypt_result
  GPGME::gpgme_op_decrypt_result(self)
end

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

Decrypt the ciphertext and return the plaintext.



1153
1154
1155
1156
1157
1158
 
# File 'lib/gpgme.rb', line 1153

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.



1114
1115
1116
1117
1118
 
# File 'lib/gpgme.rb', line 1114

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.



1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
 
# File 'lib/gpgme.rb', line 1033

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

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

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



1190
1191
1192
1193
1194
1195
 
# File 'lib/gpgme.rb', line 1190

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 



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

def encrypt_result
  GPGME::gpgme_op_encrypt_result(self)
end

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



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

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.



1091
1092
1093
1094
1095
1096
 
# File 'lib/gpgme.rb', line 1091

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: 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.



1083
1084
1085
1086
1087
 
# File 'lib/gpgme.rb', line 1083

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.



1058
1059
1060
1061
1062
1063
1064
 
# File 'lib/gpgme.rb', line 1058

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.



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

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 



1107
1108
1109
 
# File 'lib/gpgme.rb', line 1107

def import_result
  GPGME::gpgme_op_import_result(self)
end

#inspect ⇒ Object 



957
958
959
960
961
 
# File 'lib/gpgme.rb', line 957

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.



1023
1024
1025
1026
1027
 
# File 'lib/gpgme.rb', line 1023

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.



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

def keylist_mode
  GPGME::gpgme_get_keylist_mode(self)
end

#keylist_mode=(mode) ⇒ Object

Change the default behaviour of the key listing functions.



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

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.



1014
1015
1016
1017
1018
1019
1020
 
# File 'lib/gpgme.rb', line 1014

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.



1007
1008
1009
1010
1011
 
# File 'lib/gpgme.rb', line 1007

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 



1048
1049
1050
1051
1052
1053
1054
 
# File 'lib/gpgme.rb', line 1048

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.



920
921
922
 
# File 'lib/gpgme.rb', line 920

def protocol
  GPGME::gpgme_get_protocol(self)
end

#protocol=(proto) ⇒ Object

Set the protocol used within this context.



912
913
914
915
916
917
 
# File 'lib/gpgme.rb', line 912

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



983
984
985
 
# File 'lib/gpgme.rb', line 983

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



998
999
1000
 
# File 'lib/gpgme.rb', line 998

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.



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

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 



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

def sign_result
  GPGME::gpgme_sign_result(self)
end

#textmode ⇒ Object

Return true if canonical text mode is enabled.



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

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

#textmode=(yes) ⇒ Object

Tell whether canonical text mode should be used.



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

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.



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

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 



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

def verify_result
  GPGME::gpgme_op_verify_result(self)
end