Added a note that PWMD_OPTION_PINENTRY should not be set when using

[libpwmd.git] / libpwmd.h

/* vim:tw=78:ts=8:sw=4:set ft=c:  */
/*
    Copyright (C) 2006-2008 Ben Kibbey <bjk@luxsci.net>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/
#ifndef LIBPWMD_H
#define LIBPWMD_H

#define LIBPWMD_VERSION 0x505

#include <gpg-error.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * A handle is a pointer to a pwm_t that is returned with pwmd_connect().
 */
struct pwm_s;
typedef struct pwm_s pwm_t;

/*
 * Used with pwmd_open_nb() and pwmd_save_nb(). Both are non-blocking
 * functions for pin retrieval with pinentry. The pwmd_open_nb_finalize() and
 * pwmd_save_nb_finalize() functions use this type after a successful read()
 * from the returned file descriptor of those functions.
 *
 * Although version 1.4 and later of pwmd has it's own support for pinentry,
 * commands that uses pinentry will block and as a result block the client. So
 * these non-blocking functions may be used to retrieve the key before sending
 * the command that requires a key. Update: Use pwmd_open|save_async()
 * instead.
 */
typedef struct {
    char filename[FILENAME_MAX];
    int fd;                             /* Closed after the finalize function. */
    gpg_error_t error;                  /* Returned from the NB function. */
} pwmd_nb_status_t;

typedef enum {
    ASYNC_INIT,
    ASYNC_PROCESS,
    ASYNC_DONE,
} pwmd_async_t;

/*
 * A custom callback password retrieval function which is set with
 * pwmd_setopt().
 */
typedef char *(*pwmd_password_fn)(pwm_t *pwm, void *data);

/*
 * A callback to be set with pwmd_setopt() that processes Assuan protocol
 * status messages. The 'line' is the status message which is prefixed with
 * the keyword.
 */
typedef int (*pwmd_status_fn)(void *data, const char *line);

/*
 * A callback function that is passed to pwmd_inquire(). 'data' is the user
 * data that was passed to pwmd_inquire(). 'keyword' is the same as the 'cmd'
 * argument to pwmd_inquire().
 *
 * 'rc' is the return code from assuan_send_data() and is initially 0 on the
 * first call to the set callback. This gives the client a chance to cleanup
 * if assuan_send_data() fails for some reason and should probably return the
 * same error code, if set, after doing so.
 *
 * 'result' should be set to the data to be sent which is of 'len' bytes. The
 * data is not modified.
 *
 * The function should return GPG_ERR_EOF when no more data needs to be sent
 * or to finish sending the set 'result' and end the INQUIRE, 0 if there is
 * more data pending or an error code which will terminate the INQUIRE.
 */
typedef gpg_error_t (*pwmd_inquire_fn)(void *data, const char *keyword,
        gpg_error_t rc, char **result, size_t *len);

