TPTP feature: 195644

Requirement summary

This feature should cover the work required to enhance TPTP Agent Controller to provide a pluggable layer for external ssl providers. Pluggable module with required ssl provider (JSSE, OpenSSL) should be set in AC configuration file and should be loaded dynamically during AC startup.

Design summary

• Logic. To simplify AC it is suggested don't add once more network port for ssl communications but use single server port for all connections. To do this AC could create insecure ServerSocket and listen to client requests on configured network port (10006 defaults) as before. AC accepts insecure incoming connection and, if security is enabled, responses with CONNECTION_REFUSE protocol message with SECURITY_REQUIRED reason. After that AC passes this socket to ssl module for ssl handshaking over already established insecure connection. So pluggable ssl modules should support two data exchange modes - secure and insecure. After accepting connection and before ssl handshaking, module should use insecure mode, after handshaking - secure. It gives ability to do some insecure negotiations (sending securityRequest..) before ssl handshaking. Clients, receiving SECURITY_REQUIRED, mesage don't close the connection but use it for ssl handshaking as well.
  
  In current implementation ServerSocket, listening to clients, is resided in Socket Transport Layer. But taking in account that pluggable modules may be native as weel as Java based, and we can't do ssl handshaking in Java over native AC's sockets, we will not create ServerSocket and accept insecure connections in AC. Instead of this, ServerSocket should reside in a pluggable module, which should be dynamically loaded if security is enabled. Note, when security is disabled, no pluggable modules are loaded and clients are listened to in Socket Transport Layer as before.
  
  
• API. It is suggested that the pluggable layer dynamically loads ssl provider modules and use the following API, which modules should provide:
  • int sslInit(log_service_t* logService, int portToListen) - initializes the module and opens provided port to listen to client's requests. logService - pointer to the structure providing common AC logging service. sslInit() returns 0 on success and -1 on initialization error;
    
    
  • void* sslAccept() - accepts incoming insecure connection, initializes internal connection resources and returns a connection reference. Connection reference is a pointer to internal data of the pluggable module. It might be any structure or just an integer number;
    
    
  • int sslHandshake(void* con) - negotiates ssl connection over opened insecure connection. Returns 0 on success and -1 on error. Parameter con - connection reference given by sslAccept();
    
    
  • int sslRead(void* con, char* buffer, int length) - reads data from the connection into provided buffer. Before sslHandshake() is called, sslRead() reads from plain insecure socket, after - uses ssl service to read. Returns the total number of bytes read into the buffer, or -1 on error;
    
    
  • int sslWrite(void* con, char* buffer, int length) - writes data to the connection. Before sslHandshake() is called, sslWrite() writes to the plain insecure socket, after - using ssl service. Returns the total number of written bytes, or -1 on error;
    
    
  • int sslClose(void* con) - closes connection and releases allocated connection resources;
    
    
  • int sslReset() - closes server socket, releases all internal allocated resources;
    
    
  • void sslSetValue(const char* name, const char* value) – passes configuration information to the pluggable module;
    
    
  • char* sslGetValue() - retrieves information from the pluggable layer;
    
    
  • char* sslGetProviderName() - provides ssl provider name and its version;
    
    
• Configuration.
  
  • all configuration information is stored in AC’s configuration file serviceconfig.xml in parent tags <TransportLayer loadlib=”socketTL”..><Configuration>… </Configuration></TransportLayer>
  • AC recognizes and processes the two following configuration tags:
    • <SecurityEnabled>true</SecurityEnabled> - enabling security, security is disabled by default;
    • <SSLproviderLib>library name</SSLproviderName> - library name of pluggable module to be dynamically loaded by the pluggable layer;
  • all other tags are assumed to be configuration parameters of pluggable module and passed to the module via sslSetValue() call; These parameters might include path to ssl key and certificate files, path to jvm library and so on;