hashsum.c: Document `--progress' in the `--help' display.

[u/mdw/catacomb] / passphrase.h

/* -*-c-*-
 *
 * $Id$
 *
 * Reading passphrases
 *
 * (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_PASSPHRASE_H
#define CATACOMB_PASSPHRASE_H

#ifdef __cplusplus
  extern "C" {
#endif

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

#include <stddef.h>

/*----- Data structures ---------------------------------------------------*/

/* --- Passphrase modes --- *
 *
 * @PMODE_VERIFY@ requests that the passphrase be repeated to make sure it's
 * right.
 */

enum {
  PMODE_READ,
  PMODE_VERIFY
};

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

/* --- @passphrase_connect@ ---
 *
 * Arguments:	@const char *sock@ = socket name to connect to, or null for
 *			default
 *
 * Returns:	Zero if OK, nonzero if it failed
 *
 * Use:		Attempts to connect to the passphrase pixie.
 */

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

/* --- @passphrase_read@ --- *
 *
 * Arguments:	@const char *tag@ = pointer to passphrase tag string
 *		@unsigned mode@ = reading mode
 *		@char *buf@ = pointer to destination buffer
 *		@size_t sz@ = size of destination buffer
 *
 * Returns:	Zero if successful, nonzero on failure.
 *
 * Use:		Reads a passphrase from the user, using some system-specific
 *		secure mechanism.  The mechanism may keep a cache of
 *		passphrases, so the user may not necessarily be prompted.
 */

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

/* --- @passphrase_cancel@ --- *
 *
 * Arguments:	@const char *tag@ = pointer to passphrase tag string
 *
 * Returns:	---
 *
 * Use:		Attempts to make the passphrase cache forget about a
 *		particular passphrase.  This may be useful if the passphrase
 *		turns out to be wrong, or if the user is attempting to change
 *		the passphrase.
 */

extern void passphrase_cancel(const char */*tag*/);

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

#ifdef __cplusplus
  }
#endif

#endif