.TH "globus_gsi_cred_handle" 3 "Version 8.4" "globus_gsi_credential" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_gsi_cred_handle \- Credential Handle Management
.PP
 \- Credential Handle Management\&.  

.SH SYNOPSIS
.br
.PP
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct globus_l_gsi_cred_handle_s * \fBglobus_gsi_cred_handle_t\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_handle_init\fP (\fBglobus_gsi_cred_handle_t\fP *handle, \fBglobus_gsi_cred_handle_attrs_t\fP handle_attrs)"
.br
.RI "Initialize a Handle\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_handle_destroy\fP (\fBglobus_gsi_cred_handle_t\fP handle)"
.br
.RI "Destroy the credential handle\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_handle_copy\fP (\fBglobus_gsi_cred_handle_t\fP source, \fBglobus_gsi_cred_handle_t\fP *dest)"
.br
.RI "Copy a handle\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_handle_attrs\fP (\fBglobus_gsi_cred_handle_t\fP handle, \fBglobus_gsi_cred_handle_attrs_t\fP *attrs)"
.br
.RI "Get the handle attributes\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_goodtill\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, time_t *goodtill)"
.br
.RI "Get credential expiration\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_lifetime\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, time_t *lifetime)"
.br
.RI "Get credential lifetime\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_key_bits\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, int *key_bits)"
.br
.RI "Get credential strength\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_set_cert\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509 *cert)"
.br
.RI "Set the credential's certificate\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_cert\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509 **cert)"
.br
.RI "Get the credential's certificate\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_set_key\fP (\fBglobus_gsi_cred_handle_t\fP handle, EVP_PKEY *key)"
.br
.RI "Set the credential's private key\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_key\fP (\fBglobus_gsi_cred_handle_t\fP handle, EVP_PKEY **key)"
.br
.RI "Get the credential's private key\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_set_cert_chain\fP (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(X509) *cert_chain)"
.br
.RI "Set the certificate chain\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_cert_chain\fP (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(X509) **cert_chain)"
.br
.RI "Get the certificate chain\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_X509_subject_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509_NAME **subject_name)"
.br
.RI "Get credential subject name\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_X509_identity_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509_NAME **identity_name)"
.br
.RI "Get X\&.509 identity\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_subject_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, char **subject_name)"
.br
.RI "Get credential subject name\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_policies\fP (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(OPENSSL_STRING) **policies)"
.br
.RI "Get certificate chain policies\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_policy_languages\fP (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(ASN1_OBJECT) **policy_languages)"
.br
.RI "Get certificate chain policy languages\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_X509_issuer_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509_NAME **issuer_name)"
.br
.RI "Get credential issuer name object\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_issuer_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, char **issuer_name)"
.br
.RI "Get issuer name\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_identity_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, char **identity_name)"
.br
.RI "Get identity name\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_verify_cert_chain\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, globus_gsi_callback_data_t callback_data)"
.br
.RI "Verify credential\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_verify_cert_chain_when\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, globus_gsi_callback_data_t callback_data_in, time_t check_time)"
.br
.RI "Verify credential at a specific time\&. "
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_verify\fP (\fBglobus_gsi_cred_handle_t\fP handle)"
.br
.RI "Verify a credential\&. "
.in -1c
.SH "Detailed Description"
.PP 
Credential Handle Management\&. 

Create/Destroy/Modify a GSI Credential Handle\&.
.PP
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\&.
.PP
This section defines operations to create, modify and destroy GSI Credential handles\&. 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct globus_l_gsi_cred_handle_s* \fBglobus_gsi_cred_handle_t\fP"
GSI Credential Handle\&.
.PP
A GSI Credential handle keeps track of state relating to a credential\&. Handles can have immutable \fBattributes\fP associated with them\&. All credential \fBoperations \fP take a credential handle pointer as a parameter\&.
.PP
\fBSee also\fP
.RS 4
\fBglobus_gsi_cred_handle_init()\fP, \fBglobus_gsi_cred_handle_destroy()\fP, \fBglobus_gsi_cred_handle_attrs_t\fP 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "globus_result_t globus_gsi_cred_get_cert (\fBglobus_gsi_cred_handle_t\fP handle, X509 ** cert)"

