Add an internal-representation no-op function.

[u/mdw/catacomb] / pixie.h

/* -*-c-*-
 *
 * $Id: pixie.h,v 1.2 2000/06/17 11:49:49 mdw Exp $
 *
 * Passphrase pixie definitions (Unix-specific)
 *
 * (c) 1999 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * Catacomb 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 Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: pixie.h,v $
 * Revision 1.2  2000/06/17 11:49:49  mdw
 * New pixie protocol allowing application to request passphrases and send
 * them to the pixie.
 *
 * Revision 1.1  1999/12/22 15:58:41  mdw
 * Passphrase pixie support.
 *
 */

#ifndef CATACOMB_PIXIE_H
#define CATACOMB_PIXIE_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stddef.h>

#include <sys/socket.h>
#include <sys/un.h>

#ifndef CATACOMB_PASSPHRASE_H
#  include "passphrase.h"
#endif

/*----- Protocol definition -----------------------------------------------*
 *
 * The protocol is simple and text-based.  The client connects to the
 * server's socket and sends `request lines', each of which elicits one or
 * more `response lines' from the server.  Request and response lines contain
 * whitespace-separated fields, and are terminated by a single linefeed.  The
 * final field on a line may contain whitespace.  The first field describes
 * the type of the line.  The type field is not case-sensitive, although
 * writing them in uppercase is conventional.
 *
 * The requests are:
 *
 * HELP
 *      Provide (very) brief help with the pixie protocol.
 *
 * LIST
 *      Return a list of passphrases currently stored, together with expiry
 *      information.
 *
 * PASS tag [expire]
 *      Request the passphrase named `tag' from the pixie.
 *
 * VERIFY tag [expire]
 *      Request a new passphrase, which therefore requires verification.
 *
 * SET tag [expire] -- phrase
 *      Set the value of passphrase `tag'.  This will usually be a follow-up
 *      to a MISSING response.
 *
 * FLUSH [tag]
 *      Flush the passphrase named `tag', or all passphrases, from memory.
 *
 * QUIT
 *      Requests that the pixie close down.
 *
 * Response lines are as follows:
 *
 * OK [phrase]
 *      Request completed successfully.  If a passphrase was requested, it is
 *      returned by the pixie.  This is the final response to a request.
 *
 * MISSING
 *      The passphrase requested is not known, and no requester mechanism is
 *      present.  The client should request the passphrase itself and pass it
 *      back to the pixie.  This is the final response to a request.
 *
 * FAIL error
 *      Reports an error.  The message given is intended to be
 *      human-readable.  This is the final response to a request.
 *
 * INFO message
 *      Reports a human-readable informational message.  Further responses
 *      follow.  
 *
 * ITEM tag expires
 *      Reports a passphrase in response to a LIST request.  One ITEM
 *      response is given for each passphrase currently in memory.  An OK or
 *      FAIL response follows the last ITEM.
 *
 * Expiry times in requests may be given in any format acceptable to
 * `getdate'.  Expiry times in responses are returned in ISO format
 * (YYYY-MM-DD HH:MM:SS ZZZ) and are expressed relative to local time.
 */

/*----- Functions provided ------------------------------------------------*/

/* --- @pixie_open@ --- *
 *
 * Arguments:   @const char *sock@ = path to pixie socket
 *
 * Returns:     Less than zero if it failed, or file descriptor.
 *
 * Use:         Opens a connection to a passphrase pixie.
 */

extern int pixie_open(const char */*sock*/);

/* --- @pixie_read@ --- *
 *
 * Arguments:   @int fd@ = connection to passphrase pixie
 *              @const char *tag@ = pointer to tag string
 *              @unsigned mode@ = reading mode
 *              @char *buf@ = pointer to destination buffer
 *              @size_t sz@ = size of the buffer
 *
 * Returns:     Zero if all went well, @-1@ if the read fails, @+1@ to
 *              request the passphrase from the user.
 *
 * Use:         Reads a passphrase from the pixie.
 */

extern int pixie_read(int /*fd*/, const char */*tag*/, unsigned /*mode*/,
                      char */*buf*/, size_t /*sz*/);

/* --- @pixie_set@ --- *
 *
 * Arguments:   @int fd@ = pixie file descriptor
 *              @const char *tag@ = pointer to tag string
 *              @const char *phrase@ = pointer to passphrase string
 *
 * Returns:     ---
 *
 * Use:         Sends a passphrase to the passphrase pixie.
 */

extern void pixie_set(int /*fd*/, const char */*tag*/,
                      const char */*phrase*/);

/* --- @pixie_cancel@ --- *
 *
 * Arguments:   @int fd@ = pixie file descriptor
 *              @const char *tag@ = pointer to tag string
 *
 * Returns:     ---
 *
 * Use:         Cancels a passphrase if it turns out to be bogus.
 */

extern void pixie_cancel(int /*fd*/, const char */*tag*/);

/* --- @pixie_address@ --- *
 *
 * Arguments:   @const char *sock@ = pointer to socket name
 *              @size_t *psz@ = where to write the address size
 *
 * Returns:     Pointer to filled-in Unix-domain socket address.
 *
 * Use:         Returns a Unix-domain socket address to use to find the
 *              passphrase pixie.
 */

extern struct sockaddr_un *pixie_address(const char */*sock*/,
                                         size_t */*psz*/);

/* --- @pixie_fdline@ --- *
 *
 * Arguments:   @int fd@ = file descriptor to read from
 *              @char *buf@ = pointer to buffer
 *              @size_t sz@ = size of buffer
 *
 * Returns:     ---
 *
 * Use:         Reads a line from a file descriptor.  The read is done one
 *              character at a time.  If the entire line won't fit, the end
 *              is truncated.  The line is null terminated.
 */

extern void pixie_fdline(int /*fd*/, char */*buf*/, size_t /*sz*/);

/* --- @pixie_getpass@ --- *
 *
 * Arguments:   @const char *prompt@ = pointer to prompt string
 *              @char *buf@ = pointer to buffer
 *              @size_t sz@ = size of buffer
 *
 * Returns:     Zero if it worked OK, nonzero otherwise.
 *
 * Use:         Reads a passphrase from the terminal or some other requested
 *              source.
 */

extern int pixie_getpass(const char */*prompt*/,
                         char */*buf*/, size_t /*sz*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif