Module: GPGME

Defined in:
lib/gpgme.rb,
lib/gpgme.rb,
lib/gpgme.rb,
lib/gpgme/compat.rb,
lib/gpgme/constants.rb

Overview

What’s this?

Ruby-GPGME is a Ruby language binding of GPGME (GnuPG Made Easy).

Requirements

Installation

$ ruby extconf.rb
$ make
$ make install

Examples

examples/genkey.rb:: Generate a key pair in your keyring. examples/keylist.rb:: List your keyring like gpg –list-keys.

examples/roundtrip.rb

Encrypt and decrypt a plain text.

examples/sign.rb:: Create a clear text signature. examples/verify.rb:: Verify a clear text signature given from stdin.

API

Ruby-GPGME provides 3 levels of API. The highest level API is close to the command line interface of GnuPG. The lowest level API is close to the C interface of GPGME.

The highest level API

It can be written in the highest level API to create a cleartext signature of the plaintext from stdin as follows.

$ ruby -rgpgme -e 'GPGME.clearsign($stdin, $stdout)'

The lowest level API

On the other hand, the same example can be rewritten in the lowest level API as follows.

$ ruby -rgpgme -e <<End  
ret = Array.new
GPGME::gpgme_new(ret)
ctx = ret.shift
GPGME::gpgme_data_new_from_fd(ret, 0)
plain = ret.shift
GPGME::gpgme_data_new_from_fd(ret, 1)
sig = ret.shift
GPGME::gpgme_op_sign(ctx, plain, sig, GPGME::SIG_MODE_CLEAR)
End

As you see, it’s much harder to write a program in this API than the highest level API. However, if you are already familier with the C interface of GPGME and/or want to control detailed behavior of GPGME, it might be useful.

The mid level API

There is another API which looks object-oriented. It’s easier to use than the lowest level API though, you should first consult the highest level API.

$ ruby -rgpgme -e <<End  
ctx = GPGME::Ctx.new
plain = GPGME::Data.from_io($stdin)
sig = GPGME::Data.from_io($stdout)
ctx.sign(plain, sig, GPGME::SIG_MODE_CLEAR)
End

License

Copyright © 2003,2006,2007,2008,2009 Daiki Ueno

This file is a part of Ruby-GPGME.

Ruby-GPGME is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

Ruby-GPGME is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Defined Under Namespace

Classes: Ctx, Data, DecryptResult, EncryptResult, EngineInfo, Error, IOCallbacks, ImportResult, ImportStatus, InvalidKey, Key, KeySig, NewSignature, SignResult, Signature, SubKey, UserID, VerifyResult

Constant Summary collapse

