\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename libpassphrase.info
@settitle libpassphrase
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header


@dircategory Library
@direntry
* libpassphrase: (libpassphrase).     Personalisable terminal passphrase reading library
@end direntry


@copying
Copyright @copyright{} 2013, 2014, 2015 Mattias Andrée

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@ifnottex
@node Top
@top libpassphrase -- Personalisable terminal passphrase reading library
@insertcopying
@end ifnottex

@titlepage
@title libpassphrase
@subtitle Personalisable terminal passphrase reading library
@author by Mattias Andrée (maandree)

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                        Brief overview of libpassphrase.
* Advanced Programming Interface::  How to take advantage of libpassphrase in your application.
* Configuring libpassphrase::       How to configure libpassphrase.
* GNU Free Documentation License::  Copying and sharing this manual.
@end menu



@node Overview
@chapter Overview

libpassphrase is a small C library for reading passphrases from
the terminal via the standard input channel. The purpose of
libpassphrase is to provide a way to personalise the behaviour
in the terminal when applications that takes advantage of
libpassphrase reads a passphrase.

Among other configurations, you can configure libpassphrase to
print asterisks instead of disabling echoing.

libpassphrase's advanced programming interface is very small
and simple, if libpassphrase cannot do exactly what you want,
you can either modify the source code to do what it you want
or write your own replacement.



@node Advanced Programming Interface
@chapter Advanced Programming Interface

@menu
* Example::   Example of how to use libpassphrase
@end menu


To use libpassphrase, add the option @option{-lpassphrase}
to the linker. In other words add @option{-lpassphrase} to
the arguments when invoking GCC @footnote{Or your compile
or choice.}, when it creates an executable
file.

libpassphrase should be dynamically linked as static
linking would require recompilation of the program
and not just libpassphrase to reconfigure libpassphrase.

Include the system header file @file{passphrase.h}, in the
file you want to use libpassphrase.

@file{passphrase.h} uses the inclusion guard
@code{__PASSPHRASE_H__}.

Including @file{passphrase.h} gives you three functions:

@table @code

@item  void passphrase_disable_echo1(int fdin)
@itemx void passphrase_disable_echo(void)
Invoking @code{passphrase_disable_echo1} will hide
the user input in the terminal (unless passphrase
hiding is diabled). This is the first thing you
should call. @code{fdin} should be a file descriptor
to the terminal. One can be acquired by opening
@file{/dev/tty}.

@code{passphrase_disable_echo} is deprecated
and is equivalent to
@code{passphrase_disable_echo1(STDIN_FILENO)}.

@item  char* passphrase_read2(int fdin, int flags)
@itemx char* passphrase_read(void)
@code{passphrase_read2} reads the passphrase
from the terminal. On error @code{NULL}
will be returned, otherwise a NUL-terminated
passphrase will be returned. @code{fdin} should
be a file descriptor to the terminal. One can
be acquired by opening @file{/dev/tty}.

When you are done with the returned passphrase
you should wipe it and free it.

@code{passphrase_read} is deprecated
and is equivalent to
@code{passphrase_read2(STDIN_FILENO, 0)}.

@item  void passphrase_reenable_echo1(int fdin)
@itemx void passphrase_reenable_echo(void)
When you have read the passphrase you should
invoke @code{passphrase_reenable_echo1}. It will
revert all settings to the terminal made by
@code{passphrase_disable_echo1}. If you have
made settings changes to the terminal after
@code{passphrase_reenable_echo1} but before
@code{passphrase_disable_echo1}, those change
may be lost as @code{passphrase_disable_echo1}
saves all settings before changing them and
@code{passphrase_reenable_echo1} applies to
saved settings. @code{fdin} should be a file
descriptor to the terminal.

@code{passphrase_reenable_echo} is deprecated
and is equivalent to
@code{passphrase_reenable_echo1(STDIN_FILENO)}.

@item  void passphrase_wipe(char*, size_t)
When you are done using passhprase you should
erase it from the memory before freeing its
allocation. To do this securtly, call
@code{passphrase_wipe} with the passphase
as the first argument and the length of the
passphrase as the second argument.

@end table

These three functions could be made into one
function, it is however separated so that you
can hide the passphrase earlier than you can
read the passphrase, to minimise the risk that
the user starts typing before the echoing has
been disabled.


@node Example
@section Example

@example
#include <passphrase.h>  /* For libpassphrase */
#include <stdio.h>       /* For output        */
#include <stdlib.h>      /* For free          */
#include <string.h>      /* For strlen        */

int main(int argc, char** argv)
@{
  /* Variables for the passphrase */
  char* passphrase;
  
  /* Hide the passphrase */
  passphrase_disable_echo();
  
  /* Do things needed before reading the passphrase */
  printf("Passphrase: ");
  fflush(stdout);
  
  /* Read the passphrase */
  passphrase = passphrase_read();
  if (passphrase == NULL)
   @{
    /* Something went wrong, print what and exit */
    perror(*argv);
    return 1;
   @}
  
  /* Use the passphrase */
  printf("You entered: %s\n", passphrase);
  
  /* Wipe and free the passphrase */
  passphrase_wipe(passphrase, strlen(passphrase));
  free(passphrase);
  
  /* Stop hiding user input */
  passphrase_reenable_echo();
  
  /* End of program */
  return 0;
  
  /* `argc` was never used */
  (void) argc;
@}
@end example



