Credential Handle Management

Typedefs
typedef struct globus_l_gsi_cred_handle_s *	globus_gsi_cred_handle_t

Initializing and Destroying a Handle
globus_result_t	globus_gsi_cred_handle_init (globus_gsi_cred_handle_t *handle, globus_gsi_cred_handle_attrs_t handle_attrs)
globus_result_t	globus_gsi_cred_handle_destroy (globus_gsi_cred_handle_t handle)

Copying a Handle
globus_result_t	globus_gsi_cred_handle_copy (globus_gsi_cred_handle_t source, globus_gsi_cred_handle_t *dest)

Getting the Handle Attributes
globus_result_t	globus_gsi_cred_get_handle_attrs (globus_gsi_cred_handle_t handle, globus_gsi_cred_handle_attrs_t *attrs)

Getting the Credential Expiration
globus_result_t	globus_gsi_cred_get_goodtill (globus_gsi_cred_handle_t cred_handle, time_t *goodtill)

Getting the Credential Lifetime
globus_result_t	globus_gsi_cred_get_lifetime (globus_gsi_cred_handle_t cred_handle, time_t *lifetime)

Getting the Credential Strength
globus_result_t	globus_gsi_cred_get_key_bits (globus_gsi_cred_handle_t cred_handle, int *key_bits)

Setting and Getting the Certificate
globus_result_t	globus_gsi_cred_set_cert (globus_gsi_cred_handle_t handle, X509 *cert)
globus_result_t	globus_gsi_cred_get_cert (globus_gsi_cred_handle_t handle, X509 **cert)

Setting and Getting the Credential Key
globus_result_t	globus_gsi_cred_set_key (globus_gsi_cred_handle_t handle, EVP_PKEY *key)
globus_result_t	globus_gsi_cred_get_key (globus_gsi_cred_handle_t handle, EVP_PKEY **key)

Setting and Getting the Certificate Chain
globus_result_t	globus_gsi_cred_set_cert_chain (globus_gsi_cred_handle_t handle, STACK_OF(X509)*cert_chain)
globus_result_t	globus_gsi_cred_get_cert_chain (globus_gsi_cred_handle_t handle, STACK_OF(X509)**cert_chain)

Get Cred Cert X509 Subject Name object
globus_result_t	globus_gsi_cred_get_X509_subject_name (globus_gsi_cred_handle_t handle, X509_NAME **subject_name)

Get X509 Identity Name
globus_result_t	globus_gsi_cred_get_X509_identity_name (globus_gsi_cred_handle_t handle, X509_NAME **identity_name)

Get Cred Cert Subject Name
globus_result_t	globus_gsi_cred_get_subject_name (globus_gsi_cred_handle_t handle, char **subject_name)

Get Policies from Cert Chain
globus_result_t	globus_gsi_cred_get_policies (globus_gsi_cred_handle_t handle, STACK **policies)

Get Policy Languages from Cert Chain
globus_result_t	globus_gsi_cred_get_policy_languages (globus_gsi_cred_handle_t handle, STACK_OF(ASN1_OBJECT)**policy_languages)

Get Cred Cert X509 Issuer Name object
globus_result_t	globus_gsi_cred_get_X509_issuer_name (globus_gsi_cred_handle_t handle, X509_NAME **issuer_name)

Get Issuer Name
globus_result_t	globus_gsi_cred_get_issuer_name (globus_gsi_cred_handle_t handle, char **issuer_name)

Get Identity Name
globus_result_t	globus_gsi_cred_get_identity_name (globus_gsi_cred_handle_t handle, char **identity_name)

Credential validation functions
globus_result_t	globus_gsi_cred_verify_cert_chain (globus_gsi_cred_handle_t cred_handle, globus_gsi_callback_data_t callback_data)
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)
globus_result_t	globus_gsi_cred_verify (globus_gsi_cred_handle_t handle)

Detailed Description

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.

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_handle_init	(	globus_gsi_cred_handle_t *	handle,
		globus_gsi_cred_handle_attrs_t	handle_attrs
	)

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

References GLOBUS_GSI_CRED_ERROR_BAD_PARAMETER, GLOBUS_GSI_CRED_ERROR_ERRNO, GLOBUS_GSI_CRED_ERROR_WITH_CRED, globus_gsi_cred_handle_attrs_copy(), globus_gsi_cred_handle_attrs_init(), and GLOBUS_GSI_CREDENTIAL_MODULE.

