=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=-> can only be used when stdin is a terminal.

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.

=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)>.

=head1 AUTHORS

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
