---
name: "globus_gsi_proxy_handle"
section: "3"
platform: "linux"
package: "libglobus-gsi-proxy-core-doc"
version: "9.8-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/globus_gsi_proxy_handle"
---

# globus\_gsi\_proxy\_handle(3)

Handle Management - Create/Destroy/Modify a GSI Proxy Handle.

## NAME

globus\_gsi\_proxy\_handle - Handle Management

 \- Create/Destroy/Modify a GSI Proxy Handle.

## SYNOPSIS

### Typedefs

typedef struct globus\_l\_gsi\_proxy\_handle\_s \* **globus\_gsi\_proxy\_handle\_t**\
 GSI Proxy Handle.

### Functions

globus\_result\_t **globus\_gsi\_proxy\_handle\_init** (**globus\_gsi\_proxy\_handle\_t** \*handle, **globus\_gsi\_proxy\_handle\_attrs\_t** handle\_attrs)\
 Initialize a GSI Proxy handle.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_req** (**globus\_gsi\_proxy\_handle\_t** handle, X509\_REQ \*\*req)\
 Get the certificate request from a GSI Proxy handle.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_private\_key** (**globus\_gsi\_proxy\_handle\_t** handle, EVP\_PKEY \*\*proxy\_key)\
 Get the private key from a GSI Proxy handle.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_type** (**globus\_gsi\_proxy\_handle\_t** handle, globus\_gsi\_cert\_utils\_cert\_type\_t \*type)\
 Get Proxy Type.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_type** (**globus\_gsi\_proxy\_handle\_t** handle, globus\_gsi\_cert\_utils\_cert\_type\_t type)\
 Get Proxy Type.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_policy** (**globus\_gsi\_proxy\_handle\_t** handle, const unsigned char \*policy\_data, int policy\_length, int policy\_language\_NID)\
 Set Policy.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_policy** (**globus\_gsi\_proxy\_handle\_t** handle, unsigned char \*\*policy\_data, int \*policy\_length, int \*policy\_NID)\
 Get Policy.  globus\_result\_t **globus\_gsi\_proxy\_handle\_add\_extension** (**globus\_gsi\_proxy\_handle\_t** handle, X509\_EXTENSION \*ext)\
 Add X.509 Extensions.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_extensions** (**globus\_gsi\_proxy\_handle\_t** handle, STACK\_OF(X509\_EXTENSION) \*exts)\
 Set X.509 Extensions.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_extensions** (**globus\_gsi\_proxy\_handle\_t** handle, STACK\_OF(X509\_EXTENSION) \*\*exts)\
 Get X.509 Extensions.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_pathlen** (**globus\_gsi\_proxy\_handle\_t** handle, long pathlen)\
 Set Path Length.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_pathlen** (**globus\_gsi\_proxy\_handle\_t** handle, int \*pathlen)\
 Get Path Length.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_time\_valid** (**globus\_gsi\_proxy\_handle\_t** handle, int \*time\_valid)\
 Get Time Valid.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_time\_valid** (**globus\_gsi\_proxy\_handle\_t** handle, int time\_valid)\
 Set Time Valid.  globus\_result\_t **globus\_gsi\_proxy\_handle\_clear\_cert\_info** (**globus\_gsi\_proxy\_handle\_t** handle)\
 Clear Cert Info.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_proxy\_cert\_info\_openssl** (**globus\_gsi\_proxy\_handle\_t** handle, PROXY\_CERT\_INFO\_EXTENSION \*\*pci)\
 Get Cert Info.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_proxy\_cert\_info\_openssl** (**globus\_gsi\_proxy\_handle\_t** handle, PROXY\_CERT\_INFO\_EXTENSION \*pci)\
 Set Cert Info.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_signing\_algorithm** (**globus\_gsi\_proxy\_handle\_t** handle, const EVP\_MD \*\*signing\_algorithm)\
 Get Signing Algorithm.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_keybits** (**globus\_gsi\_proxy\_handle\_t** handle, int \*key\_bits)\
 Get Key Bits.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_init\_prime** (**globus\_gsi\_proxy\_handle\_t** handle, int \*init\_prime)\
 Get Init Prime.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_clock\_skew\_allowable** (**globus\_gsi\_proxy\_handle\_t** handle, int \*skew)\
 Get Clock Skew \<\>  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_key\_gen\_callback** (**globus\_gsi\_proxy\_handle\_t** handle, void(\*\*callback)(int, int, void \*))\
 Get Callback for Creating Keys.  globus\_result\_t **globus\_gsi\_proxy\_handle\_get\_common\_name** (**globus\_gsi\_proxy\_handle\_t** handle, char \*\*common\_name)\
 Get/Set Proxy Common Name.  globus\_result\_t **globus\_gsi\_proxy\_handle\_set\_is\_limited** (**globus\_gsi\_proxy\_handle\_t** handle, globus\_bool\_t is\_limited)\
 Set/Check Proxy Is Limited.

