* passwd.c (longopts): Add --reg-store-pwd option.

(opts): Add -R option.
	(usage): Add text for -R/--reg-store-pwd option.
	(main): Fix size of local user and password string arrays.
	Handle -R option.
	* utils.sgml: Add text for passwd -R/--reg-store-pwd option.

winsup/utils/utils.sgml

@@ -899,6 +899,9 @@ User operations:
                            password aging rule.
   -p, --pwd-not-required   no password required for USER.
   -P, --pwd-required       password is required for USER.
+  -R, --reg-store-pwd      enter password to store it in the registry for
+                           later usage by services to be able to switch
+                           to this user context with network credentials."
 
 System operations:
   -i, --inactive NUM       set NUM of days before inactive accounts are disabled
@@ -916,6 +919,15 @@ Other options:
 If no option is given, change USER's password.  If no user name is given,
 operate on current user.  System operations must not be mixed with user
 operations.  Don't specify a USER when triggering a system operation. 
+
+Don't specify a user or any other option together with the -R option.
+Non-Admin users can only store their password if cygserver is running and
+the CYGWIN environment variable is set to contain the word 'server'.
+Note that storing even obfuscated passwords in the registry is not overly
+secure.  Use this feature only if the machine is adequately locked down.
+Don't use this feature if you don't need network access within a remote
+session.  You can delete your stored password by using `passwd -R' and
+specifying an empty password.
 </screen>
 
 <para> <command>passwd</command> changes passwords for user accounts.
@@ -976,6 +988,31 @@ to <emphasis>LEN</emphasis> characters.  Allowed values for the minimum
 password length are 0 to 14.  In any of the above cases, a value of 0
 means `no restrictions'.</para>
 
+<para>Users can use the <command>passwd -R</command> to enter
+a password which then gets stored in a special area of the registry,
+which is also used by Windows to store passwords of accounts running
+Windows services.  When a privileged Cygwin application calls the
+<command>set{e}uid(user_id)</command> system call, Cygwin checks if a
+password for that user has been stored in this registry area.  If so, it
+uses this password to switch to this user account using that password.
+This allows to logon through, for instance, <command>ssh</command> with
+public key authentication and to get a full qualified user token with
+all credentials for network access.  However, the method has some
+drawbacks security-wise.  This is explained in more detail in the
+<xref linkend="ntsec"></xref> section.</para>
+
+<para>Please note that storing password in that registry area is a
+privileged operation which only administrative accounts are allowed to
+do.  If normal, non-admin users should be allowed to enter their
+passwords using <command>passwd -R</command>, it's required to run
+<command>cygserver</command> as a service under the LocalSystem account
+and the environment variable CYGWIN
+(see <xref linkend="using-cygwinenv"></xref>)
+must be set to contain the "server" setting before running
+<command>passwd -R</command>.  This only affects storing passwords.
+Using passwords in privileged processes does not require
+<command>cygserver</command> to run.</para>
+
 <para>Limitations: Users may not be able to change their password on
 some systems.</para>