ssh: Allow to prefer on-disk keys over active card keys.

* agent/command-ssh.c (ssh_send_available_keys): Redefine the order of
keys.
--

GnuPG-bug-id: 6212

NEWS

@@ -25,10 +25,15 @@ Noteworthy changes in version 2.4.1 (unreleased)
   * dirmngr: The LDAP modifyTimestamp is now returned by some
     keyserver commands.  [rG56d309133f]
 
+  * ssh: Allow specification of the order keys are presented to ssh.
+    See the man page entry for --enable-ssh-support.  [T5996]
+
   * gpg: Make list-options "show-sig-subpackets" work again.
     Fixes regression in 2.4.0.  [rG5a223303d7]
 
 
+  Release-info: https://dev.gnupg.org/T6454
+
 
 Noteworthy changes in version 2.4.0 (2022-12-16)
 ------------------------------------------------

agent/command-ssh.c

@@ -2648,7 +2648,8 @@ ssh_send_available_keys (ctrl_t ctrl, estream_t key_blobs, u32 *r_key_counter)
 
       /* Clamp LNR value and set the ordinal.
        * Current use of ordinals:
-       *      1..99999  - inserted cards (right now only 1)
+       *      1..999    - low value Use-for-ssh.
+       *   1000..99999  - inserted cards (right now only 1000)
        * 100000..199999 - listed in sshcontrol
        * 200000..299999 - order taken from Use-for-ssh
        */
@@ -2678,18 +2679,25 @@ ssh_send_available_keys (ctrl_t ctrl, estream_t key_blobs, u32 *r_key_counter)
            * order of card keys (which are sorted by their s/n), we
            * would need to get the use-for-ssh: value from the stub
            * file and set an appropriate ordinal.  */
-          order = 1;
+          order = 1000;
         }
       else if (is_ssh)
         err = agent_public_key_from_file (ctrl, grip, &key_public);
       else /* Examine the file if it's suitable for SSH.  */
         {
           err = agent_ssh_key_from_file (ctrl, grip, &key_public, &order);
-          if (order < 0 || err)
+          if (err)
             order = 0;
+          else if (order < 0)
+            {
+              order = -order;
+              if (order > 999)
+                order = 999;
+            }
           else if (order > 99999)
-            order = 99999;
-          order += 200000;
+            order =  299999;
+          else
+            order += 200000;
         }
       if (err)
         {

agent/keyformat.txt

@@ -124,7 +124,13 @@ gpg-agent's ssh-agent implementation.  This is thus the same as
 putting the keygrip into the 'sshcontrol' file.  Only one such item
 should exist.  If another non-zero value between 1 and 99999 is used,
 this is taken to establish the order in which the keys are returned to
-ssh; lower numbers are returned first.
+ssh; lower numbers are returned first.  If a negative value is used
+this overrides currently active (inserted) cards and thus allows to
+prefer on-disk keys over inserted cards.  A value of -1 has the
+highest priority; values are capped at -999 and have a lower priority
+but still above the positive values, inserted cards or the order in
+sshcontrol.
+
 
 *** Use-for-p11
 If given and the value is "yes" or "1" the key is allowed for use by

doc/gpg-agent.texi

@@ -675,6 +675,39 @@ and allows the use of gpg-agent with the ssh implementation
 @command{putty}.  This is similar to the regular ssh-agent support but
 makes use of Windows message queue as required by @command{putty}.
 
+
+The order in which keys are presented to ssh are:
+@table @code
+
+@item Negative Use-for-ssh values
+      If a key file has the attribute "Use-for-ssh" and its value is
+      negative, these keys are presented first to ssh.  The negative
+      values are capped at -999 with -999 beeing lower ranked than -1.
+      These values can be used to prefer on-disk keys over keys taken
+      from active cards.
+
+@item Active cards
+      Active cards (inserted into a card reader or plugged in tokens)
+      are always tried; they are ordered by their serial numbers.
+
+@item Keys listed in the sshcontrol file
+      Non-disabled keys from the sshcontrol file are presented in the
+      order they appear in this file.  Note that the sshcontrol file
+      is deprecated.
+
+@item Positive Use-for-ssh values
+      If a key file has the attribute "Use-for-ssh" and its value is
+      "yes", "true", or any positive number the key is presented in
+      the order of their values.  "yes" and "true" have a value of 1;
+      other values are capped at 99999.
+
+@end table
+
+Editing the "Use-for-ssh" values can be done with an editor or using
+@command{gpg-connect-agent} and "KEYATTR" (Remember to append a colon
+to the key; i.e. use "Use-for-ssh:").
+
+
 @anchor{option --ssh-fingerprint-digest}
 @item --ssh-fingerprint-digest
 @opindex ssh-fingerprint-digest
@@ -827,6 +860,9 @@ This file is used when support for the secure shell agent protocol has
 been enabled (@pxref{option --enable-ssh-support}). Only keys present in
 this file are used in the SSH protocol.  You should backup this file.
 
+This file is deprecated in favor of the "Use-for-ssh" attribute in the
+key files.
+
 The @command{ssh-add} tool may be used to add new entries to this file;
 you may also add them manually.  Comment lines, indicated by a leading
 hash mark, as well as empty lines are ignored.  An entry starts with
@@ -872,7 +908,6 @@ users start up with a working configuration.  For existing users the
 a small helper script is provided to create these files (@pxref{addgnupghome}).
 
 
-
 @c
 @c Agent Signals
 @c