Crate readpassphrase_3

This library endeavors to expose a thin wrapper around the C readpassphrase(3) function.

Three different interfaces are exposed; for most purposes, you will want to use either getpass (for simple password entry) or readpassphrase (when you need flags from readpassphrase(3) or need more control over the memory.)

A readpassphrase_owned function is also provided that takes ownership of the passed buffer and returns an owned String reusing that buffer’s memory.

Sensitive data should be zeroed as soon as possible to avoid leaving it visible in the process’s address space.

Usage

To read a passphrase from the console:

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

To control the buffer size or (on non-Windows) flags:

let pass = readpassphrase(c"pass: ", &mut buf, RppFlags::ECHO_ON).unwrap();
// do_something_with(pass);

To do so while transferring ownership:

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

Zeroizing memory

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)?;

This crate itself provides a minimal subset of zeroize that works on the types taken and returned by its other methods. If the zeroize feature is enabled, this minimal subset is replaced by 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 it as a String.

readpassphrase

Reads a passphrase using readpassphrase(3).

readpassphrase_owned

Reads a passphrase using readpassphrase(3) backed by the passed buffer’s memory.