[comment {-*- tcl -*- doctools manpage}]
[manpage_begin gpg n 1.0]
[copyright {2008-2016 Sergei Golovan <sgolovan@nes.ru>}]
[moddesc {Tcl interface to GNU Privacy Guard}]
[titledesc {Tcl Interface to GnuPG}]
[require Tcl 8.4]
[require Tclx]
[require gpg 1.0]
[description]
[para]

This is a Tcl interface to GNU Privacy Guard with interface similar to
TclGPGME.

[section "COMMANDS"]

[list_begin definitions]
[call [cmd set] [arg gpg] \[[cmd ::gpg::new]\]]

Create a new GPG context token.

[call [cmd "\$gpg"] [arg "free"]]

Destroy GPG token and free its resources.

[call [cmd "\$gpg"] \
      [arg "set"] \
      [arg "-property property"] \
      [opt [arg "-value value"]]]

Set or query a specified property.

The property argument may be one of the following:

[list_begin definitions]

[def "[cmd armor] [arg boolean]"]

[def "[cmd textmode] [arg boolean]"]

[def "[cmd passphrase-callback] [arg command]"]

The [cmd passphrase-callback] property sets the command which returns the
user's GPG passphrase to the signing or encrypting/decrypting routine.

Note that currently GPG commonly uses [cmd gpg-agent] to ask user for and
cache passphrases, in this case this [cmd passphrase-callback] property
will be ignored. There are two cases when it isn't:

First, [cmd gpg] 1.4 (called 'classic' at the GnuPG website) without
gpg-agent enabled.

Second, [cmd gpg] 2.1 (called 'modern' at the GnuPG website) with gpg-agent
which allows one to use loopback pinentry (essentially asking the calling
application for a passphrase) and the [cmd pinentry-mode] property set
to [arg loopback].

[def "[cmd pinentry-mode] [arg mode]"]

This property makes sense only for [cmd gpg] 2.1. See the gpg2 manual
for details.

[def [cmd "encoding"]]

[def [cmd "passphrase-encoding"]]

[list_end]

[call [cmd "\$gpg"] \
        [arg "unset"] \
        [arg "-property property"]]

Unset a specified property.

[call [cmd "\$gpg"] \
      [arg "list-keys"] \
      [opt [arg "-patterns patterns"]] \
      [opt [arg "-secretonly boolean"]] \
      [opt [arg "-command command"]]]

Return list of key tokens which match any of a specified patterns in the
patterns list [arg patterns].

[call [cmd "\$gpg"] \
      [arg "info-key"] \
      [arg "-key keytoken"]]

Return a serialized array of key properties.

[call [cmd "\$gpg"] \
      [arg "encrypt"] \
      [arg "-input input"] \
      [opt [arg "-recipients recipients"]] \
      [opt [arg "-sign boolean"]] \
      [opt [arg "-command command"]]]

Encrypt message (using either symmetric or asymmetric algorithm).

[call [cmd "\$gpg"] \
      [arg "decrypt"] \
      [arg "-input input"] \
      [opt [arg "-checkstatus boolean"]] \
      [opt [arg "-command command"]]]

Decrypt message.

[call [cmd "\$gpg"] \
      [arg "sign"] \
      [arg "-input input"] \
      [opt [arg "-mode mode"]] \
      [opt [arg "-command command"]]]

Sign message.

[call [cmd "\$gpg"] \
      [arg "verify"] \
      [arg "-signature signature"] \
      [opt [arg "-input input"]] \
      [opt [arg "-command command"]]]

Verify signature.

[call [cmd set] [arg recipient] \[[cmd ::gpg::recipient]\]]

Create recipients token.

[call [cmd "\$recipient"] \
      [arg "add"] \
      [arg "-name name"] \
      [opt [arg "-validity valid"]]]

Add name to a recipient token.

[call [cmd "\$recipient"] \
      [arg "list"]]

Return a list of recipients in a recipient token.

[list_end]

[section "ASYNCHRONOUS MODE"]

Many GPG subcommands may posess [arg "-command"] options. It turns
asynchronous mode on and specifies a callback which is called to return
operation result. This means that the command returns immediately, the pipe
to GPG is switched to non-blocking mode and data from it is read only when
it is available. After the operation is completed the callback is invoked
with appended status (\"ok\" or \"error\") and the operation result in the
same form as it would be returned in synchronous mode.

[section EXAMPLES]

Encrypt the word Hello using a symmetric encryption using
passphrase "abcdefgh":

[comment {Spaces after trailing \ are essential}]
[example {
proc pass {args} {return abcdefgh}
set gpg [::gpg::new]
$gpg set -property armor -value true
$gpg set -property encoding -value utf-8
$gpg set -property passphrase-callback -value pass
puts [$gpg encrypt -input Hello]
$gpg free
}]

[section ENVIRONMENT]

[list_begin definitions]

[def [var \$GPG_EXECUTABLE]]

This variable specifies the GnuPG executable if it isn't [cmd gpg] or
can't be found in a directory from the [var \$PATH] environment variable.

[def [var \$GPG_AGENT_INFO]]

This variable is required for the [package gpg] packge to work with GnuPG 2.0.

[list_end]

[section "SEE ALSO"]

https://www.gnupg.org

[section "AUTHORS"]

Sergei Golovan

[keywords Tcl GnuPG]
[comment { vim: set ft=tcl ts=8 sw=4 sts=4 et: }]
[manpage_end]
