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.
Parameters
handle 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.
Return values
GLOBUS_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
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().
Parameters
url 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 message packing
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.
Return values
GLOBUS_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
See also
globus_gram_protocol_callback_disallow()
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.
Parameters
context 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() returns
GLOBUS_TRUE, otherwise, this function returns
GLOBUS_FALSE.
Return values
GLOBUS_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.
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.
Parameters
url 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.
Return values
GLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
GLOBUS_GRAM_PROTOCOL_ERROR_CALLBACK_NOT_FOUND Callback not found
See also
globus_gram_protocol_allow_attach()
Get a reference to the GSSAPI security context associated with a
GRAM protocol handle. The
globus_gram_protocol_get_sec_context() function
retrieves a reference to the GSSAPI security context associated with a
particular GRAM protocol handle. This context may be inspected by the caller
but must not be destroyed by the caller. The
globus_gram_protocol_get_sec_context() function
must only be called after the GRAM protocol library has called the
callback function associated with a GRAM protocol message
exchange.
Parameters
handle 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() returns
GLOBUS_SUCCESS and modifies the context parameter to point to
the security context associated with the handle parameter. If an
error occurs, an integer error code is returned and the value of the
context parameter is undefined.
Return values
GLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
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.
Parameters
url 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.
Return values
GLOBUS_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().
See also
globus_gram_protocol_reply()
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.
Parameters
url 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.
Return values
GLOBUS_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().
See also
globus_gram_protocol_reply()
Reply to a GRAM protocol message. The
globus_gram_protocol_reply() function sends a
response message to a client which initiated a GRAM message exchange. The
globus_gram_protocol_reply() function composes
the message with an HTTP message frame and then sends it to the client which
initiated the exchange.
Parameters
handle 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.
code The HTTP response code. The code should be one from the set
described in RFC 2616.
message A pointer to a message string to be sent to the GRAM client. 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.
Returns
Upon success,
globus_gram_protocol_reply() returns GLOBUS_SUCCESS,
frames the message with an HTTP header and initiates sending the
message to the client. The caller must not try to use the value of the
handle parameter after this function returns. If an error
occurs, its integer error code will be returned.
Return values
GLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No Resources
See also
globus_gram_protocol_allow_attach()
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
Parameters
attr 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.
Return values
GLOBUS_SUCCESS Success
GLOBUS_GRAM_PROTOCOL_ERROR_CONNECTION_FAILED Error initializing
attribute