typedef enum {
    /*
     * PWMD_OPTION_PASSWORD_FUNC
     *
     * Function to retrieve a password. This function should return an
     * string which is the password or NULL on error.
     */
    PWMD_OPTION_PASSWORD_FUNC,

    /*
     * PWMD_OPTION_PASSWORD_DATA
     *
     * Data passed to the password function.
     */
    PWMD_OPTION_PASSWORD_DATA,

    /*
     * PWMD_OPTION_PINENTRY
     *
     * The following argument should be of type int and set to 1 to enable the
     * use of pinentry(1) to retrieve passwords. Setting to 0 will disable
     * using pinentry and the password must be set with PWMD_OPTION_PASSWORD
     * or gotten from PWMD_OPTION_PASSWORD_FUNC. The pwmd command "OPTION
     * PINENTRY=0" is sent when this option is set (1) to prevent pinentry
     * from being called on the pwmd server and enabled when unset.
     */
    PWMD_OPTION_PINENTRY,

    /*
     * PWMD_OPTION_PINENTRY_TRIES
     *
     * The number of password tries before giving up. If the pinentry "Cancel"
     * button is selected, pinentry will abort. Must be > 0. The default is 3.
     */
    PWMD_OPTION_PINENTRY_TRIES,

    /*
     * PWMD_OPTION_PINENTRY_PATH
     *
     * The full pathname to the pinentry program. If not specified,
     * /usr/bin/pinentry will be used.
     */
    PWMD_OPTION_PINENTRY_PATH,

    /*
     * PWMD_OPTION_PINENTRY_TTY
     *
     * pinentry --ttyname.
     */
    PWMD_OPTION_PINENTRY_TTY,

    /*
     * PWMD_OPTION_PINENTRY_DISPLAY
     *
     * pinentry --display
     */
    PWMD_OPTION_PINENTRY_DISPLAY,

    /*
     * PWMD_OPTION_PINENTRY_TERM
     *
     * pinentry --ttytype
     */
    PWMD_OPTION_PINENTRY_TERM,

    /*
     * PWMD_OPTION_PASSWORD
     *
     * The following argument should be of type char* which specifies the
     * password to use when the PWMD_OPEN or PWMD_SAVE commands are issued and
     * PWMD_OPTION_PINENTRY is 0. The password will be kept in memory until
     * pwmd_close() is called so setting this option isn't needed each time
     * pwmd_open() or pwmd_save() is called regardless of pwmd cache settings.
     */
    PWMD_OPTION_PASSWORD,

    /*
     * PWMD_OPTION_PINENTRY_TITLE
     * PWMD_OPTION_PINENTRY_PROMPT
     * PWMD_OPTION_PINENTRY_DESC
     *
     * The following argument is of type char* which specifies either the
     * title, prompt or description in the pinentry program when
     * PWMD_OPTION_PINENTRY is set. Note that any CR, LF or % must be percent
     * escape (the hexidecimal value of the character).
     */
     PWMD_OPTION_PINENTRY_TITLE,
     PWMD_OPTION_PINENTRY_PROMPT,
     PWMD_OPTION_PINENTRY_DESC,

     /*
      * PWMD_OPTION_STATUS_FUNC
      *
      * A function to be called when a status line is sent from pwmd. This
      * function should return 0 on success or a gpg-error error code. This
      * function won't be used when getting a password with pinentry.
      */
     PWMD_OPTION_STATUS_FUNC,
     
     /*
      * PWMD_OPTION_STATUS_DATA
      *
      * Data passed to the status function.
      */
     PWMD_OPTION_STATUS_DATA,
} pwmd_option_t;

/*
 * Initialize the library. This sets up various things and must be called
 * before the other functions.
 */
gpg_error_t pwmd_init(void);

/*
 * Connects to the socket specified by 'socket_path'. If socket_path is NULL,
 * then a default of ~/.pwmd/socket will be used. Returns a new handle for use
 * with the other functions or NULL if there was an error in which case
 * 'error' is set to an error code which may be described by pwmd_strerror().
 */
pwm_t *pwmd_connect(const char *socket_path, gpg_error_t *error) __attribute__ ((warn_unused_result));

/*
 * Sets 'ctx' to the assuan context associated with the handle 'pwm' and 'fd'
 * to the socket file descriptor. Returns 0 on success or an error code.
 */
struct assuan_context_s;
typedef struct assuan_context_s *assuan_context_t;
gpg_error_t pwmd_assuan_ctx(pwm_t *pwm, assuan_context_t *ctx, int *fd) __attribute__ ((warn_unused_result));

/*
 * A wrapper around assuan_pending_line() and assuan_read_line(). Returns 0 if
 * there was a pending line and sets 'line' to the content and 'len' to the
 * length. Returns GPG_ERR_NO_DATA if there was no pending line or any error
 * from assuan_read_line().
 */
gpg_error_t pwmd_pending_line(pwm_t *pwm, char **line, size_t *len) __attribute__ ((warn_unused_result));

/*
 * Sets a libpwmd option 'opt'. The next argument should be of the data type
 * required for the option. Returns 0 on success or an error code.
 */
gpg_error_t pwmd_setopt(pwm_t *pwm, pwmd_option_t opt, ...) __attribute__ ((warn_unused_result));

/*
 * Opens a file 'filename' (the OPEN command). The filename is not a full path
 * but only filename which is looked for in the pwmd configured data
 * directory. How the password is gotten depends on options set with
 * pwmd_setopt() and whether the file is cached on the server. Returns 0 on
 * success or an error code.
 */
