Changeset 63 in openpam for trunk


Ignore:
Timestamp:
Feb 18, 2002, 7:31:10 PM (18 years ago)
Author:
Dag-Erling Smørgrav
Message:

Add in-line documentation. Some functions still lack descriptions.

Sponsored by: DARPA, NAI Labs

Location:
trunk/lib
Files:
11 added
35 edited

Legend:

Unmodified
Added
Removed
  • trunk/lib/openpam_dispatch.c

    r56 r63  
    4848
    4949/*
     50 * OpenPAM internal
     51 *
    5052 * Execute a module chain
    5153 */
     
    211213}
    212214#endif /* !defined(OPENPAM_RELAX_CHECKS) */
     215
     216/*
     217 * NODOC
     218 *
     219 * Error codes:
     220 */
  • trunk/lib/openpam_findenv.c

    r16 r63  
    4242
    4343/*
     44 * OpenPAM internal
     45 *
    4446 * Locate an environment variable
    4547 */
     
    6163        return (-1);
    6264}
     65
     66/*
     67 * NODOC
     68 */
  • trunk/lib/openpam_load.c

    r50 r63  
    226226                openpam_destroy_chain(pamh->chains[i]);
    227227}
     228
     229/*
     230 * NOPARSE
     231 */
  • trunk/lib/openpam_log.c

    r52 r63  
    4848
    4949/*
     50 * OpenPAM extension
     51 *
    5052 * Log a message through syslog(3)
    5153 */
     
    122124
    123125#endif
     126
     127/*
     128 * NOLIST
     129 */
  • trunk/lib/openpam_ttyconv.c

    r35 r63  
    4747
    4848/*
    49  * Simple tty-based conversation function.
     49 * OpenPAM extension
     50 *
     51 * Simple tty-based conversation function
    5052 */
    5153
     
    130132        return (err);
    131133}
     134
     135/*
     136 * NOLIST
     137 *
     138 * Error codes:
     139 *
     140 *      PAM_SYSTEM_ERR
     141 *      PAM_BUF_ERR
     142 *      PAM_CONV_ERR
     143 */
  • trunk/lib/pam_acct_mgmt.c

    r32 r63  
    5555        return (openpam_dispatch(pamh, PAM_SM_ACCT_MGMT, flags));
    5656}
     57
     58/*
     59 * Error codes:
     60 *
     61 *      =openpam_dispatch
     62 *      =pam_sm_acct_mgmt
     63 *      !PAM_IGNORE
     64 */
  • trunk/lib/pam_authenticate.c

    r32 r63  
    5555        return (openpam_dispatch(pamh, PAM_SM_AUTHENTICATE, flags));
    5656}
     57
     58/*
     59 * Error codes:
     60 *
     61 *      =openpam_dispatch
     62 *      =pam_sm_authenticate
     63 *      !PAM_IGNORE
     64 */
  • trunk/lib/pam_authenticate_secondary.c

    r16 r63  
    3737#include <security/pam_appl.h>
    3838
     39/*
     40 * XSSO 4.2.1
     41 * XSSO 6 page 36
     42 *
     43 * Perform authentication to a secondary domain within the PAM framework
     44 */
     45
    3946int
    4047pam_authenticate_secondary(pam_handle_t *pamh,
     
    4956        return (PAM_SYSTEM_ERR);
    5057}
     58
     59/*
     60 * NODOC
     61 */
  • trunk/lib/pam_chauthtok.c

    r32 r63  
    5555        return (openpam_dispatch(pamh, PAM_SM_CHAUTHTOK, flags));
    5656}
     57
     58/*
     59 * Error codes:
     60 *
     61 *      =openpam_dispatch
     62 *      =pam_sm_chauthtok
     63 *      !PAM_IGNORE
     64 */
  • trunk/lib/pam_close_session.c

    r32 r63  
    5555        return (openpam_dispatch(pamh, PAM_SM_CLOSE_SESSION, flags));
    5656}
     57
     58/*
     59 * Error codes:
     60 *
     61 *      =openpam_dispatch
     62 *      =pam_sm_close_session
     63 *      !PAM_IGNORE
     64 */
  • trunk/lib/pam_end.c

    r21 r63  
    8383        return (PAM_SUCCESS);
    8484}
     85
     86/*
     87 * Error codes:
     88 *
     89 *      PAM_SYSTEM_ERR
     90 */
     91
     92/**
     93 * The =pam_end function terminates a PAM transaction and destroys the
     94 * corresponding PAM context, releasing all resources allocated to it.
     95 *
     96 * The =status argument should be set to the error code returned by the
     97 * last API call before the call to =pam_end.
     98 */
  • trunk/lib/pam_error.c

    r39 r63  
    6363        return (r);
    6464}
     65
     66/*
     67 * Error codes:
     68 *
     69 *     !PAM_SYMBOL_ERR
     70 *      PAM_SYSTEM_ERR
     71 *      PAM_BUF_ERR
     72 *      PAM_CONV_ERR
     73 */
     74
     75/**
     76 * The =pam_info function displays an error message through the
     77 * intermediary of the given PAM context's conversation function.
     78 *
     79 * >pam_info
     80 * >pam_prompt
     81 * >pam_verror
     82 */
  • trunk/lib/pam_get_authtok.c

    r58 r63  
    7474        return (pam_set_item(pamh, PAM_AUTHTOK, *authtok));
    7575}
     76
     77/*
     78 * Error codes:
     79 *
     80 *      =pam_get_item
     81 *      =pam_prompt
     82 *      =pam_set_item
     83 *      !PAM_SYMBOL_ERR
     84 */
  • trunk/lib/pam_get_data.c

    r54 r63  
    6666        return (PAM_NO_MODULE_DATA);
    6767}
     68
     69/*
     70 * Error codes:
     71 *
     72 *      PAM_SYSTEM_ERR
     73 *      PAM_NO_MODULE_DATA
     74 */
     75
     76/**
     77 * The =pam_get_data function looks up the opaque object associated with
     78 * the string specified by the =module_data_name argument, in the PAM
     79 * context specified by the =pamh argument.
     80 * A pointer to the object is stored in the location pointed to by the
     81 * =data argument.
     82 *
     83 * This function and its counterpart =pam_set_data are useful for managing
     84 * data that are meaningful only to a particular service module.
     85 */
  • trunk/lib/pam_get_item.c

    r61 r63  
    7373        }
    7474}
     75
     76/*
     77 * Error codes:
     78 *
     79 *      PAM_SYMBOL_ERR
     80 *      PAM_SYSTEM_ERR
     81 */
     82
     83/**
     84 * The =pam_get_item function stores a pointer to the item specified by
     85 * the =item_type argument in the location specified by the =item
     86 * argument.
     87 * The item is retrieved from the PAM context specified by the =pamh
     88 * argument.
     89 * The following item types are recognized:
     90 *
     91 *      =PAM_SERVICE:
     92 *              The name of the requesting service.
     93 *      =PAM_USER:
     94 *              The name of the user the application is trying to
     95 *              authenticate.
     96 *      =PAM_TTY:
     97 *              The name of the current terminal.
     98 *      =PAM_RHOST:
     99 *              The name of the applicant's host.
     100 *      =PAM_CONV:
     101 *              A =struct pam_conv describing the current conversation
     102 *              function.
     103 *      =PAM_AUTHTOK:
     104 *              The current authentication token.
     105 *      =PAM_OLDAUTHTOK:
     106 *              The expired authentication token.
     107 *      =PAM_RUSER:
     108 *              The name of the applicant.
     109 *      =PAM_USER_PROMPT:
     110 *              The prompt to use when asking the applicant for a user
     111 *              name to authenticate as.
     112 *      =PAM_AUTHTOK_PROMPT:
     113 *              The prompt to use when asking the applicant for an
     114 *              authentication token.
     115 *
     116 * See =pam_start for a description of =struct pam_conv.
     117 *
     118 * >pam_set_item
     119 */
  • trunk/lib/pam_get_mapped_authtok.c

    r16 r63  
    3737#include <security/pam_appl.h>
    3838
     39/*
     40 * XSSO 4.2.1
     41 * XSSO 6 page 48
     42 *
     43 * Get mapped password for the user
     44 */
     45
    3946int
    4047pam_get_mapped_authtok(pam_handle_t *pamh,
     
    4855        return (PAM_SYSTEM_ERR);
    4956}
     57
     58/*
     59 * NODOC
     60 */
  • trunk/lib/pam_get_mapped_username.c

    r16 r63  
    3737#include <security/pam_appl.h>
    3838
     39/*
     40 * XSSO 4.2.1
     41 * XSSO 6 page 50
     42 *
     43 * Get valid matched identity in new domain
     44 */
     45
    3946int
    4047pam_get_mapped_username(pam_handle_t *pamh,
     
    4956        return (PAM_SYSTEM_ERR);
    5057}
     58
     59/*
     60 * NODOC
     61 */
  • trunk/lib/pam_get_user.c

    r39 r63  
    7575        return (pam_set_item(pamh, PAM_USER, *user));
    7676}
     77
     78/*
     79 * Error codes:
     80 *
     81 *      =pam_get_item
     82 *      =pam_prompt
     83 *      =pam_set_item
     84 *      !PAM_SYMBOL_ERR
     85 */
  • trunk/lib/pam_getenv.c

    r16 r63  
    6666        return (strdup(pamh->env[i]));
    6767}
     68
     69/**
     70 * The =pam_getenv function returns the value of an environment variable.
     71 * Its semantics are similar to those of =getenv, but it accesses the PAM
     72 * context's environment list instead of the application's.
     73 *
     74 * >pam_getenvlist
     75 * >pam_putenv
     76 * >pam_setenv
     77 */
  • trunk/lib/pam_getenvlist.c

    r60 r63  
    7676        return (envlist);
    7777}
     78
     79/**
     80 * The =pam_getenvlist function returns a copy of the given PAM context's
     81 * environment list as a pointer to an array of strings.
     82 * The last element in the array is =NULL.
     83 * The pointer is suitable for assignment to {Va environ}.
     84 *
     85 * The array and the strings it lists are allocated using =malloc, and
     86 * should be released using =free after use:
     87 *
     88 *     char **envlist, **env;
     89 *     
     90 *     envlist = environ;
     91 *     environ = pam_getenvlist(pamh);
     92 *     \/\* do something nifty \*\/
     93 *     for (env = environ; *env != NULL; env++)
     94 *         free(*env);
     95 *     free(environ);
     96 *     environ = envlist;
     97 *
     98 * >environ 7
     99 * >pam_getenv
     100 * >pam_putenv
     101 * >pam_setenv
     102 */
  • trunk/lib/pam_info.c

    r39 r63  
    6363        return (r);
    6464}
     65
     66/*
     67 * Error codes:
     68 *
     69 *     !PAM_SYMBOL_ERR
     70 *      PAM_SYSTEM_ERR
     71 *      PAM_BUF_ERR
     72 *      PAM_CONV_ERR
     73 */
     74
     75/**
     76 * The =pam_info function displays an informational message through the
     77 * intermediary of the given PAM context's conversation function.
     78 *
     79 * >pam_error
     80 * >pam_prompt
     81 * >pam_vinfo
     82 */
  • trunk/lib/pam_open_session.c

    r32 r63  
    5555        return (openpam_dispatch(pamh, PAM_SM_OPEN_SESSION, flags));
    5656}
     57
     58/*
     59 * Error codes:
     60 *
     61 *      =openpam_dispatch
     62 *      =pam_sm_open_session
     63 *      !PAM_IGNORE
     64 */
  • trunk/lib/pam_prompt.c

    r39 r63  
    6161        return (r);
    6262}
     63
     64/*
     65 * Error codes:
     66 *
     67 *     !PAM_SYMBOL_ERR
     68 *      PAM_SYSTEM_ERR
     69 *      PAM_BUF_ERR
     70 *      PAM_CONV_ERR
     71 */
     72
     73/**
     74 * The =pam_prompt function constructs a message from the specified format
     75 * string and arguments and passes it to the given PAM context's
     76 * conversation function.
     77 *
     78 * A pointer to the response, or =NULL if the conversation function did
     79 * not return one, is stored in the location pointed to by the =resp
     80 * argument.
     81 *
     82 * See =pam_vprompt for further details.
     83 *
     84 * >pam_error
     85 * >pam_info
     86 * >pam_vprompt
     87 */
  • trunk/lib/pam_putenv.c

    r16 r63  
    8787        return (PAM_SUCCESS);
    8888}
     89
     90/*
     91 * Error codes:
     92 *
     93 *      PAM_SYSTEM_ERR
     94 *      PAM_BUF_ERR
     95 */
     96
     97/**
     98 * The =pam_putenv function sets a environment variable.
     99 * Its semantics are similar to those of =putenv, but it modifies the PAM
     100 * context's environment list instead of the application's.
     101 *
     102 * >pam_getenv
     103 * >pam_getenvlist
     104 * >pam_setenv
     105 */
  • trunk/lib/pam_set_data.c

    r35 r63  
    8282        return (PAM_SUCCESS);
    8383}
     84
     85/*
     86 * Error codes:
     87 *
     88 *      PAM_SYSTEM_ERR
     89 *      PAM_BUF_ERR
     90 */
     91
     92/**
     93 * The =pam_set_data function associates a pointer to an opaque object
     94 * with an arbitrary string specified by the =module_data_name argument,
     95 * in the PAM context specified by the =pamh argument.
     96 *
     97 * If not =NULL, the =cleanup argument should point to a function
     98 * responsible for releasing the resources associated with the object.
     99 *
     100 * This function and its counterpart =pam_get_data are useful for managing
     101 * data that are meaningful only to a particular service module.
     102 */
  • trunk/lib/pam_set_item.c

    r61 r63  
    9898        return (PAM_SUCCESS);
    9999}
     100
     101/*
     102 * Error codes:
     103 *
     104 *      PAM_SYMBOL_ERR
     105 *      PAM_SYSTEM_ERR
     106 *      PAM_BUF_ERR
     107 */
     108
     109/**
     110 * The =pam_set_item function sets the item specified by the =item_type
     111 * argument to a copy of the object pointed to by the =item argument.
     112 * The item is stored in the PAM context specified by the =pamh argument.
     113 * See =pam_get_item for a list of recognized item types.
     114 */
  • trunk/lib/pam_set_mapped_authtok.c

    r16 r63  
    3737#include <security/pam_appl.h>
    3838
     39/*
     40 * XSSO 4.2.1
     41 * XSSO 6 page 62
     42 *
     43 * Store the password for the username supplied
     44 */
     45
    3946int
    4047pam_set_mapped_authtok(pam_handle_t *pamh,
     
    4855        return (PAM_SYSTEM_ERR);
    4956}
     57
     58/*
     59 * NODOC
     60 */
  • trunk/lib/pam_set_mapped_username.c

    r16 r63  
    3737#include <security/pam_appl.h>
    3838
     39/*
     40 * XSSO 4.2.1
     41 * XSSO 6 page 64
     42 *
     43 * Set a username
     44 */
     45
    3946int
    4047pam_set_mapped_username(pam_handle_t *pamh,
     
    4956        return (PAM_SYSTEM_ERR);
    5057}
     58
     59/*
     60 * NODOC
     61 */
  • trunk/lib/pam_setcred.c

    r32 r63  
    5555        return (openpam_dispatch(pamh, PAM_SM_SETCRED, flags));
    5656}
     57
     58/*
     59 * Error codes:
     60 *
     61 *      =openpam_dispatch
     62 *      =pam_sm_setcred
     63 *      !PAM_IGNORE
     64 */
     65
     66/**
     67 * The =pam_setcred function manages the application's credentials.
     68 * The operation to perform is specified by the =flags argument:
     69 *
     70 *      PAM_ESTABLISH_CRED:
     71 *              Establish the credentials of the target user.
     72 *      PAM_DELETE_CRED:
     73 *              Revoke all established credentials.
     74 *      PAM_REINITIALISE_CRED:
     75 *              Fully reinitialise credentials.
     76 *      PAM_REFRESH_CRED:
     77 *              Refresh credentials.
     78 */
  • trunk/lib/pam_setenv.c

    r16 r63  
    7878        return (r);
    7979}
     80
     81/*
     82 * Error codes:
     83 *
     84 *      =pam_putenv
     85 *      PAM_SYSTEM_ERR
     86 *      PAM_BUF_ERR
     87 */
     88
     89/**
     90 * The =pam_setenv function sets a environment variable.
     91 * Its semantics are similar to those of =setenv, but it modifies the PAM
     92 * context's environment list instead of the application's.
     93 *
     94 * >pam_getenv
     95 * >pam_getenvlist
     96 * >pam_putenv
     97 */
  • trunk/lib/pam_start.c

    r49 r63  
    291291        return (PAM_SYSTEM_ERR);
    292292}
     293
     294/*
     295 * Error codes:
     296 *
     297 *      =pam_set_item
     298 *      !PAM_SYMBOL_ERR
     299 *      PAM_SYSTEM_ERR
     300 *      PAM_BUF_ERR
     301 */
     302
     303/**
     304 * The =pam_start function creates and initializes a PAM context.
     305 *
     306 * The =service argument specifies the name of the policy to apply, and is
     307 * stored in the =PAM_SERVICE item in the created context.
     308 *
     309 * The =user argument specifies the name of the target user - the user the
     310 * created context will serve to authenticate.
     311 * It is stored in the =PAM_USER item in the created context.
     312 *
     313 * The =pam_conv argument points to a =struct pam_conv describing the
     314 * conversation function to use.
     315 * This structure is defined as follows:
     316 *
     317 *     struct pam_conv {
     318 *          int   (*conv)(int, const struct pam_message **,
     319 *              struct pam_response **, void *);
     320 *          void   *appdata_ptr;
     321 *     };
     322 *
     323 * >pam_get_item
     324 * >pam_set_item
     325 * >pam_end
     326 */
  • trunk/lib/pam_strerror.c

    r61 r63  
    104104                return ("authentication token lock busy");
    105105        case PAM_AUTHTOK_DISABLE_AGING:
    106                 return ("authentication token ageing disabled");
     106                return ("authentication token aging disabled");
    107107        case PAM_NO_MODULE_DATA:
    108108                return ("module data not found");
     
    122122        }
    123123}
     124
     125/**
     126 * The =pam_strerror function returns a pointer to a string containing a
     127 * textual description of the error indicated by the =error_number
     128 * argument, in the context of the PAM transaction described by the =pamh
     129 * argument.
     130 */
  • trunk/lib/pam_verror.c

    r39 r63  
    5959        return (r);
    6060}
     61
     62/*
     63 * Error codes:
     64 *
     65 *     !PAM_SYMBOL_ERR
     66 *      PAM_SYSTEM_ERR
     67 *      PAM_BUF_ERR
     68 *      PAM_CONV_ERR
     69 */
     70
     71/**
     72 * The =pam_verror function passes its arguments to =pam_vprompt with a
     73 * =style argument of =PAM_ERROR_MSG, and discards the response.
     74 *
     75 * >pam_error
     76 * >pam_vinfo
     77 */
  • trunk/lib/pam_vinfo.c

    r39 r63  
    5959        return (r);
    6060}
     61
     62/*
     63 * Error codes:
     64 *
     65 *     !PAM_SYMBOL_ERR
     66 *      PAM_SYSTEM_ERR
     67 *      PAM_BUF_ERR
     68 *      PAM_CONV_ERR
     69 */
     70
     71/**
     72 * The =pam_vinfo function passes its arguments to =pam_vprompt with a
     73 * =style argument of =PAM_TEXT_INFO, and discards the response.
     74 *
     75 * >pam_info
     76 * >pam_verror
     77 */
  • trunk/lib/pam_vprompt.c

    r57 r63  
    7878        return (r);
    7979}
     80
     81/*
     82 * Error codes:
     83 *
     84 *     !PAM_SYMBOL_ERR
     85 *      PAM_SYSTEM_ERR
     86 *      PAM_BUF_ERR
     87 *      PAM_CONV_ERR
     88 */
     89
     90/**
     91 * The =pam_vprompt function constructs a string from the =fmt and =ap
     92 * arguments using =vsnprintf, and passes it to the given PAM context's
     93 * conversation function.
     94 *
     95 * The =style argument specifies the type of interaction requested, and
     96 * must be one of the following:
     97 *
     98 *      =PAM_PROMPT_ECHO_OFF:
     99 *              Display the message and obtain the user's response without
     100 *              displaying it.
     101 *      =PAM_PROMPT_ECHO_ON:
     102 *              Display the message and obtain the user's response.
     103 *      =PAM_ERROR_MSG:
     104 *              Display the message as an error message, and do not wait
     105 *              for a response.
     106 *      =PAM_TEXT_INFO:
     107 *              Display the message as an informational message, and do
     108 *              not wait for a response.
     109 *
     110 * A pointer to the response, or =NULL if the conversation function did
     111 * not return one, is stored in the location pointed to by the =resp
     112 * argument.
     113 *
     114 * The message and response should not exceed =PAM_MAX_MSG_SIZE or
     115 * =PAM_MAX_RESP_SIZE, respectively.
     116 * If they do, they may be truncated.
     117 *
     118 * >pam_error
     119 * >pam_info
     120 * >pam_prompt
     121 * >pam_verror
     122 * >pam_vinfo
     123 */
Note: See TracChangeset for help on using the changeset viewer.