Module GPGME
In: lib/gpgme.rb
lib/gpgme/constants.rb
lib/gpgme/compat.rb

What‘s this?

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

Requirements

Installation

 $ gem install ruby-gpgme

or

 $ 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 three levels of API. The highest level API is close to the command line interface of GnuPG. The mid level API looks object-oriented (or rubyish). 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 mid level API

The same example can be rewritten in the mid level API as follows.

 $ 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

The lowest level API

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

License

Copyright (C) 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

Methods

Classes and Modules

Class GPGME::Ctx
Class GPGME::Data
Class GPGME::DecryptResult
Class GPGME::EncryptResult
Class GPGME::EngineInfo
Class GPGME::Error
Class GPGME::ImportResult
Class GPGME::ImportStatus
Class GPGME::InvalidKey
Class GPGME::Key
Class GPGME::KeySig
Class GPGME::NewSignature
Class GPGME::SignResult
Class GPGME::Signature
Class GPGME::SubKey
Class GPGME::UserID
Class GPGME::VerifyResult

Constants

VERSION = "1.0.8"
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
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

External Aliases

gpgme_pubkey_algo_name -> pubkey_algo_name
gpgme_hash_algo_name -> hash_algo_name

Public Class methods

GPGME.clearsign creates a cleartext signature of the plaintext.

The arguments should be specified as follows.

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.

GPGME.decrypt performs decryption.

The arguments should be specified as follows.

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

GPGME.detach_sign creates a detached signature of the plaintext.

The arguments should be specified as follows.

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.

GPGME.encrypt performs encryption.

The arguments should be specified as follows.

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.

GPGME.export extracts public keys from the key ring.

The arguments should be specified as follows.

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

GPGME.import adds the keys to the key ring.

The arguments should be specified as follows.

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

GPGME.list_keys iterates over the key ring.

The arguments should be specified as follows.

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

GPGME.sign creates a signature of the plaintext.

The arguments should be specified as follows.

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.

GPGME.verify verifies a signature.

The arguments should be specified as follows.

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

Public Instance methods

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

Return a list of info structures of enabled engines.

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.

[Validate]