voms_apic.h

voms_apic.h(3)                    VOMS C API                    voms_apic.h(3)



NAME
       voms_apic.h

SYNOPSIS
       #include <openssl/x509.h>
       #include <time.h>
       #include 'newformat.h'


   Data Structures
       struct data
           User's characteristics: can be repeated.
       struct attribute
       struct contactdata
           The type of data returned.
       struct voms
       struct vomsdata

   Macros
       #define NOGLOBUS
       #define TYPE_NODATA   0
       #define TYPE_STD   1
       #define TYPE_CUSTOM   2
       #define RECURSE_CHAIN   0
       #define RECURSE_NONE   1
       #define VERIFY_FULL   0xffffffff
       #define VERIFY_NONE   0x00000000
       #define VERIFY_DATE   0x00000001
       #define VERIFY_NOTARGET   0x00000002
       #define VERIFY_KEY   0x00000004
       #define VERIFY_SIGN   0x00000008
       #define VERIFY_ORDER   0x00000010
       #define VERIFY_ID   0x00000020
       #define VERIFY_CERTLIST   0x00000040
       #define VERR_NONE   0
           Error codes.
       #define VERR_NOSOCKET   1
       #define VERR_NOIDENT   2
       #define VERR_COMM   3
       #define VERR_PARAM   4
       #define VERR_NOEXT   5
       #define VERR_NOINIT   6
       #define VERR_TIME   7
       #define VERR_IDCHECK   8
       #define VERR_EXTRAINFO   9
       #define VERR_FORMAT   10
       #define VERR_NODATA   11
       #define VERR_PARSE   12
       #define VERR_DIR   13
       #define VERR_SIGN   14
       #define VERR_SERVER   15
       #define VERR_MEM   16
       #define VERR_VERIFY   17
       #define VERR_TYPE   18
       #define VERR_ORDER   19
       #define VERR_SERVERCODE   20
       #define VERR_NOTAVAIL   21

   Typedefs
       typedef void * gss_cred_id_t
       typedef void * gss_ctx_id_t

   Functions
       struct contactdata ** VOMS_FindByAlias (struct vomsdata *vd, char
           *alias, char *system, char *user, int *error)
       struct contactdata ** VOMS_FindByVO (struct vomsdata *vd, char *vo,
           char *system, char *user, int *error)
       void VOMS_DeleteContacts (struct contactdata **list)
       struct vomsdata * VOMS_Init (char *voms, char *cert)
       struct voms * VOMS_Copy (struct voms *v, int *error)
       struct vomsdata * VOMS_CopyAll (struct vomsdata *vd, int *error)
       void VOMS_Delete (struct voms *v)
       int VOMS_AddTarget (struct vomsdata *vd, char *target, int *error)
       void VOMS_FreeTargets (struct vomsdata *vd, int *error)
       char * VOMS_ListTargets (struct vomsdata *vd, int *error)
       int VOMS_SetVerificationType (int type, struct vomsdata *vd, int
           *error)
       int VOMS_SetLifetime (int length, struct vomsdata *vd, int *error)
       void VOMS_Destroy (struct vomsdata *vd)
       int VOMS_ResetOrder (struct vomsdata *vd, int *error)
       int VOMS_Ordering (char *order, struct vomsdata *vd, int *error)
       int VOMS_Contact (char *hostname, int port, char *servsubject, char
           *command, struct vomsdata *vd, int *error)
       int VOMS_ContactRaw (char *hostname, int port, char *servsubject, char
           *command, void **data, int *datalen, int *version, struct vomsdata
           *vd, int *error)
       int VOMS_Retrieve (X509 *cert, STACK_OF(X509) *chain, int how, struct
           vomsdata *vd, int *error)
       int VOMS_Import (char *buffer, int buflen, struct vomsdata *vd, int
           *error)
       int VOMS_Export (char **buffer, int *buflen, struct vomsdata *vd, int
           *error)
       struct voms * VOMS_DefaultData (struct vomsdata *vd, int *error)
       char * VOMS_ErrorMessage (struct vomsdata *vd, int error, char *buffer,
           int len)
       int VOMS_RetrieveEXT (X509_EXTENSION *ext, struct vomsdata *vd, int
           *error)
       int VOMS_RetrieveFromCred (gss_cred_id_t cred, int how, struct vomsdata
           *vd, int *error)
       int VOMS_RetrieveFromFile (FILE *file, int how, struct vomsdata *vd,
           int *error)
       int VOMS_RetrieveFromCtx (gss_ctx_id_t ctx, int how, struct vomsdata
           *vd, int *error)
       int VOMS_RetrieveFromProxy (int how, struct vomsdata *vd, int *error)
       int VOMS_RetrieveFromAC (AC *ac, struct vomsdata *vd, int *error)
       int VOMS_GetAttributeSourcesNumber (struct voms *v, struct vomsdata
           *vd, int *error)
       int VOMS_GetAttributeSourceHandle (struct voms *v, int num, struct
           vomsdata *vd, int *error)
       const char * VOMS_GetAttributeGrantor (struct voms *v, int handle,
           struct vomsdata *vd, int *error)
       int VOMS_GetAttributesNumber (struct voms *v, int handle, struct
           vomsdata *vd, int *error)
       int VOMS_GetAttribute (struct voms *v, int handle, int num, struct
           attribute *at, struct vomsdata *vd, int *error)
       struct vomsdata * VOMS_Duplicate (struct vomsdata *vd)
       AC * VOMS_GetAC (struct voms *v)
       int getMajorVersionNumber (void)
       int getMinorVersionNumber (void)
       int getPatchVersionNumber (void)
       int VOMS_SetVerificationTime (time_t verificationtime, struct vomsdata
           *vd, int *error)
       char ** VOMS_GetTargetsList (struct voms *v, struct vomsdata *vd, int
           *error)
       void VOMS_FreeTargetsList (char **)
       int VOMS_SetTimeout (int t, struct vomsdata *vd, int *error)
       int VOMS_LoadCredentials (X509 *cert, EVP_PKEY *pkey, STACK_OF(X509)
           *chain, struct vomsdata *vd, int *error)

