<!-- secret-query.sgml - man page source for secret-query -->
<!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
  <!ENTITY trailer SYSTEM "trailer.sgml">
]>

<refentry>
  <refmeta>
    <refentrytitle>secret-query</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Quintuple Agent</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>secret-query</refname>
    <refpurpose>Ask for a secret in a secure way</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>secret-query</command>
      <arg rep=repeat><replaceable>OPTION</replaceable></arg>
      <arg><replaceable>QUESTION</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>The <command/secret-query/ program will pop up a window,
asking for the entry of a secret. It is usually called by
<command/q-agent/, or <command/q-client/ when no terminal
interaction with the user is possible. You can use it for other
things, too, as the interface is very simple, and in the default mode
not specific to the <productname>Quintuple Agent</productname> suite.</para>
    <para>If <replaceable/QUESTION/ is given, it will be used as the
prompt text in the window.</para>
    <para>All the necessary precautions are taken so that your secret
stays that way while under control of <command/secret-query/: the
keyboard is grabbed to prevent sniffing, an amount of memory is locked (if
possible) so that paging will not write the secret to disk.</para>
    <para>After a secret has been entered and the <literal/OK/ button
is pressed, <command/secret-query/ will output the secret to stdout,
and exit with code <returnvalue/0/.</para>
    <para>Cancelling entry with the appropriate button or by closing
the window will produce an exit code of <returnvalue/1/.</para>
    <variablelist>
      <varlistentry>
	<term><option/-g/, <option/--no-global-grab/</term>
	<listitem>
	  <para>usually, as soon as the query window appears the
keyboard is grabbed, diverting any keyboard input to
<command/secret-query/ - this option will prevent grabbing until the
query window gets keyboard focus by normal means. This retains
security, while doing away with the somewhat obnoxious
<phrase>snatching-from-under-your-fingers</phrase> aspect</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option/-e/, <option/--enhanced/</term>
	<listitem>
	  <para>turns on the enhanced interface, normally only useful
to <command/q-agent/: time-to-live and other options are queried
along with the secret, and later output in rfc822-like
<literal><replaceable/Keyword/: <replaceable/Value/</literal> style</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option/-d/, <option/--debug/</term>
	<listitem>
	  <para>turn on debugging output</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option/--help/</term>
	<listitem>
	  <para>print a usage synopsis, then exit</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option/--version/</term>
	<listitem>
	  <para>print version information, then exit</para>
	</listitem>
      </varlistentry>
    </variablelist>
  <refsect1>
    <title>See Also</title>
    <simplelist>
      <member><citerefentry>
	  <refentrytitle>q-agent<manvolnum/1/
	</citerefentry></member>
      <member><citerefentry>
	  <refentrytitle>q-client<manvolnum/1/
	</citerefentry></member>
    </simplelist>
  </refsect1>
&trailer;
</refentry>