.PP
Get the credential's certificate\&. Get the certificate of a credential
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle to get the certificate from 
.br
\fIcert\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object id is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_cert_chain (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(X509) ** cert_chain)"

.PP
Get the certificate chain\&. Get the certificate chain of the credential handle
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate chain to get 
.br
\fIcert_chain\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object id is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_goodtill (\fBglobus_gsi_cred_handle_t\fP cred_handle, time_t * goodtill)"

.PP
Get credential expiration\&. This function retrieves the expiration time of the credential contained in the handle
.PP
\fBParameters\fP
.RS 4
\fIcred_handle\fP The credential handle to retrieve the expiration time from 
.br
\fIgoodtill\fP Contains the expiration time on return
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error captured in a globus_result_t 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_handle_attrs (\fBglobus_gsi_cred_handle_t\fP handle, \fBglobus_gsi_cred_handle_attrs_t\fP * attrs)"

.PP
Get the handle attributes\&. This function retrieves a copy of the credential handle attributes
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle to retrieve the attributes from 
.br
\fIattrs\fP Contains the credential attributes on return
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error captured in a globus_result_t 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_identity_name (\fBglobus_gsi_cred_handle_t\fP handle, char ** identity_name)"

.PP
Get identity name\&. Get the identity's subject name from the credential handle
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate to get the identity of 
.br
\fIidentity_name\fP The identity certificate's subject name
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object identifier is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_issuer_name (\fBglobus_gsi_cred_handle_t\fP handle, char ** issuer_name)"

.PP
Get issuer name\&. Get the issuer's subject name from the credential handle
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate to get the issuer of 
.br
\fIissuer_name\fP The issuer certificate's subject name
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object identifier is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_key (\fBglobus_gsi_cred_handle_t\fP handle, EVP_PKEY ** key)"

.PP
Get the credential's private key\&. Get the credential handle's private key
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the private key to get 
.br
\fIkey\fP 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\&.
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error object identifier 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_key_bits (\fBglobus_gsi_cred_handle_t\fP cred_handle, int * key_bits)"

.PP
Get credential strength\&. This function retrieves the key strength of the credential contained in a handle
.PP
\fBParameters\fP
.RS 4
\fIcred_handle\fP The credential handle to retrieve the strength from 
.br
\fIkey_bits\fP Contains the number of bits in the key on return
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error captured in a globus_result_t 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_lifetime (\fBglobus_gsi_cred_handle_t\fP cred_handle, time_t * lifetime)"

.PP
Get credential lifetime\&. This function retrieves the lifetime of the credential contained in a handle
.PP
\fBParameters\fP
.RS 4
\fIcred_handle\fP The credential handle to retrieve the lifetime from 
.br
\fIlifetime\fP Contains the lifetime on return
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error captured in a globus_result_t 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_policies (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(OPENSSL_STRING) ** policies)"

.PP
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
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP the handle to get the cert chain containing the policies 
.br
\fIpolicies\fP the stack of policies retrieved from the handle's cert chain 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error object if an error occurred 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_policy_languages (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(ASN1_OBJECT) ** policy_languages)"

.PP
Get certificate chain policy languages\&. Get the policy languages from the cert chain in the handle\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP the handle to get the cert chain containing the policies 
.br
\fIpolicy_languages\fP the stack of policies retrieved from the handle's cert chain 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error object if an error occurred 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_subject_name (\fBglobus_gsi_cred_handle_t\fP handle, char ** subject_name)"

.PP
Get credential subject name\&. Get the credential handle's certificate subject name
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate to get the subject name of 
.br
\fIsubject_name\fP The subject name as a string\&. This should be freed using OPENSSL_free() when the user is finished with it 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, a error object id otherwise 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_X509_identity_name (\fBglobus_gsi_cred_handle_t\fP handle, X509_NAME ** identity_name)"

