contrib/libpam/doc/man/pam_authenticate.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\" $Id: pam_authenticate.3,v 1.2 1997/02/15 18:39:59 morgan Exp $
   3 .\" $FreeBSD: src/contrib/libpam/doc/man/pam_authenticate.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
   4 .\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
   5 .TH PAM_AUTHENTICATE 3 "1996 Dec 9" "PAM 0.55" "App. Programmers' Manual"
   6 .SH NAME
   7
   8 pam_authenticate \- authenticate a user
   9
  10 .SH SYNOPSIS
  11 .B #include <security/pam_appl.h>
  12 .sp
  13 .BI "int pam_authenticate(pam_handle_t " *pamh ", int  " flags ");"
  14 .sp 2
  15 .SH DESCRIPTION
  16 .B pam_authenticate
  17
  18 .br
  19 Use this function to authenticate an applicant user.  It is linked
  20 .I dynamically
  21 to the authentication modules by
  22 .BR PAM ". "
  23 It is the task of these module to perform such an authentication.  The
  24 specific nature of the authentication is not the concern of the
  25 application.
  26
  27 .br
  28 Following successful completion, the
  29 .BR name
  30 of the authenticated user will be present in the
  31 .BR PAM
  32 item
  33 .BR PAM_USER ". "
  34 This item may be recovered with a call to
  35 .BR pam_get_item "(3)."
  36
  37 .br
  38 The application developer should note that the modules may request
  39 that the user enter their username via the conversation mechanism (see
  40 .BR pam_start "(3))."
  41 Should this be the case, the user-prompt string can be set via
  42 the
  43 .BR PAM_USER_PROMPT
  44 item (see
  45 .BR pam_set_item "(3))."
  46
  47 .SH "RETURN VALUE"
  48 On success
  49 .BR PAM_SUCCESS
  50 is returned.  All other returns should be considered
  51 authentication failures and will be
  52 .I delayed
  53 by an amount specified with prior calls to
  54 .BR pam_fail_delay "(3). "
  55 Specific failures that demand special attention are the following:
  56 .TP
  57 .B PAM_ABORT
  58 the application should exit immediately. Of course,
  59 .BR pam_end "(3)"
  60 should be called first.
  61
  62 .TP
  63 .B PAM_MAXTRIES
  64 the application has tried too many times to authenticate the
  65 user, authentication should not be attempted again.
  66
  67 .SH ERRORS
  68 May be translated to text with
  69 .BR pam_strerror "(3). "
  70
  71 .SH "CONFORMING TO"
  72 DCE-RFC 86.0, October 1995.
  73
  74 .SH BUGS
  75 .sp 2
  76 none known.
  77
  78 .SH "SEE ALSO"
  79
  80 .BR pam_start "(3), "
  81 .BR pam_get_item "(3) "
  82 .BR pam_fail_delay "(3) "
  83 and
  84 .BR pam_strerror "(3). "
  85
  86 Also, see the three
  87 .BR PAM
  88 Guides, for
  89 .BR "System administrators" ", "
  90 .BR "module developers" ", "
  91 and
  92 .BR "application developers" ". "