.TH "Credential Handle Management" 3 "Mon Apr 30 2012" "Version 5.3" "globus gsi credential" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Credential Handle Management \- 
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct 
.br
globus_l_gsi_cred_handle_s * \fBglobus_gsi_cred_handle_t\fP"
.br
.in -1c
.SS "Initializing and Destroying a Handle"

.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
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_handle_destroy\fP (\fBglobus_gsi_cred_handle_t\fP handle)"
.br
.in -1c
.SS "Copying a Handle"

.in +1c
.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
.in -1c
.SS "Getting the Handle Attributes"

.in +1c
.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
.in -1c
.SS "Getting the Credential Expiration"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_goodtill\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, time_t *goodtill)"
.br
.in -1c
.SS "Getting the Credential Lifetime"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_lifetime\fP (\fBglobus_gsi_cred_handle_t\fP cred_handle, time_t *lifetime)"
.br
.in -1c
.SS "Getting the Credential Strength"

.in +1c
.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
.in -1c
.SS "Setting and Getting the Certificate"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_set_cert\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509 *cert)"
.br
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_cert\fP (\fBglobus_gsi_cred_handle_t\fP handle, X509 **cert)"
.br
.in -1c
.SS "Setting and Getting the Credential Key"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_set_key\fP (\fBglobus_gsi_cred_handle_t\fP handle, EVP_PKEY *key)"
.br
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_key\fP (\fBglobus_gsi_cred_handle_t\fP handle, EVP_PKEY **key)"
.br
.in -1c
.SS "Setting and Getting the Certificate Chain"

.in +1c
.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
.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
.in -1c
.SS "Get Cred Cert X509 Subject Name object"

.in +1c
.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
.in -1c
.SS "Get X509 Identity Name"

.in +1c
.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
.in -1c
.SS "Get Cred Cert Subject Name"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_subject_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, char **subject_name)"
.br
.in -1c
.SS "Get Policies from Cert Chain"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_policies\fP (\fBglobus_gsi_cred_handle_t\fP handle, STACK **policies)"
.br
.in -1c
.SS "Get Policy Languages from Cert Chain"

.in +1c
.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
.in -1c
.SS "Get Cred Cert X509 Issuer Name object"

.in +1c
.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
.in -1c
.SS "Get Issuer Name"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_issuer_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, char **issuer_name)"
.br
.in -1c
.SS "Get Identity Name"

.in +1c
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_get_identity_name\fP (\fBglobus_gsi_cred_handle_t\fP handle, char **identity_name)"
.br
.in -1c
.SS "Credential validation functions"

.in +1c
.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
.ti -1c
.RI "globus_result_t \fBglobus_gsi_cred_verify\fP (\fBglobus_gsi_cred_handle_t\fP handle)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Create/Destroy/Modify a GSI Credential Handle\&. 

Within the Globus GSI Credential Library, all credential operations require a handle parameter\&. Currenlty 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"
.PP
GSI Credential Handle\&. 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 \fBglobus_gsi_cred_handle_init\fP (\fBglobus_gsi_cred_handle_t\fP *handle, \fBglobus_gsi_cred_handle_attrs_t\fPhandle_attrs)"
.PP
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 \fBglobus_gsi_cred_handle_destroy\fP (\fBglobus_gsi_cred_handle_t\fPhandle)"
.PP
Destroys the credential handle\&. \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 \fBglobus_gsi_cred_handle_copy\fP (\fBglobus_gsi_cred_handle_t\fPsource, \fBglobus_gsi_cred_handle_t\fP *dest)"
.PP
Copies a credential handle\&. \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 \fBglobus_gsi_cred_get_handle_attrs\fP (\fBglobus_gsi_cred_handle_t\fPhandle, \fBglobus_gsi_cred_handle_attrs_t\fP *attrs)"
.PP
This function retreives a copy of the credential handle attributes\&. \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 \fBglobus_gsi_cred_get_goodtill\fP (\fBglobus_gsi_cred_handle_t\fPcred_handle, time_t *goodtill)"
.PP
This function retreives the expiration time of the credential contained in the handle\&. \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 \fBglobus_gsi_cred_get_lifetime\fP (\fBglobus_gsi_cred_handle_t\fPcred_handle, time_t *lifetime)"
.PP
This function retreives the lifetime of the credential contained in a handle\&. \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 \fBglobus_gsi_cred_get_key_bits\fP (\fBglobus_gsi_cred_handle_t\fPcred_handle, int *key_bits)"
.PP
This function retreives the key strength of the credential contained in a handle\&. \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 \fBglobus_gsi_cred_set_cert\fP (\fBglobus_gsi_cred_handle_t\fPhandle, X509 *cert)"
.PP
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 \fBglobus_gsi_cred_get_cert\fP (\fBglobus_gsi_cred_handle_t\fPhandle, X509 **cert)"
.PP
Get the certificate of a credential\&. \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 \fBglobus_gsi_cred_set_key\fP (\fBglobus_gsi_cred_handle_t\fPhandle, EVP_PKEY *key)"
.PP
Set the private key of the credential handle\&. \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\&. 
.RE
.PP