GpgmeError = 
Error
GpgmeData = 
Data
GpgmeEngineInfo = 
EngineInfo
GpgmeCtx = 
Ctx
GpgmeKey = 
Key
GpgmeSubKey = 
SubKey
GpgmeUserID = 
UserID
GpgmeKeySig = 
KeySig
GpgmeVerifyResult = 
VerifyResult
GpgmeSignature = 
Signature
GpgmeDecryptResult = 
DecryptResult
GpgmeSignResult = 
SignResult
GpgmeEncryptResult = 
EncryptResult
GpgmeInvalidKey = 
InvalidKey
GpgmeNewSignature = 
NewSignature
GpgmeImportStatus = 
ImportStatus
GpgmeImportResult = 
ImportResult
ATTR_ALGO = 
GPGME_ATTR_ALGO
ATTR_CAN_CERTIFY = 
GPGME_ATTR_CAN_CERTIFY
ATTR_CAN_ENCRYPT = 
GPGME_ATTR_CAN_ENCRYPT
ATTR_CAN_SIGN = 
GPGME_ATTR_CAN_SIGN
ATTR_CHAINID = 
GPGME_ATTR_CHAINID
ATTR_COMMENT = 
GPGME_ATTR_COMMENT
ATTR_CREATED = 
GPGME_ATTR_CREATED
ATTR_EMAIL = 
GPGME_ATTR_EMAIL
ATTR_ERRTOK = 
GPGME_ATTR_ERRTOK
ATTR_EXPIRE = 
GPGME_ATTR_EXPIRE
ATTR_FPR = 
GPGME_ATTR_FPR
ATTR_ISSUER = 
GPGME_ATTR_ISSUER
ATTR_IS_SECRET = 
GPGME_ATTR_IS_SECRET
ATTR_KEYID = 
GPGME_ATTR_KEYID
ATTR_KEY_CAPS = 
GPGME_ATTR_KEY_CAPS
ATTR_KEY_DISABLED = 
GPGME_ATTR_KEY_DISABLED
ATTR_KEY_EXPIRED = 
GPGME_ATTR_KEY_EXPIRED
ATTR_KEY_INVALID = 
GPGME_ATTR_KEY_INVALID
ATTR_KEY_REVOKED = 
GPGME_ATTR_KEY_REVOKED
ATTR_LEN = 
GPGME_ATTR_LEN
ATTR_LEVEL = 
GPGME_ATTR_LEVEL
ATTR_NAME = 
GPGME_ATTR_NAME
ATTR_OTRUST = 
GPGME_ATTR_OTRUST
ATTR_SERIAL = 
GPGME_ATTR_SERIAL
ATTR_SIG_STATUS = 
GPGME_ATTR_SIG_STATUS
ATTR_SIG_SUMMARY = 
GPGME_ATTR_SIG_SUMMARY
ATTR_TYPE = 
GPGME_ATTR_TYPE
ATTR_UID_INVALID = 
GPGME_ATTR_UID_INVALID
ATTR_UID_REVOKED = 
GPGME_ATTR_UID_REVOKED
ATTR_USERID = 
GPGME_ATTR_USERID
ATTR_VALIDITY = 
GPGME_ATTR_VALIDITY
DATA_ENCODING_ARMOR = 
GPGME_DATA_ENCODING_ARMOR
DATA_ENCODING_BASE64 = 
GPGME_DATA_ENCODING_BASE64
DATA_ENCODING_BINARY = 
GPGME_DATA_ENCODING_BINARY
DATA_ENCODING_NONE = 
GPGME_DATA_ENCODING_NONE
ENCRYPT_ALWAYS_TRUST = 
GPGME_ENCRYPT_ALWAYS_TRUST
IMPORT_NEW = 
GPGME_IMPORT_NEW
IMPORT_SECRET = 
GPGME_IMPORT_SECRET
IMPORT_SIG = 
GPGME_IMPORT_SIG
IMPORT_SUBKEY = 
GPGME_IMPORT_SUBKEY
IMPORT_UID = 
GPGME_IMPORT_UID
KEYLIST_MODE_EXTERN = 
GPGME_KEYLIST_MODE_EXTERN
KEYLIST_MODE_LOCAL = 
GPGME_KEYLIST_MODE_LOCAL
KEYLIST_MODE_SIGS = 
GPGME_KEYLIST_MODE_SIGS
KEYLIST_MODE_VALIDATE = 
GPGME_KEYLIST_MODE_VALIDATE
MD_CRC24_RFC2440 = 
GPGME_MD_CRC24_RFC2440
MD_CRC32 = 
GPGME_MD_CRC32
MD_CRC32_RFC1510 = 
GPGME_MD_CRC32_RFC1510
MD_HAVAL = 
GPGME_MD_HAVAL
MD_MD2 = 
GPGME_MD_MD2
MD_MD4 = 
GPGME_MD_MD4
MD_MD5 = 
GPGME_MD_MD5
MD_RMD160 = 
GPGME_MD_RMD160
MD_SHA1 = 
GPGME_MD_SHA1
MD_SHA256 = 
GPGME_MD_SHA256
MD_SHA384 = 
GPGME_MD_SHA384
MD_SHA512 = 
GPGME_MD_SHA512
MD_TIGER = 
GPGME_MD_TIGER
PK_DSA = 
GPGME_PK_DSA
PK_ELG = 
GPGME_PK_ELG
PK_ELG_E = 
GPGME_PK_ELG_E
PK_RSA = 
GPGME_PK_RSA
PROTOCOL_CMS = 
GPGME_PROTOCOL_CMS
PROTOCOL_OpenPGP = 
GPGME_PROTOCOL_OpenPGP
SIGSUM_BAD_POLICY = 
GPGME_SIGSUM_BAD_POLICY
SIGSUM_CRL_MISSING = 
GPGME_SIGSUM_CRL_MISSING
SIGSUM_CRL_TOO_OLD = 
GPGME_SIGSUM_CRL_TOO_OLD
SIGSUM_GREEN = 
GPGME_SIGSUM_GREEN
SIGSUM_KEY_EXPIRED = 
GPGME_SIGSUM_KEY_EXPIRED
SIGSUM_KEY_MISSING = 
GPGME_SIGSUM_KEY_MISSING
SIGSUM_KEY_REVOKED = 
GPGME_SIGSUM_KEY_REVOKED
SIGSUM_RED = 
GPGME_SIGSUM_RED
SIGSUM_SIG_EXPIRED = 
GPGME_SIGSUM_SIG_EXPIRED
SIGSUM_SYS_ERROR = 
GPGME_SIGSUM_SYS_ERROR
SIGSUM_VALID = 
GPGME_SIGSUM_VALID
SIG_MODE_CLEAR = 
GPGME_SIG_MODE_CLEAR
SIG_MODE_DETACH = 
GPGME_SIG_MODE_DETACH
SIG_MODE_NORMAL = 
GPGME_SIG_MODE_NORMAL
SIG_STAT_BAD = 
GPGME_SIG_STAT_BAD
SIG_STAT_DIFF = 
GPGME_SIG_STAT_DIFF
SIG_STAT_ERROR = 
GPGME_SIG_STAT_ERROR
SIG_STAT_GOOD = 
GPGME_SIG_STAT_GOOD
SIG_STAT_GOOD_EXP = 
GPGME_SIG_STAT_GOOD_EXP
SIG_STAT_GOOD_EXPKEY = 
GPGME_SIG_STAT_GOOD_EXPKEY
SIG_STAT_NOKEY = 
GPGME_SIG_STAT_NOKEY
SIG_STAT_NONE = 
GPGME_SIG_STAT_NONE
SIG_STAT_NOSIG = 
GPGME_SIG_STAT_NOSIG
STATUS_ABORT = 
GPGME_STATUS_ABORT
STATUS_ALREADY_SIGNED = 
GPGME_STATUS_ALREADY_SIGNED
STATUS_BADARMOR = 
GPGME_STATUS_BADARMOR
STATUS_BADMDC = 
GPGME_STATUS_BADMDC
STATUS_BADSIG = 
GPGME_STATUS_BADSIG
STATUS_BAD_PASSPHRASE = 
GPGME_STATUS_BAD_PASSPHRASE
STATUS_BEGIN_DECRYPTION = 
GPGME_STATUS_BEGIN_DECRYPTION
STATUS_BEGIN_ENCRYPTION = 
GPGME_STATUS_BEGIN_ENCRYPTION
STATUS_BEGIN_STREAM = 
GPGME_STATUS_BEGIN_STREAM
STATUS_DECRYPTION_FAILED = 
GPGME_STATUS_DECRYPTION_FAILED
STATUS_DECRYPTION_OKAY = 
GPGME_STATUS_DECRYPTION_OKAY
STATUS_DELETE_PROBLEM = 
GPGME_STATUS_DELETE_PROBLEM
STATUS_ENC_TO = 
GPGME_STATUS_ENC_TO
STATUS_END_DECRYPTION = 
GPGME_STATUS_END_DECRYPTION
STATUS_END_ENCRYPTION = 
GPGME_STATUS_END_ENCRYPTION
STATUS_END_STREAM = 
GPGME_STATUS_END_STREAM
STATUS_ENTER = 
GPGME_STATUS_ENTER
STATUS_EOF = 
GPGME_STATUS_EOF
STATUS_ERRMDC = 
GPGME_STATUS_ERRMDC
STATUS_ERROR = 
GPGME_STATUS_ERROR
STATUS_ERRSIG = 
GPGME_STATUS_ERRSIG
STATUS_EXPKEYSIG = 
GPGME_STATUS_EXPKEYSIG
STATUS_EXPSIG = 
GPGME_STATUS_EXPSIG
STATUS_FILE_DONE = 
GPGME_STATUS_FILE_DONE
STATUS_FILE_ERROR = 
GPGME_STATUS_FILE_ERROR
STATUS_FILE_START = 
GPGME_STATUS_FILE_START
STATUS_GET_BOOL = 
GPGME_STATUS_GET_BOOL
STATUS_GET_HIDDEN = 
GPGME_STATUS_GET_HIDDEN
STATUS_GET_LINE = 
GPGME_STATUS_GET_LINE
STATUS_GOODMDC = 
GPGME_STATUS_GOODMDC
STATUS_GOODSIG = 
GPGME_STATUS_GOODSIG
STATUS_GOOD_PASSPHRASE = 
GPGME_STATUS_GOOD_PASSPHRASE
STATUS_GOT_IT = 
GPGME_STATUS_GOT_IT
STATUS_IMPORTED = 
GPGME_STATUS_IMPORTED
STATUS_IMPORT_RES = 
GPGME_STATUS_IMPORT_RES
STATUS_INV_RECP = 
GPGME_STATUS_INV_RECP
STATUS_KEYEXPIRED = 
GPGME_STATUS_KEYEXPIRED
STATUS_KEYREVOKED = 
GPGME_STATUS_KEYREVOKED
STATUS_KEY_CREATED = 
GPGME_STATUS_KEY_CREATED
STATUS_LEAVE = 
GPGME_STATUS_LEAVE
STATUS_MISSING_PASSPHRASE = 
GPGME_STATUS_MISSING_PASSPHRASE
STATUS_NEED_PASSPHRASE = 
GPGME_STATUS_NEED_PASSPHRASE
STATUS_NEED_PASSPHRASE_SYM = 
GPGME_STATUS_NEED_PASSPHRASE_SYM
STATUS_NODATA = 
GPGME_STATUS_NODATA
STATUS_NOTATION_DATA = 
GPGME_STATUS_NOTATION_DATA
STATUS_NOTATION_NAME = 
GPGME_STATUS_NOTATION_NAME
STATUS_NO_PUBKEY = 
GPGME_STATUS_NO_PUBKEY
STATUS_NO_RECP = 
GPGME_STATUS_NO_RECP
STATUS_NO_SECKEY = 
GPGME_STATUS_NO_SECKEY
STATUS_POLICY_URL = 
GPGME_STATUS_POLICY_URL
STATUS_PROGRESS = 
GPGME_STATUS_PROGRESS
STATUS_RSA_OR_IDEA = 
GPGME_STATUS_RSA_OR_IDEA
STATUS_SESSION_KEY = 
GPGME_STATUS_SESSION_KEY
STATUS_SHM_GET = 
GPGME_STATUS_SHM_GET
STATUS_SHM_GET_BOOL = 
GPGME_STATUS_SHM_GET_BOOL
STATUS_SHM_GET_HIDDEN = 
GPGME_STATUS_SHM_GET_HIDDEN
STATUS_SHM_INFO = 
GPGME_STATUS_SHM_INFO
STATUS_SIGEXPIRED = 
GPGME_STATUS_SIGEXPIRED
STATUS_SIG_CREATED = 
GPGME_STATUS_SIG_CREATED
STATUS_SIG_ID = 
GPGME_STATUS_SIG_ID
STATUS_TRUNCATED = 
GPGME_STATUS_TRUNCATED
STATUS_TRUST_FULLY = 
GPGME_STATUS_TRUST_FULLY
STATUS_TRUST_MARGINAL = 
GPGME_STATUS_TRUST_MARGINAL
STATUS_TRUST_NEVER = 
GPGME_STATUS_TRUST_NEVER
STATUS_TRUST_ULTIMATE = 
GPGME_STATUS_TRUST_ULTIMATE
STATUS_TRUST_UNDEFINED = 
GPGME_STATUS_TRUST_UNDEFINED
STATUS_UNEXPECTED = 
GPGME_STATUS_UNEXPECTED
STATUS_USERID_HINT = 
GPGME_STATUS_USERID_HINT
STATUS_VALIDSIG = 
GPGME_STATUS_VALIDSIG
VALIDITY_FULL = 
GPGME_VALIDITY_FULL
VALIDITY_MARGINAL = 
GPGME_VALIDITY_MARGINAL
VALIDITY_NEVER = 
GPGME_VALIDITY_NEVER
VALIDITY_ULTIMATE = 
GPGME_VALIDITY_ULTIMATE
VALIDITY_UNDEFINED = 
GPGME_VALIDITY_UNDEFINED
VALIDITY_UNKNOWN = 
GPGME_VALIDITY_UNKNOWN

