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

The readpassphrase_owned function is a bit more niche; it may be used when you need a String output but need to pass flags or control the buffer size (vs getpass.)

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

To do so while transferring ownership:

let pass = readpassphrase_owned(c"pass: ", buf, RppFlags::empty())?;

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

“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. Contains the passed buffer.

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) by reusing the passed buffer’s memory.