(pinentry.info.gz) Protocol

 
 2 pinentry's Assuan Protocol
 ****************************
 
 The PIN-Entry should never service more than one connection at once.
 It is reasonable to exec the PIN-Entry prior to a request.
 
    The PIN-Entry does not need to stay in memory because the GPG-AGENT
 has the ability to cache passphrases.  The usual way to run the
 PIN-Entry is by setting up a pipe (and not a socket) and then fork/exec
 the PIN-Entry.  The communication is then done by means of the protocol
 described here until the client is satisfied with the result.
 
    Although it is called a PIN-Entry, it does allow to enter reasonably
 long strings (at least 2048 characters are supported by every
 pinentry).  The client using the PIN-Entry has to check for correctness.
 
    Note that all strings are expected to be encoded as UTF-8; PINENTRY
 takes care of converting it to the locally used codeset.  To include
 linefeeds or other special characters, you may percent-escape them
 (i.e. a line feed is encoded as `%0A', the percent sign itself is
 encoded as `%25').
 
    Here is the list of supported commands:
 
 `Set the descriptive text to be displayed'
             C: SETDESC Enter PIN for Richard Nixon <nobody@trickydicky.gov>
             S: OK
 
 `Set the prompt to be shown'
      When asking for a PIN, set the text just before the widget for
      passphrase entry.
             C: SETPROMPT PIN:
             S: OK
 
      You should use an underscore in the text only if you known that a
      modern version of pinentry is used.  Modern versions underline the
      next character after the underscore and use the first such
      underlined character as a keyboard accelerator.  Use a double
      underscore to escape an underscore.
 
 `Set the window title'
      This command may be used to change the default window title.  When
      using this feature you should take care that the window is still
      identifiable as the pinentry.
             C: SETTITLE Tape Recorder Room
             S: OK
 
 `Set the button texts'
      There are three texts which should be used to override the English
      defaults:
 
      To set the text for the button signaling confirmation (in UTF-8).
      See SETPROMPT on how to use an keyboard accelerator.
             C: SETOK Yes
             S: OK
 
      To set the text for the button signaling cancellation or
      disagreement (in UTF-8).  See SETPROMPT on how to use an keyboard
      accelerator.
             C: SETCANCEL No
             S: OK
 
      In case tree buttons are required, use the follwing command to set
      the text (UTF-8) for the non-affirmative response button.  The
      affirmative button text is still set using SETOK and the CANCEL
      button text with SETCANCEL.  See SETPROMPT on how to use an
      keyboard accelerator.
             C: SETNOTOK Do not do this
             S: OK
 
 `Set the Error text'
      This is used by the client to display an error message.  In
      contrast to the other commands this error message is automatically
      reset with a GETPIN or CONFIRM, and is only displayed when asking
      for a PIN.
             C: SETERROR Invalid PIN entered - please try again
             S: OK
 
 `Enable a passphrase quality indicator'
      Adds a quality indicator to the GETPIN window.  This indicator is
      updated as the passphrase is typed.  The clients needs to
      implement an inquiry named "QUALITY" which gets passed the current
      passpharse (percent-plus escaped) and should send back a string
      with a single numerical vauelue between -100 and 100.  Negative
      values will be displayed in red.
             C: SETQUALITYBAR
             S: OK
 
      If a custom label for the quality bar is required, just add that
      label as an argument as percent escaped string.  You will need
      this feature to translate the label because pinentry has no
      internal gettext except for stock strings from the toolkit library.
 
      If you want to show a tooltip for the quality bar, you may use
             C: SETQUALITYBAR_TT string
             S: OK
 
      With STRING being a percent escaped string shown as the tooltip.
 
 `Ask for a PIN'
      The meat of this tool is to ask for a passphrase of PIN, it is
      done with this command:
             C: GETPIN
             S: D no more tapes
             S: OK
      Note that the passphrase is transmitted in clear using standard
      data responses.  Expect it to be in UTF-8.
 
 `Ask for confirmation'
      To ask for a confirmation (yes or no), you can use this command:
             C: CONFIRM
             S: OK
      The client should use SETDESC to set an appropriate text before
      issuing this command, and may use SETPROMPT to set the button
      texts.  The value returned is either OK for YES or the error code
      `ASSUAN_Not_Confirmed'.
 
 `Show a message'
      To show a message, you can use this command:
             C: MESSAGE
             S: OK
      alternativly you may add an option to confirm:
             C: CONFIRM --one-button
             S: OK
      The client should use SETDESC to set an appropriate text before
      issuing this command, and may use SETOK to set the text for the
      dismiss button.  The value returned is OK or an error message.
 
 `Set the output device'
      When using X, the PINENTRY program must be invoked with an
      appropriate `DISPLAY' environment variable or the `--display'
      option.
 
      When using a text terminal:
             C: OPTION ttyname=/dev/tty3
             S: OK
             C: OPTION ttytype=vt100
             S: OK
             C: OPTION lc-ctype=de_DE.UTF-8
             S: OK
      The client should use the `ttyname' option to set the output TTY
      file name, the `ttytype' option to the `TERM' variable appropriate
      for this tty and `lc-ctype' to the locale which defines the
      character set to use for this terminal.
 
 `Set the default strings'
      To avoid having transaltions in Pinentry proper, the caller may set
      certain translated strings which are used by Pinentry as default
      strings.
 
             C: OPTION default-ok=_Korrekt
             S: OK
             C: OPTION default-cancel=Abbruch
             S: OK
             C: OPTION default-prompt=PIN eingeben:
             S: OK
      The strings are subject to accelerator marking, see SETPROMPT for
      details.
Info Catalog
(pinentry.info.gz) Using pinentry
(pinentry.info.gz) Top
(pinentry.info.gz) Copying
automatically generated by info2html