## Detailed Description

Create/Destroy/Modify a GSI Proxy Handle.

Within the Globus GSI Proxy Library, all proxy operations require a handle parameter. Currently, only one proxy operation may be in progress at once per proxy handle.

This section defines operations to create, modify and destroy GSI Proxy handles.

## Typedef Documentation

### typedef struct globus\_l\_gsi\_proxy\_handle\_s\* globus\_gsi\_proxy\_handle\_t

GSI Proxy Handle. An GSI Proxy handle is used to associate state with a group of operations. Handles can have immutable **attributes** associated with them. All proxy **operations**  take a handle pointer as a parameter.

**See also**

**globus\_gsi\_proxy\_handle\_init()**, **globus\_gsi\_proxy\_handle\_destroy()**, **Handle Attributes**

## Function Documentation

### globus\_result\_t globus\_gsi\_proxy\_handle\_add\_extension (globus\_gsi\_proxy\_handle\_t handle, X509\_EXTENSION \* ext)

Add X.509 Extensions. Add an X.509 extension to the GSI Proxy handle to be added to certificate

This function adds a X.509 extension to the proxy certificate.

**Parameters**

*handle* The handle for the proxy to which the extension should be added. \
 *ext* The extension to be added.

**Returns**

GLOBUS\_SUCCESS if the addition was successful, otherwise an error is returned.

**See also**

**globus\_gsi\_proxy\_handle\_get\_extensions()**

**globus\_gsi\_proxy\_handle\_set\_extensions()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_clear\_cert\_info (globus\_gsi\_proxy\_handle\_t handle)

Clear Cert Info. Clear the proxy cert info extension stored in the GSI Proxy handle.

This function clears proxy cert info extension related setting in the GSI Proxy handle.

**Parameters**

*handle* The handle for which to clear the proxy cert info extension.

**Returns**

GLOBUS\_SUCCESS if the handle is valid, otherwise an error is returned

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_clock\_skew\_allowable (globus\_gsi\_proxy\_handle\_t handle, int \* skew)

Get Clock Skew \<\> Get the clock skew of the proxy handle

**Parameters**

*handle* The handle to get the clock skew of \
 *skew* The resulting clock skew

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case an error object identifier (in the form of a globus\_result\_t) is returned

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_common\_name (globus\_gsi\_proxy\_handle\_t handle, char \*\* common\_name)

Get/Set Proxy Common Name. Get the proxy common name stored in the GSI Proxy handle.

This function retrieves the proxy common name from the GSI Proxy handle. The common name only impacts draft compliant proxies.

**Parameters**

*handle* The handle from which to get the proxy common name. \
 *common\_name* Contains the proxy common name upon successful return. If the handle does not contain a common name, this parameter will be NULL upon return.

**Returns**

GLOBUS\_SUCCESS upon success GLOBUS\_GSI\_PROXY\_ERROR\_WITH\_HANDLE if handle is invalid

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_extensions (globus\_gsi\_proxy\_handle\_t handle, STACK\_OF(X509\_EXTENSION) \*\* exts)

Get X.509 Extensions. Get the X.509 extensions from a GSI Proxy handle

This function returns the X.509 extensions from the proxy certificate.

**Parameters**

*handle* The handle for the proxy from which the extensions should be retrieved. \
 *exts* The variable to hold the extensions. The caller is responsible for freeing the extensions with sk\_X509\_EXTENSION\_free() when they are done with them.

**Returns**

GLOBUS\_SUCCESS if the retrieval was successful, otherwise an error is returned.

**See also**

**globus\_gsi\_proxy\_handle\_add\_extension()**

**globus\_gsi\_proxy\_handle\_set\_extensions()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_init\_prime (globus\_gsi\_proxy\_handle\_t handle, int \* init\_prime)

Get Init Prime. Get the init prime of the proxy handle

**Parameters**

*handle* The handle to get the init prime used in generating the key pair \
 *init\_prime* The resulting init prime

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case an error object identifier (in the form of a globus\_result\_t) is returned

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_key\_gen\_callback (globus\_gsi\_proxy\_handle\_t handle, void(\*\*)(int, int, void \*) callback)

Get Callback for Creating Keys. Get the callback for creating the public/private key pair

**Parameters**