Class Method Summary collapse

Class Method Details

.clearsign(plain, *args_options) ⇒ Object

call-seq:

GPGME.clearsign(plain, sig=nil, options=Hash.new)

GPGME.clearsign creates a cleartext signature of the plaintext.

The arguments should be specified as follows.

  • GPGME.clearsign(plain, sig, options)

  • GPGME.clearsign(plain, options) -> sig

All arguments except plain are optional. plain is input and sig is output. If the last argument is a Hash, options will be read from it.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

options are same as GPGME::Ctx.new() except for

  • :signers Signing keys. If specified, it is an array whose elements are a GPGME::Key object or a string.

Raises:

  • (ArgumentError) 


283
284
285
286
287
288
 
# File 'lib/gpgme.rb', line 283

def GPGME.clearsign(plain, *args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 2
  args, options = split_args(args_options)
  args.push(options.merge({:mode => GPGME::SIG_MODE_CLEAR}))
  GPGME.sign(plain, *args)
end

.decrypt(cipher, *args_options) ⇒ Object

call-seq:

GPGME.decrypt(cipher, plain=nil, options=Hash.new){|signature| ...}

GPGME.decrypt performs decryption.

The arguments should be specified as follows.

  • GPGME.decrypt(cipher, plain, options)

  • GPGME.decrypt(cipher, options) -> plain

All arguments except cipher are optional. cipher is input, and plain is output. If the last argument is a Hash, options will be read from it.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

options are same as GPGME::Ctx.new().

Raises:

  • (ArgumentError) 


121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/gpgme.rb', line 121

def GPGME.decrypt(cipher, *args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 2
  args, options = split_args(args_options)
  plain = args[0]

  GPGME::Ctx.new(options) do |ctx|
    cipher_data = input_data(cipher)
    plain_data = output_data(plain)
    begin
      ctx.decrypt_verify(cipher_data, plain_data)
    rescue GPGME::Error::UnsupportedAlgorithm => exc
      exc.algorithm = ctx.decrypt_result.unsupported_algorithm
      raise exc
    rescue GPGME::Error::WrongKeyUsage => exc
      exc.key_usage = ctx.decrypt_result.wrong_key_usage
      raise exc
    end

    verify_result = ctx.verify_result
    if verify_result && block_given?
      verify_result.signatures.each do |signature|
        yield signature
      end
    end

    unless plain
      plain_data.seek(0, IO::SEEK_SET)
      plain_data.read
    end
  end
end

.detach_sign(plain, *args_options) ⇒ Object

call-seq:

GPGME.detach_sign(plain, sig=nil, options=Hash.new)

GPGME.detach_sign creates a detached signature of the plaintext.

The arguments should be specified as follows.

  • GPGME.detach_sign(plain, sig, options)

  • GPGME.detach_sign(plain, options) -> sig

All arguments except plain are optional. plain is input and sig is output. If the last argument is a Hash, options will be read from it.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

options are same as GPGME::Ctx.new() except for

  • :signers Signing keys. If specified, it is an array whose elements are a GPGME::Key object or a string.

Raises:

  • (ArgumentError) 


315
316
317
318
319
320
 
# File 'lib/gpgme.rb', line 315

def GPGME.detach_sign(plain, *args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 2
  args, options = split_args(args_options)
  args.push(options.merge({:mode => GPGME::SIG_MODE_DETACH}))
  GPGME.sign(plain, *args)
end

.encrypt(recipients, plain, *args_options) ⇒ Object

call-seq:

GPGME.encrypt(recipients, plain, cipher=nil, options=Hash.new)

GPGME.encrypt performs encryption.

The arguments should be specified as follows.

  • GPGME.encrypt(recipients, plain, cipher, options)

  • GPGME.encrypt(recipients, plain, options) -> cipher

All arguments except recipients and plain are optional. plain is input and cipher is output. If the last argument is a Hash, options will be read from it.

The recipients are specified by an array whose elements are a string or a GPGME::Key object. If recipients is nil, it performs symmetric encryption.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

options are same as GPGME::Ctx.new() except for

  • :sign If true, it performs a combined sign and encrypt operation.

  • :signers Signing keys. If specified, it is an array whose elements are a GPGME::Key object or a string.

  • :always_trust Setting this to true specifies all the recipients should be trusted.

Raises:

  • (ArgumentError) 


355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
 
# File 'lib/gpgme.rb', line 355

def GPGME.encrypt(recipients, plain, *args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 3
  args, options = split_args(args_options)
  cipher = args[0]
  recipient_keys = recipients ? resolve_keys(recipients, false, [:encrypt]) : nil

  GPGME::Ctx.new(options) do |ctx|
    plain_data = input_data(plain)
    cipher_data = output_data(cipher)
    begin
      flags = 0
      if options[:always_trust]
        flags |= GPGME::ENCRYPT_ALWAYS_TRUST
      end
      if options[:sign]
        if options[:signers]
          ctx.add_signer(*resolve_keys(options[:signers], true, [:sign]))
        end
        ctx.encrypt_sign(recipient_keys, plain_data, cipher_data, flags)
      else
        ctx.encrypt(recipient_keys, plain_data, cipher_data, flags)
      end
    rescue GPGME::Error::UnusablePublicKey => exc
      exc.keys = ctx.encrypt_result.invalid_recipients
      raise exc
    rescue GPGME::Error::UnusableSecretKey => exc
      exc.keys = ctx.sign_result.invalid_signers
      raise exc
    end

    unless cipher
      cipher_data.seek(0, IO::SEEK_SET)
      cipher_data.read
    end
  end
end

.engine_check_version(proto) ⇒ Object

Verify that the engine implementing the protocol proto is installed in the system.



730
731
732
733
734
 
# File 'lib/gpgme.rb', line 730

def engine_check_version(proto)
  err = GPGME::gpgme_engine_check_version(proto)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end

.engine_info ⇒ Object

Return a list of info structures of enabled engines.



738
739
740
741
742
 
# File 'lib/gpgme.rb', line 738

def engine_info
  rinfo = Array.new
  GPGME::gpgme_get_engine_info(rinfo)
  rinfo
end

.error_to_exception(err) ⇒ Object

:nodoc:



661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
 
# File 'lib/gpgme.rb', line 661

def error_to_exception(err)   # :nodoc:
  case GPGME::gpgme_err_code(err)
  when GPG_ERR_EOF
    EOFError.new
  when GPG_ERR_NO_ERROR
    nil
  when GPG_ERR_GENERAL
    Error::General.new(err)
  when GPG_ERR_ENOMEM
    Errno::ENOMEM.new
  when GPG_ERR_INV_VALUE
    Error::InvalidValue.new(err)
  when GPG_ERR_UNUSABLE_PUBKEY
    Error::UnusablePublicKey.new(err)
  when GPG_ERR_UNUSABLE_SECKEY
    Error::UnusableSecretKey.new(err)
  when GPG_ERR_NO_DATA
    Error::NoData.new(err)
  when GPG_ERR_CONFLICT
    Error::Conflict.new(err)
  when GPG_ERR_NOT_IMPLEMENTED
    Error::NotImplemented.new(err)
  when GPG_ERR_DECRYPT_FAILED
    Error::DecryptFailed.new(err)
  when GPG_ERR_BAD_PASSPHRASE
    Error::BadPassphrase.new(err)
  when GPG_ERR_CANCELED
    Error::Canceled.new(err)
  when GPG_ERR_INV_ENGINE
    Error::InvalidEngine.new(err)
  when GPG_ERR_AMBIGUOUS_NAME
    Error::AmbiguousName.new(err)
  when GPG_ERR_WRONG_KEY_USAGE
    Error::WrongKeyUsage.new(err)
  when GPG_ERR_CERT_REVOKED
    Error::CertificateRevoked.new(err)
  when GPG_ERR_CERT_EXPIRED
    Error::CertificateExpired.new(err)
  when GPG_ERR_NO_CRL_KNOWN
    Error::NoCRLKnown.new(err)
  when GPG_ERR_NO_POLICY_MATCH
    Error::NoPolicyMatch.new(err)
  when GPG_ERR_NO_SECKEY
    Error::NoSecretKey.new(err)
  when GPG_ERR_MISSING_CERT
    Error::MissingCertificate.new(err)
  when GPG_ERR_BAD_CERT_CHAIN
    Error::BadCertificateChain.new(err)
  when GPG_ERR_UNSUPPORTED_ALGORITHM
    Error::UnsupportedAlgorithm.new(err)
  when GPG_ERR_BAD_SIGNATURE
    Error::BadSignature.new(err)
  when GPG_ERR_NO_PUBKEY
    Error::NoPublicKey.new(err)
  else
    Error.new(err)
  end
end

.export(*args_options) ⇒ Object

call-seq:

GPGME.export(pattern)

GPGME.export extracts public keys from the key ring.

The arguments should be specified as follows.

  • GPGME.export(pattern, options) -> keydata

  • GPGME.export(pattern, keydata, options)

All arguments are optional. If the last argument is a Hash, options will be read from it.

pattern is a string or nil. If pattern is nil, all available public keys are returned. keydata is output.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

options are same as GPGME::Ctx.new().

Raises:

  • (ArgumentError) 


448
449
450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'lib/gpgme.rb', line 448

def GPGME.export(*args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 2
  args, options = split_args(args_options)
  pattern, key = args[0]
  key_data = output_data(key)
  GPGME::Ctx.new(options) do |ctx|
    ctx.export_keys(pattern, key_data)

    unless key
      key_data.seek(0, IO::SEEK_SET)
      key_data.read
    end
  end
end

.gpgme_data_rewind(dh) ⇒ Object 



29
30
31
32
33
34
35
 
# File 'lib/gpgme/compat.rb', line 29

def gpgme_data_rewind(dh)
  begin
    GPGME::gpgme_data_seek(dh, 0, IO::SEEK_SET)
  rescue SystemCallError => e
    return e.errno
  end
end

.gpgme_op_import_ext(ctx, keydata, nr) ⇒ Object 



38
39
40
41
42
43
44
 
# File 'lib/gpgme/compat.rb', line 38

def gpgme_op_import_ext(ctx, keydata, nr)
  err = GPGME::gpgme_op_import(ctx, keydata)
  if GPGME::gpgme_err_code(err) == GPGME::GPG_ERR_NO_ERROR
    result = GPGME::gpgme_op_import_result(ctx)
    nr.push(result.considered)
  end
end

.import(*args_options) ⇒ Object

call-seq:

GPGME.import(keydata)

GPGME.import adds the keys to the key ring.

The arguments should be specified as follows.

  • GPGME.import(keydata, options)

All arguments are optional. If the last argument is a Hash, options will be read from it.

keydata is input.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

options are same as GPGME::Ctx.new().

Raises:

  • (ArgumentError) 


482
483
484
485
486
487
488
489
490
491
 
# File 'lib/gpgme.rb', line 482

def GPGME.import(*args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 2
  args, options = split_args(args_options)
  key = args[0]
  key_data = input_data(key)
  GPGME::Ctx.new(options) do |ctx|
    ctx.import_keys(key_data)
    ctx.import_result
  end
end

.input_data(input) ⇒ Object 



527
528
529
530
531
532
533
534
535
536
537
 
# File 'lib/gpgme.rb', line 527

def input_data(input)
  if input.kind_of? GPGME::Data
    input
  elsif input.respond_to? :to_str
    GPGME::Data.from_str(input.to_str)
  elsif input.respond_to? :read
    GPGME::Data.from_callbacks(IOCallbacks.new(input))
  else
    raise ArgumentError, input.inspect
  end
end

.list_keys(*args_options) ⇒ Object

call-seq:

GPGME.list_keys(pattern=nil, secret_only=false, options=Hash.new){|key| ...}

GPGME.list_keys iterates over the key ring.

The arguments should be specified as follows.

  • GPGME.list_keys(pattern, secret_only, options)

All arguments are optional. If the last argument is a Hash, options will be read from it.

pattern is a string or nil. If pattern is nil, all available keys are returned. If secret_only is true, the only secret keys are returned.

options are same as GPGME::Ctx.new().

Raises:

  • (ArgumentError) 


411
412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/gpgme.rb', line 411

def GPGME.list_keys(*args_options) # :yields: key
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 3
  args, options = split_args(args_options)
  pattern, secret_only = args
  GPGME::Ctx.new do |ctx|
    if block_given?  
      ctx.each_key(pattern, secret_only || false) do |key|
        yield key
      end
    else
      ctx.keys(pattern, secret_only || false)
    end
  end
end

.output_data(output) ⇒ Object 



540
541
542
543
544
545
546
547
548
549
550
 
# File 'lib/gpgme.rb', line 540

def output_data(output)
  if output.kind_of? GPGME::Data
    output
  elsif output.respond_to? :write
    GPGME::Data.from_callbacks(IOCallbacks.new(output))
  elsif !output
    GPGME::Data.empty
  else
    raise ArgumentError, output.inspect
  end
end

.resolve_keys(keys_or_names, secret_only, purposes = Array.new) ⇒ Object 



509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/gpgme.rb', line 509

def resolve_keys(keys_or_names, secret_only, purposes = Array.new)
  keys = Array.new
  keys_or_names.each do |key_or_name|
    if key_or_name.kind_of? Key
      keys << key_or_name
    elsif key_or_name.kind_of? String
      GPGME::Ctx.new do |ctx|
        key = ctx.keys(key_or_name, secret_only).find {|k|
          k.usable_for?(purposes)
        }
        keys << key if key
      end
    end
  end
  keys
end

.set_engine_info(proto, file_name, home_dir) ⇒ Object

Change the default configuration of the crypto engine implementing protocol proto.

file_name is the file name of the executable program implementing the protocol. home_dir is the directory name of the configuration directory.



751
752
753
754
755
 
# File 'lib/gpgme.rb', line 751

def set_engine_info(proto, file_name, home_dir)
  err = GPGME::gpgme_set_engine_info(proto, file_name, home_dir)
  exc = GPGME::error_to_exception(err)
  raise exc if exc
end

.sign(plain, *args_options) ⇒ Object

call-seq:

GPGME.sign(plain, sig=nil, options=Hash.new)

GPGME.sign creates a signature of the plaintext.

The arguments should be specified as follows.

  • GPGME.sign(plain, sig, options)

  • GPGME.sign(plain, options) -> sig

All arguments except plain are optional. plain is input and sig is output. If the last argument is a Hash, options will be read from it.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

options are same as GPGME::Ctx.new() except for

  • :signers Signing keys. If specified, it is an array whose elements are a GPGME::Key object or a string.

  • :mode Desired type of a signature. Either GPGME::SIG_MODE_NORMAL for a normal signature, GPGME::SIG_MODE_DETACH for a detached signature, or GPGME::SIG_MODE_CLEAR for a cleartext signature.

Raises:

  • (ArgumentError) 


234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/gpgme.rb', line 234

def GPGME.sign(plain, *args_options)
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 2
  args, options = split_args(args_options)
  sig = args[0]

  GPGME::Ctx.new(options) do |ctx|
    ctx.add_signer(*resolve_keys(options[:signers], true, [:sign])) if options[:signers]
    mode = options[:mode] || GPGME::SIG_MODE_NORMAL
    plain_data = input_data(plain)
    sig_data = output_data(sig)
    begin
      ctx.sign(plain_data, sig_data, mode)
    rescue GPGME::Error::UnusableSecretKey => exc
      exc.keys = ctx.sign_result.invalid_signers
      raise exc
    end

    unless sig
      sig_data.seek(0, IO::SEEK_SET)
      sig_data.read
    end
  end
end

.split_args(args_options) ⇒ Object 



497
498
499
500
501
502
503
504
505
506
 
# File 'lib/gpgme.rb', line 497

def split_args(args_options)
  if args_options.length > 0 and args_options[-1].respond_to? :to_hash
    args = args_options[0 ... -1]
    options = args_options[-1].to_hash
  else
    args = args_options
    options = Hash.new
  end
  [args, options]
end

.verify(sig, *args_options) ⇒ Object

call-seq:

GPGME.verify(sig, signed_text=nil, plain=nil, options=Hash.new){|signature| ...}

GPGME.verify verifies a signature.

The arguments should be specified as follows.

  • GPGME.verify(sig, signed_text, plain, options)

  • GPGME.verify(sig, signed_text, options) -> plain

All arguments except sig are optional. sig and signed_text are input. plain is output. If the last argument is a Hash, options will be read from it.

An input argument is specified by an IO like object (which responds to read), a string, or a GPGME::Data object.

An output argument is specified by an IO like object (which responds to write) or a GPGME::Data object.

If sig is a detached signature, then the signed text should be provided in signed_text and plain should be nil. Otherwise, if sig is a normal (or cleartext) signature, signed_text should be nil.

options are same as GPGME::Ctx.new().

Raises:

  • (ArgumentError) 


180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/gpgme.rb', line 180

def GPGME.verify(sig, *args_options) # :yields: signature
  raise ArgumentError, 'wrong number of arguments' if args_options.length > 3
  args, options = split_args(args_options)
  signed_text, plain = args

  GPGME::Ctx.new(options) do |ctx|
    sig_data = input_data(sig)
    if signed_text
      signed_text_data = input_data(signed_text)
      plain_data = nil
    else
      signed_text_data = nil
      plain_data = output_data(plain)
    end
    ctx.verify(sig_data, signed_text_data, plain_data)
    ctx.verify_result.signatures.each do |signature|
      yield signature
    end
    if !signed_text && !plain
      plain_data.seek(0, IO::SEEK_SET)
      plain_data.read
    end
  end
end