Vincenzo's original proposal

Some introductory points were removed as are already contained in the requirements list.

* All functions make an internal copy of the passed parameters.  The
  caller retains ownership of the passed arguments.  The library takes
  ownership of the copies. Exceptions are noted in the text.
* All function that return a value, return a copy of it.  The caller
  receives ownership of the copy, but modifying them has obviously no
  effect on the library. 
* This function are not fully specified yet. For example, error codes
  are not listed.  This document is to reach an agreement on what 
  should be provided.



COMMUNICATIONS:

name: create_io_handler
OUT : iohandler
DESC: This function will return an IO handler to be used in all
functions dealing with io. It is an opaque type.  Its size will never
change.
HINTS: for C, this could be a void*, for Java and C++ it will be the object.


name: set_own_credentials
IN  : iohandler
IN  : credhandler
DESC: This function sets the credentials to use for the functions that
require them.  If this function is not called, credentials will be
looked for in the default locations. If a function needs credentials,
and they are not available, this is an error.  If this function is
called when credentials have already been loaded, the existing ones
are deleted, and the new ones are loaded in place.  The function takes
ownership of credhandler.


name: get_remote_credentials
IN  : iohandler
OUT : credhandler
DESC: This function returns a copy of the credential presented by the remote
size, if any, or an error otherwise


name: get_own_credentials
IN  : iohandler
OUT : credhandler
DESC: This function returns a copy of the caller's own credentials, if
available, or an erro otherwise.


name: connect
IN  : iohandler
IN  : host
IN  : port
IN  : flags
IN  : validator_handler
DESC: This function will attempt to estblish a connection with a
partner. The meaning of iohandler, host and port is obvious, while
flags may be:

FLAG_CLEAR    -- connection on the clear
FLAG_SSL      -- SSL connection
FLAG_BLOCKING -- should the socket be blocking?
FLAG_DO_NOT_AUTHENTICATE -- Do not try to authenticate the server's
credentials.
ERROR: If FLAG_CLEAR is not specified, and no credentials are loaded,
this is an error
NOTE: After this call, the iohandler can no longer be shared among
threads.


name: accept
IN  : iohandler
IN  : port
IN  : flags
IN  : validator_handle
OUT : iohandler
DESC: This function starts accepting connections on the port
specified. Flags may be:

FLAG_CLEAR    -- connection on the clear
FLAG_SSL      -- SSL connection
FLAG_BLOCKING -- should the socket be blocking?
FLAG_DO_NOT_AUTHENTICATE -- Do not try to authenticate the server's
credentials.
ERROR: If FLAG_CLEAR is not specified, and no credentials are loaded,
this is an error
RETURN: A new iohandler is returned which has the established
connection. The input iohandler may be reused to accept a new
connection. The returned iohandler can no longer be shared among
threads. 


name: get_socket
IN  : iohandler
OUT : socket
OUT : SSL_handler
DESC: This function returns the real socket used under the covers to
communicate, and the SSL handler if it was defined.


name: put_socket
IN  : iohandler
IN  : socket
IN  : flags
DESC: this function sets a specially defined socket as the socket to
use for communication. 'flags' describe the state the socket is in:
SOCKET_OPEN -- newly created
SOCKET_CONNECTED -- syscall connect() returned
SOCKET_ACCEPTED  -- syscall accept()  returned
-- one of these MUST be present, otherwise it is an error.

SOCKET_CLEAR     -- use socket for cleartext connections
SOCKET_SSL       -- use socket for SSL connections
SOCKET_SSL_ONLY  -- use socket for SSL-only connections
-- one of these MUST be present, otherwise it is an error.

SOCKET_BLOCKING  -- wether the socket is blocking
NOTE: APIs connect() or accept() APIs MUST still be called for sockets with
the SOCKET_CONNECTED or SOCKET_ACCEPTED flags.


name: read
IN  : iohandler
IN  : size
OUT : data
OUT : read_size
DESC: Attempts to read 'size' bytes.  May read less and return
'read_size' bytes instead.  -1 means an error occurred. 'data' MUST be
large enough to accomodate at least 'size' bytes. 


name: write
IN  : iohandler
IN  : data
IN  : size
OUT : written_size
DESC: Attempts to write 'size' bytes from 'data'.  May write less and
write only 'written_size' bytes instead.  -1 means an error
occurred.  


name: get_error
IN  : iohandler
OUT : code
OUT : text_reason
DESC: Return an error code describing the problem, if present, or 0
otherwise.  In case of errors, text_reason may contain a textual
description for it.  The memory taken by it becomes the caller's
property.
NOTE: This is explicitly *not* the content of 'errno', though it may
be used when choosing which error to return.


name: close
IN  : iohandler
DESC: Closes the connection if a connection is established.  It does
nothing otherwise. The iohandler may be reused for new connection. 
iohandler.


name: destroy
IN  : iohandler
DESC: Destroys the iohandler, making it unusable afterwards.  Also
closes existing established connection if there are any. 



CREDENTIALS:

NOTE: below, credential stands for a couple (certificate stack,
private key) where the latter may be empty.

name: create_cred_handler
OUT : credhandler
DESC: This function will returns a cred handler to be used in all
functions dealing with io. It is an opaque type.  Its size will never
change.  A newly created credhandler is empty and cannot be used for
anything useful. A single credhandler may be shared by multiple
iohandlers as long as they contain the same credentials
HINTS:  for C, this could be a void*, for Java and C++ it will be the
object.