Macro Definition Documentation
   #define NOGLOBUS
       Definition at line 33 of file voms_apic.h.

   #define RECURSE_CHAIN   0
       Definition at line 105 of file voms_apic.h.

   #define RECURSE_NONE   1
       Definition at line 106 of file voms_apic.h.

   #define TYPE_CUSTOM   2
       result of an S command

       Definition at line 77 of file voms_apic.h.

   #define TYPE_NODATA   0
       no data

       Definition at line 75 of file voms_apic.h.

   #define TYPE_STD   1
       group, role, capability triplet

       Definition at line 76 of file voms_apic.h.

   #define VERIFY_CERTLIST   0x00000040
       Definition at line 116 of file voms_apic.h.

   #define VERIFY_DATE   0x00000001
       Definition at line 110 of file voms_apic.h.

   #define VERIFY_FULL   0xffffffff
       Definition at line 108 of file voms_apic.h.

   #define VERIFY_ID   0x00000020
       Definition at line 115 of file voms_apic.h.

   #define VERIFY_KEY   0x00000004
       Definition at line 112 of file voms_apic.h.

   #define VERIFY_NONE   0x00000000
       Definition at line 109 of file voms_apic.h.

   #define VERIFY_NOTARGET   0x00000002
       Definition at line 111 of file voms_apic.h.

   #define VERIFY_ORDER   0x00000010
       Definition at line 114 of file voms_apic.h.

   #define VERIFY_SIGN   0x00000008
       Definition at line 113 of file voms_apic.h.

   #define VERR_COMM   3
       Server problem

       Definition at line 123 of file voms_apic.h.

   #define VERR_DIR   13
       Directory error

       Definition at line 135 of file voms_apic.h.

   #define VERR_EXTRAINFO   9
       VO name and URI missing

       Definition at line 131 of file voms_apic.h.

   #define VERR_FORMAT   10
       Wrong data format

       Definition at line 132 of file voms_apic.h.

   #define VERR_IDCHECK   8
       User data in extension different from the real ones

       Definition at line 128 of file voms_apic.h.

   #define VERR_MEM   16
       Memory problems

       Definition at line 138 of file voms_apic.h.

   #define VERR_NODATA   11
       Empty extension

       Definition at line 133 of file voms_apic.h.

   #define VERR_NOEXT   5
       VOMS extension missing

       Definition at line 125 of file voms_apic.h.

   #define VERR_NOIDENT   2
       Cannot identify itself (certificate problem)

       Definition at line 122 of file voms_apic.h.

   #define VERR_NOINIT   6
       Initialization error

       Definition at line 126 of file voms_apic.h.

   #define VERR_NONE   0
       Error codes.

       Definition at line 120 of file voms_apic.h.

   #define VERR_NOSOCKET   1
       Socket problem

       Definition at line 121 of file voms_apic.h.

   #define VERR_NOTAVAIL   21
       Method not available

       Definition at line 143 of file voms_apic.h.

   #define VERR_ORDER   19
       Ordering different than required

       Definition at line 141 of file voms_apic.h.

   #define VERR_PARAM   4
       Wrong parameters

       Definition at line 124 of file voms_apic.h.

   #define VERR_PARSE   12
       Parse error

       Definition at line 134 of file voms_apic.h.

   #define VERR_SERVER   15
       Unidentifiable VOMS server

       Definition at line 137 of file voms_apic.h.

   #define VERR_SERVERCODE   20
       Error from the server

       Definition at line 142 of file voms_apic.h.

   #define VERR_SIGN   14
       Signature error

       Definition at line 136 of file voms_apic.h.

   #define VERR_TIME   7
       Error in time checking

       Definition at line 127 of file voms_apic.h.

   #define VERR_TYPE   18
       Returned data of unknown type

       Definition at line 140 of file voms_apic.h.

   #define VERR_VERIFY   17
       Generic verification error

       Definition at line 139 of file voms_apic.h.

