\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 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.
* 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.

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_echo(void)
Invoking @code{passphrase_disable_echo} will hide
the user input in the terminal (unless passphrase
hiding is diabled). This is the first thing you
should call.

@item  char* passphrase_read(void)
@code{passphrase_read} reads the passphrase
from standard input. On error @code{NULL}
will be returned, otherwise a NUL-terminated
passphrase will be returned.

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

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

@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        */

int main(int argc, char** argv)
@{
  /* Variables for the passphrase */
  char* passphrase, 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_ = passphrase;
  while (*passphrase)
    *passphrase++ = 0;
  free(passphrase_);
  
  /* Stop hiding user input */
  passphrase_reenable_echo();
  
  /* End of program */
  return 0;
  
  /* `argc` was never used */
  (void) argc;
@}
@end example




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

@bye