pageant.h

   1 /*
   2  * pageant.h: header for pageant.c.
   3  */
   4
   5 #include <stdarg.h>
   6
   7 /*
   8  * FIXME: it would be nice not to have this arbitrary limit. It's
   9  * currently needed because the Windows Pageant IPC system needs an
  10  * upper bound known to the client, but it's also reused as a basic
  11  * sanity check on incoming messages' length fields.
  12  */
  13 #define AGENT_MAX_MSGLEN  8192
  14
  15 typedef void (*pageant_logfn_t)(void *logctx, const char *fmt, va_list ap);
  16
  17 /*
  18  * Initial setup.
  19  */
  20 void pageant_init(void);
  21
  22 /*
  23  * The main agent function that answers messages.
  24  *
  25  * Expects a message/length pair as input, minus its initial length
  26  * field but still with its type code on the front.
  27  *
  28  * Returns a fully formatted message as output, *with* its initial
  29  * length field, and sets *outlen to the full size of that message.
  30  */
  31 void *pageant_handle_msg(const void *msg, int msglen, int *outlen,
  32                          void *logctx, pageant_logfn_t logfn);
  33
  34 /*
  35  * Construct a failure response. Useful for agent front ends which
  36  * suffer a problem before they even get to pageant_handle_msg.
  37  */
  38 void *pageant_failure_msg(int *outlen);
  39
  40 /*
  41  * Construct a list of public keys, just as the two LIST_IDENTITIES
  42  * requests would have returned them.
  43  */
  44 void *pageant_make_keylist1(int *length);
  45 void *pageant_make_keylist2(int *length);
  46
  47 /*
  48  * Accessor functions for Pageant's internal key lists. Fetch the nth
  49  * key; count the keys; attempt to add a key (returning true on
  50  * success, in which case the ownership of the key structure has been
  51  * taken over by pageant.c); attempt to delete a key (returning true
  52  * on success, in which case the ownership of the key structure is
  53  * passed back to the client).
  54  */
  55 struct RSAKey *pageant_nth_ssh1_key(int i);
  56 struct ssh2_userkey *pageant_nth_ssh2_key(int i);
  57 int pageant_count_ssh1_keys(void);
  58 int pageant_count_ssh2_keys(void);
  59 int pageant_add_ssh1_key(struct RSAKey *rkey);
  60 int pageant_add_ssh2_key(struct ssh2_userkey *skey);
  61 int pageant_delete_ssh1_key(struct RSAKey *rkey);
  62 int pageant_delete_ssh2_key(struct ssh2_userkey *skey);
  63
  64 /*
  65  * This callback must be provided by the Pageant front end code.
  66  * pageant_handle_msg calls it to indicate that the message it's just
  67  * handled has changed the list of keys held by the agent. Front ends
  68  * which expose that key list through dedicated UI may need to refresh
  69  * that UI's state in this function; other front ends can leave it
  70  * empty.
  71  */
  72 void keylist_update(void);
  73
  74 /*
  75  * Functions to establish a listening socket speaking the SSH agent
  76  * protocol. Call pageant_listener_new() to set up a state; then
  77  * create a socket using the returned pointer as a Plug; then call
  78  * pageant_listener_got_socket() to give the listening state its own
  79  * socket pointer. Also, provide a logging function later if you want
  80  * to.
  81  */
  82 struct pageant_listen_state;
  83 struct pageant_listen_state *pageant_listener_new(void);
  84 void pageant_listener_got_socket(struct pageant_listen_state *pl, Socket sock);
  85 void pageant_listener_set_logfn(struct pageant_listen_state *pl,
  86                                 void *logctx, pageant_logfn_t logfn);
  87 void pageant_listener_free(struct pageant_listen_state *pl);
  88
  89 /*
  90  * Functions to perform specific key actions, either as a client of an
  91  * ssh-agent running elsewhere, or directly on the agent state in this
  92  * process. (On at least one platform we want to do this in an
  93  * agnostic way between the two situations.)
  94  *
  95  * pageant_get_keylist{1,2} work just like pageant_make_keylist{1,2}
  96  * above, except that they can also cope if they have to contact an
  97  * external agent.
  98  *
  99  * pageant_add_keyfile() is used to load a private key from a file and
 100  * add it to the agent. Initially, you should call it with passphrase
 101  * NULL, and it will check if the key is already in the agent, and
 102  * whether a passphrase is required. Return values are given in the
 103  * enum below. On return, *retstr will either be NULL, or a
 104  * dynamically allocated string containing a key comment or an error
 105  * message.
 106  *
 107  * pageant_add_keyfile() also remembers passphrases with which it's
 108  * successfully decrypted keys (because if you try to add multiple
 109  * keys in one go, you might very well have used the same passphrase
 110  * for keys that have the same trust properties). Call
 111  * pageant_forget_passphrases() to get rid of them all.
 112  */
 113 void *pageant_get_keylist1(int *length);
 114 void *pageant_get_keylist2(int *length);
 115 enum {
 116     PAGEANT_ACTION_OK,       /* success; no further action needed */
 117     PAGEANT_ACTION_FAILURE,  /* failure; *retstr is error message */
 118     PAGEANT_ACTION_NEED_PP   /* need passphrase: *retstr is key comment */
 119 };
 120 int pageant_add_keyfile(Filename *filename, const char *passphrase,
 121                         char **retstr);
 122 void pageant_forget_passphrases(void);
 123
 124 struct pageant_pubkey {
 125     /* Everything needed to identify a public key found by
 126      * pageant_enum_keys and pass it back to the agent or other code
 127      * later */
 128     void *blob;
 129     int bloblen;
 130     char *comment;
 131     int ssh_version;
 132 };
 133 struct pageant_pubkey *pageant_pubkey_copy(struct pageant_pubkey *key);
 134 void pageant_pubkey_free(struct pageant_pubkey *key);
 135
 136 typedef void (*pageant_key_enum_fn_t)(void *ctx,
 137                                       const char *fingerprint,
 138                                       const char *comment,
 139                                       struct pageant_pubkey *key);
 140 int pageant_enum_keys(pageant_key_enum_fn_t callback, void *callback_ctx,
 141                       char **retstr);
 142 int pageant_delete_key(struct pageant_pubkey *key, char **retstr);
 143 int pageant_delete_all_keys(char **retstr);