2 * pageant.h: header for pageant.c.
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.
13 #define AGENT_MAX_MSGLEN 8192
15 typedef void (*pageant_logfn_t
)(void *logctx
, const char *fmt
, va_list ap
);
20 void pageant_init(void);
23 * The main agent function that answers messages.
25 * Expects a message/length pair as input, minus its initial length
26 * field but still with its type code on the front.
28 * Returns a fully formatted message as output, *with* its initial
29 * length field, and sets *outlen to the full size of that message.
31 void *pageant_handle_msg(const void *msg
, int msglen
, int *outlen
,
32 void *logctx
, pageant_logfn_t logfn
);
35 * Construct a failure response. Useful for agent front ends which
36 * suffer a problem before they even get to pageant_handle_msg.
38 void *pageant_failure_msg(int *outlen
);
41 * Construct a list of public keys, just as the two LIST_IDENTITIES
42 * requests would have returned them.
44 void *pageant_make_keylist1(int *length
);
45 void *pageant_make_keylist2(int *length
);
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).
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
);
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
72 void keylist_update(void);
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
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
);
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.)
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
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
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.
113 void *pageant_get_keylist1(int *length
);
114 void *pageant_get_keylist2(int *length
);
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 */
120 int pageant_add_keyfile(Filename
*filename
, const char *passphrase
,
122 void pageant_forget_passphrases(void);
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
133 struct pageant_pubkey
*pageant_pubkey_copy(struct pageant_pubkey
*key
);
134 void pageant_pubkey_free(struct pageant_pubkey
*key
);
136 typedef void (*pageant_key_enum_fn_t
)(void *ctx
,
137 const char *fingerprint
,
139 struct pageant_pubkey
*key
);
140 int pageant_enum_keys(pageant_key_enum_fn_t callback
, void *callback_ctx
,
142 int pageant_delete_key(struct pageant_pubkey
*key
, char **retstr
);
143 int pageant_delete_all_keys(char **retstr
);