[u/mdw/catacomb] / pixie.h

/* -*-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
Commit	Line	Data
069c185c	1	/* --c--
069c185c	2	*
b817bfc6	3	* $Id: pixie.h,v 1.3 2004/04/08 01:36:15 mdw Exp $
069c185c	4	*
	5	* Passphrase pixie definitions (Unix-specific)
	6	*
	7	* (c) 1999 Straylight/Edgeware
	8	*/
	9
45c0fd36	10	/----- Licensing notice --------------------------------------------------
069c185c	11	*
	12	* This file is part of Catacomb.
	13	*
	14	* Catacomb is free software; you can redistribute it and/or modify
	15	* it under the terms of the GNU Library General Public License as
	16	* published by the Free Software Foundation; either version 2 of the
	17	* License, or (at your option) any later version.
45c0fd36	18	*
069c185c	19	* Catacomb is distributed in the hope that it will be useful,
	20	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	21	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	22	* GNU Library General Public License for more details.
45c0fd36	23	*
069c185c	24	* You should have received a copy of the GNU Library General Public
	25	* License along with Catacomb; if not, write to the Free
	26	* Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
	27	* MA 02111-1307, USA.
	28	*/
	29
069c185c	30	#ifndef CATACOMB_PIXIE_H
	31	#define CATACOMB_PIXIE_H
	32
	33	#ifdef __cplusplus
	34	extern "C" {
	35	#endif
	36
	37	/----- Header files ------------------------------------------------------/
	38
	39	#include <stddef.h>
	40
	41	#include <sys/socket.h>
	42	#include <sys/un.h>
	43
	44	#ifndef CATACOMB_PASSPHRASE_H
	45	# include "passphrase.h"
	46	#endif
	47
	48	/----- Protocol definition -----------------------------------------------
	49	*
	50	* The protocol is simple and text-based. The client connects to the
	51	* server's socket and sends `request lines', each of which elicits one or
	52	* more `response lines' from the server. Request and response lines contain
	53	* whitespace-separated fields, and are terminated by a single linefeed. The
	54	* final field on a line may contain whitespace. The first field describes
	55	* the type of the line. The type field is not case-sensitive, although
	56	* writing them in uppercase is conventional.
	57	*
	58	* The requests are:
	59	*
	60	* HELP
	61	* Provide (very) brief help with the pixie protocol.
	62	*
	63	* LIST
	64	* Return a list of passphrases currently stored, together with expiry
	65	* information.
	66	*
	67	* PASS tag [expire]
	68	* Request the passphrase named `tag' from the pixie.
	69	*
	70	* VERIFY tag [expire]
	71	* Request a new passphrase, which therefore requires verification.
	72	*
95959d10	73	* SET tag [expire] -- phrase
	74	* Set the value of passphrase `tag'. This will usually be a follow-up
	75	* to a MISSING response.
	76	*
069c185c	77	* FLUSH [tag]
	78	* Flush the passphrase named `tag', or all passphrases, from memory.
	79	*
	80	* QUIT
	81	* Requests that the pixie close down.
	82	*
	83	* Response lines are as follows:
	84	*
	85	* OK [phrase]
	86	* Request completed successfully. If a passphrase was requested, it is
	87	* returned by the pixie. This is the final response to a request.
	88	*
95959d10	89	* MISSING
	90	* The passphrase requested is not known, and no requester mechanism is
	91	* present. The client should request the passphrase itself and pass it
	92	* back to the pixie. This is the final response to a request.
	93	*
069c185c	94	* FAIL error
	95	* Reports an error. The message given is intended to be
	96	* human-readable. This is the final response to a request.
	97	*
	98	* INFO message
	99	* Reports a human-readable informational message. Further responses
45c0fd36	100	* follow.
069c185c	101	*
	102	* ITEM tag expires
	103	* Reports a passphrase in response to a LIST request. One ITEM
	104	* response is given for each passphrase currently in memory. An OK or
	105	* FAIL response follows the last ITEM.
	106	*
	107	* Expiry times in requests may be given in any format acceptable to
	108	* `getdate'. Expiry times in responses are returned in ISO format
	109	* (YYYY-MM-DD HH:MM:SS ZZZ) and are expressed relative to local time.
	110	*/
	111
	112	/----- Functions provided ------------------------------------------------/
	113
	114	/* --- @pixie_open@ --- *
	115	*
	116	* Arguments: @const char *sock@ = path to pixie socket
	117	*
	118	* Returns: Less than zero if it failed, or file descriptor.
	119	*
	120	* Use: Opens a connection to a passphrase pixie.
	121	*/
	122
	123	extern int pixie_open(const char /sock*/);
	124
	125	/* --- @pixie_read@ --- *
	126	*
	127	* Arguments: @int fd@ = connection to passphrase pixie
	128	* @const char *tag@ = pointer to tag string
	129	* @unsigned mode@ = reading mode
	130	* @char *buf@ = pointer to destination buffer
	131	* @size_t sz@ = size of the buffer
	132	*
95959d10	133	* Returns: Zero if all went well, @-1@ if the read fails, @+1@ to
95959d10	134	* request the passphrase from the user.
069c185c	135	*
	136	* Use: Reads a passphrase from the pixie.
	137	*/
	138
	139	extern int pixie_read(int /fd/, const char /tag/, unsigned /mode*/,
	140	char /buf/, size_t /sz*/);
	141
95959d10	142	/* --- @pixie_set@ --- *
	143	*
	144	* Arguments: @int fd@ = pixie file descriptor
	145	* @const char *tag@ = pointer to tag string
	146	* @const char *phrase@ = pointer to passphrase string
	147	*
	148	* Returns: ---
	149	*
	150	* Use: Sends a passphrase to the passphrase pixie.
	151	*/
	152
	153	extern void pixie_set(int /fd/, const char /tag*/,
	154	const char /phrase*/);
	155
069c185c	156	/* --- @pixie_cancel@ --- *
	157	*
	158	* Arguments: @int fd@ = pixie file descriptor
	159	* @const char *tag@ = pointer to tag string
	160	*
	161	* Returns: ---
	162	*
	163	* Use: Cancels a passphrase if it turns out to be bogus.
	164	*/
	165
	166	extern void pixie_cancel(int /fd/, const char /tag*/);
	167
	168	/* --- @pixie_address@ --- *
	169	*
	170	* Arguments: @const char *sock@ = pointer to socket name
	171	* @size_t *psz@ = where to write the address size
	172	*
	173	* Returns: Pointer to filled-in Unix-domain socket address.
	174	*
	175	* Use: Returns a Unix-domain socket address to use to find the
	176	* passphrase pixie.
	177	*/
	178
	179	extern struct sockaddr_un pixie_address(const char /sock/,
	180	size_t /psz*/);
	181
	182	/* --- @pixie_fdline@ --- *
	183	*
	184	* Arguments: @int fd@ = file descriptor to read from
	185	* @char *buf@ = pointer to buffer
	186	* @size_t sz@ = size of buffer
	187	*
	188	* Returns: ---
	189	*
	190	* Use: Reads a line from a file descriptor. The read is done one
	191	* character at a time. If the entire line won't fit, the end
	192	* is truncated. The line is null terminated.
	193	*/
	194
	195	extern void pixie_fdline(int /fd/, char /buf/, size_t /sz*/);
	196
	197	/* --- @pixie_getpass@ --- *
	198	*
	199	* Arguments: @const char *prompt@ = pointer to prompt string
	200	* @char *buf@ = pointer to buffer
	201	* @size_t sz@ = size of buffer
	202	*
	203	* Returns: Zero if it worked OK, nonzero otherwise.
	204	*
	205	* Use: Reads a passphrase from the terminal or some other requested
	206	* source.
	207	*/
	208
	209	extern int pixie_getpass(const char /prompt*/,
	210	char /buf/, size_t /sz*/);
	211
	212	/----- That's all, folks -------------------------------------------------/
	213
	214	#ifdef __cplusplus
	215	}
	216	#endif
	217
	218	#endif