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