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