Provided by: libglobus-gsi-credential-doc_8.4-2_all bug

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.