contrib/libpam/doc/man/pam_chauthtok.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\" $Id: pam_chauthtok.3,v 1.2 1997/02/15 18:42:23 morgan Exp $
   3 .\" $FreeBSD: src/contrib/libpam/doc/man/pam_chauthtok.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
   4 .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
   5 .TH PAM_CHAUTHTOK 3 "1997 Jan 4" "PAM 0.55" "App. Programmers' Manual"
   6 .SH NAME
   7
   8 pam_chauthtok \- updating authentication tokens
   9
  10 .SH SYNOPSIS
  11 .B #include <security/pam_appl.h>
  12 .sp
  13 .BI "int pam_chauthtok(pam_handle_t " *pamh ", int  " flags ");"
  14 .sp 2
  15 .SH DESCRIPTION
  16 .B pam_chauthtok
  17
  18 .br
  19 Use this function to rejuvenate the authentication tokens (passwords
  20 etc.) of an applicant user.
  21
  22 .br
  23 Note, the application should not pre-authenticate the user, as this is
  24 performed (if required) by the
  25 .BR PAM
  26 framework.
  27
  28 .br
  29 The
  30 .I flags
  31 argument can
  32 .I optionally
  33 take the value,
  34 .BR PAM_CHANGE_EXPIRED_AUTHTOK "."
  35 In such cases the framework is only required to update those
  36 authentication tokens that have expired. Without this argument, the
  37 framework will attempt to obtain new tokens for all configured
  38 authentication mechanisms. The details of the types and number of such
  39 schemes should not concern the calling application.
  40
  41 .SH RETURN VALUE
  42 A successful return from this function will be indicated with
  43 .BR PAM_SUCCESS "."
  44
  45 .br
  46 Specific errors of special interest when calling this function are
  47
  48 .br
  49 .BR PAM_AUTHTOK_ERROR
  50 - a valid new token was not obtained
  51
  52 .br
  53 .BR PAM_AUTHTOK_RECOVERY_ERR
  54 - old authentication token was not available
  55
  56 .br
  57 .BR PAM_AUTHTOK_LOCK_BUSY
  58 - a resource needed to update the token was locked (try again later)
  59
  60 .br
  61 .BR PAM_AUTHTOK_DISABLE_AGING
  62 - one or more of the authentication modules does not honor
  63 authentication token aging
  64
  65 .br
  66 .BR PAM_TRY_AGAIN
  67 - one or more authentication mechanism is not prepared to update a
  68 token at this time
  69
  70 .br
  71 In general other return values may be returned. They should be treated
  72 as indicating failure.
  73
  74 .SH ERRORS
  75 May be translated to text with
  76 .BR pam_strerror "(3). "
  77
  78 .SH "CONFORMING TO"
  79 DCE-RFC 86.0, October 1995.
  80
  81 .SH BUGS
  82 .sp 2
  83 none known.
  84
  85 .SH "SEE ALSO"
  86
  87 .BR pam_start "(3), "
  88 .BR pam_authenticate "(3), "
  89 .BR pam_setcred "(3), "
  90 .BR pam_get_item "(3), "
  91 .BR pam_strerror "(3) "
  92 and
  93 .BR pam "(8)."
  94
  95 .br
  96 Also, see the three
  97 .BR PAM
  98 Guides, for
  99 .BR "System administrators" ", "
 100 .BR "module developers" ", "
 101 and
 102 .BR "application developers" ". "