ex_gpgme v0.1.0 ExGpgme.Context

GPG Context

Warning: The context is not immutable. Therefore multiple processes will influence each other with configuration, flags etc.

Link to this section Summary

Types

GPG Context for all functions of ExGpgme.Context

Functions

The function returns true if the output is ASCII armored, and false if it is not

The function decrypts the ciphertext in the argument ciphertext and returns the plain text

The function deletes the key key from the key ring of the crypto engine used by context

The function deletes the secret key key from the key ring of the crypto engine used by context

Encrypts a message for the specified recipients

Returns an EngineInfo struct that describes the configuration of the context

Find a key by Fingerprint

The function creates a context with the protocol. All crypto operations will be performed by the crypto engine configured for that protocol. See Protocols and Engines

The value of flags settable by set_flag/3 can be retrieved by this function. If name is unknown the function returns :error. For boolean flags an empty string is returned for false and the string "1" is returned for true; a test for an empty string can be used to get the boolean value

Import Keys

The function returns true if offline mode is enabled, and false if it is not

The function returns the mode set for the context

The function retrieves the protocol currently used with the context

The function specifies if the output should be ASCII armored. By default, output is not ASCII armored

Set home directory for GPG Context

Set engine path for GPG Context

Some minor properties of the context can be controlled with flags set by this function. The properties are identified by the following values for name

The function specifies if offline mode should be used. By default, offline mode is not used

The function sets the mode for the context

The function specifies if canonical text mode should be used. By default, text mode is not used

The function creates a signature for the text in the data. The type of the signature created is determined by the ASCII armor (or, if that is not set, by the encoding specified for sig), the text mode attributes set for the context ctx and the requested signature mode mode

Signs and encrypts a message for the specified recipients

The function returns true if canonical text mode is enabled, and false if it is not

The function verifies that the signature signature is a valid signature

Link to this section Types

GPG Context for all functions of ExGpgme.Context.

Warning: The context is not immutable. Therefore multiple processes will influence each other with configuration, flags etc.

Link to this section Functions

Link to this function armor?(context)
armor?(context :: context()) :: boolean()

The function returns true if the output is ASCII armored, and false if it is not.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.armor?
false
Link to this function decrypt(context, cyphertext)
decrypt(context :: context(), cypertext :: String.t()) ::
  {:ok, String.t()} |
  {:error, String.t()}

The function decrypts the ciphertext in the argument ciphertext and returns the plain text.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.set_armor(context, true)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_secret.asc"))
iex> recipient = ExGpgme.Context.find_key!(context, "95E93F470BCB2E96C648572DFBFA85913EE05E95")
iex> cyphertext = ExGpgme.Context.encrypt!(context, [recipient], "Hello World", [:always_trust])
iex> ExGpgme.Context.decrypt(context, cyphertext)
{:ok, "Hello World"}
Link to this function decrypt!(context, cyphertext)
decrypt!(context :: context(), cypertext :: String.t()) ::
  String.t() |
  no_return()

See decrypt/2

Link to this function delete_key(context, key)
delete_key(context :: context(), key :: ExGpgme.Keys.Key.t()) ::
  :ok |
  {:error, String.t()}

The function deletes the key key from the key ring of the crypto engine used by context.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_public.asc"))
iex> key = ExGpgme.Context.find_key!(context, "95E93F470BCB2E96C648572DFBFA85913EE05E95")
iex> ExGpgme.Context.delete_key(context, key)
:ok
Link to this function delete_key!(context, key)
delete_key!(context :: context(), key :: ExGpgme.Keys.Key.t()) ::
  nil |
  no_return()

See delete_key/2

Link to this function delete_secret_key(context, key)
delete_secret_key(context :: context(), key :: ExGpgme.Keys.Key.t()) ::
  :ok |
  {:error, String.t()}

The function deletes the secret key key from the key ring of the crypto engine used by context.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_public.asc"))
iex> key = ExGpgme.Context.find_key!(context, "95E93F470BCB2E96C648572DFBFA85913EE05E95")
iex> ExGpgme.Context.delete_secret_key(context, key)
:ok
Link to this function delete_secret_key!(context, key)
delete_secret_key!(context :: context(), key :: ExGpgme.Keys.Key.t()) ::
  nil |
  no_return()

See delete_secret_key/2