globus_result_t globus_gsi_cred_handle_destroy

(

globus_gsi_cred_handle_t

handle

)

Destroys the credential handle.

Parameters

handle

The credential handle to be destroyed

Returns

GLOBUS_SUCCESS

References globus_gsi_cred_handle_attrs_destroy().

globus_result_t globus_gsi_cred_handle_copy	(	globus_gsi_cred_handle_t	source,
		globus_gsi_cred_handle_t *	dest
	)

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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and globus_gsi_cred_handle_init().

globus_result_t globus_gsi_cred_get_handle_attrs	(	globus_gsi_cred_handle_t	handle,
		globus_gsi_cred_handle_attrs_t *	attrs
	)

This function retreives 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and globus_gsi_cred_handle_attrs_copy().

globus_result_t globus_gsi_cred_get_goodtill	(	globus_gsi_cred_handle_t	cred_handle,
		time_t *	goodtill
	)

This function retreives 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED.

globus_result_t globus_gsi_cred_get_lifetime	(	globus_gsi_cred_handle_t	cred_handle,
		time_t *	lifetime
	)

This function retreives 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED.

globus_result_t globus_gsi_cred_get_key_bits	(	globus_gsi_cred_handle_t	cred_handle,
		int *	key_bits
	)

This function retreives 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT.

globus_result_t globus_gsi_cred_set_cert	(	globus_gsi_cred_handle_t	handle,
		X509 *	cert
	)

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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT.

globus_result_t globus_gsi_cred_get_cert	(	globus_gsi_cred_handle_t	handle,
		X509 **	cert
	)

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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED.

globus_result_t globus_gsi_cred_set_key	(	globus_gsi_cred_handle_t	handle,
		EVP_PKEY *	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.

References GLOBUS_GSI_CRED_ERROR_WITH_CRED.

globus_result_t globus_gsi_cred_get_key	(	globus_gsi_cred_handle_t	handle,
		EVP_PKEY **	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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_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 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT_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 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT_CHAIN.

globus_result_t globus_gsi_cred_get_X509_subject_name	(	globus_gsi_cred_handle_t	handle,
		X509_NAME **	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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT.

globus_result_t globus_gsi_cred_get_X509_identity_name	(	globus_gsi_cred_handle_t	handle,
		X509_NAME **	identity_name
	)

Get the identity's X509 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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED.

globus_result_t globus_gsi_cred_get_subject_name	(	globus_gsi_cred_handle_t	handle,
		char **	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 free() when the user is finished with it

Returns

GLOBUS_SUCCESS if no error, a error object id otherwise

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and globus_gsi_cred_get_X509_subject_name().

globus_result_t globus_gsi_cred_get_policies	(	globus_gsi_cred_handle_t	handle,
		STACK **	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

References GLOBUS_GSI_CRED_ERROR_ERRNO, GLOBUS_GSI_CRED_ERROR_WITH_CRED, GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT_CHAIN, and GLOBUS_GSI_CREDENTIAL_MODULE.

globus_result_t globus_gsi_cred_get_policy_languages	(	globus_gsi_cred_handle_t	handle,
		STACK_OF(ASN1_OBJECT)**	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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT_CHAIN.

globus_result_t globus_gsi_cred_get_X509_issuer_name	(	globus_gsi_cred_handle_t	handle,
		X509_NAME **	issuer_name
	)

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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT.

globus_result_t globus_gsi_cred_get_issuer_name	(	globus_gsi_cred_handle_t	handle,
		char **	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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT.

globus_result_t globus_gsi_cred_get_identity_name	(	globus_gsi_cred_handle_t	handle,
		char **	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

References GLOBUS_GSI_CRED_ERROR_WITH_CRED, GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT_NAME, and globus_gsi_cred_get_X509_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
	)

This function performs path valiadtion 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

References GLOBUS_GSI_CRED_ERROR_VERIFYING_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CALLBACK_DATA.

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
	)

This function performs path valiadtion 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	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

References GLOBUS_GSI_CRED_ERROR_VERIFYING_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CALLBACK_DATA.

globus_result_t globus_gsi_cred_verify

(

globus_gsi_cred_handle_t

handle

)

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

References GLOBUS_GSI_CRED_ERROR_VERIFYING_CRED, and GLOBUS_GSI_CRED_ERROR_WITH_CRED_CERT_CHAIN.