Convert this `IOStream` to an `SSLIOStream`. This enables protocols that begin in clear-text mode and switch to SSL after some initial negotiation (such as the ``STARTTLS`` extension to SMTP and IMAP). This method cannot be used if there are outstanding reads
(
self,
server_side: bool,
ssl_options: Optional[Union[Dict[str, Any], ssl.SSLContext]] = None,
server_hostname: Optional[str] = None,
)
| 1218 | return future |
| 1219 | |
| 1220 | def start_tls( |
| 1221 | self, |
| 1222 | server_side: bool, |
| 1223 | ssl_options: Optional[Union[Dict[str, Any], ssl.SSLContext]] = None, |
| 1224 | server_hostname: Optional[str] = None, |
| 1225 | ) -> Awaitable["SSLIOStream"]: |
| 1226 | """Convert this `IOStream` to an `SSLIOStream`. |
| 1227 | |
| 1228 | This enables protocols that begin in clear-text mode and |
| 1229 | switch to SSL after some initial negotiation (such as the |
| 1230 | ``STARTTLS`` extension to SMTP and IMAP). |
| 1231 | |
| 1232 | This method cannot be used if there are outstanding reads |
| 1233 | or writes on the stream, or if there is any data in the |
| 1234 | IOStream's buffer (data in the operating system's socket |
| 1235 | buffer is allowed). This means it must generally be used |
| 1236 | immediately after reading or writing the last clear-text |
| 1237 | data. It can also be used immediately after connecting, |
| 1238 | before any reads or writes. |
| 1239 | |
| 1240 | The ``ssl_options`` argument may be either an `ssl.SSLContext` |
| 1241 | object or a dictionary of keyword arguments for the |
| 1242 | `ssl.wrap_socket` function. The ``server_hostname`` argument |
| 1243 | will be used for certificate validation unless disabled |
| 1244 | in the ``ssl_options``. |
| 1245 | |
| 1246 | This method returns a `.Future` whose result is the new |
| 1247 | `SSLIOStream`. After this method has been called, |
| 1248 | any other operation on the original stream is undefined. |
| 1249 | |
| 1250 | If a close callback is defined on this stream, it will be |
| 1251 | transferred to the new stream. |
| 1252 | |
| 1253 | .. versionadded:: 4.0 |
| 1254 | |
| 1255 | .. versionchanged:: 4.2 |
| 1256 | SSL certificates are validated by default; pass |
| 1257 | ``ssl_options=dict(cert_reqs=ssl.CERT_NONE)`` or a |
| 1258 | suitably-configured `ssl.SSLContext` to disable. |
| 1259 | """ |
| 1260 | if ( |
| 1261 | self._read_future |
| 1262 | or self._write_futures |
| 1263 | or self._connect_future |
| 1264 | or self._closed |
| 1265 | or self._read_buffer |
| 1266 | or self._write_buffer |
| 1267 | ): |
| 1268 | raise ValueError("IOStream is not idle; cannot convert to SSL") |
| 1269 | if ssl_options is None: |
| 1270 | if server_side: |
| 1271 | ssl_options = _server_ssl_defaults |
| 1272 | else: |
| 1273 | ssl_options = _client_ssl_defaults |
| 1274 | |
| 1275 | socket = self.socket |
| 1276 | self.io_loop.remove_handler(socket) |
| 1277 | self.socket = None # type: ignore |