@node Configuring libpassphrase
@chapter Configuring libpassphrase

libpassphrase is configured at compile time.
Its makefile contains the variable @var{OPTIONS}
which is composed of the definitions you want
to add to the C preprocessor when compiling
libpassphrase. The definitions are blank space
separated, for example
@command{make OPTIONS="PASSPHRASE_STAR PASSPHRASE_REALLOC"}
will compile libpassphrase with the options
@code{PASSPHRASE_STAR} and @code{PASSPHRASE_REALLOC}.

The following options are defined:

@table @asis

@item @code{PASSPHRASE_ECHO}
Do not hide the passphrase.

@item @code{PASSPHRASE_STAR} @footnote{May not be combined with @code{PASSPHRASE_ECHO} or @code{PASSPHRASE_TEXT}.}
Use `*' for each character instead of disabling echoing.

@item @code{PASSPHRASE_TEXT} @footnote{May not be combined with @code{PASSPHRASE_STAR} or @code{PASSPHRASE_ECHO}.}
Use the texts `(empty)' and `(not empty)' to describe whether
anything has been entered or not the instead of disabling echoing.

@item @code{PASSPHRASE_REALLOC}
Soften security by using @code{realloc} instead of
using @code{malloc} and wiping the passphrase from
the old allocation after duplicating it.

@item @code{PASSPHRASE_MOVE}
Add the possibilty to move the point (cursor),
even if the passphrase is hidden this is usable.

If using this options you should use at
least one of @code{PASSPHRASE_INSERT} and
@code{PASSPHRASE_OVERRIDE}, and at least
on of @code{PASSPHRASE_CONTROL} and
@code{PASSPHRASE_DEDICATED}.

Provided that all options that requires
@code{PASSPHRASE_MOVE} are used, the
following key combinations are recognised:

@table @kbd

@item <left>
@itemx C-b
Move the point one step to the left.

@item <right>
@itemx C-f
Move the point one step to the right.

@item <home>
@itemx C-a
Move the point to the beginning of the passphrase.

@item <end>
@itemx C-e
Move the point to the end of the passphrase.

@item backspace
@itemx C-h
Erase the letter before the point.

@item <delete>
@itemx C-d
Reverse erase: erase the letter at the point.

@item <insert>
Switch between insert mode and override mode.

@end table

@item @code{PASSPHRASE_INSERT} @footnote{Requires @code{PASSPHRASE_MOVE}.}
Enable insert mode.

@item @code{PASSPHRASE_OVERRIDE} @footnote{Requires @code{PASSPHRASE_MOVE}.}
Enable override mode.

@item @code{PASSPHRASE_DELETE} @footnote{Requires @code{PASSPHRASE_MOVE}.}
Enable reversed erase command.

@item @code{PASSPHRASE_CONTROL} @footnote{Requires @code{PASSPHRASE_MOVE}.}
Enable use of key combinations using the
control modifier.

@item @code{PASSPHRASE_DEDICATED} @footnote{Requires @code{PASSPHRASE_MOVE}.}
Enable use of keys with specific purpose,
such as the Delete key and the arrow keys.

@item @code{DEFAULT_INSERT} @footnote{Requires @code{PASSPHRASE_INSERT} and @code{PASSPHRASE_OVERRIDE}.}
Use insert mode and not override mode as default.
It is toggleable with the Insert key if
@code{PASSPHRASE_DEDICATED} is used.

@item @code{PASSPHRASE_INVALID}
Prevent duplication of non-initialised memory.

Only allocated memory will be duplication,
but at the end of the passphrase allocation
non-initialised memory can be read. Adding
@code{PASSPHRASE_INVALID} ensures that all
read memory is initialised by NUL-terminating
the passphrase before it is completed when
it is possible that non-initialised memory
is about to be read.

This options is not really needed, but not
using it means that you can get warnings
in @command{valgrind}.

@end table


In addition, you may use the follow flags.

@table @asis

@item @code{PASSPHRASE_STAR_CHAR}
The text to print instead of the character `*' when
@code{PASSPHRASE_STAR} is used. For example you may run
@example
make OPTIONS=PASSPHRASE_STAR  \
     PASSPHRASE_STAR_CHAR="#"
@end example

@item @code{PASSPHRASE_TEXT_EMPTY}
The text to print instead of the `(empty)' when
@code{PASSPHRASE_TEXT} is used. For example you may run
@example
make OPTIONS=PASSPHRASE_TEXT  \
     PASSPHRASE_TEXT_EMPTY="there is nothing here"
@end example

@item @code{PASSPHRASE_TEXT_NOT_EMPTY}
The text to print instead of the `(not empty)' when
@code{PASSPHRASE_TEXT} is used. For example you may run
@example
make OPTIONS=PASSPHRASE_TEXT  \
     PASSPHRASE_TEXT_NOT_EMPTY="there is something here"
@end example

@end table



@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye