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 | |
29 | namespace Poco { |
30 | namespace Net { |
31 | |
32 | |
33 | class SecureStreamSocket; |
34 | class HTTPRequest; |
35 | class HTTPResponse; |
36 | |
37 | |
38 | class 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 | { |
72 | public: |
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 | |
147 | protected: |
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 | |
153 | private: |
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 | |