1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
/*!
# privdrop
A secure and comprehensive crate for privilege dropping in Unix-based systems.
## Overview
This crate provides a robust mechanism for privileged processes to safely drop
their elevated permissions, a critical operation for services that need to start
with root privileges but should run with minimal permissions afterward. It supports:
- Changing the root directory (chroot) to restrict filesystem access
- Switching to a non-root user to relinquish privileges
- Setting primary group memberships for proper resource access
- Managing supplementary groups for fine-grained permission control
All operations are performed atomically during the `apply()` call, ensuring
security during the transition.
## Features
- **Atomic Operations**: All privilege-dropping actions occur in one atomic step
- **Builder Pattern**: Simple and flexible configuration interface
- **Error Handling**: Comprehensive error reporting with specific error types
- **Safety Focused**: Designed with security best practices
## Basic Example
```no_run
use privdrop::PrivDrop;
fn main() {
PrivDrop::default()
.chroot("/var/empty")
.user("nobody")
.apply()
.unwrap_or_else(|e| panic!("Failed to drop privileges: {}", e));
// Continue running with dropped privileges...
}
```
## Advanced Example
```no_run
use privdrop::PrivDrop;
fn main() {
PrivDrop::default()
.chroot("/var/empty") // Change root directory
.user("nobody") // Switch to non-root user
.group("nogroup") // Set primary group
.group_list(&["www-data", "adm"]) // Set supplementary groups
.include_default_supplementary_groups() // Include default groups
.fallback_to_ids_if_names_are_numeric() // Allow numeric IDs
.apply()
.unwrap_or_else(|e| panic!("Failed to drop privileges: {}", e));
// Continue running with dropped privileges...
}
```
## Safety Considerations
This crate performs privilege operations that require root access initially.
All operations are executed in a specific order to ensure security:
1. Preloading necessary resources before privilege drop to prevent deadlocks
2. Looking up user and group IDs
3. Performing chroot operations if configured
4. Dropping privileges by changing user and group IDs
The system ensures that once privileges are dropped, they cannot be regained.
*/
pub use *;
pub use *;
/// Reexported dependencies for use in consuming crates.
///
/// This module provides access to the underlying dependencies used by this crate,
/// allowing consumers to utilize the same versions without specifying them separately.
///
/// ## Available Reexports
///
/// - `libc`: Low-level bindings to the C standard library
/// - `nix`: Rust friendly bindings to *nix APIs with user and filesystem features