@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

@smallexample
@code{/* Prefixes @emph{authority_}, @emph{ticket_}, and @emph{wicket_} are reserved. */}
@code{#include <mailutils/auth.h>}

@end smallexample

There are many ways to authenticate to a server.  To be flexible the
authentication process is provided by three objects @code{authority_t},
@code{ticket_t}, and @code{wicket_t}.  The @code{authority_t} can implement
different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
if a mailbox does not understand or know how to authenticate it falls back
to user/passwd authentication.  The @code{ticket_t} is a way for
Mailboxes and Mailers provide a way to authenticate when the URL does not
contain enough information.  The default action is to call the function
@code{authority_authenticate()} which will get the @emph{user} and @emph{passwd}
if not set, this function can be overridden by a custom method.

@c
@c Ticket
@c

@deftypefun  int ticket_create (ticket_t *, void *@var{owner})
@end deftypefun

@deftypefun void ticket_destroy (ticket_t *, void *@var{owner})
@end deftypefun

@deftypefun  int ticket_set_destroy (ticket_t, void (*) (ticket_t), void *@var{owner})
@end deftypefun

@deftypefun void* ticket_get_owner (ticket_t)
@end deftypefun

@deftypefun  int ticket_set_pop (ticket_t, int (*@var{_pop}) (ticket_t, url_t, const char *, char **), void *)
@end deftypefun

@deftypefun  int ticket_pop (ticket_t, url_t, const char *, char **)
@end deftypefun

@deftypefun  int ticket_set_data (ticket_t, void *, void *@var{owner})
@end deftypefun

@deftypefun  int ticket_get_data (ticket_t, void **)
@end deftypefun

@c
@c Authority
@c

@sp 1

@deftypefun  int authority_create (authority_t *, ticket_t, void *)
@end deftypefun

@deftypefun void authority_destroy (authority_t *, void *)
@end deftypefun

@deftypefun void* authority_get_owner (authority_t)
@end deftypefun

@deftypefun  int authority_set_ticket (authority_t, ticket_t)
@end deftypefun

@deftypefun  int authority_get_ticket (authority_t, ticket_t *)
@end deftypefun

@deftypefun  int authority_authenticate (authority_t)
@end deftypefun

@deftypefun  int authority_set_authenticate (authority_t, int (*@var{_authenticate}) (authority_t), void *)
@end deftypefun

@deftypefun  int authority_create_null (authority_t *@var{authority}, void *@var{owner})
@end deftypefun

@c
@c Wicket
@c

@sp 1

@deftypefun  int wicket_create (wicket_t *, const char *)
@end deftypefun

@deftypefun void wicket_destroy (wicket_t *)
@end deftypefun

@deftypefun  int wicket_set_filename (wicket_t, const char *)
@end deftypefun

@deftypefun  int wicket_get_filename (wicket_t, char *, size_t, size_t *)
@end deftypefun

@deftypefun  int wicket_set_ticket (wicket_t, int (*) (wicket_t, const char *, const char *, ticket_t *))
@end deftypefun

@deftypefun  int wicket_get_ticket (wicket_t, ticket_t *, const char *, const char *)
@end deftypefun

@c
@c An example.
@c

@sp 1
A simple example of an authenticate function:

@smallexample
#include <stdio.h>
#include <string.h>
#include <mailutils/auth.h>

int
my_authenticate (auth_t auth, char **user, char **passwd)
@{
  char u[128] = "";
  char p[128] = "";

  /* prompt the user name */
  printf ("User: ");
  fflush (stdout);
  fgets (u, sizeof (u), stdin);
  u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */

  /* prompt the passwd */
  printf ("Passwd: "); fflush (stdout);
  echo_off ();
  fgets (p, sizeof(p), stdin);
  echo_on ();
  p[strlen (p) - 1] = '\0';

  /* duplicate */
  *user = strdup (u);
  *passwd = strdup (p);
  return 0;
@}
@end smallexample