.TH "globus_gss_assist_gridmap" 3 "Wed Feb 27 2019" "Version 12.2" "globus_gss_assist" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_gss_assist_gridmap \- Gridmap Authorization and Local User Mapping\&.  

.SH SYNOPSIS
.br
.PP
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBGlobusGssAssistFreeDNArray\fP(dn_a)"
.br
.RI "Free array of distinguished names\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBglobus_gss_assist_gridmap\fP (char *globusidp, char **useridp)"
.br
.RI "Look up the default mapping for a Grid identity in a gridmap file\&. "
.ti -1c
.RI "int \fBglobus_gss_assist_userok\fP (char *globusid, char *userid)"
.br
.RI "Gridmap entry existence check\&. "
.ti -1c
.RI "int \fBglobus_gss_assist_map_local_user\fP (char *local_user, char **globusidp)"
.br
.RI "Look up the default Grid identity associated with a local user name\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gss_assist_lookup_all_globusid\fP (char *username, char **dns[], int *dn_count)"
.br
.RI "Look up all Grid IDs associated with a local user ID\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gss_assist_map_and_authorize\fP (gss_ctx_id_t context, char *service, char *desired_identity, char *identity_buffer, unsigned int identity_buffer_length)"
.br
.RI "Authorize the peer of a security context to use a service\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gss_assist_map_and_authorize_sharing\fP (char *shared_user_certificate, gss_ctx_id_t context, char *desired_identity, char *identity_buffer, unsigned int identity_buffer_length)"
.br
.RI "Authorize a particular credential for shared access\&. "
.in -1c
.SH "Detailed Description"
.PP 
Gridmap Authorization and Local User Mapping\&. 

Functions in this group are used to authorize a GSSAPI credential to perform some action on the local machine\&. In addition to checking whether a credential is authorized, it can also be mapped to a local user name\&. 
.SH "Macro Definition Documentation"
.PP 
.SS "#define GlobusGssAssistFreeDNArray(dn_a)"

.PP
Free array of distinguished names\&. Free the contents of a name array created during a successful call to \fBglobus_gss_assist_lookup_all_globusid()\fP
.PP
\fBParameters:\fP
.RS 4
\fIdn_a\fP Array of names to free\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIvoid\fP 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "int globus_gss_assist_gridmap (char * globusidp, char ** useridp)"

.PP
Look up the default mapping for a Grid identity in a gridmap file\&. The \fBglobus_gss_assist_gridmap()\fP function parses the default gridmap file and modifies its \fIuseridp\fP parameter to point to a copy of the string containing the default local identity that the grid identity is mapped to\&. If successful, the caller is responsible for freeing the string pointed to by \fIuseridp\fP\&.
.PP
By default, \fBglobus_gss_assist_gridmap()\fP looks for the default gridmap file defined by the value of the GRIDMAP environment variable\&. If that is not set, it falls back to $HOME/\&.gridmap\&.
.PP
\fBParameters:\fP
.RS 4
\fIglobusidp\fP The GSSAPI name string of the identity who requested authorization 
.br
\fIuseridp\fP A pointer to a string to be set to the default user ID for the local system\&. No validation is done to check that such a user exists\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_gss_assist_gridmap()\fP returns 0 and modifies the the string pointed to by the \fIuseridp\fP parameter\&. If an error occurs, a non-zero value is returned and the value pointed to by \fIuseridp\fP is undefined\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fI1\fP Error 
.RE
.PP

.SS "globus_result_t globus_gss_assist_lookup_all_globusid (char * username, char ** dns[], int * dn_count)"

.PP
Look up all Grid IDs associated with a local user ID\&. The \fBglobus_gss_assist_lookup_all_globusid()\fP function parses a gridmap file and finds all Grid IDs that map to a local user ID\&. The \fIdns\fP parameter is modified to point to an array of Grid ID strings from the gridmap file, and the \fIdn_count\fP parameter is modified to point to the number of Grid ID strings in the array\&. The caller is responsible for freeing the array using the macro \fI\fBGlobusGssAssistFreeDNArray()\fP\fP\&.
.PP
By default, \fBglobus_gss_assist_lookup_all_globusid()\fP looks for the default gridmap file defined by the value of the GRIDMAP environment variable\&. If that is not set, it falls back to $HOME/\&.gridmap\&.
.PP
\fBParameters:\fP
.RS 4
\fIusername\fP The local username to look up in the gridmap file\&. 
.br
\fIdns\fP A pointer to an array of strings\&. This function modifies this to point to a newly allocated array of strings\&. The caller must use the macro \fI\fBGlobusGssAssistFreeDNArray()\fP\fP to free this memory\&. 
.br
\fIdn_count\fP A pointer to an integer that is modified to contain the number of entries in the array returned via the \fIdns\fP parameter\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_gss_assist_lookup_all_globusid()\fP returns GLOBUS_SUCCESS and modifies its \fIdns\fP and \fIdn_count\fP parameters as described above\&. If an error occurs, \fBglobus_gss_assist_lookup_all_globusid()\fP returns a globus_result_t that can be resolved to an error object and the values pointed to by \fIdns\fP and \fIdn_count\fP are undefined\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fIGLOBUS_GSI_GSS_ASSIST_ERROR_WITH_ARGUMENTS\fP Error with arguments 
.br
\fIGLOBUS_GSI_GSS_ASSIST_ERROR_WITH_GRIDMAP\fP Invalid path to gridmap 
.br
\fIGLOBUS_GSI_GSS_ASSIST_ERROR_ERRNO\fP System error 
.RE
.PP

