From 3419d7d1408007d4fdf28758f6ecc15938aca9fc Mon Sep 17 00:00:00 2001
From: "Panagiotis \"Ivory\" Vasilopoulos" <git@n0toose.net>
Date: Sun, 17 Nov 2024 15:19:57 +0100
Subject: [PATCH] docs: improve security documentation

Partially addresses #303.
---
 src/lib.rs | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 7fe44b180..af46674e0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -26,10 +26,12 @@
 //! In the presence of pathological temporary file cleaner, relying on file paths is unsafe because
 //! a temporary file cleaner could delete the temporary file which an attacker could then replace.
 //!
-//! `tempfile` doesn't rely on file paths so this isn't an issue. However, `NamedTempFile` does
-//! rely on file paths for _some_ operations. See the security documentation on
-//! the `NamedTempFile` type for more information.
-//! 
+//! `tempfile` doesn't rely on file paths, so this should not be an issue. However,
+//! `NamedTempFile` does rely on file paths for _some_ operations. On Unix-like
+//! operating systems, it may also be possible to mitigate this issue by overriding the
+//! default permissions that the crate sets. For more information, consult the Security
+//! documentation of the [`NamedTempFile`] type and [`Builder::permissions`].
+//!
 //! The OWASP Foundation provides a resource on vulnerabilities concerning insecure
 //! temporary files: https://owasp.org/www-community/vulnerabilities/Insecure_Temporary_File
 //!
@@ -172,7 +174,7 @@ pub use crate::file::{
 };
 pub use crate::spooled::{spooled_tempfile, SpooledData, SpooledTempFile};
 
-/// Create a new temporary file or directory with custom parameters.
+/// Create a new temporary file or directory with custom parameters and permissions.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct Builder<'a, 'b> {
     random_len: usize,
@@ -349,7 +351,7 @@ impl<'a, 'b> Builder<'a, 'b> {
     ///
     /// # Security
     ///
-    /// By default, the permissions of tempfiles on unix are set for it to be
+    /// By default, the permissions of tempfiles on Unix are set for it to be
     /// readable and writable by the owner only, yielding the greatest amount
     /// of security.
     /// As this method allows to widen the permissions, security would be
@@ -369,7 +371,7 @@ impl<'a, 'b> Builder<'a, 'b> {
     /// ## Windows and others
     ///
     /// This setting is unsupported and trying to set a file or directory read-only
-    /// will cause an error to be returned..
+    /// will return an error.
     ///
     /// # Examples
     ///