intglobus_gram_protocol_accept_delegation(globus_gram_protocol_handle_thandle,gss_OID_setrestriction_oids,gss_buffer_set_trestriction_buffers,OM_uint32req_flags,OM_uint32time_req,globus_gram_protocol_delegation_callback_tcallback,void*arg)
Perform the server-side of the GSSAPI delegation handshake to receive a new delegated credential. The
globus_gram_protocol_accept_delegation() function performs the service side accepting of a GRAM protocol
delegation exchange with a GRAM protocol client. This is performed after the delegation HTTP message has
been unpacked by the application.
The globus_gram_protocol_accept_delegation() function returns after processing the GSSAPI handshake,
passing the delegated credential or error information to the function pointed to by the callback
parameter.
Parametershandle A GRAM protocol handle on which the server received a protocol refresh message.
restriction_oids A set of OID values indicating the data in the restriction_buffers parameter. This
parameter may have the value GSS_C_NO_OID_SET if there are no restriction buffers.
restriction_buffers A set of binary data buffers which will be included in the delegated credential.
The type of data in these buffers is determined by the OID values in restriction_oids. This parameter
may have the value GSS_C_EMPTY_BUFFER_SET if there are no extra restrictions to be added to the
credential.
req_flags A bitwise-or of GSSAPI flag values to use when delegating the credential using
gss_init_delegation().
time_req An integer value indicating the length of time (in seconds) that the delegated credential
should be valid for. This is an advisory parameter: no error will be returned if a credential with
the requested lifetime can not be created.
callback A pointer to a function to call when the delegation handshake has completed or failed. This
function will be passed the value of arg as well as the handle and delegated credential or error that
occurred processing the delegation messages.
arg A pointer to application-specific data which will be passed to the function pointed to by
callback as its first parameter. This may be NULL if the application has a NULL callback or does not
require the pointer to establish its context in the callback.
Returns
Upon success, globus_gram_protocol_accept_delegation() returns GLOBUS_SUCCESS and registers the
function pointed to by callback to be called after the delegation completes or fails. If an error
occurs, globus_gram_protocol_accept_delegation() returns an integer error code and the callback
function is not registered.
ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_MALLOC_FAILED Malloc failed
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources
intglobus_gram_protocol_allow_attach(char**url,globus_gram_protocol_callback_tcallback,void*callback_arg)
Create a GRAM protocol service listener. The globus_gram_protocol_allow_attach() function creates a GRAM
protocol listener to which other processes can send GRAM protocol messages. The listener will
automatically accept new connections on it's TCP/IP port and parse GRAM requests. The requests will be
passed to the function pointed to by the callback parameter for the application to unpack, handle, and
send a reply by calling globus_gram_protocol_reply().
Parametersurl An output parameter that will be initialized to point to a string that will hold the URL of the
new listener. This URL may be published or otherwise passed to applications which need to contact
this GRAM protocol server. The URL will be of the form https://host:port/.
callback A pointer to a function to be called when a new request has been received by this listener.
This function will be passed the request, which may be unpacked using one of the functions described
in the messagepacking section of the documentation.
callback_arg A pointer to arbitrary user data which will be passed to the callback function as its
first parameter.
Returns
Upon success, globus_gram_protocol_allow_attach() returns GLOBUS_SUCCESS and modifies the url
parameter to point to a newly allocated string. The caller is then responsible for freeing this
string. If an error occurs, an integer error code will be returned and the url parameter value will
be uninitialized.
ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources
Seealsoglobus_gram_protocol_callback_disallow()globus_bool_tglobus_gram_protocol_authorize_self(gss_ctx_id_tcontext)
Determine if a GSSAPI context has the same source and target identities. The
globus_gram_protocol_authorize_self() function implements a predicate which returns true if the source
and destination identities used to establish the GSSAPI security context are the same.
Parameterscontext A GSSAPI security context which has been previously established. The source and target names
of this context will be inspected by this function.
Returns
If the source and target identiies are the same, then globus_gram_protocol_authorize_self()returnsGLOBUS_TRUE,otherwise,thisfunctionreturnsGLOBUS_FALSE.ReturnvaluesGLOBUS_TRUE The source and target identities are the same.
GLOBUS_FALSE The source and target identities are not the same or this function is unabled to inspect
the security context.
intglobus_gram_protocol_callback_disallow(char*url)
Stop a GASS protocol listener from handling new requests. The globus_gram_protocol_callback_disallow()
function stops the listener named by the value of the url parameter from receiving any new requests. It
also frees memory used internally by the GRAM protocol implementation to handle requests for this
listener.
The globus_gram_protocol_callback_disallow() function will wait until all requests being processed by
this listener have completed processing. Once globus_gram_protocol_callback_disallow() returns, no
further request callbacks will occur for the listener.
Parametersurl A pointer to the URL string which names the listener to disable.
Returns
Upon success, the globus_gram_protocol_callback_disallow() function returns GLOBUS_SUCCESS and frees
internal state associated with the listener named by the url parameter. If an error occurs, its
integer error code value will be returned and no listener will be affected.
ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
GLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND Callback not found
Seealsoglobus_gram_protocol_allow_attach()intglobus_gram_protocol_get_sec_context(globus_gram_protocol_handle_thandle,gss_ctx_id_t*context)
Get a reference to the GSSAPI security context associated with a GRAM protocol handle. The
globus_gram_protocol_get_sec_context()functionretrievesareferencetotheGSSAPIsecuritycontextassociatedwithaparticularGRAMprotocolhandle.Thiscontextmaybeinspectedbythecallerbutmustnotbedestroyedbythecaller.Theglobus_gram_protocol_get_sec_context()functionmustonlybecalledaftertheGRAMprotocollibraryhascalledthecallbackfunctionassociatedwithaGRAMprotocolmessageexchange.Parametershandle The GRAM protocol handle associated with a GRAM protocol message exchange.
context The GSSAPI security context associated with the protocol handle.
Returns
Upon success, globus_gram_protocol_get_sec_context()returnsGLOBUS_SUCCESSandmodifiesthecontextparametertopointtothesecuritycontextassociatedwiththehandleparameter.Ifanerroroccurs,anintegererrorcodeisreturnedandthevalueofthecontextparameterisundefined.ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
intglobus_gram_protocol_post(constchar*url,globus_gram_protocol_handle_t*handle,globus_io_attr_t*attr,globus_byte_t*message,globus_size_tmessage_size,globus_gram_protocol_callback_tcallback,void*callback_arg)
Post a GRAM protocol request to a GRAM server. The globus_gram_protocol_post() function initiates a GRAM
protocol message exchange with a GRAM protocol listener. It returns after framing the message and
initiating the connection. When the message exchange is complete, the function pointed to by callback is
invoked either in another thread or when a non-threaded application calls the globus_poll() or
globus_cond_wait() functions.
Parametersurl A pointer to a string containing the URL of the server to post the request to. This URL must be
an HTTPS URL naming a GRAM service resource.
handle A pointer to a globus_gram_protocol_handle_t which will be initialized with a unique handle
identifier. This identifier will be passed to the callback function to allow the caller to
differentiate replies to multiple GRAM Protocol requests. This pointer may be NULL if the caller will
not have multiple simultaneous requests.
attr A pointer to a Globus I/O attribute set, which will be used as parameters when connecting to the
GRAM server. The value of attr may be NULL, in which case, the default GRAM Protocol attributes will
be used (authentication to self, SSL-compatible transport, with message integrity).
message A pointer to a message string to be sent to the GRAM server. This is normally created by
calling one of the GRAM Protocol pack functions. This message need not be NULL terminated as the
length is passed in the message_size parameter.
message_size The length of the message string. Typically generated as one of the output parameters to
one of the GRAM Protocol pack functions.
callback A pointer to a function to call when the response to this message is received or the message
exchange fails. This may be NULL, in which case no callback will be received, and the caller will be
unable to verify whether the message was successfully received.
callback_arg A pointer to application-specific data which will be passed to the function pointed to
by callback as its first parameter. This may be NULL if the application has a NULL callback or does
not require the pointer to establish its context in the callback.
Returns
Upon success, globus_gram_protocol_post() returns GLOBUS_SUCCESS, initiates the message exchange,
registers the function pointed to by callback to be called when the exchange completes or fails, and
modifies the handle parameter if it is non-NULL. If an error occurs, its error code will be returned,
the handle parameter will be uninitialized and the function pointed to be callback will not be
called.
ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources
Note
There is no way to time out or cancel a service request that is begun with
globus_gram_protocol_post().
Seealsoglobus_gram_protocol_reply()intglobus_gram_protocol_post_delegation(constchar*url,globus_gram_protocol_handle_t*handle,globus_io_attr_t*attr,globus_byte_t*message,globus_size_tmessage_size,gss_cred_id_tcred_handle,gss_OID_setrestriction_oids,gss_buffer_set_trestriction_buffers,OM_uint32req_flags,OM_uint32time_req,globus_gram_protocol_callback_tcallback,void*callback_arg)
Post a GRAM protocol delegation request to a GRAM server. The globus_gram_protocol_post_delegation()
function initiates a GRAM protocol delegation exchange with a GRAM protocol listener. The delegation
protocol is a custom mix of HTTP and SSL records.
The globus_gram_protocol_post_delegation() function returns after framing the message and initiating the
connection to be used for delegation. When the message exchange is complete, the function pointed to by
callback is invoked either in another thread or when a non-threaded application calls the globus_poll()
or globus_cond_wait() functions.
Parametersurl A pointer to a string containing the URL of the server to post the request to. This URL must be
an HTTPS URL naming a GRAM service resource.
handle A pointer to a globus_gram_protocol_handle_t which will be initialized with a unique handle
identifier. This identifier will be passed to the callback function to allow the caller to
differentiate replies to multiple GRAM Protocol requests. This pointer may be NULL if the caller will
not have multiple simultaneous requests.
attr A pointer to a Globus I/O attribute set, which will be used as parameters when connecting to the
GRAM server. The value of attr may be NULL, in which case, the default GRAM Protocol attributes will
be used (authentication to self, SSL-compatible transport, with message integrity).
message A pointer to a message string to be sent to the GRAM server. This is normally created by
calling one of the GRAM Protocol pack functions. This message need not be NULL terminated as the
length is passed in the message_size parameter.
message_size The length of the message string. Typically generated as one of the output parameters to
one of the GRAM Protocol pack functions.
cred_handle Handle to an existing GSSAPI security credential. If this parameter is set to
GSS_C_NO_CREDENTIAL, then the current account's default credential will be used. A proxy credential
sharing the identity of this credential will be delegated to the GRAM protocol server.
restriction_oids A set of OID values indicating the data in the restriction_buffers parameter. This
parameter may have the value GSS_C_NO_OID_SET if there are no restriction buffers.
restriction_buffers A set of binary data buffers which will be included in the delegated credential.
The type of data in these buffers is determined by the OID values in restriction_oids. This parameter
may have the value GSS_C_EMPTY_BUFFER_SET if there are no extra restrictions to be added to the
credential.
req_flags A bitwise-or of GSSAPI flag values to use when delegating the credential using
gss_init_delegation().
time_req An integer value indicating the length of time (in seconds) that the delegated credential
should be valid for. This is an advisory parameter: no error will be returned if a credential with
the requested lifetime can not be created.
callback A pointer to a function to call when the response to this message is received or the message
exchange fails. This may be NULL, in which case no callback will be received, and the caller will be
unable to verify whether the message was successfully received.
callback_arg A pointer to application-specific data which will be passed to the function pointed to
by callback as its first parameter. This may be NULL if the application has a NULL callback or does
not require the pointer to establish its context in the callback.
Returns
Upon success, globus_gram_protocol_post_delegation() returns GLOBUS_SUCCESS, initiates the message
exchange, registers the function pointed to by callback to be called when the exchange completes or
fails, and modifies the handle parameter if it is non-NULL. If an error occurs, its error code will
be returned, the handle parameter will be uninitialized and the function pointed to be callback will
not be called. In the case of a protocol or delegation failure, the callback function will be called
with the errorcode parameter set to the error.
ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources
Note
There is no way to time out or cancel a service request that is begun with
globus_gram_protocol_post_delegation().
Seealsoglobus_gram_protocol_reply()intglobus_gram_protocol_reply(globus_gram_protocol_handle_thandle,intcode,globus_byte_t*message,globus_size_tmessage_size)
Reply to a GRAM protocol message. The globus_gram_protocol_reply()functionsendsaresponsemessagetoaclientwhichinitiatedaGRAMmessageexchange.Theglobus_gram_protocol_reply()functioncomposesthemessagewithanHTTPmessageframeandthensendsittotheclientwhichinitiatedtheexchange.Parametershandle A GRAM protocol handle which is used by this function to determine the network connection to
use for this reply. This must be the same value as was passed as a parameter to the callback function
registered with the globus_gram_protocol_allow_attach()function.codeTheHTTPresponsecode.ThecodeshouldbeonefromthesetdescribedinRFC2616.messageApointertoamessagestringtobesenttotheGRAMclient.ThisisnormallycreatedbycallingoneoftheGRAMProtocolpackfunctions.ThismessageneednotbeNULLterminatedasthelengthispassedinthemessage_sizeparameter.message_sizeThelengthofthemessagestring.TypicallygeneratedasoneoftheoutputparameterstooneoftheGRAMProtocolpackfunctions.Returns
Upon success, globus_gram_protocol_reply()returnsGLOBUS_SUCCESS,framesthemessagewithanHTTPheaderandinitiatessendingthemessagetotheclient.Thecallermustnottrytousethevalueofthehandleparameterafterthisfunctionreturns.Ifanerroroccurs,itsintegererrorcodewillbereturned.ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No Resources
Seealsoglobus_gram_protocol_allow_attach()intglobus_gram_protocol_setup_attr(globus_io_attr_t*attr)
Create default I/O attribute for GRAM. The globus_gram_protocol_setup_attr() function creates a new
globus_io attribute containing the default set of values needed for communication between a GRAM client
and a job manager. These attributes include:
• SO_KEEPALIVE
• GSSAPI Mutual Authentication
• GSSAPI Self Authorization
• SSL-compatible message wrapping
Parametersattr A pointer to a globus_io_attr_t structure which will be initialized by this function.
Returns
Upon success, globus_gram_protocol_setup_attr() modifies the attr parameter to point to a new
attribute and returns the value GLOBUS_SUCCESS. When this occurs, the caller must destroy the
attribute when no longer needed by calling globus_io_tcpattr_destroy(). If an error occurs, its value
will be returned and the attribute pointed to by the attr parameter will be set to an uninitialized
state.
ReturnvaluesGLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_CONNECTION_FAILED Error initializing attribute
Install Now
PNG Icons
