--- name: "globus_gsi_cred_set_key" section: "3" platform: "linux" package: "libglobus-gsi-credential-doc" version: "8.4-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_gsi_cred_handle" --- # globus\_gsi\_cred\_set\_key(3) Credential Handle Management - Credential Handle Management. Part of [globus\_gsi\_cred\_handle(3)](/globus_gsi_cred_handle/3.md). ## NAME globus\_gsi\_cred\_handle - Credential Handle Management \- Credential Handle Management. ## SYNOPSIS ### Typedefs typedef struct globus\_l\_gsi\_cred\_handle\_s \* **globus\_gsi\_cred\_handle\_t**\ ### Functions globus\_result\_t **globus\_gsi\_cred\_handle\_init** (**globus\_gsi\_cred\_handle\_t** \*handle, **globus\_gsi\_cred\_handle\_attrs\_t** handle\_attrs)\ Initialize a Handle. globus\_result\_t **globus\_gsi\_cred\_handle\_destroy** (**globus\_gsi\_cred\_handle\_t** handle)\ Destroy the credential handle. globus\_result\_t **globus\_gsi\_cred\_handle\_copy** (**globus\_gsi\_cred\_handle\_t** source, **globus\_gsi\_cred\_handle\_t** \*dest)\ Copy a handle. globus\_result\_t **globus\_gsi\_cred\_get\_handle\_attrs** (**globus\_gsi\_cred\_handle\_t** handle, **globus\_gsi\_cred\_handle\_attrs\_t** \*attrs)\ Get the handle attributes. globus\_result\_t **globus\_gsi\_cred\_get\_goodtill** (**globus\_gsi\_cred\_handle\_t** cred\_handle, time\_t \*goodtill)\ Get credential expiration. globus\_result\_t **globus\_gsi\_cred\_get\_lifetime** (**globus\_gsi\_cred\_handle\_t** cred\_handle, time\_t \*lifetime)\ Get credential lifetime. globus\_result\_t **globus\_gsi\_cred\_get\_key\_bits** (**globus\_gsi\_cred\_handle\_t** cred\_handle, int \*key\_bits)\ Get credential strength. globus\_result\_t **globus\_gsi\_cred\_set\_cert** (**globus\_gsi\_cred\_handle\_t** handle, X509 \*cert)\ Set the credential's certificate. globus\_result\_t **globus\_gsi\_cred\_get\_cert** (**globus\_gsi\_cred\_handle\_t** handle, X509 \*\*cert)\ Get the credential's certificate. globus\_result\_t **globus\_gsi\_cred\_set\_key** (**globus\_gsi\_cred\_handle\_t** handle, EVP\_PKEY \*key)\ Set the credential's private key. globus\_result\_t **globus\_gsi\_cred\_get\_key** (**globus\_gsi\_cred\_handle\_t** handle, EVP\_PKEY \*\*key)\ Get the credential's private key. globus\_result\_t **globus\_gsi\_cred\_set\_cert\_chain** (**globus\_gsi\_cred\_handle\_t** handle, STACK\_OF(X509) \*cert\_chain)\ Set the certificate chain. globus\_result\_t **globus\_gsi\_cred\_get\_cert\_chain** (**globus\_gsi\_cred\_handle\_t** handle, STACK\_OF(X509) \*\*cert\_chain)\ Get the certificate chain. globus\_result\_t **globus\_gsi\_cred\_get\_X509\_subject\_name** (**globus\_gsi\_cred\_handle\_t** handle, X509\_NAME \*\*subject\_name)\ Get credential subject name. globus\_result\_t **globus\_gsi\_cred\_get\_X509\_identity\_name** (**globus\_gsi\_cred\_handle\_t** handle, X509\_NAME \*\*identity\_name)\ Get X.509 identity. globus\_result\_t **globus\_gsi\_cred\_get\_subject\_name** (**globus\_gsi\_cred\_handle\_t** handle, char \*\*subject\_name)\ Get credential subject name. globus\_result\_t **globus\_gsi\_cred\_get\_policies** (**globus\_gsi\_cred\_handle\_t** handle, STACK\_OF(OPENSSL\_STRING) \*\*policies)\ Get certificate chain policies. globus\_result\_t **globus\_gsi\_cred\_get\_policy\_languages** (**globus\_gsi\_cred\_handle\_t** handle, STACK\_OF(ASN1\_OBJECT) \*\*policy\_languages)\ Get certificate chain policy languages. globus\_result\_t **globus\_gsi\_cred\_get\_X509\_issuer\_name** (**globus\_gsi\_cred\_handle\_t** handle, X509\_NAME \*\*issuer\_name)\ Get credential issuer name object. globus\_result\_t **globus\_gsi\_cred\_get\_issuer\_name** (**globus\_gsi\_cred\_handle\_t** handle, char \*\*issuer\_name)\ Get issuer name. globus\_result\_t **globus\_gsi\_cred\_get\_identity\_name** (**globus\_gsi\_cred\_handle\_t** handle, char \*\*identity\_name)\ Get identity name. globus\_result\_t **globus\_gsi\_cred\_verify\_cert\_chain** (**globus\_gsi\_cred\_handle\_t** cred\_handle, globus\_gsi\_callback\_data\_t callback\_data)\ Verify credential. globus\_result\_t **globus\_gsi\_cred\_verify\_cert\_chain\_when** (**globus\_gsi\_cred\_handle\_t** cred\_handle, globus\_gsi\_callback\_data\_t callback\_data\_in, time\_t check\_time)\ Verify credential at a specific time. globus\_result\_t **globus\_gsi\_cred\_verify** (**globus\_gsi\_cred\_handle\_t** handle)\ Verify a credential. ## Detailed Description Credential Handle Management. Create/Destroy/Modify a GSI Credential Handle. Within the Globus GSI Credential Library, all credential operations require a handle parameter. Currently only one operation may be in progress at once per credential handle. This section defines operations to create, modify and destroy GSI Credential handles. ## Typedef Documentation ### typedef struct globus\_l\_gsi\_cred\_handle\_s\* globus\_gsi\_cred\_handle\_t GSI Credential Handle. A GSI Credential handle keeps track of state relating to a credential. Handles can have immutable **attributes** associated with them. All credential **operations** take a credential handle pointer as a parameter. **See also** **globus\_gsi\_cred\_handle\_init()**, **globus\_gsi\_cred\_handle\_destroy()**, **globus\_gsi\_cred\_handle\_attrs\_t** ## Function Documentation ### globus\_result\_t globus\_gsi\_cred\_get\_cert (globus\_gsi\_cred\_handle\_t handle, X509 \*\* cert) Get the credential's certificate. Get the certificate of a credential **Parameters** *handle* The credential handle to get the certificate from \ *cert* The resulting X509 certificate, a duplicate of the certificate in the credential handle. This variable should be freed when the user is finished with it using the function X509\_free. **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object id is returned ### globus\_result\_t globus\_gsi\_cred\_get\_cert\_chain (globus\_gsi\_cred\_handle\_t handle, STACK\_OF(X509) \*\* cert\_chain) Get the certificate chain. Get the certificate chain of the credential handle **Parameters** *handle* The credential handle containing the certificate chain to get \ *cert\_chain* The certificate chain to set as a duplicate of the cert chain in the credential handle. This variable (or the variable it points to) needs to be freed when the user is finished with it using sk\_X509\_free. **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object id is returned ### globus\_result\_t globus\_gsi\_cred\_get\_goodtill (globus\_gsi\_cred\_handle\_t cred\_handle, time\_t \* goodtill) Get credential expiration. This function retrieves the expiration time of the credential contained in the handle **Parameters** *cred\_handle* The credential handle to retrieve the expiration time from \ *goodtill* Contains the expiration time on return **Returns** GLOBUS\_SUCCESS or an error captured in a globus\_result\_t ### globus\_result\_t globus\_gsi\_cred\_get\_handle\_attrs (globus\_gsi\_cred\_handle\_t handle, globus\_gsi\_cred\_handle\_attrs\_t \* attrs) Get the handle attributes. This function retrieves a copy of the credential handle attributes **Parameters** *handle* The credential handle to retrieve the attributes from \ *attrs* Contains the credential attributes on return **Returns** GLOBUS\_SUCCESS or an error captured in a globus\_result\_t ### globus\_result\_t globus\_gsi\_cred\_get\_identity\_name (globus\_gsi\_cred\_handle\_t handle, char \*\* identity\_name) Get identity name. Get the identity's subject name from the credential handle **Parameters** *handle* The credential handle containing the certificate to get the identity of \ *identity\_name* The identity certificate's subject name **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object identifier is returned ### globus\_result\_t globus\_gsi\_cred\_get\_issuer\_name (globus\_gsi\_cred\_handle\_t handle, char \*\* issuer\_name) Get issuer name. Get the issuer's subject name from the credential handle **Parameters** *handle* The credential handle containing the certificate to get the issuer of \ *issuer\_name* The issuer certificate's subject name **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object identifier is returned ### globus\_result\_t globus\_gsi\_cred\_get\_key (globus\_gsi\_cred\_handle\_t handle, EVP\_PKEY \*\* key) Get the credential's private key. Get the credential handle's private key **Parameters** *handle* The credential handle containing the private key to get \ *key* The private key which after this function returns is set to a duplicate of the private key of the credential handle. This variable needs to be freed by the user when it is no longer used via the function EVP\_PKEY\_free. **Returns** GLOBUS\_SUCCESS or an error object identifier ### globus\_result\_t globus\_gsi\_cred\_get\_key\_bits (globus\_gsi\_cred\_handle\_t cred\_handle, int \* key\_bits) Get credential strength. This function retrieves the key strength of the credential contained in a handle **Parameters** *cred\_handle* The credential handle to retrieve the strength from \ *key\_bits* Contains the number of bits in the key on return **Returns** GLOBUS\_SUCCESS or an error captured in a globus\_result\_t ### globus\_result\_t globus\_gsi\_cred\_get\_lifetime (globus\_gsi\_cred\_handle\_t cred\_handle, time\_t \* lifetime) Get credential lifetime. This function retrieves the lifetime of the credential contained in a handle **Parameters** *cred\_handle* The credential handle to retrieve the lifetime from \ *lifetime* Contains the lifetime on return **Returns** GLOBUS\_SUCCESS or an error captured in a globus\_result\_t ### globus\_result\_t globus\_gsi\_cred\_get\_policies (globus\_gsi\_cred\_handle\_t handle, STACK\_OF(OPENSSL\_STRING) \*\* policies) Get certificate chain policies. Get the Policies from the Cert Chain in the handle. The policies will be null-terminated as they are added to the handle. If a policy for a cert in the chain doesn't exist, the string in the stack will be set to the static string GLOBUS\_NULL\_POLICIES **Parameters** *handle* the handle to get the cert chain containing the policies \ *policies* the stack of policies retrieved from the handle's cert chain **Returns** GLOBUS\_SUCCESS or an error object if an error occurred ### globus\_result\_t globus\_gsi\_cred\_get\_policy\_languages (globus\_gsi\_cred\_handle\_t handle, STACK\_OF(ASN1\_OBJECT) \*\* policy\_languages) Get certificate chain policy languages. Get the policy languages from the cert chain in the handle. **Parameters** *handle* the handle to get the cert chain containing the policies \ *policy\_languages* the stack of policies retrieved from the handle's cert chain **Returns** GLOBUS\_SUCCESS or an error object if an error occurred ### globus\_result\_t globus\_gsi\_cred\_get\_subject\_name (globus\_gsi\_cred\_handle\_t handle, char \*\* subject\_name) Get credential subject name. Get the credential handle's certificate subject name **Parameters** *handle* The credential handle containing the certificate to get the subject name of \ *subject\_name* The subject name as a string. This should be freed using OPENSSL\_free() when the user is finished with it **Returns** GLOBUS\_SUCCESS if no error, a error object id otherwise ### globus\_result\_t globus\_gsi\_cred\_get\_X509\_identity\_name (globus\_gsi\_cred\_handle\_t handle, X509\_NAME \*\* identity\_name) Get X.509 identity. Get the identity's X.509 subject name from the credential handle **Parameters** *handle* The credential handle containing the certificate to get the identity from \ *identity\_name* The identity certificate's X509 subject name **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object identifier is returned ### globus\_result\_t globus\_gsi\_cred\_get\_X509\_issuer\_name (globus\_gsi\_cred\_handle\_t handle, X509\_NAME \*\* issuer\_name) Get credential issuer name object. Get the credential handle's certificate issuer name **Parameters** *handle* The credential handle containing the certificate to get the issuer name of \ *issuer\_name* The issuer name as an X509\_NAME object. This should be freed using X509\_NAME\_free when the user is finished with it **Returns** GLOBUS\_SUCCESS if no error, a error object id otherwise ### globus\_result\_t globus\_gsi\_cred\_get\_X509\_subject\_name (globus\_gsi\_cred\_handle\_t handle, X509\_NAME \*\* subject\_name) Get credential subject name. Get the credential handle's certificate subject name **Parameters** *handle* The credential handle containing the certificate to get the subject name of \ *subject\_name* The subject name as an X509\_NAME object. This should be freed using X509\_NAME\_free when the user is finished with it **Returns** GLOBUS\_SUCCESS if no error, a error object id otherwise ### globus\_result\_t globus\_gsi\_cred\_handle\_copy (globus\_gsi\_cred\_handle\_t source, globus\_gsi\_cred\_handle\_t \* dest) Copy a handle. Copies a credential handle. **Parameters** *source* The handle to be copied \ *dest* The destination of the copy **Returns** GLOBUS\_SUCCESS or an error captured in a globus\_result\_t ### globus\_result\_t globus\_gsi\_cred\_handle\_destroy (globus\_gsi\_cred\_handle\_t handle) Destroy the credential handle. Destroys the credential handle **Parameters** *handle* The credential handle to be destroyed **Returns** GLOBUS\_SUCCESS ### globus\_result\_t globus\_gsi\_cred\_handle\_init (globus\_gsi\_cred\_handle\_t \* handle, globus\_gsi\_cred\_handle\_attrs\_t handle\_attrs) Initialize a Handle. Initializes a credential handle to be used credential handling functions. Takes a set of handle attributes that are immutable to the handle. The handle attributes are only pointed to by the handle, so the lifetime of the attributes needs to be as long as that of the handle. **Parameters** *handle* The handle to be initialized \ *handle\_attrs* The immutable attributes of the handle **Returns** GLOBUS\_SUCCESS or an error captured in a globus\_result\_t ### globus\_result\_t globus\_gsi\_cred\_set\_cert (globus\_gsi\_cred\_handle\_t handle, X509 \* cert) Set the credential's certificate. Set the Credential's Certificate. The X509 cert that is passed in should be a valid X509 certificate object **Parameters** *handle* The credential handle to set the certificate on \ *cert* The X509 cert to set in the cred handle. The cert passed in can be NULL which will set the cert in the handle to NULL, freeing the current cert in the handle. **Returns** GLOBUS\_SUCCESS or an error object id if an error ### globus\_result\_t globus\_gsi\_cred\_set\_cert\_chain (globus\_gsi\_cred\_handle\_t handle, STACK\_OF(X509) \* cert\_chain) Set the certificate chain. Set the certificate chain of the credential handle **Parameters** *handle* The handle containing the certificate chain field to set \ *cert\_chain* The certificate chain to set the handle's certificate chain to **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object id is returned ### globus\_result\_t globus\_gsi\_cred\_set\_key (globus\_gsi\_cred\_handle\_t handle, EVP\_PKEY \* key) Set the credential's private key. Set the private key of the credential handle. **Parameters** *handle* The handle on which to set the key. \ *key* The private key to set the handle's key to. This value can be NULL, in which case the current handle's key is freed. \ ### globus\_result\_t globus\_gsi\_cred\_verify (globus\_gsi\_cred\_handle\_t handle) Verify a credential. This function checks that the certificate is signed by the public key of the issuer cert (the first cert in the chain). Note that this function DOES NOT check the private key or the public of the certificate, as stated in a previous version of the documentation. **Parameters** *handle* The credential handle containing the certificate and key to be validated **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object identifier is returned ### globus\_result\_t globus\_gsi\_cred\_verify\_cert\_chain (globus\_gsi\_cred\_handle\_t cred\_handle, globus\_gsi\_callback\_data\_t callback\_data) Verify credential. This function performs path validation on the certificate chain contained in the credential handle. **Parameters** *cred\_handle* The credential handle containing the certificate chain to be validated \ *callback\_data* A initialized callback data structure **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object identifier is returned ### globus\_result\_t globus\_gsi\_cred\_verify\_cert\_chain\_when (globus\_gsi\_cred\_handle\_t cred\_handle, globus\_gsi\_callback\_data\_t callback\_data\_in, time\_t check\_time) Verify credential at a specific time. This function performs path validation on the certificate chain contained in the credential handle. Expiration checks are done at the time given. **Parameters** *cred\_handle* The credential handle containing the certificate chain to be validated \ *callback\_data\_in* A callback data structure. If NULL, one will be initialized with only the default cert dir set. \ *check\_time* Check if the cert chain was valid at this time. Set to 0 to use a time that the cert is valid, essentially bypassing the expiration check. **Returns** GLOBUS\_SUCCESS if no error, otherwise an error object identifier is returned ## Author Generated automatically by Doxygen for globus\_gsi\_credential from the source code.