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
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
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"}
See decrypt/2
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
delete_key!(context :: context(), key :: ExGpgme.Keys.Key.t()) :: nil | no_return()
See delete_key/2
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
delete_secret_key!(context :: context(), key :: ExGpgme.Keys.Key.t()) :: nil | no_return()
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"}
encrypt!(context :: context(), recipients :: [ExGpgme.Keys.Key.t()], data :: String.t(), flags :: ExGpgme.EncryptFlags.flags()) :: String.t() | no_return()
See encrypt/4
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"}
engine_info!(context :: context()) :: ExGpgme.Engine.EngineInfo.t() | no_return()
See engine_info/1
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"}
find_key!(context :: context(), fingerprint :: String.t()) :: ExGpgme.Keys.Key.t() | no_return()
See find_key/2
.
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>}
from_protocol!(protocol :: ExGpgme.protocol()) :: context() | no_return()
See from_protocol/1
.
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, ""}
See get_flag/2
.
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}}
import!(context :: context(), data :: String.t()) :: ExGpgme.Results.ImportResult.t() | no_return()
See import/2
.
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
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
The function retrieves the protocol currently used with the context.
Examples
iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.protocol
:open_pgp
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
Set home directory for GPG Context.
Examples
iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_engine_home_dir("/some/path")
:ok
Set engine path for GPG Context.
Examples
iex> :open_pgp
...> |> ExGpgme.Context.from_protocol!
...> |> ExGpgme.Context.set_engine_path("/some/path")
:ok
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 avalue
of"1"
the status callback set by gpgme_set_status_cb returns all status lines with the exception ofPROGRESS
lines. With the default of"0"
the status callback is only called in certain situations."raw-description"
- Setting thevalue
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 avalue
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 invalue
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 viaps(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
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
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
set_pinentry_mode!(context :: context(), mode :: ExGpgme.pinentry_mode()) :: nil | no_return()
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
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"}
sign!(context :: context(), mode :: ExGpgme.sign_mode(), data :: String.t()) :: String.t() | no_return()
See sign/3
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"}
sign_and_encrypt!(context :: context(), recipients :: [ExGpgme.Keys.Key.t()], data :: String.t(), flags :: ExGpgme.EncryptFlags.flags()) :: String.t() | no_return()
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
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}]}}
verify_opaque!(context :: context(), signature :: String.t(), data :: String.t()) :: ExGpgme.Results.VerificationResult.t() | no_return()
See verify_opaque/3