1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
\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
|