*handle* The proxy handle to get the callback from \
 *callback* Parameter used for returning the callback

**Returns**

GLOBUS\_SUCCESS or an error object identifier

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_keybits (globus\_gsi\_proxy\_handle\_t handle, int \* key\_bits)

Get Key Bits. Get the key bits used for the pub/private key pair of the proxy

**Parameters**

*handle* The proxy handle to get the key bits of \
 *key\_bits* key bits of the proxy handle

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned GLOBUS\_SUCCESS

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_pathlen (globus\_gsi\_proxy\_handle\_t handle, int \* pathlen)

Get Path Length. Get the path length from the GSI Proxy handle.

This function gets the path length that is being used in the proxy cert info extension.

**Parameters**

*handle* The handle to be interrogated. \
 *pathlen* The maximum allowable path length

**Returns**

GLOBUS\_SUCCESS if the handle is valid, otherwise an error is returned

**See also**

**globus\_gsi\_proxy\_handle\_set\_pathlen()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_policy (globus\_gsi\_proxy\_handle\_t handle, unsigned char \*\* policy\_data, int \* policy\_length, int \* policy\_NID)

Get Policy. Get the policy from the GSI Proxy handle.

This function gets the policy that is being used in the proxy cert info extension.

**Parameters**

*handle* The handle to be interrogated. \
 *policy\_data* The policy data. \
 *policy\_length* The length of the returned policy \
 *policy\_NID* The NID of the policy language.

**Returns**

GLOBUS\_SUCCESS if the handle is valid, otherwise an error is returned

**See also**

**globus\_gsi\_proxy\_handle\_set\_policy()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_private\_key (globus\_gsi\_proxy\_handle\_t handle, EVP\_PKEY \*\* proxy\_key)

Get the private key from a GSI Proxy handle. Copies the private key associated with the proxy handle to the value pointed to by the proxy\_key parameter.

**Parameters**

*handle* The handle from which to get the private key \
 *proxy\_key* Parameter used to return the key. It is the users responsibility to free the returned key by calling EVP\_PKEY\_free().

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

**See also**

globus\_gsi\_proxy\_handle\_set\_private\_key()

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_proxy\_cert\_info\_openssl (globus\_gsi\_proxy\_handle\_t handle, PROXY\_CERT\_INFO\_EXTENSION \*\* pci)

Get Cert Info. Get the proxy cert info extension stored in the GSI Proxy handle.

This function retrieves the proxy cert info extension from the GSI Proxy handle.

**Parameters**

*handle* The handle from which to get the proxy cert info extension. \
 *pci* Contains the proxy cert info extension upon successful return. If the handle does not contain a pci extension, this parameter will be NULL upon return.

**Returns**

GLOBUS\_SUCCESS upon success GLOBUS\_GSI\_PROXY\_ERROR\_WITH\_HANDLE if handle is invalid GLOBUS\_GSI\_PROXY\_ERROR\_WITH\_PROXYCERTINFO if the pci pointer is invalid or if the get failed.

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_req (globus\_gsi\_proxy\_handle\_t handle, X509\_REQ \*\* req)

Get the certificate request from a GSI Proxy handle. Copies the certificate request associated with the proxy handle to the req parameter.

**Parameters**

*handle* The handle from which to get the certificate request \
 *req* Parameter used to return the request. It is the users responsibility to free the returned request.

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

**See also**

globus\_gsi\_proxy\_handle\_set\_req()

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_signing\_algorithm (globus\_gsi\_proxy\_handle\_t handle, const EVP\_MD \*\* signing\_algorithm)

Get Signing Algorithm. Get the signing algorithm used to sign the proxy cert request

**Parameters**

*handle* The proxy handle containing the type of signing algorithm used \
 *signing\_algorithm* signing algorithm of the proxy handle

**Return values**

*GLOBUS\_SUCCESS* unless an error occurred, in which case, a globus error object ID is returned

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_time\_valid (globus\_gsi\_proxy\_handle\_t handle, int \* time\_valid)

Get Time Valid. Get the validity time of the proxy

**Parameters**

*handle* The proxy handle to get the expiration date of \
 *time\_valid* expiration date of the proxy handle

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

### globus\_result\_t globus\_gsi\_proxy\_handle\_get\_type (globus\_gsi\_proxy\_handle\_t handle, globus\_gsi\_cert\_utils\_cert\_type\_t \* type)

Get Proxy Type. Determine the type of proxy that will be generated when using this handle.

**Parameters**

*handle* The handle from which to get the type \
 *type* Parameter used to return the type.

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

**See also**

