Crate readpassphrase_3 

This library exposes a thin but usable wrapper around the C readpassphrase(3) function.

Usage

For the simplest of cases, where you would just like to read a password from the console into a String to use elsewhere, you can use getpass:

let _ = getpass(c"Enter your password: ").expect("failed reading password");

If you need to pass RppFlags or to control the buffer size, then you can use readpassphrase or readpassphrase_owned depending on your ownership requirements:

let mut buf = vec![0u8; 256];
let _ = readpassphrase(c"Password: ", &mut buf, RppFlags::default()).unwrap();

let _ = readpassphrase_owned(c"Pass: ", buf, RppFlags::FORCELOWER).unwrap();

Security

Sensitive data should be zeroed as soon as possible to avoid leaving it visible in the process’s address space. This crate ships with a minimal zeroize module that may be used for this purpose on the types taken and returned by these functions:

let mut pass = getpass(c"password: ").unwrap();
// do_something_with(&pass);
pass.zeroize();

let mut buf = vec![0u8; 256];
let res = readpassphrase(c"password: ", &mut buf, RppFlags::empty());
// match_something_on(res);
buf.zeroize();

let mut pass = readpassphrase_owned(c"password: ", buf, RppFlags::empty()).unwrap();
// do_something_with(&pass);
pass.zeroize();

zeroize feature

This crate works well with the zeroize crate; for example, zeroize::Zeroizing may be used to zero buffer contents regardless of a function’s control flow:

use zeroize::Zeroizing;
let mut buf = Zeroizing::new(vec![0u8; PASSWORD_LEN]);
let pass = readpassphrase(c"pass: ", &mut buf, RppFlags::REQUIRE_TTY)?;
// do_something_that_can_fail_with(pass)?;

// Or alternatively:
let pass = Zeroizing::new(getpass(c"pass: ")?);
// do_something_that_can_fail_with(&pass)?;

If this crate’s zeroize feature is enabled, then its zeroize will be replaced by the upstream zeroize::Zeroize.

“Mismatched types” errors

The prompt strings in this API are references to CStr, not str. This is because the underlying C function assumes that the prompt is a null-terminated string; were we to take &str instead of &CStr, we would need to make a copy of the prompt on every call.

Most of the time, your prompts will be string literals; you can ask Rust to give you a &CStr literal by simply prepending c to the string:

let _ = getpass(c"pass: ")?;
//              ^
//              |
//              like this

Windows Limitations

The Windows implementation of readpassphrase(3) that we are using does not yet support UTF-8 in prompts; they must be ASCII. It also does not yet support flags, and always behaves as though called with RppFlags::empty().

Modules

zeroize

A minimal in-crate implementation of zeroize::Zeroize.

Structs

OwnedError

An error from readpassphrase_owned.

RppFlags

Flags for controlling readpassphrase.

Enums

Error

Errors that can occur in readpassphrase.

Constants

PASSWORD_LEN

Size of buffer used in getpass.

Functions

explicit_bzeroDeprecated

Securely zero the memory in buf.

getpass

Reads a passphrase using readpassphrase(3), returning a String.

readpassphrase

Reads a passphrase using readpassphrase(3), returning a &str.

readpassphrase_owned

Reads a passphrase using readpassphrase(3), returning a String reusing buf’s memory.