Major revamp of credential and trust handling code, PKIX engine still needs work.

[shibboleth/cpp-xmltooling.git] / xmltooling / soap / SOAPTransport.h

diff --git a/xmltooling/soap/SOAPTransport.h b/xmltooling/soap/SOAPTransport.h
index c25f43d..d3b8bc5 100644 (file)
--- a/xmltooling/soap/SOAPTransport.h
+++ b/xmltooling/soap/SOAPTransport.h
@@ -1,5 +1,5 @@
 /*
- *  Copyright 2001-2006 Internet2
+ *  Copyright 2001-2007 Internet2
  * 
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,13 +26,10 @@
 #include <xmltooling/base.h>
 #include <iostream>
 
-namespace xmlsignature {
-    class XMLTOOL_API CredentialResolver;
-    class XMLTOOL_API KeyResolver;
-};
-
 namespace xmltooling {
     
+    class XMLTOOL_API Credential;
+    class XMLTOOL_API CredentialResolver;
     class XMLTOOL_API X509TrustEngine;
     
     /**
@@ -50,12 +47,19 @@ namespace xmltooling {
         virtual ~SOAPTransport() {}
         
         /**
+         * Indicates whether transport provides confidentiality.
+         * 
+         * @return  true iff transport layer provides confidentiality
+         */
+        virtual bool isConfidential() const=0;
+        
+        /**
          * Sets the connection timeout.
          * 
          * @param timeout  time to wait for connection to server in seconds, or -1 for no timeout
          * @return  true iff the transport supports connection timeouts
          */
-        virtual bool setConnectTimeout(long timeout) const=0;
+        virtual bool setConnectTimeout(long timeout)=0;
         
         /**
          * Sets the request timeout.
@@ -63,7 +67,7 @@ namespace xmltooling {
          * @param timeout  time to wait for a response in seconds, or -1 for no timeout
          * @return  true iff the transport supports request/response timeouts
          */
-        virtual bool setTimeout(long timeout) const=0;
+        virtual bool setTimeout(long timeout)=0;
         
         /**
          * Common types of transport authentication that may be supported.
@@ -84,40 +88,62 @@ namespace xmltooling {
          * @param password  simple password/credential for transport authentication
          * @return  true iff the transport supports the indicated form of authentication
          */
-        virtual bool setAuth(transport_auth_t authType, const char* username=NULL, const char* password=NULL) const=0;
+        virtual bool setAuth(transport_auth_t authType, const char* username=NULL, const char* password=NULL)=0;
 
-#ifndef XMLTOOLING_NO_XMLSEC 
+#ifndef XMLTOOLING_NO_XMLSEC
         /**
-         * Provides a CredentialResolver to the transport to supply transport credentials.
-         * The lifetime of the resolver must be longer than the lifetime of this object.
-         * 
-         * <p>The CredentialResolver <strong>MUST</strong> be locked by the caller. 
+         * Supplies transport credentials.
+         *
+         * <p>The lifetime of the credential must be longer than the lifetime of this object.
          * 
-         * @param credResolver  a locked CredentialResolver instance, or NULL
-         * @return true iff the transport supports the use of a CredentialResolver
+         * @param credential  a Credential instance, or NULL
+         * @return true iff the transport supports the use of the Credential
          */
-        virtual bool setCredentialResolver(const xmlsignature::CredentialResolver* credResolver) const=0;
+        virtual bool setCredential(const Credential* credential=NULL)=0;
 
         /**
-         * Provides a TrustEngine to the transport to authenticate the transport peer.
+         * Provides an X509TrustEngine to the transport to authenticate the transport peer.
          * The lifetime of the engine must be longer than the lifetime of this object.
          * 
-         * @param trustEngine   a TrustEngine instance, or NULL
-         * @param keyResolver   optional externally supplied KeyResolver, or NULL
+         * @param trustEngine   an X509TrustEngine instance, or NULL
+         * @param credResolver  a CredentialResolver to supply the peer's trusted credentials, or NULL
+         * @param criteria      optional criteria for selecting peer credentials
+         * @param mandatory     flag controls whether message is sent at all if the
+         *                      transport isn't authenticated using the TrustEngine
          * @return true iff the transport supports the use of a TrustEngine
          */
-        virtual bool setTrustEngine(const X509TrustEngine* trustEngine, const xmlsignature::KeyResolver* keyResolver=NULL) const=0;
+        virtual bool setTrustEngine(
+            const X509TrustEngine* trustEngine=NULL,
+            const CredentialResolver* credResolver=NULL,
+            CredentialCriteria* criteria=NULL,
+            bool mandatory=true
+            )=0;
 #endif
 
         /**
-         * Sends a stream of data over the transport, and writes the results into another.
+         * Sends a stream of data over the transport. The function may return without
+         * having received any data, depending on the nature of the transport.
          * 
          * @param in    input stream to send
-         * @param out   output stream to write result into 
          */        
-        virtual size_t send(std::istream& in, std::ostream& out)=0;
+        virtual void send(std::istream& in)=0;
         
         /**
+         * Returns reference to response stream.  The resulting stream must be
+         * checked directly to determine whether data is available.
+         * 
+         * @return  reference to a stream containing the response, if any
+         */
+        virtual std::istream& receive()=0;
+        
+        /**
+         * Returns result of authenticating transport peer.
+         * 
+         * @return true iff TrustEngine or other mechanism successfully authenticated the peer
+         */
+        virtual bool isSecure() const=0;
+
+        /**
          * Returns the MIME type of the response, if any.
          * 
          * @return  MIME type of response, or an empty string