.SS "globus_result_t \fBglobus_gsi_cred_get_key\fP (\fBglobus_gsi_cred_handle_t\fPhandle, EVP_PKEY **key)"
.PP
Get the credential handle's private key\&. \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 \fBglobus_gsi_cred_set_cert_chain\fP (\fBglobus_gsi_cred_handle_t\fPhandle, STACK_OF(X509)*cert_chain)"
.PP
Set the certificate chain of the credential handle\&. \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 \fBglobus_gsi_cred_get_cert_chain\fP (\fBglobus_gsi_cred_handle_t\fPhandle, STACK_OF(X509)**cert_chain)"
.PP
Get the certificate chain of the credential handle\&. \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 \fBglobus_gsi_cred_get_X509_subject_name\fP (\fBglobus_gsi_cred_handle_t\fPhandle, X509_NAME **subject_name)"
.PP
Get the credential handle's certificate subject name\&. \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 \fBglobus_gsi_cred_get_X509_identity_name\fP (\fBglobus_gsi_cred_handle_t\fPhandle, X509_NAME **identity_name)"
.PP
Get the identity's X509 subject name from the credential handle\&. \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 \fBglobus_gsi_cred_get_subject_name\fP (\fBglobus_gsi_cred_handle_t\fPhandle, char **subject_name)"
.PP
Get the credential handle's certificate subject name\&. \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 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 \fBglobus_gsi_cred_get_policies\fP (\fBglobus_gsi_cred_handle_t\fPhandle, STACK **policies)"
.PP
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 \fBglobus_gsi_cred_get_policy_languages\fP (\fBglobus_gsi_cred_handle_t\fPhandle, STACK_OF(ASN1_OBJECT)**policy_languages)"
.PP
Get the policy languages from the cert chain in the handle\&. \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 \fBglobus_gsi_cred_get_X509_issuer_name\fP (\fBglobus_gsi_cred_handle_t\fPhandle, X509_NAME **issuer_name)"
.PP
Get the credential handle's certificate issuer name\&. \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 \fBglobus_gsi_cred_get_issuer_name\fP (\fBglobus_gsi_cred_handle_t\fPhandle, char **issuer_name)"
.PP
Get the issuer's subject name from the credential handle\&. \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 \fBglobus_gsi_cred_get_identity_name\fP (\fBglobus_gsi_cred_handle_t\fPhandle, char **identity_name)"
.PP
Get the identity's subject name from the credential handle\&. \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 \fBglobus_gsi_cred_verify_cert_chain\fP (\fBglobus_gsi_cred_handle_t\fPcred_handle, globus_gsi_callback_data_tcallback_data)"
.PP
This function performs path valiadtion on the certificate chain contained in the credential handle\&. \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 \fBglobus_gsi_cred_verify\fP (\fBglobus_gsi_cred_handle_t\fPhandle)"
.PP
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

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