1//
2// HTTPSClientSession.h
3//
4// Library: NetSSL_OpenSSL
5// Package: HTTPSClient
6// Module: HTTPSClientSession
7//
8// Definition of the HTTPSClientSession class.
9//
10// Copyright (c) 2006-2009, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef NetSSL_HTTPSClientSession_INCLUDED
18#define NetSSL_HTTPSClientSession_INCLUDED
19
20
21#include "Poco/Net/NetSSL.h"
22#include "Poco/Net/Utility.h"
23#include "Poco/Net/HTTPClientSession.h"
24#include "Poco/Net/Context.h"
25#include "Poco/Net/Session.h"
26#include "Poco/Net/X509Certificate.h"
27
28
29namespace Poco {
30namespace Net {
31
32
33class SecureStreamSocket;
34class HTTPRequest;
35class HTTPResponse;
36
37
38class NetSSL_API HTTPSClientSession: public HTTPClientSession
39 /// This class implements the client-side of
40 /// a HTTPS session.
41 ///
42 /// To send a HTTPS request to a HTTPS server, first
43 /// instantiate a HTTPSClientSession object and
44 /// specify the server's host name and port number.
45 ///
46 /// Then create a HTTPRequest object, fill it accordingly,
47 /// and pass it as argument to the sendRequest() method.
48 ///
49 /// sendRequest() will return an output stream that can
50 /// be used to send the request body, if there is any.
51 ///
52 /// After you are done sending the request body, create
53 /// a HTTPResponse object and pass it to receiveResponse().
54 ///
55 /// This will return an input stream that can be used to
56 /// read the response body.
57 ///
58 /// See RFC 2616 <http://www.faqs.org/rfcs/rfc2616.html> for more
59 /// information about the HTTP protocol.
60 ///
61 /// Note that sending requests that neither contain a content length
62 /// field in the header nor are using chunked transfer encoding will
63 /// result in a SSL protocol violation, as the framework shuts down
64 /// the socket after sending the message body. No orderly SSL shutdown
65 /// will be performed in this case.
66 ///
67 /// If session caching has been enabled for the Context object passed
68 /// to the HTTPSClientSession, the HTTPSClientSession class will
69 /// attempt to reuse a previously obtained Session object in
70 /// case of a reconnect.
71{
72public:
73 enum
74 {
75 HTTPS_PORT = 443
76 };
77
78 HTTPSClientSession();
79 /// Creates an unconnected HTTPSClientSession.
80
81 explicit HTTPSClientSession(const SecureStreamSocket& socket);
82 /// Creates a HTTPSClientSession using the given socket.
83 /// The socket must not be connected. The session
84 /// takes ownership of the socket.
85
86 HTTPSClientSession(const SecureStreamSocket& socket, Session::Ptr pSession);
87 /// Creates a HTTPSClientSession using the given socket.
88 /// The socket must not be connected. The session
89 /// takes ownership of the socket.
90 ///
91 /// The given Session is reused, if possible (client session
92 /// caching is enabled for the given Context, and the server
93 /// agrees to reuse the session).
94
95 HTTPSClientSession(const std::string& host, Poco::UInt16 port = HTTPS_PORT);
96 /// Creates a HTTPSClientSession using the given host and port.
97
98 explicit HTTPSClientSession(Context::Ptr pContext);
99 /// Creates an unconnected HTTPSClientSession, using the
100 /// give SSL context.
101
102 HTTPSClientSession(Context::Ptr pContext, Session::Ptr pSession);
103 /// Creates an unconnected HTTPSClientSession, using the
104 /// give SSL context.
105 ///
106 /// The given Session is reused, if possible (client session
107 /// caching is enabled for the given Context, and the server
108 /// agrees to reuse the session).
109
110 HTTPSClientSession(const std::string& host, Poco::UInt16 port, Context::Ptr pContext);
111 /// Creates a HTTPSClientSession using the given host and port,
112 /// using the given SSL context.
113
114 HTTPSClientSession(const std::string& host, Poco::UInt16 port, Context::Ptr pContext, Session::Ptr pSession);
115 /// Creates a HTTPSClientSession using the given host and port,
116 /// using the given SSL context.
117 ///
118 /// The given Session is reused, if possible (client session
119 /// caching is enabled for the given Context, and the server
120 /// agrees to reuse the session).
121
122 ~HTTPSClientSession();
123 /// Destroys the HTTPSClientSession and closes
124 /// the underlying socket.
125
126 bool secure() const;
127 /// Return true iff the session uses SSL or TLS,
128 /// or false otherwise.
129
130 X509Certificate serverCertificate();
131 /// Returns the server's certificate.
132 ///
133 /// The certificate is available after the first request has been sent.
134
135 Session::Ptr sslSession();
136 /// Returns the SSL Session object for the current
137 /// connection, if session caching has been enabled for
138 /// the HTTPSClientSession's Context. A null pointer is
139 /// returned otherwise.
140 ///
141 /// The Session object can be obtained after the first request has
142 /// been sent.
143
144 // HTTPSession
145 void abort();
146
147protected:
148 void connect(const SocketAddress& address);
149 std::string proxyRequestPrefix() const;
150 void proxyAuthenticate(HTTPRequest& request);
151 int read(char* buffer, std::streamsize length);
152
153private:
154 HTTPSClientSession(const HTTPSClientSession&);
155 HTTPSClientSession& operator = (const HTTPSClientSession&);
156
157 Context::Ptr _pContext;
158 Session::Ptr _pSession;
159};
160
161
162} } // namespace Poco::Net
163
164
165#endif // Net_HTTPSClientSession_INCLUDED
166