.PP
Get X\&.509 identity\&. Get the identity's X\&.509 subject name from the credential handle
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate to get the identity from 
.br
\fIidentity_name\fP The identity certificate's X509 subject name
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object identifier is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_X509_issuer_name (\fBglobus_gsi_cred_handle_t\fP handle, X509_NAME ** issuer_name)"

.PP
Get credential issuer name object\&. Get the credential handle's certificate issuer name
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate to get the issuer name of 
.br
\fIissuer_name\fP The issuer name as an X509_NAME object\&. This should be freed using X509_NAME_free when the user is finished with it 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, a error object id otherwise 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_get_X509_subject_name (\fBglobus_gsi_cred_handle_t\fP handle, X509_NAME ** subject_name)"

.PP
Get credential subject name\&. Get the credential handle's certificate subject name
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate to get the subject name of 
.br
\fIsubject_name\fP The subject name as an X509_NAME object\&. This should be freed using X509_NAME_free when the user is finished with it 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, a error object id otherwise 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_handle_copy (\fBglobus_gsi_cred_handle_t\fP source, \fBglobus_gsi_cred_handle_t\fP * dest)"

.PP
Copy a handle\&. Copies a credential handle\&.
.PP
\fBParameters\fP
.RS 4
\fIsource\fP The handle to be copied 
.br
\fIdest\fP The destination of the copy
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error captured in a globus_result_t 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_handle_destroy (\fBglobus_gsi_cred_handle_t\fP handle)"

.PP
Destroy the credential handle\&. Destroys the credential handle
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle to be destroyed 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_handle_init (\fBglobus_gsi_cred_handle_t\fP * handle, \fBglobus_gsi_cred_handle_attrs_t\fP handle_attrs)"

.PP
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\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The handle to be initialized 
.br
\fIhandle_attrs\fP The immutable attributes of the handle
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error captured in a globus_result_t 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_set_cert (\fBglobus_gsi_cred_handle_t\fP handle, X509 * cert)"

.PP
Set the credential's certificate\&. Set the Credential's Certificate\&. The X509 cert that is passed in should be a valid X509 certificate object
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle to set the certificate on 
.br
\fIcert\fP 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\&. 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS or an error object id if an error 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_set_cert_chain (\fBglobus_gsi_cred_handle_t\fP handle, STACK_OF(X509) * cert_chain)"

.PP
Set the certificate chain\&. Set the certificate chain of the credential handle
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The handle containing the certificate chain field to set 
.br
\fIcert_chain\fP The certificate chain to set the handle's certificate chain to 
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object id is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_set_key (\fBglobus_gsi_cred_handle_t\fP handle, EVP_PKEY * key)"

.PP
Set the credential's private key\&. Set the private key of the credential handle\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The handle on which to set the key\&. 
.br
\fIkey\fP 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\&. 
.br
 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_verify (\fBglobus_gsi_cred_handle_t\fP handle)"

.PP
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\&.
.PP
\fBParameters\fP
.RS 4
\fIhandle\fP The credential handle containing the certificate and key to be validated
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object identifier is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_verify_cert_chain (\fBglobus_gsi_cred_handle_t\fP cred_handle, globus_gsi_callback_data_t callback_data)"

.PP
Verify credential\&. This function performs path validation on the certificate chain contained in the credential handle\&.
.PP
\fBParameters\fP
.RS 4
\fIcred_handle\fP The credential handle containing the certificate chain to be validated 
.br
\fIcallback_data\fP A initialized callback data structure
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object identifier is returned 
.RE
.PP

.SS "globus_result_t globus_gsi_cred_verify_cert_chain_when (\fBglobus_gsi_cred_handle_t\fP cred_handle, globus_gsi_callback_data_t callback_data_in, time_t check_time)"

.PP
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\&.
.PP
\fBParameters\fP
.RS 4
\fIcred_handle\fP The credential handle containing the certificate chain to be validated 
.br
\fIcallback_data_in\fP A callback data structure\&. If NULL, one will be initialized with only the default cert dir set\&. 
.br
\fIcheck_time\fP 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\&.
.RE
.PP
\fBReturns\fP
.RS 4
GLOBUS_SUCCESS if no error, otherwise an error object identifier is returned 
.RE
.PP

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