gpg_error_t pwmd_open(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));

/*
 * This is like pwmd_open() but won't block the process when pinentry is used
 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 * on the server or if the file doesn't exist on the file system (a new file).
 * Otherwise it returns a file descriptor that select() can use. When ready
 * for a read, read() should read a pwmd_nb_status_t. If there is a system
 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 * error code that pwmd_strerror() can describe. See pwmd_open_nb_finalize().
 *
 * The 'timeout' parameter specifies the number of seconds until the pinentry
 * terminates. Setting to 0 (the default) will disable timeouts. Note that the
 * child process will reset the SIGALRM handler (if any) to it's own handler
 * and that the actual OPEN command isn't calculated as part of the elapsed
 * time.
 *
 * Be sure to set PWMD_OPTION_PINENTRY.
 */
int pwmd_open_nb(pwm_t *pwm, gpg_error_t *error, const char *filename,
        int timeout) __attribute__ ((warn_unused_result,deprecated));

/*
 * When a file descriptor has been returned from pwmd_open_nb() and after a
 * successful read(), you should call pwmd_open_nb_finalize() to update the
 * 'pwm' handle. If there was a pinentry or protocol error
 * pwmd_open_nb_finalize() will return an error code or 0 on success. Note
 * that pwmd_open_nb_finalize() will close the file descriptor returned from
 * pwmd_open_nb().
 */
gpg_error_t pwmd_open_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result,deprecated));

/*
 * This is another way to do a non-blocking open. The difference from
 * pwmd_open_nb() is that libpwmd wont fork() to get the pin. Instead, it will
 * let pwmd use it's pinentry retrieval method. When successful this function
 * returns 0 and pwmd_process() should be called until the command completes.
 */
gpg_error_t pwmd_open_async(pwm_t *pwm, const char *filename) __attribute__ ((warn_unused_result));
;

/*
 * After pwmd_open_async() or pwmd_save_async() returns 0, this function
 * should be called until ASYNC_DONE is returned. It will return ASYNC_PROCESS
 * when the command is still running. After ASYNC_DONE is returned, any error
 * that may have occurred is stored in 'rc'. If an error occurred or not,
 * pwmd_finalize() must be called to reset a control variable so the next
 * async command may be performed.
 */
pwmd_async_t pwmd_process(pwm_t *pwm, gpg_error_t *rc) __attribute__ ((warn_unused_result));
;

/*
 * Resets the control variable for the associated handle. Call this function
 * after ASYNC_DONE is returned from pwmd_process().
 */
gpg_error_t pwmd_finalize(pwm_t *pwm) __attribute__ ((warn_unused_result));
;

/*
 * Sends the SAVE command to the associated handle 'pwm'. If a password is
 * required, how it is gotten depends on options set with pwmd_setopt().
 * Returns 0 on success or an error code.
 */
gpg_error_t pwmd_save(pwm_t *pwm) __attribute__ ((warn_unused_result));

/*
 * This is like pwmd_save() but won't block the process when pinentry is used
 * to retrieve the password. It returns -2 when the file is cached (ISCACHED)
 * on the server or if the file doesn't exist on the file system (a new file).
 * Otherwise it returns a file descriptor that select() can use. When ready
 * for a read, read() should read a pwmd_nb_status_t. If there is a system
 * error (pipe() or fork()), then -1 is returned and 'error' is set to an
 * error code that pwmd_strerror() can describe. See pwmd_save_nb_finalize().
 *
 * Note that there is no timeout setting. If a password is required, pinentry
 * won't timeout.
 *
 * Be sure to set PWMD_OPTION_PINENTRY.
 */
int pwmd_save_nb(pwm_t *pwm, gpg_error_t *error) __attribute__ ((warn_unused_result,deprecated));

/*
 * When a file descriptor has been returned from pwmd_save_nb() and after a
 * successful read(), you should call pwmd_save_nb_finalize() to update the
 * 'pwm' handle. If there was a pinentry or protocol error
 * pwmd_save_nb_finalize() will return an error code or 0 on success. Note
 * that pwmd_save_nb_finalize() will close the file descriptor returned from
 * pwmd_save_nb().
 */
