--- name: "globus_gss_assist_gridmap" section: "3" platform: "linux" package: "libglobus-gss-assist-doc" version: "12.7-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_gss_assist_gridmap" --- # globus\_gss\_assist\_gridmap(3) Gridmap Authorization - Gridmap Authorization and Local User Mapping. ## NAME globus\_gss\_assist\_gridmap - Gridmap Authorization \- Gridmap Authorization and Local User Mapping. ## SYNOPSIS ### Macros \#define **GlobusGssAssistFreeDNArray**(dn\_a)\ Free array of distinguished names. ### Functions int **globus\_gss\_assist\_gridmap** (char \*globusidp, char \*\*useridp)\ Look up the default mapping for a Grid identity in a gridmap file. int **globus\_gss\_assist\_userok** (char \*globusid, char \*userid)\ Gridmap entry existence check. int **globus\_gss\_assist\_map\_local\_user** (char \*local\_user, char \*\*globusidp)\ Look up the default Grid identity associated with a local user name. globus\_result\_t **globus\_gss\_assist\_lookup\_all\_globusid** (char \*username, char \*\*dns\[\], int \*dn\_count)\ Look up all Grid IDs associated with a local user ID. 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)\ Authorize the peer of a security context to use a service. 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)\ Authorize a particular credential for shared access. ## Detailed Description 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. ## Macro Definition Documentation ### #define GlobusGssAssistFreeDNArray(dn\_a) Free array of distinguished names. Free the contents of a name array created during a successful call to **globus\_gss\_assist\_lookup\_all\_globusid()** **Parameters** *dn\_a* Array of names to free. **Return values** *void* ## Function Documentation ### int globus\_gss\_assist\_gridmap (char \* globusidp, char \*\* useridp) Look up the default mapping for a Grid identity in a gridmap file. The **globus\_gss\_assist\_gridmap()** function parses the default gridmap file and modifies its *useridp* 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 *useridp*. By default, **globus\_gss\_assist\_gridmap()** 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. **Parameters** *globusidp* The GSSAPI name string of the identity who requested authorization \ *useridp* 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. **Returns** On success, **globus\_gss\_assist\_gridmap()** returns 0 and modifies the the string pointed to by the *useridp* parameter. If an error occurs, a non-zero value is returned and the value pointed to by *useridp* is undefined. **Return values** *GLOBUS\_SUCCESS* Success \ *1* Error ### globus\_result\_t globus\_gss\_assist\_lookup\_all\_globusid (char \* username, char \*\* dns\[\], int \* dn\_count) Look up all Grid IDs associated with a local user ID. The **globus\_gss\_assist\_lookup\_all\_globusid()** function parses a gridmap file and finds all Grid IDs that map to a local user ID. The *dns* parameter is modified to point to an array of Grid ID strings from the gridmap file, and the *dn\_count* 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 **GlobusGssAssistFreeDNArray().** **By default, globus\_gss\_assist\_lookup\_all\_globusid() 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.** **Parameters** *username* **The local username to look up in the gridmap file.** \ *dns* **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 GlobusGssAssistFreeDNArray() to free this memory.** \ *dn\_count* **A pointer to an integer that is modified to contain the number of entries in the array returned via the** *dns* **parameter.** **Returns** **On success, globus\_gss\_assist\_lookup\_all\_globusid() returns GLOBUS\_SUCCESS and modifies its** *dns* **and** *dn\_count* **parameters as described above. If an error occurs, globus\_gss\_assist\_lookup\_all\_globusid() returns a globus\_result\_t that can be resolved to an error object and the values pointed to by** *dns* **and** *dn\_count* **are undefined.** **Return values** *GLOBUS\_SUCCESS* **Success** \ *GLOBUS\_GSI\_GSS\_ASSIST\_ERROR\_WITH\_ARGUMENTS* **Error with arguments** \ *GLOBUS\_GSI\_GSS\_ASSIST\_ERROR\_WITH\_GRIDMAP* **Invalid path to gridmap** \ *GLOBUS\_GSI\_GSS\_ASSIST\_ERROR\_ERRNO* **System error** ### 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) **Authorize the peer of a security context to use a service. The globus\_gss\_assist\_map\_and\_authorize() function attempts to authorize the peer of a security context to use a particular service. If the** *desired\_identity* **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** *identity\_buffer* **parameter, which must be at least as long as the value passed as the** *identity\_buffer\_length* **parameter.** **If authorization callouts are defined in the callout configuration file, globus\_gss\_assist\_map\_and\_authorize() 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.** **If globus\_gss\_assist\_map\_and\_authorize() 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.** **Parameters** *context* **Security context to inspect for peer identity information.** \ *service* **A NULL-terminated string containing the name of the service that an authorization decision is being made for.** \ *desired\_identity* **Optional. If non-NULL, perform an authorization to act as the local user named by this NULL-terminated string.** \ *identity\_buffer* **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.** \ *identity\_buffer\_length* **Length of the** *identity\_buffer* **array.** **Returns** **On success, globus\_gss\_assist\_map\_and\_authorize() returns GLOBUS\_SUCCESS and copies the authorized local identity to the** *identity\_buffer* **parameter. If an error occurs, globus\_gss\_assist\_map\_and\_authorize() returns a globus\_result\_t that can be resolved to an error object.** **Return values** *GLOBUS\_SUCCESS* **Success** \ *GLOBUS\_GSI\_GSS\_ASSIST\_ERROR\_WITH\_CALLOUT\_CONFIG* **Invalid authorization configuration file** \ *GLOBUS\_CALLOUT\_ERROR\_WITH\_HASHTABLE* \ \ **Hash table operation failed.** \ *GLOBUS\_CALLOUT\_ERROR\_CALLOUT\_ERROR* **The callout itself returned a error.** \ *GLOBUS\_CALLOUT\_ERROR\_WITH\_DL* **Dynamic library operation failed.** \ *GLOBUS\_CALLOUT\_ERROR\_OUT\_OF\_MEMORY* **Out of memory** \ *GLOBUS\_GSI\_GSS\_ASSIST\_GSSAPI\_ERROR* **A GSSAPI function returned an error** \ *GLOBUS\_GSI\_GSS\_ASSIST\_GRIDMAP\_LOOKUP\_FAILED* **Gridmap lookup failure** \ *GLOBUS\_GSI\_GSS\_ASSIST\_BUFFER\_TOO\_SMALL* **Caller provided insufficient buffer space for local identity** ### 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) **Authorize a particular credential for shared access. The globus\_gss\_assist\_map\_and\_authorize\_sharing() function attempts to authorize a particular credential for shared access. the** *desired\_identity* **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** *identity\_buffer* **parameter, which must be at least as long as the value passed as the** *identity\_buffer\_length* **parameter.** **If authorization callouts are defined in the callout configuration file, globus\_gss\_assist\_map\_and\_authorize\_sharing() 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.** **If globus\_gss\_assist\_map\_and\_authorize\_sharing() 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.** **Parameters** *shared\_user\_certificate* **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.** \ *context* **Security context of the underlying connection. This should generally be ignored.** \ *desired\_identity* **Optional. If non-NULL, perform an authorization to act as the local user named by this NULL-terminated string.** \ *identity\_buffer* **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.** \ *identity\_buffer\_length* **Length of the** *identity\_buffer* **array.** **Returns** **On success, globus\_gss\_assist\_map\_and\_authorize\_sharing() returns GLOBUS\_SUCCESS and copies the authorized local identity to the** *identity\_buffer* **parameter. If an error occurs, globus\_gss\_assist\_map\_and\_authorize\_sharing() returns a globus\_result\_t that can be resolved to an error object.** **Return values** *GLOBUS\_SUCCESS* **Success** \ *GLOBUS\_GSI\_GSS\_ASSIST\_ERROR\_WITH\_CALLOUT\_CONFIG* **Invalid authorization configuration file** \ *GLOBUS\_CALLOUT\_ERROR\_WITH\_HASHTABLE* \ \ **Hash table operation failed.** \ *GLOBUS\_CALLOUT\_ERROR\_CALLOUT\_ERROR* **The callout itself returned a error.** \ *GLOBUS\_CALLOUT\_ERROR\_WITH\_DL* **Dynamic library operation failed.** \ *GLOBUS\_CALLOUT\_ERROR\_OUT\_OF\_MEMORY* **Out of memory** \ *GLOBUS\_GSI\_GSS\_ASSIST\_GSSAPI\_ERROR* **A GSSAPI function returned an error** \ *GLOBUS\_GSI\_GSS\_ASSIST\_GRIDMAP\_LOOKUP\_FAILED* **Gridmap lookup failure** \ *GLOBUS\_GSI\_GSS\_ASSIST\_BUFFER\_TOO\_SMALL* **Caller provided insufficient buffer space for local identity** ### int globus\_gss\_assist\_map\_local\_user (char \* local\_user, char \*\* globusidp) **Look up the default Grid identity associated with a local user name. The globus\_gss\_assist\_map\_local\_user() function parses the gridmap file to determine a if the user name passed as the** *local\_user* **parameter is the default local user for a Grid ID in the gridmap file. If so, it modifies** *globusidp* **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** *local\_user* **and modifies** *globusidp* **to point to a copy of that ID. If successful, the caller is responsible for freeing the string pointed to by the** *globusidp* **pointer.** **By default, globus\_gss\_assist\_map\_local\_user() 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.** **Parameters** *local\_user* **The local username to find a Grid ID for** \ *globusidp* **A Grid ID that maps from the local\_user.** **Returns** **On success, globus\_gss\_assist\_map\_local\_user() returns 0 and modifies** *globusidp* **to point to a Grid ID that maps to** *local\_user***; otherwise, globus\_gss\_assist\_map\_local\_user() returns 1 and the value pointed to by** *globusidp* **is undefined.** **Return values** *GLOBUS\_SUCCESS* **Success** \ *1* **Error** ### int globus\_gss\_assist\_userok (char \* globusid, char \* userid) **Gridmap entry existence check. The globus\_gss\_assist\_userok() function parses the default gridmap file and checks whether any mapping exists for the grid identity passed as the** *globusid* **parameter and the local user identity passed as the @ userid parameter.** **By default, globus\_gss\_assist\_userok() 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.** **Parameters** *globusid* **The GSSAPI name string of the identity who requested authorization** \ *userid* **The local account name that access is sought for.** **Returns** **If globus\_gss\_assist\_userok() is able to find a mapping between** *globusid* **and** *userid***, it returns 0; otherwise it returns 1.** **Return values** *GLOBUS\_SUCCESS* **Success** \ *1* **Error** ## Author **Generated automatically by Doxygen for globus\_gss\_assist from the source code.**