From 9b50d2e52e6c85bc3ab991cd8a4b870aff397bda Mon Sep 17 00:00:00 2001
From: Andrew Bartlett <abartlet@samba.org>
Date: Tue, 10 Aug 2021 09:14:08 +1200
Subject: docs: Document all the other ways to send a password to smbclient et
 al

This was previously hidden knowlege not easily available to
administrators and end users.

BUG: https://bugzilla.samba.org/show_bug.cgi?id=14791

Signed-off-by: Andrew Bartlett <abartlet@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>
---
 docs-xml/build/DTD/samba.entities | 52 ++++++++++++++++++++++++++++++---------
 1 file changed, 41 insertions(+), 11 deletions(-)

(limited to 'docs-xml')

diff --git a/docs-xml/build/DTD/samba.entities b/docs-xml/build/DTD/samba.entities
index 80e051e7684..beff3cb1f6e 100644
--- a/docs-xml/build/DTD/samba.entities
+++ b/docs-xml/build/DTD/samba.entities
@@ -595,13 +595,16 @@
 		</para>
 
 		<para>
-			If &pct;password is not specified, the user will be
+			If &pct;PASSWORD is not specified, the user will be
 			prompted. The client will first check the
-			<envar>USER</envar> environment variable, then the
-			<envar>LOGNAME</envar> variable and if either exists,
-			the string is uppercased. If these environmental
+			<envar>USER</envar> environment variable
+			(which is also permitted to also contain the
+			password seperated by a &pct;), then the
+			<envar>LOGNAME</envar> variable (which is not
+			permitted to contain a password) and if either exists,
+			the value is used. If these environmental
 			variables are not found, the username
-			<constant>GUEST</constant> is used.
+			found in a Kerberos Credentials cache may be used.
 		</para>
 
 		<para>
@@ -616,9 +619,15 @@
 		</para>
 
 		<para>
-			Be cautious about including passwords in scripts. For
-			security it is better to let the client ask for the
-			password if needed.
+			Be cautious about including passwords in scripts
+			or passing user-supplied values onto the command line. For
+			security it is better to let the Samba client tool ask for the
+			password if needed, or obtain the password once with <command>kinit</command>.
+		</para>
+		<para>
+			While Samba will attempt to scrub the password
+			from the process title (as seen in ps), this
+			is after startup and so is subject to a race.
 		</para>
 	</listitem>
 </varlistentry>
@@ -659,10 +668,31 @@
 			Specify the password on the commandline.
 		</para>
 
+		<para> Be cautious about including passwords in
+			scripts or passing user-supplied values onto
+			the command line. For security it is better to
+			let the Samba client tool ask for the password
+			if needed, or obtain the password once with
+			<command>kinit</command>.
+		</para>
+
+		<para> If --password is not specified,
+		       the tool will check the <envar>PASSWD</envar>
+		       environment variable, followed by <envar>PASSWD_FD</envar>
+		       which is expected to contain an open
+		       file descriptor (FD) number.
+		</para>
+		<para>
+		       Finally it will check <envar>PASSWD_FILE</envar> (containing
+		       a file path to be opened). The file should only
+		       contain the password. Make certain that the
+		       permissions on the file restrict
+		       access from unwanted users!
+		</para>
 		<para>
-			Be cautious about including passwords in scripts. For
-			security it is better to let the client ask for the
-			password if needed.
+			While Samba will attempt to scrub the password
+			from the process title (as seen in ps), this
+			is after startup and so is subject to a race.
 		</para>
 	</listitem>
 </varlistentry>
-- 
cgit v1.2.1