=head1 NAME

nbdkit_read_password - read passwords and other secrets for nbdkit

=head1 SYNOPSIS

 #include <nbdkit-plugin.h>

 int nbdkit_read_password (const char *value, char **password);

=head1 DESCRIPTION

The C<nbdkit_read_password> utility function can be used to read
passwords from config parameters.

The C<password> result string is allocated by malloc, and so you may
need to free it.

=head2 Example

 char *password = NULL;

 static int
 myplugin_config (const char *key, const char *value)
 {
   ..
   if (strcmp (key, "password") == 0) {
     free (password);
     if (nbdkit_read_password (value, &password) == -1)
       return -1;
   }
   ..
 }

=head2 Password formats

This function recognizes several password formats.  A password may be
used directly on the command line, eg:

 nbdkit myplugin password=mostsecret

But more securely this function can also read a password
interactively:

 nbdkit myplugin password=-

or from a file:

 nbdkit myplugin password=+/tmp/secret

or from a file descriptor inherited by nbdkit:

 nbdkit myplugin password=-99

=head2 Notes on reading passwords

If the password begins with a C<-> or C<+> character then it must be
passed in a file.

C<password=-FD> cannot be used with stdin, stdout or stderr
(ie. C<-0>, C<-1> or C<-2>).  The reason is that after reading the
password the file descriptor is closed, which causes bad stuff to
happen.

=head2 password=- (read password interactively)

In nbdkit E<le> 1.46, C<password=-> read the password from stdin and
did not work with the nbdkit I<-s> option.

=over 4

=item *

In nbdkit E<ge> 1.48, except on Windows, C<password=-> opens
F</dev/tty>.  This works with the I<-s> option or if stdin is
redirected.

=item *

In nbdkit E<ge> 1.48 on Windows, C<password=-> still reads from the
standard input handle and so behaves the same as in earlier versions,
including being incompatible with the I<-s> option.

=back

=head1 RETURN VALUE

The function returns 0 on success.

If there is an error it calls L<nbdkit_error(3)> and returns C<-1>.

=head1 LANGUAGE BINDINGS

In L<nbdkit-ocaml-plugin(3)>:

 NBDKit.read_password : string -> string

In L<nbdkit-python-plugin(3)>:

 import nbdkit
 password = nbdkit.read_password(value)

=head1 HISTORY

C<nbdkit_read_password> was added in nbdkit 1.12.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit_stdio_safe(3)>,
L<nbdkit-plugin(3)>,
L<nbdkit-filter(3)>,
L<nbdkit-luks-filter(1)>,
L<readpassphrase(3)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