Link to this function encrypt(context, recipients, data, flags \\ [])
encrypt(context :: context(), recipients :: [ExGpgme.Keys.Key.t()], data :: String.t(), flags :: ExGpgme.EncryptFlags.flags()) ::
  {:ok, String.t()} |
  {:error, String.t()}

Encrypts a message for the specified recipients.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.set_armor(context, true)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_public.asc"))
iex> recipient = ExGpgme.Context.find_key!(context, "95E93F470BCB2E96C648572DFBFA85913EE05E95")
iex> ExGpgme.Context.encrypt(context, [recipient], "Hello World", [:always_trust])
{:ok,
 "-----BEGIN PGP MESSAGE-----\n[data]\n-----END PGP MESSAGE-----\n"}
Link to this function encrypt!(context, recipients, data, flags \\ [])
encrypt!(context :: context(), recipients :: [ExGpgme.Keys.Key.t()], data :: String.t(), flags :: ExGpgme.EncryptFlags.flags()) ::
  String.t() |
  no_return()

See encrypt/4

Link to this function engine_info(context)
engine_info(context :: context()) ::
  {:ok, ExGpgme.Engine.EngineInfo.t()} |
  {:error, String.t()}

Returns an EngineInfo struct that describes the configuration of the context.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.engine_info
%ExGpgme.Engine.EngineInfo{home_dir: "",
  path: "/usr/local/MacGPG2/bin/gpg", protocol: :open_pgp,
  required_version: "1.4.0", version: "2.2.0"}
Link to this function engine_info!(context)
engine_info!(context :: context()) ::
  ExGpgme.Engine.EngineInfo.t() |
  no_return()

See engine_info/1

Link to this function find_key(context, fingerprint)
find_key(context :: context(), fingerprint :: String.t()) ::
  {:ok, ExGpgme.Keys.Key.t()} |
  {:error, String.t()}

