+++ /dev/null
-/* -*-c-*-
- *
- * $Id: pixie.h,v 1.3 2004/04/08 01:36:15 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.
- */
-
-#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
projects / u / mdw / catacomb / blobdiff