-/*
- * 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.
- * You may obtain a copy of the License at
+/**
+ * Licensed to the University Corporation for Advanced Internet
+ * Development, Inc. (UCAID) under one or more contributor license
+ * agreements. See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ *
+ * UCAID licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the
+ * License at
*
- * http://www.apache.org/licenses/LICENSE-2.0
+ * http://www.apache.org/licenses/LICENSE-2.0
*
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific
+ * language governing permissions and limitations under the License.
*/
/**
* @file xmltooling/soap/SOAPTransport.h
- *
+ *
* Encapsulates a transport layer protocol for sending/receiving messages.
*/
#define __xmltooling_soaptrans_h__
#include <xmltooling/base.h>
+
+#include <string>
#include <iostream>
namespace xmltooling {
-
+
+ class XMLTOOL_API Credential;
+ class XMLTOOL_API CredentialCriteria;
class XMLTOOL_API CredentialResolver;
- class XMLTOOL_API KeyResolver;
class XMLTOOL_API X509TrustEngine;
-
+
/**
* Encapsulates a transport layer protocol for sending/receiving messages.
- *
+ *
* Most of the methods are const, meaning they don't affect the transport
* layer until the data is sent.
*/
{
MAKE_NONCOPYABLE(SOAPTransport);
protected:
- SOAPTransport() {}
+ SOAPTransport();
public:
- virtual ~SOAPTransport() {}
-
+ virtual ~SOAPTransport();
+
+ /**
+ * A simple structure to capture SOAP addressing information.
+ */
+ struct XMLTOOL_API Address {
+ /**
+ * Constructor.
+ *
+ * @param from name of sender
+ * @param to name of recipient
+ * @param endpoint endpoint URL
+ */
+ Address(const char* from, const char* to, const char* endpoint) : m_from(from), m_to(to), m_endpoint(endpoint) {
+ }
+
+ /** Name of sender. */
+ const char* m_from;
+
+ /** Name of recipient. */
+ const char* m_to;
+
+ /** Endpoint URL. */
+ const char* m_endpoint;
+ };
+
/**
* 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)=0;
-
+
/**
* Sets the request timeout.
- *
+ *
* @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)=0;
-
+
/**
* Common types of transport authentication that may be supported.
*/
transport_auth_ntlm = 3,
transport_auth_gss = 4
};
-
+
/**
* Sets a particular form of transport authentication and credentials.
- *
+ *
* @param authType type of transport authentication to use
* @param username username for transport authentication
* @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)=0;
+ virtual bool setAuth(transport_auth_t authType, const char* username=nullptr, const char* password=nullptr)=0;
+
+ /**
+ * Determines whether TLS/SSL connections include a check of the server's certificate
+ * against the expected hostname or address. Defaults to true, and has no effect for
+ * insecure protocols.
+ *
+ * @param verify true iff the hostname should be verified against the server's certificate
+ * @return true iff the transport supports hostname verification
+ */
+ virtual bool setVerifyHost(bool verify)=0;
#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.
- *
- * @param credResolver a locked CredentialResolver instance, or NULL
- * @return true iff the transport supports the use of a CredentialResolver
+ * Supplies transport credentials.
+ *
+ * <p>The lifetime of the credential must be longer than the lifetime of this object.
+ *
+ * @param credential a Credential instance, or nullptr
+ * @return true iff the transport supports the use of the Credential
*/
- virtual bool setCredentialResolver(const CredentialResolver* credResolver)=0;
+ virtual bool setCredential(const Credential* credential=nullptr)=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 trustEngine an X509TrustEngine instance, or nullptr
+ * @param credResolver a CredentialResolver to supply the peer's trusted credentials, or nullptr
+ * @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
- * @param keyResolver optional externally supplied KeyResolver, or NULL
* @return true iff the transport supports the use of a TrustEngine
*/
virtual bool setTrustEngine(
- const X509TrustEngine* trustEngine,
- bool mandatory=true,
- const KeyResolver* keyResolver=NULL
+ const X509TrustEngine* trustEngine=nullptr,
+ const CredentialResolver* credResolver=nullptr,
+ CredentialCriteria* criteria=nullptr,
+ bool mandatory=true
)=0;
#endif
/**
+ * Installs (or clears) a pointer to an object used for cache management of the
+ * content being accessed. The lifetime of the object must be longer than the lifetime
+ * of this object.
+ *
+ * @param cacheTag optional pointer to string used for cache management
+ */
+ virtual bool setCacheTag(std::string* cacheTag=nullptr);
+
+ /**
+ * Sets an implementation-specific transport provider option.
+ *
+ * <p>Requires knowledge of the underlying SOAPTransport implementation.
+ * Without the proper knowledge and inputs, crashes may result.
+ *
+ * @param provider name of the SOAPTransport class the caller believes is in use
+ * @param option implementation-specific string containing the option to set
+ * @param value implementation- and option-specific string to use
+ * @return true iff the transport supports the option and value supplied
+ */
+ virtual bool setProviderOption(const char* provider, const char* option, const char* value);
+
+ /**
* Sends a stream of data over the transport. The function may return without
* having received any data, depending on the nature of the transport.
- *
+ *
+ * <p>If the stream is empty, a request may be issued with no body if the transport
+ * supports that feature.
+ *
* @param in input stream to send
- */
+ */
virtual void send(std::istream& in)=0;
-
+
+ /**
+ * Sends an optional stream of data over the transport. The function may return without
+ * having received any data, depending on the nature of the transport.
+ *
+ * <p>If the parameter is omitted, a request may be issued with no body if the transport
+ * supports that feature.
+ *
+ * @param in input stream to send
+ */
+ virtual void send(std::istream* in=nullptr);
+
/**
* 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;
+ virtual bool isAuthenticated() const=0;
/**
* Returns the MIME type of the response, if any.
- *
+ *
* @return MIME type of response, or an empty string
*/
virtual std::string getContentType() const=0;
+
+ /**
+ * Returns the status code of the response.
+ *
+ * @return transport status code, or 0 if unknown
+ */
+ virtual long getStatusCode() const;
};
+#ifndef XMLTOOLING_NO_XMLSEC
/**
* Registers SOAPTransport classes into the runtime.
*/
void XMLTOOL_API registerSOAPTransports();
-
+
/**
- * Notifies transport infrastructure to initialize.
+ * Notifies transport infrastructure to initialize.
*/
void XMLTOOL_API initSOAPTransports();
-
+
/**
- * Notifies transport infrastructure to shutdown.
+ * Notifies transport infrastructure to shutdown.
*/
void XMLTOOL_API termSOAPTransports();
+#endif
};
projects / shibboleth / cpp-xmltooling.git / blobdiff