Find a key by Fingerprint

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_public.asc"))
iex> ExGpgme.Context.find_key(context, "95E93F470BCB2E96C648572DFBFA85913EE05E95")
{:ok, #Reference<0.411470915.3086352388.254522>}

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_public.asc"))
iex> ExGpgme.Context.find_key(context, "not-existing-fingerprint")
{:error, "End of file"}
Link to this function find_key!(context, fingerprint)
find_key!(context :: context(), fingerprint :: String.t()) ::
  ExGpgme.Keys.Key.t() |
  no_return()

See find_key/2.

Link to this function from_protocol(protocol)
from_protocol(protocol :: ExGpgme.protocol()) ::
  {:ok, context()} |
  {:error, String.t()}

The function creates a context with the protocol. All crypto operations will be performed by the crypto engine configured for that protocol. See Protocols and Engines.

Setting the protocol does not check if the crypto engine for that protocol is available and installed correctly. See Engine Version Check.

Examples

iex> ExGpgme.Context.from_protocol(:open_pgp)
{:ok, #Reference<0.1689386418.123076612.191614>}
Link to this function from_protocol!(protocol)
from_protocol!(protocol :: ExGpgme.protocol()) ::
  context() |
  no_return()

See from_protocol/1.

Link to this function get_flag(context, name)
get_flag(context :: context(), name :: String.t()) ::
  {:ok, String.t()} |
  {:error, :not_set | String.t()}

The value of flags settable by set_flag/3 can be retrieved by this function. If name is unknown the function returns :error. For boolean flags an empty string is returned for false and the string "1" is returned for true; a test for an empty string can be used to get the boolean value.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.get_flag("not-existing-flag")
{:error, :not_set}

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.get_flag("export-session-key")
{:ok, ""}
Link to this function get_flag!(context, name)
get_flag!(context :: context(), name :: String.t()) ::
  String.t() |
  no_return()

See get_flag/2.

Link to this function import(context, data)
import(context :: context(), data :: String.t()) ::
  {:ok, ExGpgme.Results.ImportResult.t()} |
  {:error, String.t()}

Import Keys

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.import(File.read!("priv/test/keys/sender_public.asc"))
{:ok,
 %ExGpgme.Results.ImportResult{considered: 1, imported: 0,
  imported_rsa: 0,
  imports: [%ExGpgme.Results.Import{fingerprint: "95E93F470BCB2E96C648572DFBFA85913EE05E95"}],
  new_revocations: 0, new_signatures: 0, new_subkeys: 0,
  new_user_ids: 0, not_imported: 0, secret_considered: 0,
  secret_imported: 0, secret_unchanged: 0, unchanged: 1,
  without_user_id: 0}}
Link to this function import!(context, data)
import!(context :: context(), data :: String.t()) ::
  ExGpgme.Results.ImportResult.t() |
  no_return()

See import/2.

Link to this function offline?(context)
offline?(context :: context()) :: boolean()

The function returns true if offline mode is enabled, and false if it is not.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.offline?
false
Link to this function pinentry_mode(context)
pinentry_mode(context :: context()) :: ExGpgme.pinentry_mode()

The function returns the mode set for the context.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.pinentry_mode
:default
Link to this function protocol(context)
protocol(context :: context()) :: ExGpgme.protocol()

The function retrieves the protocol currently used with the context.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.protocol
:open_pgp
Link to this function set_armor(context, yes)
set_armor(context :: context(), yes :: boolean()) :: :ok

The function specifies if the output should be ASCII armored. By default, output is not ASCII armored.

ASCII armored output is disabled if yes is false, and enabled otherwise.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_armor(true)
:ok
Link to this function set_engine_home_dir(context, home_dir)
set_engine_home_dir(context :: context(), home_dir :: String.t()) ::
  :ok |
  {:error, String.t()}

Set home directory for GPG Context.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_engine_home_dir("/some/path")
:ok
Link to this function set_engine_home_dir!(context, home_dir)
set_engine_home_dir!(context :: context(), home_dir :: String.t()) ::
  nil |
  no_return()

See set_engine_home_dir/2

Link to this function set_engine_path(context, path)
set_engine_path(context :: context(), path :: String.t()) ::
  :ok |
  {:error, String.t()}

Set engine path for GPG Context.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_engine_path("/some/path")
:ok
Link to this function set_engine_path!(context, path)
set_engine_path!(context :: context(), path :: String.t()) ::
  nil |
  no_return()

See set_engine_path/2

Link to this function set_flag(context, flag, value)
set_flag(context :: context(), flag :: String.t(), value :: String.t()) ::
  :ok |
  {:error, String.t()}

Some minor properties of the context can be controlled with flags set by this function. The properties are identified by the following values for name:

  • "redraw" - This flag is normally not changed by the caller because GPGME sets and clears it automatically: The flag is cleared before an operation and set if an operation noticed that the engine has launched a Pinentry. A Curses based application may use this information to redraw the screen.
  • "full-status" - Using a value of "1" the status callback set by gpgme_set_status_cb returns all status lines with the exception of PROGRESS lines. With the default of "0" the status callback is only called in certain situations.
  • "raw-description" - Setting the value to "1" returns human readable strings in a raw format. For example the non breaking space characters (~) will not be removed from the description field of the gpgme_tofu_info_t object.
  • "export-session-key" - Using a value of "1" specifies that the context should try to export the symmetric session key when decrypting data. By default, or when using an empty string or "0" for value, session keys are not exported.
  • override-session-key" - The string given in value is passed to the GnuPG engine to override the session key for decryption. The format of that session key is specific to GnuPG and can be retrieved during a decrypt operation when the context flag "export-session-key" is enabled. Please be aware that using this feature with GnuPG < 2.1.16 will leak the session key on many platforms via ps(1).

Examples

iex> context = :open_pgp
...> |> ExGpgme.Context.from_protocol!
iex> ExGpgme.Context.set_flag(context, "not-existing-flag", "1")
{:error, "Unknown name"}

iex> context = :open_pgp
...> |> ExGpgme.Context.from_protocol!
iex> ExGpgme.Context.set_flag(context, "raw-description", "1")
:ok
Link to this function set_offline(context, yes)
set_offline(context :: context(), yes :: boolean()) :: :ok

The function specifies if offline mode should be used. By default, offline mode is not used.

The offline mode specifies if dirmngr should be used to do additional validation that might require connections to external services. (e.g. CRL / OCSP checks).

Offline mode only affects the keylist mode GPGME_KEYLIST_MODE_VALIDATE and is only relevant to the CMS crypto engine. Offline mode is ignored otherwise.

This option may be extended in the future to completely disable the use of dirmngr for any engine.

Offline mode is disabled if yes is false, and enabled otherwise.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_offline(true)
:ok
Link to this function set_pinentry_mode(context, mode)
set_pinentry_mode(context :: context(), mode :: ExGpgme.pinentry_mode()) ::
  :ok |
  {:error, String.t()}

The function sets the mode for the context.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_pinentry_mode(:ask)
:ok
Link to this function set_pinentry_mode!(context, mode)
set_pinentry_mode!(context :: context(), mode :: ExGpgme.pinentry_mode()) ::
  nil |
  no_return()

See set_pinentry_mode/2

Link to this function set_text_mode(context, yes)
set_text_mode(context :: context(), yes :: boolean()) :: :ok

The function specifies if canonical text mode should be used. By default, text mode is not used.

Text mode is for example used for the RFC2015 signatures; note that the updated RFC 3156 mandates that the mail user agent does some preparations so that text mode is not needed anymore.

This option is only relevant to the OpenPGP crypto engine, and ignored by all other engines.

Canonical text mode is disabled if yes is false, and enabled otherwise.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_text_mode(true)
:ok
Link to this function sign(context, mode \\ :normal, data)
sign(context :: context(), mode :: ExGpgme.sign_mode(), data :: String.t()) ::
  {:ok, String.t()} |
  {:error, String.t()}

The function creates a signature for the text in the data. The type of the signature created is determined by the ASCII armor (or, if that is not set, by the encoding specified for sig), the text mode attributes set for the context ctx and the requested signature mode mode.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.set_armor(context, true)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_secret.asc"))
iex> ExGpgme.Context.sign(context, "Hello World")
{:ok, "-----BEGIN PGP MESSAGE-----\n[data]\n-----END PGP MESSAGE-----\n"}
Link to this function sign!(context, mode \\ :normal, data)
sign!(context :: context(), mode :: ExGpgme.sign_mode(), data :: String.t()) ::
  String.t() |
  no_return()

See sign/3

Link to this function sign_and_encrypt(context, recipients, data, flags \\ [])
sign_and_encrypt(context :: context(), recipients :: [ExGpgme.Keys.Key.t()], data :: String.t(), flags :: ExGpgme.EncryptFlags.flags()) ::
  {:ok, String.t()} |
  {:error, String.t()}

Signs and encrypts a message for the specified recipients.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.set_armor(context, true)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_public.asc"))
iex> recipient = ExGpgme.Context.find_key!(context, "95E93F470BCB2E96C648572DFBFA85913EE05E95")
iex> ExGpgme.Context.sign_and_encrypt(context, [recipient], "Hello World", [:always_trust])
{:ok, "-----BEGIN PGP MESSAGE-----\n[data]\n-----END PGP MESSAGE-----\n"}
Link to this function sign_and_encrypt!(context, recipients, data, flags \\ [])
sign_and_encrypt!(context :: context(), recipients :: [ExGpgme.Keys.Key.t()], data :: String.t(), flags :: ExGpgme.EncryptFlags.flags()) ::
  String.t() |
  no_return()

See sign_and_encrypt/4

Link to this function text_mode?(context)
text_mode?(context :: context()) :: boolean()

The function returns true if canonical text mode is enabled, and false if it is not.

Examples

iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.text_mode?
false
Link to this function verify_opaque(context, signature, data)
verify_opaque(context :: context(), signature :: String.t(), data :: String.t()) ::
  {:ok, ExGpgme.Results.VerificationResult.t()} |
  {:error, String.t()}

The function verifies that the signature signature is a valid signature.

Examples

iex> context = ExGpgme.Context.from_protocol!(:open_pgp)
iex> ExGpgme.Context.set_armor(context, true)
iex> ExGpgme.Context.import!(context, File.read!("priv/test/keys/sender_secret.asc"))
iex> signature = ExGpgme.Context.sign!(context, "Hello World")
iex> ExGpgme.Context.verify_opaque(context, signature, "Hello World")
{:ok,
  %ExGpgme.Results.VerificationResult{filename: nil,
   signatures: [%ExGpgme.Results.Signature{creation_time: 1510648065,
     expiration_time: nil,
     fingerprint: "406B5EE427BA5396C39D0F1DD257FFE3438B29DB",
     hash_algorithm: :sha512, is_wrong_key_usage: false, key: nil,
     key_algorithm: :rsa, never_expires: true,
     nonvalidity_reason: nil, notations: [], pka_address: nil,
     pka_trust: :unknown, policy_url: nil, status: :valid,
     validity: :full, verified_by_chain: false}]}}
Link to this function verify_opaque!(context, signature, data)
verify_opaque!(context :: context(), signature :: String.t(), data :: String.t()) ::
  ExGpgme.Results.VerificationResult.t() |
  no_return()

See verify_opaque/3