=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 void
 myplugin_unload (void)
 {
   /* Free password when the plugin is unloaded. */
   free (password);
 }

 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 directly on the command line

A password may be used directly on the command line, eg:

 nbdkit myplugin password=mostsecret

This is insecure since any user on the same machine can see the
command line.

C<-> and C<+> at the beginning of the value have a special meaning
(see below).  Therefore if the plaintext password begins with a C<->
or C<+> character then it must be passed in a file.

=head2 Password from a file

Use C<+FILENAME> to read from a file:

 nbdkit myplugin password=+/tmp/secret

=head2 Password from a file descriptor

Use C<-FD> to read the password from a file descriptor inherited by
nbdkit (fd=99 in this example):

 nbdkit myplugin password=-99

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

=head2 Read password interactively

To read a password interactively:

 nbdkit myplugin password=-

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

In nbdkit E<ge> 1.48:

=over 4

=item *

Except on Windows, C<password=-> opens F</dev/tty>.  This works with
the I<-s> option or if stdin is redirected.

=item *

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