.SS "globus_result_t globus_gss_assist_map_and_authorize (gss_ctx_id_t context, char * service, char * desired_identity, char * identity_buffer, unsigned int identity_buffer_length)"

.PP
Authorize the peer of a security context to use a service\&. The \fBglobus_gss_assist_map_and_authorize()\fP function attempts to authorize the peer of a security context to use a particular service\&. If the \fIdesired_identity\fP parameter is non-NULL, the authorization will succeed only if the peer is authorized for that identity\&. Otherwise, any valid authorized local user name will be used\&. If authorized, the local user name will be copied to the string pointed to by the \fIidentity_buffer\fP parameter, which must be at least as long as the value passed as the \fIidentity_buffer_length\fP parameter\&.
.PP
If authorization callouts are defined in the callout configuration file, \fBglobus_gss_assist_map_and_authorize()\fP will invoke both the GLOBUS_GENERIC_MAPPING_TYPE callout and the GLOBUS_GENERIC_AUTHZ_TYPE callout; otherwise the default gridmap file will be used for mapping and no service-specific authorization will be done\&.
.PP
If \fBglobus_gss_assist_map_and_authorize()\fP uses a gridmap file, it first looks for a file defined by the value of the GRIDMAP environment variable\&. If that is not set, it falls back to $HOME/\&.gridmap\&.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Security context to inspect for peer identity information\&. 
.br
\fIservice\fP A NULL-terminated string containing the name of the service that an authorization decision is being made for\&. 
.br
\fIdesired_identity\fP Optional\&. If non-NULL, perform an authorization to act as the local user named by this NULL-terminated string\&. 
.br
\fIidentity_buffer\fP A pointer to a string buffer into which will be copied the local user name that the peer of the context is authorized to act as\&. 
.br
\fIidentity_buffer_length\fP Length of the \fIidentity_buffer\fP array\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_gss_assist_map_and_authorize()\fP returns GLOBUS_SUCCESS and copies the authorized local identity to the \fIidentity_buffer\fP parameter\&. If an error occurs, \fBglobus_gss_assist_map_and_authorize()\fP returns a globus_result_t that can be resolved to an error object\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fIGLOBUS_GSI_GSS_ASSIST_ERROR_WITH_CALLOUT_CONFIG\fP Invalid authorization configuration file 
.br
\fIGLOBUS_CALLOUT_ERROR_WITH_HASHTABLE\fP Hash table operation failed\&. 
.br
\fIGLOBUS_CALLOUT_ERROR_CALLOUT_ERROR\fP The callout itself returned a error\&. 
.br
\fIGLOBUS_CALLOUT_ERROR_WITH_DL\fP Dynamic library operation failed\&. 
.br
\fIGLOBUS_CALLOUT_ERROR_OUT_OF_MEMORY\fP Out of memory 
.br
\fIGLOBUS_GSI_GSS_ASSIST_GSSAPI_ERROR\fP A GSSAPI function returned an error 
.br
\fIGLOBUS_GSI_GSS_ASSIST_GRIDMAP_LOOKUP_FAILED\fP Gridmap lookup failure 
.br
\fIGLOBUS_GSI_GSS_ASSIST_BUFFER_TOO_SMALL\fP Caller provided insufficient buffer space for local identity 
.RE
.PP

.SS "globus_result_t globus_gss_assist_map_and_authorize_sharing (char * shared_user_certificate, gss_ctx_id_t context, char * desired_identity, char * identity_buffer, unsigned int identity_buffer_length)"