**globus\_gsi\_proxy\_handle\_set\_type()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_init (globus\_gsi\_proxy\_handle\_t \* handle, globus\_gsi\_proxy\_handle\_attrs\_t handle\_attrs)

Initialize a GSI Proxy handle. Initialize a proxy handle which can be used in subsequent operations. The handle may only be used in one sequence of operations at a time.

**Parameters**

*handle* A pointer to the handle to be initialized. If the handle is originally NULL, space is allocated for it. Otherwise, the current values of the handle are overwritten.\
 *handle\_attrs* Initial attributes to be used to create this handle.

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

**See also**

globus\_gsi\_proxy\_handle\_destroy()

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_extensions (globus\_gsi\_proxy\_handle\_t handle, STACK\_OF(X509\_EXTENSION) \* exts)

Set X.509 Extensions. Set the X.509 extensions from a GSI Proxy handle

This function sets the X.509 extensions for a proxy certificate.

**Parameters**

*handle* The handle for the proxy from which the extension should be set. \
 *exts* The extensions to be set. Can be NULL to clear extensions.

**Returns**

GLOBUS\_SUCCESS if the addition was successful, otherwise an error is returned.

**See also**

**globus\_gsi\_proxy\_handle\_add\_extension()**

**globus\_gsi\_proxy\_handle\_get\_extensions()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_is\_limited (globus\_gsi\_proxy\_handle\_t handle, globus\_bool\_t is\_limited)

Set/Check Proxy Is Limited. Set the limited proxy flag on the proxy handle

**Parameters**

*handle* the proxy handle \
 *is\_limited* boolean value to set on the proxy handle

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_pathlen (globus\_gsi\_proxy\_handle\_t handle, long pathlen)

Set Path Length. Set the path length to be used in the GSI Proxy handle.

This function sets the path length to be used in the proxy cert info extension.

**Parameters**

*handle* The handle to be modified. \
 *pathlen* The maximum allowable path length

**Returns**

GLOBUS\_SUCCESS if the handle is valid, otherwise an error is returned

**See also**

**globus\_gsi\_proxy\_handle\_get\_pathlen()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_policy (globus\_gsi\_proxy\_handle\_t handle, const unsigned char \* policy\_data, int policy\_length, int policy\_language\_NID)

Set Policy. Set the policy to be used in the GSI Proxy handle.

This function sets the policy to be used in the proxy cert info extension.

**Parameters**

*handle* The handle to be modified. \
 *policy\_data* The policy data. \
 *policy\_length* The length of the policy data \
 *policy\_language\_NID* The NID of the policy language.

**Returns**

GLOBUS\_SUCCESS if the handle and its associated fields are valid otherwise an error is returned

**See also**

**globus\_gsi\_proxy\_handle\_get\_policy()**

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_proxy\_cert\_info\_openssl (globus\_gsi\_proxy\_handle\_t handle, PROXY\_CERT\_INFO\_EXTENSION \* pci)

Set Cert Info. Set the proxy cert info extension stored in the GSI Proxy handle.

This function sets the proxy cert info extension in the GSI Proxy handle.

**Parameters**

*handle* The handle for which to set the proxy cert info extension. \
 *pci* The proxy cert info extension to set.

**Return values**

*GLOBUS\_SUCCESS* Success \
 *GLOBUS\_GSI\_PROXY\_ERROR\_WITH\_HANDLE* Handle is invalid \
 *GLOBUS\_GSI\_PROXY\_ERROR\_WITH\_PROXYCERTINFO* pci pointer is invalid or if the set failed.

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_time\_valid (globus\_gsi\_proxy\_handle\_t handle, int time\_valid)

Set Time Valid. Set the validity time of the proxy

**Parameters**

*handle* The proxy handle to set the expiration date for \
 *time\_valid* desired expiration date of the proxy

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned GLOBUS\_SUCCESS

### globus\_result\_t globus\_gsi\_proxy\_handle\_set\_type (globus\_gsi\_proxy\_handle\_t handle, globus\_gsi\_cert\_utils\_cert\_type\_t type)

Get Proxy Type. Set the type of proxy that will be generated when using this handle. Note that this will have no effect when generating a proxy from a proxy. In that case the generated proxy will inherit the type of the parent.

**Parameters**

*handle* The handle for which to set the type \
 *type* Parameter used to pass the type.

**Returns**

GLOBUS\_SUCCESS unless an error occurred, in which case, a globus error object ID is returned

**See also**

**globus\_gsi\_proxy\_handle\_set\_type()**

## Author

Generated automatically by Doxygen for globus\_gsi\_proxy\_core from the source code.