name: set_validator_handle
IN  : credhandler
IN  : validhandler
DESC: Specifies the validation handler to use for verifying this set
of credentials


name: destroy
IN  : credhandler
DESC: Destroys the passed credhandler, making it unusable for further
usage.  It also destroy the credentials if needed.


name: put_credential
IN  : credhandler
IN  : credential
OUT : success
DESC: loads the given credential


name: get_credential
IN  : credhandler
OUT : credential
DESC: gets access to a copy of the actual credentials.  It is an error
if no credentials are present


name: delete_credentials
IN  : credhandler
DESC: Removes the credentials from the credhandler.  It is explicitly
not an error to call it when no credentials have been loaded.


name: validate
IN  : credhandler
OUT : result
DESC: attempts validation.  The result is either SUCCESS or FAILURE


name: get_error
IN  : credhandler
OUT : reason
OUT : text_reason
DESC: In case of a failed validation, returns an error code and some
text specifying WHY validation failed.  It is undefined in case of
validation success.



VALIDATOR

name: create_validator_handler
OUT : validhandler
DESC: This function will returns a validation handler to be used in all
functions dealing with io. It is an opaque type.  Its size will never
change.  A newly created credhandler is empty and cannot be used for
anything useful. A single credhandler may be shared by multiple
iohandlers as long as they contain the same credentials
HINTS:  for C, this could be a void*, for Java and C++ it will be the
object.


name: set_validation_mode
IN  : validhandler
IN  : FLAGS
DESC: describe how much validation should actually occur.  Several
modes available, but a least:
MODE_FULL -- full validation (default)
MODE_NONE -- no validation at all


name: set_ancillary_data
IN  : validhandler
IN  : CA certificate location
IN  : CRL location
DESC: loads all the ancillary data needed for credential
validation. 


name: set_validation_callback
IN  : validhandler
IN  : callback function
IN  : userdata
DESC: Sets up a callback function to be called when validation fails.
The function should expect the following parameters, in order:
IN  : certificate stack 
IN  : position
IN  : reason
IN  : userdata
OUT : result
OUT : reason
'certificate stack' -- This is the *whole* certificate stack that
is being validated, up to and including the root certification
autority.
'position' -- This is the position inside the stack of the certificate
that caused the failure
'reason' (IN) -- This is the reason for the failure
'result' -- This is the new result of the validation, either SUCCESS
or FAILURE
'reason' (OUT) -- This is the updated reason for the failure
'userdata' (IN) -- This is the value that was passed to the
set_validation_callback() function.  It is the callback function
responsibility to make sure that access to it in a multi-threaded
environment is done correctly.

The result of this function becomes the updated result for the
validation of the specified certificate in the chain.
NOTE: The callback function, when met with a failure reason it does
not understand, SHOULD return FAILURE and leave 'reason' (OUT)
unchanged from 'reason' (IN).
NOTE: This function may be invoked multiple times.  Al callbacks will
be registered, but the order in which they will be called will be
undefined.  Furthermore, calling callbacks will stop as soon as a
callback returns success, so it may well be that some callbacks will
not be called.




WORKFLOW EXAMPLE (C like -- error checking removed for clarity):

void *valid_handler = create_validator_handler();
set_ancillary_data(valid_handler, "/etc/grid-security/certificates);
set_validation_mode(valid_handler, MODE_FULL);
void *cred_handler = create_cred_handler();
put_credential(cred_handler, "/home/marotta/.globus/usercert.pem",
                             "/home/marotta/.globus/userkey.pem");
set_validator_handle(cred_handler, valid_handler);
void *io_handler = create_io_handler();
set_own_credentials(io_handler, cred_handler);
connect(io_handler, "www.infn.it", 443, FLAG_SSL, valid_handler);
char data[1000];
read_size = read(io_handler, 1000, data);
destroy(io_handler);


WORKFLOW EXAMPLE (C++ like -- error checking removed for clarity):

validator_handler v;
v.set_ancillary_data("/etc/grid-security/certificates);
v.set_validation_mode(MODE_FULL);
cred_handler c;
c.put_credentials("/home/marotta/.globus/usercert.pem",
                  "/home/marotta/.globus/userkey.pem");
c.set_validator_handler(v);
io_handler io;
io.set_own_credentials(c);
io.connect("www.infn.it", 443, FLAG_SSL, v);
char data[1000];
read_size = io.read(1000, data);
// io.destroy(); (destroy role is taken by the destructor)



WORKFLOW EXAMPLE (Java like -- error checking removed for clarity):

cred_handler c = new cred_handler();
validator_handler v = new validator_handler();
v.set_ancillary_data("/etc/grid-security/certificates);
v.set_validation_mode(MODE_FULL);
c.put_credentials("/home/marotta/.globus/usercert.pem",
                  "/home/marotta/.globus/userkey.pem");

c.set_validator_handler(v);
io_handler io = new io_handler();
io.set_own_credentials(c);
io.connect("www.infn.it", 443, FLAG_SSL, v);
char data[1000];
read_size = io.read(1000, data);
io.destroy(); 

-- KrzysztofBenedyczak - 11-Oct-2010