.PP
Authorize a particular credential for shared access\&. The \fBglobus_gss_assist_map_and_authorize_sharing()\fP function attempts to authorize a particular credential for shared access\&. the \fIdesired_identity\fP parameter is non-NULL, the authorization will succeed only if the credential is authorized for that identity\&. Otherwise, any valid authorized local user name will be used\&. If authorized, the local user name will be copied to the string pointed to by the \fIidentity_buffer\fP parameter, which must be at least as long as the value passed as the \fIidentity_buffer_length\fP parameter\&.
.PP
If authorization callouts are defined in the callout configuration file, \fBglobus_gss_assist_map_and_authorize_sharing()\fP will invoke both the GLOBUS_GENERIC_MAPPING_TYPE callout and the GLOBUS_GENERIC_AUTHZ_TYPE callout; otherwise the default gridmap file will be used for mapping and no service-specific authorization will be done\&.
.PP
If \fBglobus_gss_assist_map_and_authorize_sharing()\fP uses a gridmap file, it first looks for a file defined by the value of the GRIDMAP environment variable\&. If that is not set, it falls back to $HOME/\&.gridmap\&.
.PP
\fBParameters:\fP
.RS 4
\fIshared_user_certificate\fP cert and cert chain of user that owns the resources to be shared, in PEM format\&. This will be parsed to find the identity that should be mapped\&. 
.br
\fIcontext\fP Security context of the underlying connection\&. This should generally be ignored\&. 
.br
\fIdesired_identity\fP Optional\&. If non-NULL, perform an authorization to act as the local user named by this NULL-terminated string\&. 
.br
\fIidentity_buffer\fP A pointer to a string buffer into which will be copied the local user name that the peer of the context is authorized to act as\&. 
.br
\fIidentity_buffer_length\fP Length of the \fIidentity_buffer\fP array\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_gss_assist_map_and_authorize_sharing()\fP returns GLOBUS_SUCCESS and copies the authorized local identity to the \fIidentity_buffer\fP parameter\&. If an error occurs, \fBglobus_gss_assist_map_and_authorize_sharing()\fP returns a globus_result_t that can be resolved to an error object\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fIGLOBUS_GSI_GSS_ASSIST_ERROR_WITH_CALLOUT_CONFIG\fP Invalid authorization configuration file 
.br
\fIGLOBUS_CALLOUT_ERROR_WITH_HASHTABLE\fP Hash table operation failed\&. 
.br
\fIGLOBUS_CALLOUT_ERROR_CALLOUT_ERROR\fP The callout itself returned a error\&. 
.br
\fIGLOBUS_CALLOUT_ERROR_WITH_DL\fP Dynamic library operation failed\&. 
.br
\fIGLOBUS_CALLOUT_ERROR_OUT_OF_MEMORY\fP Out of memory 
.br
\fIGLOBUS_GSI_GSS_ASSIST_GSSAPI_ERROR\fP A GSSAPI function returned an error 
.br
\fIGLOBUS_GSI_GSS_ASSIST_GRIDMAP_LOOKUP_FAILED\fP Gridmap lookup failure 
.br
\fIGLOBUS_GSI_GSS_ASSIST_BUFFER_TOO_SMALL\fP Caller provided insufficient buffer space for local identity 
.RE
.PP

.SS "int globus_gss_assist_map_local_user (char * local_user, char ** globusidp)"

.PP
Look up the default Grid identity associated with a local user name\&. The \fBglobus_gss_assist_map_local_user()\fP function parses the gridmap file to determine a if the user name passed as the \fIlocal_user\fP parameter is the default local user for a Grid ID in the gridmap file\&. If so, it modifies \fIglobusidp\fP to point to a copy of that ID\&. Otherwise, it searches the gridmap file for a Grid ID that has a non-default mapping for \fIlocal_user\fP and modifies \fIglobusidp\fP to point to a copy of that ID\&. If successful, the caller is responsible for freeing the string pointed to by the \fIglobusidp\fP pointer\&.
.PP
By default, \fBglobus_gss_assist_map_local_user()\fP looks for the default gridmap file defined by the value of the GRIDMAP environment variable\&. If that is not set, it falls back to $HOME/\&.gridmap\&.
.PP
\fBParameters:\fP
.RS 4
\fIlocal_user\fP The local username to find a Grid ID for 
.br
\fIglobusidp\fP A Grid ID that maps from the local_user\&.
.RE
.PP
\fBReturns:\fP
.RS 4
On success, \fBglobus_gss_assist_map_local_user()\fP returns 0 and modifies \fIglobusidp\fP to point to a Grid ID that maps to \fIlocal_user\fP; otherwise, \fBglobus_gss_assist_map_local_user()\fP returns 1 and the value pointed to by \fIglobusidp\fP is undefined\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fI1\fP Error 
.RE
.PP

.SS "int globus_gss_assist_userok (char * globusid, char * userid)"

.PP
Gridmap entry existence check\&. The \fBglobus_gss_assist_userok()\fP function parses the default gridmap file and checks whether any mapping exists for the grid identity passed as the \fIglobusid\fP parameter and the local user identity passed as the @ userid parameter\&.
.PP
By default, \fBglobus_gss_assist_userok()\fP looks for the default gridmap file defined by the value of the GRIDMAP environment variable\&. If that is not set, it falls back to $HOME/\&.gridmap\&.
.PP
\fBParameters:\fP
.RS 4
\fIglobusid\fP The GSSAPI name string of the identity who requested authorization 
.br
\fIuserid\fP The local account name that access is sought for\&.
.RE
.PP
\fBReturns:\fP
.RS 4
If \fBglobus_gss_assist_userok()\fP is able to find a mapping between \fIglobusid\fP and \fIuserid\fP, it returns 0; otherwise it returns 1\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIGLOBUS_SUCCESS\fP Success 
.br
\fI1\fP Error 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus_gss_assist from the source code\&.