gpg_error_t pwmd_save_nb_finalize(pwm_t *pwm, pwmd_nb_status_t *status) __attribute__ ((warn_unused_result,deprecated));

/*
 * Like pwmd_save_nb() but uses pwmd to launch pinentry rather than having
 * libpwmd fork(). This function returns 0 on success and pwmd_process()
 * should be called until the command completes.
 */
gpg_error_t pwmd_save_async(pwm_t *pwm) __attribute__ ((warn_unused_result));
;

/*
 * Terminates a pinentry process. If your not using pwmd_open_nb() and want to
 * timeout the associated pinentry process, then call this function after your
 * timer has expired. Returns 0 on success or an error code.
 */
gpg_error_t pwmd_terminate_pinentry(pwm_t *pwm) __attribute__ ((warn_unused_result));

/*
 * Sends a protocol command 'cmd' to the daemon using handle 'pwm'. If the
 * command fails an error code is returned which may be described by passing
 * the error to pwmd_strerror(). If successful the function returns 0 and the
 * 'result' is the character data of the command or NULL if there was none.
 *
 * For commands which use an INQUIRE (i.e., STORE), use pwmd_inquire() and not
 * pwmd_command().
 *
 * A note about the BYE command: Client's should not send this command
 * directly with pwmd_command(). They should use pwmd_close() instead because
 * libassuan will close the file descriptors with the associated context. This
 * is fine except when pwmd_close() is called. pwmd_close() calls
 * assuan_disconnect() which then sends the BYE command to the closed file
 * descriptor resulting in a segfault.
 */
gpg_error_t pwmd_command(pwm_t *pwm, char **result, const char *cmd, ...) __attribute__ ((warn_unused_result));
 
/*
 * Commands which use an INQUIRE to send data (i.e., STORE) should use this
 * function and not pwmd_command(). 'cmd' is the command to send and is also
 * the 'keyword' argument to the callback function 'func'. 'data' is user data
 * passed to the callback function. Returnes 0 on success or and error code
 * which may have been returned from the callback function.
 */
gpg_error_t pwmd_inquire(pwm_t *pwm, const char *cmd, pwmd_inquire_fn func,
        void *data) __attribute__ ((warn_unused_result));

/*
 * Free the memory used by the result of pwmd_command() if any. It is
 * important to use this function because libpwmd keeps track of all memory
 * de/allocations.
 */
void pwmd_free_result(void *);

/*
 * Closes the connection to the socket and frees the resources of the handle.
 * Returns no value.
 */
void pwmd_close(pwm_t *pwm);

/*
 * Protocol error codes.
 */
#define EPWMD_BADKEY            GPG_ERR_INV_PASSPHRASE
#define EPWMD_COMMAND_SYNTAX    GPG_ERR_SYNTAX
#define EPWMD_ELEMENT_NOT_FOUND GPG_ERR_ELEMENT_NOT_FOUND
#define EPWMD_ACCOUNT_EXISTS    GPG_ERR_AMBIGUOUS_NAME
#define EPWMD_CACHE_NOT_FOUND   GPG_ERR_NOT_FOUND
#define EPWMD_ATTR_SYNTAX       GPG_ERR_SYNTAX
#define EPWMD_ATTR_NOT_FOUND    GPG_ERR_NOT_FOUND
#define EPWMD_INVALID_FILENAME  GPG_ERR_INV_VALUE
#define EPWMD_EMPTY_ELEMENT     GPG_ERR_NO_VALUE
#define EPWMD_INVALID_ELEMENT   GPG_ERR_INV_VALUE
#define EPWMD_ERROR             GPG_ERR_USER_1
#define EPWMD_MAX_SLOTS         GPG_ERR_USER_2
#define EPWMD_LOOP              GPG_ERR_USER_3
#define EPWMD_NO_FILE           GPG_ERR_USER_4
#define EPWMD_LIBXML_ERROR      GPG_ERR_USER_5
#define EPWMD_FILE_MODIFIED     GPG_ERR_USER_6
#define EPWMD_MAX               GPG_ERR_USER_7

/*
 * Return a string describing a pwmd protocol error code.
 */
const char *pwmd_strerror(gpg_error_t error);

#ifdef __cplusplus
}
#endif

#endif