Typedef Documentation
   typedef void* gss_cred_id_t
       Definition at line 35 of file voms_apic.h.

   typedef void* gss_ctx_id_t
       Definition at line 36 of file voms_apic.h.

Function Documentation
   int getMajorVersionNumber (void)
   int getMinorVersionNumber (void)
   int getPatchVersionNumber (void)
   int VOMS_AddTarget (struct vomsdata * vd, char * target, int * error)
       Adds a target to the AC.

       Parameters:
           vd The vomsdata structure.
           target The target to add. It should be a FQDN.
           error RETURN PARAMETER: qualifies the error message.

       Returns:
           failure (0) or success (<>0)

   int VOMS_Contact (char * hostname, int port, char * servsubject, char *
       command, struct vomsdata * vd, int * error)
       Contacts a VOMS server to get a certificate

       It is the equivalent of the voms_proxy_init command, but without the
       --include functionality.

       Parameters:
           hostname FQDN of the VOMS server
           port the port on which the VOMS server is listening
           servsubject the subject of the server's certificate
           command Command
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_ContactRaw (char * hostname, int port, char * servsubject, char *
       command, void ** data, int * datalen, int * version, struct vomsdata *
       vd, int * error)
       The same as VOMS_Contact, except that instead of starting the
       verification process, the data is returned as is in the

       Parameters:
           data and
           datalen fields.
           hostname FQDN of the VOMS server
           port the port on which the VOMS server is listening
           servsubject the subject of the server's certificate
           command the command sent to the server
           version is the version number of the data.
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   struct voms* VOMS_Copy (struct voms * v, int * error)
       Copies a voms structure. N.B: This is the ONLY way to correctly
       initialize a voms structure as a copy of another voms structure.

       Parameters:
           v The structure to copy.
           error RETURN PARAMETER: qualifies the error message.

       Returns:
           NULL (error) or the new voms structure.

   struct vomsdata* VOMS_CopyAll (struct vomsdata * vd, int * error)
       Copies a vomsdata structure. N.B: This is the ONLY way to correctly
       initialize a vomsdata structure as a copy of another vomsdata
       structure.

       Parameters:
           vd The structure to copy.
           error RETURN PARAMETER: qualifies the error message.

       Returns:
           NULL (error) or the new vomsdata structure.

   struct voms* VOMS_DefaultData (struct vomsdata * vd, int * error)
       Gets the default attributes from a vomsdata structure.

       Parameters:
           vd the vomsdata structure to analyze
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           a pointer to the relevant voms structure. DO NOT modify the fields.

   void VOMS_Delete (struct voms * v)
       Deletes a voms structure

       Parameters:
           v Pointer to the structure to delete.

   void VOMS_DeleteContacts (struct contactdata ** list)
       Frees a contactdata vector.

       Parameters:
           list The vector to free.

       Returns:
           NONE

   void VOMS_Destroy (struct vomsdata * vd)
       Destroys a proper vomsdata structure /param vd The structure to
       deallocate.

   struct vomsdata* VOMS_Duplicate (struct vomsdata * vd)
   char* VOMS_ErrorMessage (struct vomsdata * vd, int error, char * buffer,
       int len)
       Gets a textual description of the error.

       Parameters:
           vd The vomsdata structure to analyze
           error The error returned by the last function
           buffer A pointer to a buffer where the error message will be
           written. If NULL, then memory is allocated by the function, and
           will have to be free()ed by the caller.
           len The length of the memory pointed to by the buffer parameter.

       Returns:
           A pointer to the error message.

   int VOMS_Export (char ** buffer, int * buflen, struct vomsdata * vd, int *
       error)
       Converts data into a test format

       Parameters:
           buffer OUTPUT PARAMETER contains the converted data
           buflen OUTPUT PARAMETER contains the length of buffer
           vd contains the data to convert
           error RETURN PARAMETER Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   struct contactdata** VOMS_FindByAlias (struct vomsdata * vd, char * alias,
       char * system, char * user, int * error)
       Gets a list of VOMS servers which share an alias.

       Parameters:
           vd The correctly initialized vomsdata structured.
           alias The alias to look for.
           system The directory in which to look for the system configuration
           files. If NULL, defaults to /opt/edc/etc/vomses
           user The directory in which to look for the user configuration
           files. Defaults to $VOMS_USERCONF if NULL. Again defaults to
           $HOME/.edg/vomses if the latter is NULL, or to ~/.edg/vomses as a
           last resort.
           error RETURN PARAMETER: qualifies the error message.

       Returns:
           NULL, or a NULL-terminated vector of contactdata structures. The
           only supported way to free this array is via the
           VOMS_DeleteContacts function. Note also that the order in which the
           servers are returned is unspecified.

   struct contactdata** VOMS_FindByVO (struct vomsdata * vd, char * vo, char *
       system, char * user, int * error)
       Gets a list of VOMS servers which serve the same VO.

       Parameters:
           vd The correctly initialized vomsdata structured.
           vo The VO to look for.
           system The directory in which to look for the system configuration
           files. If NULL, defaults to /opt/edc/etc/vomses
           user The directory in which to look for the user configuration
           files. Defaults to $VOMS_USERCONF if NULL. Again defaults to
           $HOME/.edg/vomses if the latter is NULL, or to ~/.edg/vomses as a
           last resort.
           error RETURN PARAMETER: qualifies the error message.

       Returns:
           NULL, or a NULL-terminated vector of contactdata structures. The
           only supported way to free this array is via the
           VOMS_DeleteContacts function. Note also that the order in which the
           servers are returned is unspecified.

   void VOMS_FreeTargets (struct vomsdata * vd, int * error)
       Delete the targets from the AC.

       Parameters:
           vd The vomsdata structure.
           error RETURN PARAMETER: qualifies the error message.

   void VOMS_FreeTargetsList (char **)
   AC* VOMS_GetAC (struct voms * v)
   int VOMS_GetAttribute (struct voms * v, int handle, int num, struct
       attribute * at, struct vomsdata * vd, int * error)
   const char* VOMS_GetAttributeGrantor (struct voms * v, int handle, struct
       vomsdata * vd, int * error)
   int VOMS_GetAttributesNumber (struct voms * v, int handle, struct vomsdata
       * vd, int * error)
   int VOMS_GetAttributeSourceHandle (struct voms * v, int num, struct
       vomsdata * vd, int * error)
   int VOMS_GetAttributeSourcesNumber (struct voms * v, struct vomsdata * vd,
       int * error)
   char** VOMS_GetTargetsList (struct voms * v, struct vomsdata * vd, int *
       error)
   int VOMS_Import (char * buffer, int buflen, struct vomsdata * vd, int *
       error)
       Converts data from the format used for inclusion into a certificate to
       the internal format

       The function does verify the data.

       Parameters:
           buffer contains the data to be converted
           buflen contains the length of buffer
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   struct vomsdata* VOMS_Init (char * voms, char * cert)
       Initializes a vomsdata structure for use by the other functions. N.B:
       This is the ONLY way to correctly initialize a vomsdata structure. It
       is also forbidden to directly take the sizeof() of this structure.

       Parameters:
           voms The directory which contains the certificates of the VOMS
           servers
           cert The directory which contains the CA certificates

       If voms_dir is empty, the value of the environment variable
       X509_VOMS_DIR is taken

       If cert_dir is empty, the value of the environment variable
       X509_CERT_DIR is taken

       Returns:
           NULL for failure, or a pointer to a properly initialized structure.

   char* VOMS_ListTargets (struct vomsdata * vd, int * error)
   int VOMS_LoadCredentials (X509 * cert, EVP_PKEY * pkey, STACK_OF(X509) *
       chain, struct vomsdata * vd, int * error)
   int VOMS_Ordering (char * order, struct vomsdata * vd, int * error)
       Further specified the order of the returned attributes. Please do note
       that calls are cumulative unless VOMS_ResetOrder() is called.

       Parameters:
           order the group:role attribute.
           vd RETURN PARAMETER: contains the modified data.
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_ResetOrder (struct vomsdata * vd, int * error)
       Unsets the return order of the attributes.

       Parameters:
           vd RETURN PARAMETER: contains the modified data.
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_Retrieve (X509 * cert, STACK_OF(X509) * chain, int how, struct
       vomsdata * vd, int * error)
       Extracts the VOMS extension from an X.509 certificate.

                   The function doesn't check the validity of the certificates,
                   but it does check the content of the user data.
                   aram cert The certificate with the VOMS extensions
                   aram chain The chain of the validation certificates
                         (only the intermediate ones)
                   aram how Recursion type
                aram vd RETURN PARAMETER: contains the data returned by the connection
                eturnefailureT(0) orRsuccess (<>0)fies the error message



   int VOMS_RetrieveEXT (X509_EXTENSION * ext, struct vomsdata * vd, int *
       error)
       Gets VOMS information from the given extension

       Parameters:
           ext The extension to parse.
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_RetrieveFromAC (AC * ac, struct vomsdata * vd, int * error)
       Gets VOMS information from an existing globus proxy

       Parameters:
           ac AC from which to get the credentials
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_RetrieveFromCred (gss_cred_id_t cred, int how, struct vomsdata *
       vd, int * error)
       Gets VOMS information from the given globus credential

       Parameters:
           cred The credential from which to retrieve the certificate.
           how Recursion type
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_RetrieveFromCtx (gss_ctx_id_t ctx, int how, struct vomsdata * vd,
       int * error)
       Gets VOMS information from the given globus context

       Parameters:
           ctx The context from which to retrieve the certificate.
           how Recursion type
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_RetrieveFromFile (FILE * file, int how, struct vomsdata * vd, int
       * error)
       Gets VOMS information from the given globus credential

       Parameters:
           file The file from which to retrieve the certificate.
           how Recursion type
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_RetrieveFromProxy (int how, struct vomsdata * vd, int * error)
       Gets VOMS information from an existing globus proxy

       Parameters:
           how Recursion type
           vd RETURN PARAMETER: contains the data returned by the connection
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_SetLifetime (int length, struct vomsdata * vd, int * error)
       Set requested lifetime for VOMS_Contact() calls.

       Parameters:
           length Lifetime requested.
           vd RETURN PARAMETER: contains the modified data.
           error RETURN PARAMETER: Qualifies the error message

       Returns:
           failure (0) or success (<>0)

   int VOMS_SetTimeout (int t, struct vomsdata * vd, int * error)
   int VOMS_SetVerificationTime (time_t verificationtime, struct vomsdata *
       vd, int * error)
   int VOMS_SetVerificationType (int type, struct vomsdata * vd, int * error)
Author
       Generated automatically by Doxygen for VOMS C API from the source code.



Version 1.5.0                   Sun Feb 3 2019                  voms_apic.h(3)