Class GPGME::Crypto
In: lib/gpgme/crypto.rb
Parent: Object

Different, independent methods providing the simplest possible API to execute crypto operations via GPG. All methods accept as options the same common options as {GPGME::Ctx.new}. Read the documentation for that class to know how to customize things further (like output stuff in ASCII armored format, for example).

@example

  crypto = GPGME::Crypto.new :armor => true
  encrypted = crypto.encrypt 'Plain text'

Methods

clearsign   decrypt   detach_sign   encrypt   method_missing   new   sign   verify  

Attributes

default_options  [R] 

Public Class methods

Allows calling of methods directly in the module without the need to create a new instance.

Public Instance methods

Clearsigns an element

  crypto.clearsign text, options

Same functionality of {.sign} only doing clearsigns by default.

Decrypts a previously encrypted element

  crypto.decrypt cipher, options, &block

Must have the appropiate key to be able to decrypt, of course. Returns a {GPGME::Data} object which can then be read.

@param cipher

  Must be something that can be converted into a {GPGME::Data} object,
  or a {GPGME::Data} object itself. It is the element that will be
  decrypted.

@param [Hash] options

  The optional parameters:
  * +:output+ if specified, it will write the output into it. It will
    me converted to a {GPGME::Data} object, so it can also be a file,
    for example.
  * If the file was encrypted with symmentric encryption, must provide
    a :password option.
  * Any other option accepted by {GPGME::Ctx.new}

@param &block

  In the block all the signatures are yielded, so one could verify them.
  See examples.

@return [GPGME::Data] a {GPGME::Data} that can be read.

@example Simple decrypt

  crypto.decrypt encrypted_data

@example symmetric encryption, or passwored key

  crypto.decrypt encrypted_data, :password => "gpgme"

@example Output to file

  file = File.open("decrypted.txt", "w+")
  crypto.decrypt encrypted_data, :output => file

@example Verifying signatures

  crypto.decrypt encrypted_data do |signature|
    raise "Signature could not be verified" unless signature.valid?
  end

@raise [GPGME::Error::UnsupportedAlgorithm] when the cipher was encrypted

  using an algorithm that's not supported currently.

@raise [GPGME::Error::WrongKeyUsage] TODO Don‘t know when

@raise [GPGME::Error::DecryptFailed] when the cipher was encrypted

  for a key that's not available currently.

Creates a detached signature of an element

  crypto.detach_sign text, options

Same functionality of {.sign} only doing detached signs by default.

Encrypts an element

 crypto.encrypt something, options

Will return a {GPGME::Data} element which can then be read.

Must have some key imported, look for {GPGME::Key.import} to know how to import one, or the gpg documentation to know how to create one

@param plain

 Must be something that can be converted into a {GPGME::Data} object, or
 a {GPGME::Data} object itself.

@param [Hash] options

 The optional parameters are as follows:
  * +:recipients+ for which recipient do you want to encrypt this file. It
    will pick the first one available if none specified. Can be an array of
    identifiers or just one (a string).
  * +:symmetric+ if set to true, will ignore +:recipients+, and will perform
    a symmetric encryption. Must provide a password via the +:password+
    option.
  * +:always_trust+ if set to true specifies all the recipients to be
    trusted, thus not requiring confirmation.
  * +:sign+ if set to true, performs a combined sign and encrypt operation.
  * +:signers+ if +:sign+ specified to true, a list of additional possible
    signers. Must be an array of sign identifiers.
  * +:output+ if specified, it will write the output into it. It will be
    converted to a {GPGME::Data} object, so it could be a file for example.
  * Any other option accepted by {GPGME::Ctx.new}

@return [GPGME::Data] a {GPGME::Data} object that can be read.

@example returns a {GPGME::Data} that can be later encrypted

 encrypted = crypto.encrypt "Hello world!"
 encrypted.read # => Encrypted stuff

@example to be decrypted by someone@example.com.

 crypto.encrypt "Hello", :recipients => "someone@example.com"

@example If I didn‘t trust any of my keys by default

 crypto.encrypt "Hello" # => GPGME::Error::General
 crypto.encrypt "Hello", :always_trust => true # => Will work fine

@example encrypted string that can be decrypted and/or verified

 crypto.encrypt "Hello", :sign => true

@example multiple signers

 crypto.encrypt "Hello", :sign => true, :signers => "extra@example.com"

@example writing to a file instead

 file = File.open("signed.sec","w+")
 crypto.encrypt "Hello", :output => file # output written to signed.sec

@raise [GPGME::Error::General] when trying to encrypt with a key that is

  not trusted, and +:always_trust+ wasn't specified

Creates a signature of a text

  crypto.sign text, options

Must have the appropiate key to be able to decrypt, of course. Returns a {GPGME::Data} object which can then be read.

@param text

  The object that will be signed. Must be something that can be converted
  to {GPGME::Data}.

@param [Hash] options

 Optional parameters.
  * +:signer+ sign identifier to sign the text with. Will use the first
   key it finds if none specified.
  * +:output+ if specified, it will write the output into it. It will be
    converted to a {GPGME::Data} object, so it could be a file for example.
  * +:mode+ Desired type of signature. Options are:
   - +GPGME::SIG_MODE_NORMAL+ for a normal signature. The default one if
     not specified.
   - +GPGME::SIG_MODE_DETACH+ for a detached signature
   - +GPGME::SIG_MODE_CLEAR+ for a cleartext signature
  * Any other option accepted by {GPGME::Ctx.new}

@return [GPGME::Data] a {GPGME::Data} that can be read.

@example normal sign

  crypto.sign "Hi there"

@example outputing to a file

  file = File.open("text.sign", "w+")
  crypto.sign "Hi there", :options => file

@example doing a detached signature

  crypto.sign "Hi there", :mode => GPGME::SIG_MODE_DETACH

@example specifying the signer

  crypto.sign "Hi there", :signer => "mrsimo@example.com"

@raise [GPGME::Error::UnusableSecretKey] TODO don‘t know when

Verifies a previously signed element

  crypto.verify sig, options, &block

Must have the proper keys available.

@param sig

  The signature itself. Must be possible to convert into a {GPGME::Data}
  object, so can be a file.

@param [Hash] options

  * +:signed_text+ if the sign is detached, then must be the plain text
    for which the signature was created.
  * +:output+ where to store the result of the signature. Will be
    converted to a {GPGME::Data} object.
  * Any other option accepted by {GPGME::Ctx.new}

@param &block

  In the block all the signatures are yielded, so one could verify them.
  See examples.

@return [GPGME::Data] unless the sign is detached, the {GPGME::Data}

  object with the plain text. If the sign is detached, will return nil.

@example simple verification

  sign = crypto.sign("Hi there")
  data = crypto.verify(sign) { |signature| signature.valid? }
  data.read # => "Hi there"

@example saving output to file

  sign = crypto.sign("Hi there")
  out  = File.open("test.asc", "w+")
  crypto.verify(sign, :output => out) {|signature| signature.valid?}
  out.read # => "Hi there"

@example verifying a detached signature

  sign = crypto.detach_sign("Hi there")
  # Will fail
  crypto.verify(sign) { |signature| signature.valid? }
  # Will succeed
  crypto.verify(sign, :signed_text => "hi there") do |signature|
    signature.valid?
  end

[Validate]