#ifndef _AGENT_CLIENT_H_57f85a71_
#define _AGENT_CLIENT_H_57f85a71_

/* This file is in the public domain. */

#include "algs.h"
#include "agent.h"
#include "agent-util.h"

/*
 * External interface to the agent client code.
 */

/*
 * agent_add() implements the -add option, connecting to the agent and
 *  adding keys to it.  It uses the constraints in constraints_add.
 */
extern void agent_add(void);

/*
 * agent_list() implements the -list option, connecting to the agent
 *  and listing the keys in it.  It is affected by -long via the
 *  list-long config-file variable.
 */
extern void agent_list(void);

/*
 * agent_delete() implements the -delete option, connecting to the
 *  agent and deleting keys from it.
 */
extern void agent_delete(void);

/*
 * agent_delete_all() implements the -delete-all option, connecting to
 *  the agent and deleting all the keys from it.
 */
extern void agent_delete_all(void);

/*
 * agent_list_keys(fn) lists the keys from the agent, calling fn for
 *  each one.  This is used by the -list code, but also by other code
 *  that cares what keys are in the agent, notably the public-key
 *  authentication code in the client.
 *
 * The callback is (*fn)(alg,pkdata,pklen,comment), where alg is the
 *  algorithm for the key (keys using unrecognized algorithms pass a
 *  nil pointer for this argument), pkdata/pklen are the key's public
 *  data and length, and comment is the comment string.  The data
 *  pointed to by pkdata and comment is not guaranteed to remain valid
 *  past the point at which the callback returns; it must be copied if
 *  it is to be saved.
 *
 * Public blobs marked as being for an algorithm we support, but which
 *  are rejected by that algorithm's checkpub method, are treated as if
 *  we didn't support their algorithms.
 */
extern void agent_list_keys(void (*)(HKALG *, void *, int, char *));

/*
 * agent_sign(keyd,keyl,hashd,hashl,sigdp,siglp) has the agent perform
 *  a signing operation.  keyd and keyl are the key blob data and
 *  length, the hashd and hashl the data hash data and length, and
 *  sigdp and siglp are pointers to where to store the signature data
 *  and length (the signature data will be mallocked and the caller is
 *  responsible for freeing it as appropriate).  On success, the return
 *  value is nonzero, with a signature returned.  If we get
 *  SSH_AGENT_FAILURE back, the return value is zero, with no signature
 *  returned (the arguments may be stored through, but if so, the
 *  value(s) stored is/are meaningless).  Other failures are considered
 *  catastrophic protocol failures and produce gripes on errf with
 *  exit(1).
 */
extern int agent_sign(const void *, int, const void *, int, void **, int *);

/*
 * agent_available() checks whether an agent appears to be available.
 *  This does not actually connect to the agent; it just checks whether
 *  the agent access data is present and appears valid.  Return value
 *  is an "is-available" boolean.
 */
extern int agent_available(void);

/*
 * open_agent_connection(errp,proto) opens a connection to the
 *  agent.  If the connection succeeds, a non-nil handle pointer is
 *  returned, and errp is not stored through.  If the connection fails,
 *  nil is returned, and a mallocked error message string is stored
 *  through errp (which the caller is responsible for freeing).  proto
 *  indicates which agent protocol is to be used (one of the
 *  AGENT_PROTO_* constants).
 */
extern void *open_agent_connection(char **, AGENT_PROTO);

/*
 * Return the file descriptor underlying an agent connection handle.
 *  This is suitable for passing to, eg, add_poll_fd, or read.
 */
extern int agent_client_fd(void *);

/*
 * Close down an agent client connection.  This closes the underlying
 *  file descriptor and frees the handle.
 */
extern void agent_client_close(void *);

/*
 * constraints_add is an AGENT_CONSTRAINTS describing the constraints
 *  to be used by agent_add().  (It is exported so it can be affected
 *  by the -constraints option.)
 */
extern AGENT_CONSTRAINTS constraints_add;

#endif