~dkuhlman/python-training-materials/Materials

<h1>17.3. <a class="reference internal" href="#module-ssl" title="ssl: TLS/SSL wrapper for socket objects"><code class="xref py py-mod docutils literal">ssl</code></a> — TLS/SSL wrapper for socket objects<a class="headerlink" href="#module-ssl" title="Permalink to this headline">¶</a></h1>

New in version 2.6.

</div>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/2.7/Lib/ssl.py">Lib/ssl.py</a>

This module provides access to Transport Layer Security (often known as “Secure

Sockets Layer”) encryption and peer authentication facilities for network

sockets, both client-side and server-side. This module uses the OpenSSL

library. It is available on all modern Unix systems, Windows, Mac OS X, and

probably additional platforms, as long as OpenSSL is installed on that platform.

Note

Some behavior may be platform dependent, since calls are made to the

operating system socket APIs. The installed version of OpenSSL may also

cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with

openssl version 1.0.1.

</div>

Warning

Don’t use this module without reading the <a class="reference internal" href="#ssl-security">Security considerations</a>. Doing so

may lead to a false sense of security, as the default settings of the

100

ssl module are not necessarily appropriate for your application.

101

</div>

102

This section documents the objects and functions in the <code class="docutils literal">ssl</code> module; for more

103

general information about TLS, SSL, and certificates, the reader is referred to

104

the documents in the “See Also” section at the bottom.

105

This module provides a class, <code class="xref py py-class docutils literal">ssl.SSLSocket</code>, which is derived from the

106

<a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a> type, and provides a socket-like wrapper that also

107

encrypts and decrypts the data going over the socket with SSL. It supports

108

additional methods such as <code class="xref py py-meth docutils literal">getpeercert()</code>, which retrieves the

109

certificate of the other side of the connection, and <code class="xref py py-meth docutils literal">cipher()</code>,which

110

retrieves the cipher being used for the secure connection.

111

For more sophisticated applications, the <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">ssl.SSLContext</code></a> class

112

helps manage settings and certificates, which can then be inherited

113

by SSL sockets created through the <a class="reference internal" href="#ssl.SSLContext.wrap_socket" title="ssl.SSLContext.wrap_socket"><code class="xref py py-meth docutils literal">SSLContext.wrap_socket()</code></a> method.

114

115

<h2>17.3.1. Functions, Constants, and Exceptions<a class="headerlink" href="#functions-constants-and-exceptions" title="Permalink to this headline">¶</a></h2>

116

117

118

exception <code class="descclassname">ssl.</code><code class="descname">SSLError</code><a class="headerlink" href="#ssl.SSLError" title="Permalink to this definition">¶</a></dt>

119

<dd>Raised to signal an error from the underlying SSL implementation (currently

120

provided by the OpenSSL library). This signifies some problem in the

121

higher-level encryption and authentication layer that’s superimposed on the

122

underlying network connection. This error is a subtype of

123

<a class="reference internal" href="socket.html#socket.error" title="socket.error"><code class="xref py py-exc docutils literal">socket.error</code></a>, which in turn is a subtype of <a class="reference internal" href="exceptions.html#exceptions.IOError" title="exceptions.IOError"><code class="xref py py-exc docutils literal">IOError</code></a>. The

124

error code and message of <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-exc docutils literal">SSLError</code></a> instances are provided by the

125

OpenSSL library.

126

127

128

<code class="descname">library</code><a class="headerlink" href="#ssl.SSLError.library" title="Permalink to this definition">¶</a></dt>

129

<dd>A string mnemonic designating the OpenSSL submodule in which the error

130

occurred, such as <code class="docutils literal">SSL</code>, <code class="docutils literal">PEM</code> or <code class="docutils literal">X509</code>. The range of possible

131

values depends on the OpenSSL version.

132

133

New in version 2.7.9.

134

</div>

135

</dd></dl>

136

137

138

139

<code class="descname">reason</code><a class="headerlink" href="#ssl.SSLError.reason" title="Permalink to this definition">¶</a></dt>

140

<dd>A string mnemonic designating the reason this error occurred, for

141

example <code class="docutils literal">CERTIFICATE_VERIFY_FAILED</code>. The range of possible

142

values depends on the OpenSSL version.

143

144

New in version 2.7.9.

145

</div>

146

</dd></dl>

147

148

</dd></dl>

149

150

151

152

exception <code class="descclassname">ssl.</code><code class="descname">SSLZeroReturnError</code><a class="headerlink" href="#ssl.SSLZeroReturnError" title="Permalink to this definition">¶</a></dt>

153

154

the SSL connection has been closed cleanly. Note that this doesn’t

155

mean that the underlying transport (read TCP) has been closed.

156

157

New in version 2.7.9.

158

</div>

159

</dd></dl>

160

161

162

163

exception <code class="descclassname">ssl.</code><code class="descname">SSLWantReadError</code><a class="headerlink" href="#ssl.SSLWantReadError" title="Permalink to this definition">¶</a></dt>

164

<dd>A subclass of <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-exc docutils literal">SSLError</code></a> raised by a <a class="reference internal" href="#ssl-nonblocking">non-blocking SSL socket</a> when trying to read or write data, but more data needs

165

to be received on the underlying TCP transport before the request can be

166

fulfilled.

167

168

New in version 2.7.9.

169

</div>

170

</dd></dl>

171

172

173

174

exception <code class="descclassname">ssl.</code><code class="descname">SSLWantWriteError</code><a class="headerlink" href="#ssl.SSLWantWriteError" title="Permalink to this definition">¶</a></dt>

175

176

to be sent on the underlying TCP transport before the request can be

177

fulfilled.

178

179

New in version 2.7.9.

180

</div>

181

</dd></dl>

182

183

184

185

exception <code class="descclassname">ssl.</code><code class="descname">SSLSyscallError</code><a class="headerlink" href="#ssl.SSLSyscallError" title="Permalink to this definition">¶</a></dt>

186

187

while trying to fulfill an operation on a SSL socket. Unfortunately,

188

there is no easy way to inspect the original errno number.

189

190

New in version 2.7.9.

191

</div>

192

</dd></dl>

193

194

195

196

exception <code class="descclassname">ssl.</code><code class="descname">SSLEOFError</code><a class="headerlink" href="#ssl.SSLEOFError" title="Permalink to this definition">¶</a></dt>

197

198

terminated abruptly. Generally, you shouldn’t try to reuse the underlying

199

transport when this error is encountered.

200

201

New in version 2.7.9.

202

</div>

203

</dd></dl>

204

205

206

207

exception <code class="descclassname">ssl.</code><code class="descname">CertificateError</code><a class="headerlink" href="#ssl.CertificateError" title="Permalink to this definition">¶</a></dt>

208

<dd>Raised to signal an error with a certificate (such as mismatching

209

hostname). Certificate errors detected by OpenSSL, though, raise

210

an <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-exc docutils literal">SSLError</code></a>.

211

</dd></dl>

212

213

214

<h3>17.3.1.1. Socket creation<a class="headerlink" href="#socket-creation" title="Permalink to this headline">¶</a></h3>

215

The following function allows for standalone socket creation. Starting from

216

Python 2.7.9, it can be more flexible to use <a class="reference internal" href="#ssl.SSLContext.wrap_socket" title="ssl.SSLContext.wrap_socket"><code class="xref py py-meth docutils literal">SSLContext.wrap_socket()</code></a>

217

instead.

218

219

220

<code class="descclassname">ssl.</code><code class="descname">wrap_socket</code>(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version={see docs}, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)<a class="headerlink" href="#ssl.wrap_socket" title="Permalink to this definition">¶</a></dt>

221

<dd>Takes an instance <code class="docutils literal">sock</code> of <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a>, and returns an instance

222

of <code class="xref py py-class docutils literal">ssl.SSLSocket</code>, a subtype of <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a>, which wraps

223

the underlying socket in an SSL context. <code class="docutils literal">sock</code> must be a

224

<a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-data docutils literal">SOCK_STREAM</code></a> socket; other socket types are unsupported.

225

For client-side sockets, the context construction is lazy; if the

226

underlying socket isn’t connected yet, the context construction will be

227

performed after <code class="xref py py-meth docutils literal">connect()</code> is called on the socket. For

228

server-side sockets, if the socket has no remote peer, it is assumed

229

to be a listening socket, and the server-side SSL wrapping is

230

automatically performed on client connections accepted via the

231

<code class="xref py py-meth docutils literal">accept()</code> method. <a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a> may raise <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-exc docutils literal">SSLError</code></a>.

232

The <code class="docutils literal">keyfile</code> and <code class="docutils literal">certfile</code> parameters specify optional files which

233

contain a certificate to be used to identify the local side of the

234

connection. See the discussion of <a class="reference internal" href="#ssl-certificates">Certificates</a> for more

235

information on how the certificate is stored in the <code class="docutils literal">certfile</code>.

236

The parameter <code class="docutils literal">server_side</code> is a boolean which identifies whether

237

server-side or client-side behavior is desired from this socket.

238

The parameter <code class="docutils literal">cert_reqs</code> specifies whether a certificate is required from

239

the other side of the connection, and whether it will be validated if

240

provided. It must be one of the three values <a class="reference internal" href="#ssl.CERT_NONE" title="ssl.CERT_NONE"><code class="xref py py-const docutils literal">CERT_NONE</code></a>

241

(certificates ignored), <a class="reference internal" href="#ssl.CERT_OPTIONAL" title="ssl.CERT_OPTIONAL"><code class="xref py py-const docutils literal">CERT_OPTIONAL</code></a> (not required, but validated

242

if provided), or <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-const docutils literal">CERT_REQUIRED</code></a> (required and validated). If the

243

value of this parameter is not <a class="reference internal" href="#ssl.CERT_NONE" title="ssl.CERT_NONE"><code class="xref py py-const docutils literal">CERT_NONE</code></a>, then the <code class="docutils literal">ca_certs</code>

244

parameter must point to a file of CA certificates.

245

The <code class="docutils literal">ca_certs</code> file contains a set of concatenated “certification

246

authority” certificates, which are used to validate certificates passed from

247

the other end of the connection. See the discussion of

248

<a class="reference internal" href="#ssl-certificates">Certificates</a> for more information about how to arrange the

249

certificates in this file.

250

The parameter <code class="docutils literal">ssl_version</code> specifies which version of the SSL protocol to

251

use. Typically, the server chooses a particular protocol version, and the

252

client must adapt to the server’s choice. Most of the versions are not

253

interoperable with the other versions. If not specified, the default is

254

<a class="reference internal" href="#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-data docutils literal">PROTOCOL_SSLv23</code></a>; it provides the most compatibility with other

255

versions.

256

Here’s a table showing which versions in a client (down the side) can connect

257

to which versions in a server (along the top):

258

259

260

261

262

263

264

265

266

267

268

</colgroup>

269

270

<tr class="row-odd"><td>client / server</td>

271

272

273

274

275

276

277

</tr>

278

279

280

281

282

283

284

285

</tr>

286

287

288

289

290

291

292

293

</tr>

294

295

296

297

298

299

300

301

</tr>

302

303

304

305

306

307

308

309

</tr>

310

311

312

313

314

315

316

317

</tr>

318

319

320

321

322

323

324

325

</tr>

326

</tbody>

327

</table>

328

</div></blockquote>

329

330

Note

331

Which connections succeed will vary depending on the version of

332

OpenSSL. For example, before OpenSSL 1.0.0, an SSLv23 client

333

would always attempt SSLv2 connections.

334

</div>

335

The ciphers parameter sets the available ciphers for this SSL object.

336

It should be a string in the <a class="reference external" href="https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT">OpenSSL cipher list format</a>.

337

The parameter <code class="docutils literal">do_handshake_on_connect</code> specifies whether to do the SSL

338

handshake automatically after doing a <code class="xref py py-meth docutils literal">socket.connect()</code>, or whether the

339

application program will call it explicitly, by invoking the

340

<a class="reference internal" href="#ssl.SSLSocket.do_handshake" title="ssl.SSLSocket.do_handshake"><code class="xref py py-meth docutils literal">SSLSocket.do_handshake()</code></a> method. Calling

341

342

blocking behavior of the socket I/O involved in the handshake.

343

The parameter <code class="docutils literal">suppress_ragged_eofs</code> specifies how the

344

<code class="xref py py-meth docutils literal">SSLSocket.read()</code> method should signal unexpected EOF from the other end

345

of the connection. If specified as <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> (the default), it returns a

346

normal EOF (an empty bytes object) in response to unexpected EOF errors

347

raised from the underlying socket; if <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a>, it will raise the

348

exceptions back to the caller.

349

350

Changed in version 2.7: New optional argument ciphers.

351

</div>

352

</dd></dl>

353

354

</div>

355

356

<h3>17.3.1.2. Context creation<a class="headerlink" href="#context-creation" title="Permalink to this headline">¶</a></h3>

357

A convenience function helps create <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> objects for common

358

purposes.

359

360

361

<code class="descclassname">ssl.</code><code class="descname">create_default_context</code>(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)<a class="headerlink" href="#ssl.create_default_context" title="Permalink to this definition">¶</a></dt>

362

<dd>Return a new <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> object with default settings for

363

the given purpose. The settings are chosen by the <a class="reference internal" href="#module-ssl" title="ssl: TLS/SSL wrapper for socket objects"><code class="xref py py-mod docutils literal">ssl</code></a> module,

364

and usually represent a higher security level than when calling the

365

<a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> constructor directly.

366

cafile, capath, cadata represent optional CA certificates to

367

trust for certificate verification, as in

368

<a class="reference internal" href="#ssl.SSLContext.load_verify_locations" title="ssl.SSLContext.load_verify_locations"><code class="xref py py-meth docutils literal">SSLContext.load_verify_locations()</code></a>. If all three are

369

<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, this function can choose to trust the system’s default

370

CA certificates instead.

371

The settings are: <a class="reference internal" href="#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-data docutils literal">PROTOCOL_SSLv23</code></a>, <a class="reference internal" href="#ssl.OP_NO_SSLv2" title="ssl.OP_NO_SSLv2"><code class="xref py py-data docutils literal">OP_NO_SSLv2</code></a>, and

372

373

without unauthenticated cipher suites. Passing <a class="reference internal" href="#ssl.Purpose.SERVER_AUTH" title="ssl.Purpose.SERVER_AUTH"><code class="xref py py-data docutils literal">SERVER_AUTH</code></a>

374

as purpose sets <a class="reference internal" href="#ssl.SSLContext.verify_mode" title="ssl.SSLContext.verify_mode"><code class="xref py py-data docutils literal">verify_mode</code></a> to <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-data docutils literal">CERT_REQUIRED</code></a>

375

and either loads CA certificates (when at least one of cafile, capath or

376

cadata is given) or uses <a class="reference internal" href="#ssl.SSLContext.load_default_certs" title="ssl.SSLContext.load_default_certs"><code class="xref py py-meth docutils literal">SSLContext.load_default_certs()</code></a> to load

377

default CA certificates.

378

379

Note

380

The protocol, options, cipher and other settings may change to more

381

restrictive values anytime without prior deprecation. The values

382

represent a fair balance between compatibility and security.

383

If your application needs specific settings, you should create a

384

<a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> and apply the settings yourself.

385

</div>

386

387

Note

388

If you find that when certain older clients or servers attempt to connect

389

with a <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> created by this function that they get an error

390

stating “Protocol or cipher suite mismatch”, it may be that they only

391

support SSL3.0 which this function excludes using the

392

<a class="reference internal" href="#ssl.OP_NO_SSLv3" title="ssl.OP_NO_SSLv3"><code class="xref py py-data docutils literal">OP_NO_SSLv3</code></a>. SSL3.0 is widely considered to be <a class="reference external" href="https://en.wikipedia.org/wiki/POODLE">completely broken</a>. If you still wish to continue to

393

use this function but still allow SSL 3.0 connections you can re-enable

394

them using:

395

<div class="last highlight-python"><div class="highlight"><pre>ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)

396

ctx.options &= ~ssl.OP_NO_SSLv3

397

</pre></div>

398

</div>

399

</div>

400

401

New in version 2.7.9.

402

</div>

403

404

Changed in version 2.7.10: RC4 was dropped from the default cipher string.

405

</div>

406

407

Changed in version 2.7.13: ChaCha20/Poly1305 was added to the default cipher string.

408

3DES was dropped from the default cipher string.

409

</div>

410

</dd></dl>

411

412

413

414

<code class="descclassname">ssl.</code><code class="descname">_https_verify_certificates</code>(enable=True)<a class="headerlink" href="#ssl._https_verify_certificates" title="Permalink to this definition">¶</a></dt>

415

<dd>Specifies whether or not server certificates are verified when creating

416

client HTTPS connections without specifying a particular SSL context.

417

Starting with Python 2.7.9, <a class="reference internal" href="httplib.html#module-httplib" title="httplib: HTTP and HTTPS protocol client (requires sockets)."><code class="xref py py-mod docutils literal">httplib</code></a> and modules which use it, such as

418

<a class="reference internal" href="urllib2.html#module-urllib2" title="urllib2: Next generation URL opening library."><code class="xref py py-mod docutils literal">urllib2</code></a> and <a class="reference internal" href="xmlrpclib.html#module-xmlrpclib" title="xmlrpclib: XML-RPC client access."><code class="xref py py-mod docutils literal">xmlrpclib</code></a>, default to verifying remote server

419

certificates received when establishing client HTTPS connections. This

420

default verification checks that the certificate is signed by a Certificate

421

Authority in the system trust store and that the Common Name (or Subject

422

Alternate Name) on the presented certificate matches the requested host.

423

Setting enable to <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> ensures this default behaviour is in

424

effect.

425

Setting enable to <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> reverts the default HTTPS certificate

426

handling to that of Python 2.7.8 and earlier, allowing connections to

427

servers using self-signed certificates, servers using certificates signed

428

by a Certicate Authority not present in the system trust store, and servers

429

where the hostname does not match the presented server certificate.

430

The leading underscore on this function denotes that it intentionally does

431

not exist in any implementation of Python 3 and may not be present in all

432

Python 2.7 implementations. The portable approach to bypassing certificate

433

checks or the system trust store when necessary is for tools to enable that

434

on a case-by-case basis by explicitly passing in a suitably configured SSL

435

context, rather than reverting the default behaviour of the standard library

436

client modules.

437

438

New in version 2.7.12.

439

</div>

440

441

See also

442

443

444

– HTTPS man-in-the-middle attack against Python clients using default settings</li>

445

<li><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0476">PEP 476</a> – Enabling certificate verification by default for HTTPS</li>

446

<li><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0493">PEP 493</a> – HTTPS verification migration tools for Python 2.7</li>

447

</ul>

448

</div>

449

</dd></dl>

450

451

</div>

452

453

<h3>17.3.1.3. Random generation<a class="headerlink" href="#random-generation" title="Permalink to this headline">¶</a></h3>

454

455

456

Deprecated since version 2.7.13: OpenSSL has deprecated <code class="xref py py-func docutils literal">ssl.RAND_pseudo_bytes()</code>, use

457

<code class="xref py py-func docutils literal">ssl.RAND_bytes()</code> instead.

458

</div>

459

</div></blockquote>

460

461

462

<code class="descclassname">ssl.</code><code class="descname">RAND_status</code>()<a class="headerlink" href="#ssl.RAND_status" title="Permalink to this definition">¶</a></dt>

463

<dd>Return <code class="docutils literal">True</code> if the SSL pseudo-random number generator has been seeded

464

with ‘enough’ randomness, and <code class="docutils literal">False</code> otherwise. You can use

465

<a class="reference internal" href="#ssl.RAND_egd" title="ssl.RAND_egd"><code class="xref py py-func docutils literal">ssl.RAND_egd()</code></a> and <a class="reference internal" href="#ssl.RAND_add" title="ssl.RAND_add"><code class="xref py py-func docutils literal">ssl.RAND_add()</code></a> to increase the randomness of

466

the pseudo-random number generator.

467

</dd></dl>

468

469

470

471

472

<dd>If you are running an entropy-gathering daemon (EGD) somewhere, and path

473

is the pathname of a socket connection open to it, this will read 256 bytes

474

of randomness from the socket, and add it to the SSL pseudo-random number

475

generator to increase the security of generated secret keys. This is

476

typically only necessary on systems without better sources of randomness.

477

See <a class="reference external" href="http://egd.sourceforge.net/">http://egd.sourceforge.net/</a> or <a class="reference external" href="http://prngd.sourceforge.net/">http://prngd.sourceforge.net/</a> for sources

478

of entropy-gathering daemons.

479

Availability: not available with LibreSSL and OpenSSL > 1.1.0

480

</dd></dl>

481

482

483

484

<code class="descclassname">ssl.</code><code class="descname">RAND_add</code>(bytes, entropy)<a class="headerlink" href="#ssl.RAND_add" title="Permalink to this definition">¶</a></dt>

485

<dd>Mix the given bytes into the SSL pseudo-random number generator. The

486

parameter entropy (a float) is a lower bound on the entropy contained in

487

string (so you can always use <code class="xref py py-const docutils literal">0.0</code>). See <a class="rfc reference external" href="https://tools.ietf.org/html/rfc1750.html">RFC 1750</a> for more

488

information on sources of entropy.

489

</dd></dl>

490

491

</div>

492

493

<h3>17.3.1.4. Certificate handling<a class="headerlink" href="#certificate-handling" title="Permalink to this headline">¶</a></h3>

494

495

496

<code class="descclassname">ssl.</code><code class="descname">match_hostname</code>(cert, hostname)<a class="headerlink" href="#ssl.match_hostname" title="Permalink to this definition">¶</a></dt>

497

<dd>Verify that cert (in decoded format as returned by

498

499

applied are those for checking the identity of HTTPS servers as outlined

500

in <a class="rfc reference external" href="https://tools.ietf.org/html/rfc2818.html">RFC 2818</a> and <a class="rfc reference external" href="https://tools.ietf.org/html/rfc6125.html">RFC 6125</a>, except that IP addresses are not currently

501

supported. In addition to HTTPS, this function should be suitable for

502

checking the identity of servers in various SSL-based protocols such as

503

FTPS, IMAPS, POPS and others.

504

<a class="reference internal" href="#ssl.CertificateError" title="ssl.CertificateError"><code class="xref py py-exc docutils literal">CertificateError</code></a> is raised on failure. On success, the function

505

returns nothing:

506

<div class="highlight-python"><div class="highlight"><pre>>>> cert = {'subject': ((('commonName', 'example.com'),),)}

507

>>> ssl.match_hostname(cert, "example.com")

508

509

Traceback (most recent call last):

510

File "<stdin>", line 1, in <module>

511

File "/home/py3k/Lib/ssl.py", line 130, in match_hostname

512

ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

513

</pre></div>

514

</div>

515

516

New in version 2.7.9.

517

</div>

518

</dd></dl>

519

520

521

522

<code class="descclassname">ssl.</code><code class="descname">cert_time_to_seconds</code>(cert_time)<a class="headerlink" href="#ssl.cert_time_to_seconds" title="Permalink to this definition">¶</a></dt>

523

<dd>Return the time in seconds since the Epoch, given the <code class="docutils literal">cert_time</code>

524

string representing the “notBefore” or “notAfter” date from a

525

certificate in <code class="docutils literal">"%b %d %H:%M:%S %Y %Z"</code> strptime format (C

526

locale).

527

Here’s an example:

528

<div class="highlight-python"><div class="highlight"><pre>>>> import ssl

529

>>> timestamp = ssl.cert_time_to_seconds("Jan 5 09:34:43 2018 GMT")

530

>>> timestamp

531

1515144883

532

>>> from datetime import datetime

533

>>> print(datetime.utcfromtimestamp(timestamp))

534

2018-01-05 09:34:43

535

</pre></div>

536

</div>

537

“notBefore” or “notAfter” dates must use GMT (<a class="rfc reference external" href="https://tools.ietf.org/html/rfc5280.html">RFC 5280</a>).

538

539

Changed in version 2.7.9: Interpret the input time as a time in UTC as specified by ‘GMT’

540

timezone in the input string. Local timezone was used

541

previously. Return an integer (no fractions of a second in the

542

input format)

543

</div>

544

</dd></dl>

545

546

547

548

<code class="descclassname">ssl.</code><code class="descname">get_server_certificate</code>(addr, ssl_version=PROTOCOL_SSLv23, ca_certs=None)<a class="headerlink" href="#ssl.get_server_certificate" title="Permalink to this definition">¶</a></dt>

549

<dd>Given the address <code class="docutils literal">addr</code> of an SSL-protected server, as a (hostname,

550

port-number) pair, fetches the server’s certificate, and returns it as a

551

PEM-encoded string. If <code class="docutils literal">ssl_version</code> is specified, uses that version of

552

the SSL protocol to attempt to connect to the server. If <code class="docutils literal">ca_certs</code> is

553

specified, it should be a file containing a list of root certificates, the

554

same format as used for the same parameter in <a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a>. The call

555

will attempt to validate the server certificate against that set of root

556

certificates, and will fail if the validation attempt fails.

557

558

Changed in version 2.7.9: This function is now IPv6-compatible, and the default ssl_version is

559

changed from <a class="reference internal" href="#ssl.PROTOCOL_SSLv3" title="ssl.PROTOCOL_SSLv3"><code class="xref py py-data docutils literal">PROTOCOL_SSLv3</code></a> to <a class="reference internal" href="#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-data docutils literal">PROTOCOL_SSLv23</code></a> for

560

maximum compatibility with modern servers.

561

</div>

562

</dd></dl>

563

564

565

566

<code class="descclassname">ssl.</code><code class="descname">DER_cert_to_PEM_cert</code>(DER_cert_bytes)<a class="headerlink" href="#ssl.DER_cert_to_PEM_cert" title="Permalink to this definition">¶</a></dt>

567

<dd>Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded

568

string version of the same certificate.

569

</dd></dl>

570

571

572

573

<code class="descclassname">ssl.</code><code class="descname">PEM_cert_to_DER_cert</code>(PEM_cert_string)<a class="headerlink" href="#ssl.PEM_cert_to_DER_cert" title="Permalink to this definition">¶</a></dt>

574

<dd>Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of

575

bytes for that same certificate.

576

</dd></dl>

577

578

579

580

<code class="descclassname">ssl.</code><code class="descname">get_default_verify_paths</code>()<a class="headerlink" href="#ssl.get_default_verify_paths" title="Permalink to this definition">¶</a></dt>

581

<dd>Returns a named tuple with paths to OpenSSL’s default cafile and capath.

582

The paths are the same as used by

583

<a class="reference internal" href="#ssl.SSLContext.set_default_verify_paths" title="ssl.SSLContext.set_default_verify_paths"><code class="xref py py-meth docutils literal">SSLContext.set_default_verify_paths()</code></a>. The return value is a

584

<a class="reference internal" href="../glossary.html#term-named-tuple">named tuple</a> <code class="docutils literal">DefaultVerifyPaths</code>:

585

586

<li><code class="xref py py-attr docutils literal">cafile</code> - resolved path to cafile or <code class="docutils literal">None</code> if the file doesn’t exist,</li>

587

<li><code class="xref py py-attr docutils literal">capath</code> - resolved path to capath or <code class="docutils literal">None</code> if the directory doesn’t exist,</li>

588

<li><code class="xref py py-attr docutils literal">openssl_cafile_env</code> - OpenSSL’s environment key that points to a cafile,</li>

589

<li><code class="xref py py-attr docutils literal">openssl_cafile</code> - hard coded path to a cafile,</li>

590

<li><code class="xref py py-attr docutils literal">openssl_capath_env</code> - OpenSSL’s environment key that points to a capath,</li>

591

<li><code class="xref py py-attr docutils literal">openssl_capath</code> - hard coded path to a capath directory</li>

592

</ul>

593

Availability: LibreSSL ignores the environment vars

594

<code class="xref py py-attr docutils literal">openssl_cafile_env</code> and <code class="xref py py-attr docutils literal">openssl_capath_env</code>

595

596

New in version 2.7.9.

597

</div>

598

</dd></dl>

599

600

601

602

<code class="descclassname">ssl.</code><code class="descname">enum_certificates</code>(store_name)<a class="headerlink" href="#ssl.enum_certificates" title="Permalink to this definition">¶</a></dt>

603

<dd>Retrieve certificates from Windows’ system cert store. store_name may be

604

one of <code class="docutils literal">CA</code>, <code class="docutils literal">ROOT</code> or <code class="docutils literal">MY</code>. Windows may provide additional cert

605

stores, too.

606

The function returns a list of (cert_bytes, encoding_type, trust) tuples.

607

The encoding_type specifies the encoding of cert_bytes. It is either

608

<code class="xref py py-const docutils literal">x509_asn</code> for X.509 ASN.1 data or <code class="xref py py-const docutils literal">pkcs_7_asn</code> for

609

PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set

610

of OIDS or exactly <code class="docutils literal">True</code> if the certificate is trustworthy for all

611

purposes.

612

Example:

613

<div class="highlight-python"><div class="highlight"><pre>>>> ssl.enum_certificates("CA")

614

[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),

615

(b'data...', 'x509_asn', True)]

616

</pre></div>

617

</div>

618

Availability: Windows.

619

620

New in version 2.7.9.

621

</div>

622

</dd></dl>

623

624

625

626

<code class="descclassname">ssl.</code><code class="descname">enum_crls</code>(store_name)<a class="headerlink" href="#ssl.enum_crls" title="Permalink to this definition">¶</a></dt>

627

<dd>Retrieve CRLs from Windows’ system cert store. store_name may be

628

629

stores, too.

630

The function returns a list of (cert_bytes, encoding_type, trust) tuples.

631

The encoding_type specifies the encoding of cert_bytes. It is either

632

633

PKCS#7 ASN.1 data.

634

Availability: Windows.

635

636

New in version 2.7.9.

637

</div>

638

</dd></dl>

639

640

</div>

641

642

<h3>17.3.1.5. Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h3>

643

644

645

646

<dd>Possible value for <a class="reference internal" href="#ssl.SSLContext.verify_mode" title="ssl.SSLContext.verify_mode"><code class="xref py py-attr docutils literal">SSLContext.verify_mode</code></a>, or the <code class="docutils literal">cert_reqs</code>

647

parameter to <a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a>. In this mode (the default), no

648

certificates will be required from the other side of the socket connection.

649

If a certificate is received from the other end, no attempt to validate it

650

is made.

651

See the discussion of <a class="reference internal" href="#ssl-security">Security considerations</a> below.

652

</dd></dl>

653

654

655

656

<code class="descclassname">ssl.</code><code class="descname">CERT_OPTIONAL</code><a class="headerlink" href="#ssl.CERT_OPTIONAL" title="Permalink to this definition">¶</a></dt>

657

658

659

required from the other side of the socket connection; but if they

660

are provided, validation will be attempted and an <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-class docutils literal">SSLError</code></a>

661

will be raised on failure.

662

Use of this setting requires a valid set of CA certificates to

663

be passed, either to <a class="reference internal" href="#ssl.SSLContext.load_verify_locations" title="ssl.SSLContext.load_verify_locations"><code class="xref py py-meth docutils literal">SSLContext.load_verify_locations()</code></a> or as a

664

value of the <code class="docutils literal">ca_certs</code> parameter to <a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a>.

665

</dd></dl>

666

667

668

669

<code class="descclassname">ssl.</code><code class="descname">CERT_REQUIRED</code><a class="headerlink" href="#ssl.CERT_REQUIRED" title="Permalink to this definition">¶</a></dt>

670

671

672

required from the other side of the socket connection; an <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-class docutils literal">SSLError</code></a>

673

will be raised if no certificate is provided, or if its validation fails.

674

Use of this setting requires a valid set of CA certificates to

675

676

677

</dd></dl>

678

679

680

681

<code class="descclassname">ssl.</code><code class="descname">VERIFY_DEFAULT</code><a class="headerlink" href="#ssl.VERIFY_DEFAULT" title="Permalink to this definition">¶</a></dt>

682

<dd>Possible value for <a class="reference internal" href="#ssl.SSLContext.verify_flags" title="ssl.SSLContext.verify_flags"><code class="xref py py-attr docutils literal">SSLContext.verify_flags</code></a>. In this mode, certificate

683

revocation lists (CRLs) are not checked. By default OpenSSL does neither

684

require nor verify CRLs.

685

686

New in version 2.7.9.

687

</div>

688

</dd></dl>

689

690

691

692

<code class="descclassname">ssl.</code><code class="descname">VERIFY_CRL_CHECK_LEAF</code><a class="headerlink" href="#ssl.VERIFY_CRL_CHECK_LEAF" title="Permalink to this definition">¶</a></dt>

693

694

peer cert is check but non of the intermediate CA certificates. The mode

695

requires a valid CRL that is signed by the peer cert’s issuer (its direct

696

ancestor CA). If no proper has been loaded

697

<a class="reference internal" href="#ssl.SSLContext.load_verify_locations" title="ssl.SSLContext.load_verify_locations"><code class="xref py py-attr docutils literal">SSLContext.load_verify_locations</code></a>, validation will fail.

698

699

New in version 2.7.9.

700

</div>

701

</dd></dl>

702

703

704

705

<code class="descclassname">ssl.</code><code class="descname">VERIFY_CRL_CHECK_CHAIN</code><a class="headerlink" href="#ssl.VERIFY_CRL_CHECK_CHAIN" title="Permalink to this definition">¶</a></dt>

706

707

all certificates in the peer cert chain are checked.

708

709

New in version 2.7.9.

710

</div>

711

</dd></dl>

712

713

714

715

<code class="descclassname">ssl.</code><code class="descname">VERIFY_X509_STRICT</code><a class="headerlink" href="#ssl.VERIFY_X509_STRICT" title="Permalink to this definition">¶</a></dt>

716

717

for broken X.509 certificates.

718

719

New in version 2.7.9.

720

</div>

721

</dd></dl>

722

723

724

725

<code class="descclassname">ssl.</code><code class="descname">VERIFY_X509_TRUSTED_FIRST</code><a class="headerlink" href="#ssl.VERIFY_X509_TRUSTED_FIRST" title="Permalink to this definition">¶</a></dt>

726

727

prefer trusted certificates when building the trust chain to validate a

728

certificate. This flag is enabled by default.

729

730

New in version 2.7.10.

731

</div>

732

</dd></dl>

733

734

735

736

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_TLS</code><a class="headerlink" href="#ssl.PROTOCOL_TLS" title="Permalink to this definition">¶</a></dt>

737

<dd>Selects the highest protocol version that both the client and server support.

738

Despite the name, this option can select “TLS” protocols as well as “SSL”.

739

740

New in version 2.7.13.

741

</div>

742

</dd></dl>

743

744

745

746

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_SSLv23</code><a class="headerlink" href="#ssl.PROTOCOL_SSLv23" title="Permalink to this definition">¶</a></dt>

747

<dd>Alias for <code class="docutils literal">PROTOCOL_TLS</code>.

748

749

Deprecated since version 2.7.13: Use <code class="docutils literal">PROTOCOL_TLS</code> instead.

750

</div>

751

</dd></dl>

752

753

754

755

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_SSLv2</code><a class="headerlink" href="#ssl.PROTOCOL_SSLv2" title="Permalink to this definition">¶</a></dt>

756

<dd>Selects SSL version 2 as the channel encryption protocol.

757

This protocol is not available if OpenSSL is compiled with the

758

<code class="docutils literal">OPENSSL_NO_SSL2</code> flag.

759

760

Warning

761

SSL version 2 is insecure. Its use is highly discouraged.

762

</div>

763

764

Deprecated since version 2.7.13: OpenSSL has removed support for SSLv2.

765

</div>

766

</dd></dl>

767

768

769

770

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_SSLv3</code><a class="headerlink" href="#ssl.PROTOCOL_SSLv3" title="Permalink to this definition">¶</a></dt>

771

<dd>Selects SSL version 3 as the channel encryption protocol.

772

This protocol is not be available if OpenSSL is compiled with the

773

<code class="docutils literal">OPENSSL_NO_SSLv3</code> flag.

774

775

Warning

776

SSL version 3 is insecure. Its use is highly discouraged.

777

</div>

778

779

Deprecated since version 2.7.13: OpenSSL has deprecated all version specific protocols. Use the default

780

protocol with flags like <code class="docutils literal">OP_NO_SSLv3</code> instead.

781

</div>

782

</dd></dl>

783

784

785

786

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_TLSv1</code><a class="headerlink" href="#ssl.PROTOCOL_TLSv1" title="Permalink to this definition">¶</a></dt>

787

<dd>Selects TLS version 1.0 as the channel encryption protocol.

788

789

Deprecated since version 2.7.13: OpenSSL has deprecated all version specific protocols. Use the default

790

protocol with flags like <code class="docutils literal">OP_NO_SSLv3</code> instead.

791

</div>

792

</dd></dl>

793

794

795

796

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_TLSv1_1</code><a class="headerlink" href="#ssl.PROTOCOL_TLSv1_1" title="Permalink to this definition">¶</a></dt>

797

<dd>Selects TLS version 1.1 as the channel encryption protocol.

798

Available only with openssl version 1.0.1+.

799

800

New in version 2.7.9.

801

</div>

802

803

Deprecated since version 2.7.13: OpenSSL has deprecated all version specific protocols. Use the default

804

protocol with flags like <code class="docutils literal">OP_NO_SSLv3</code> instead.

805

</div>

806

</dd></dl>

807

808

809

810

<code class="descclassname">ssl.</code><code class="descname">PROTOCOL_TLSv1_2</code><a class="headerlink" href="#ssl.PROTOCOL_TLSv1_2" title="Permalink to this definition">¶</a></dt>

811

<dd>Selects TLS version 1.2 as the channel encryption protocol. This is the

812

most modern version, and probably the best choice for maximum protection,

813

if both sides can speak it. Available only with openssl version 1.0.1+.

814

815

New in version 2.7.9.

816

</div>

817

818

Deprecated since version 2.7.13: OpenSSL has deprecated all version specific protocols. Use the default

819

protocol with flags like <code class="docutils literal">OP_NO_SSLv3</code> instead.

820

</div>

821

</dd></dl>

822

823

824

825

826

<dd>Enables workarounds for various bugs present in other SSL implementations.

827

This option is set by default. It does not necessarily set the same

828

flags as OpenSSL’s <code class="docutils literal">SSL_OP_ALL</code> constant.

829

830

New in version 2.7.9.

831

</div>

832

</dd></dl>

833

834

835

836

837

<dd>Prevents an SSLv2 connection. This option is only applicable in

838

conjunction with <a class="reference internal" href="#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-const docutils literal">PROTOCOL_SSLv23</code></a>. It prevents the peers from

839

choosing SSLv2 as the protocol version.

840

841

New in version 2.7.9.

842

</div>

843

</dd></dl>

844

845

846

847

848

<dd>Prevents an SSLv3 connection. This option is only applicable in

849

850

choosing SSLv3 as the protocol version.

851

852

New in version 2.7.9.

853

</div>

854

</dd></dl>

855

856

857

858

859

<dd>Prevents a TLSv1 connection. This option is only applicable in

860

861

choosing TLSv1 as the protocol version.

862

863

New in version 2.7.9.

864

</div>

865

</dd></dl>

866

867

868

869

870

<dd>Prevents a TLSv1.1 connection. This option is only applicable in conjunction

871

with <a class="reference internal" href="#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-const docutils literal">PROTOCOL_SSLv23</code></a>. It prevents the peers from choosing TLSv1.1 as

872

the protocol version. Available only with openssl version 1.0.1+.

873

874

New in version 2.7.9.

875

</div>

876

</dd></dl>

877

878

879

880

881

<dd>Prevents a TLSv1.2 connection. This option is only applicable in conjunction

882

883

the protocol version. Available only with openssl version 1.0.1+.

884

885

New in version 2.7.9.

886

</div>

887

</dd></dl>

888

889

890

891

<code class="descclassname">ssl.</code><code class="descname">OP_CIPHER_SERVER_PREFERENCE</code><a class="headerlink" href="#ssl.OP_CIPHER_SERVER_PREFERENCE" title="Permalink to this definition">¶</a></dt>

892

<dd>Use the server’s cipher ordering preference, rather than the client’s.

893

This option has no effect on client sockets and SSLv2 server sockets.

894

895

New in version 2.7.9.

896

</div>

897

</dd></dl>

898

899

900

901

<code class="descclassname">ssl.</code><code class="descname">OP_SINGLE_DH_USE</code><a class="headerlink" href="#ssl.OP_SINGLE_DH_USE" title="Permalink to this definition">¶</a></dt>

902

<dd>Prevents re-use of the same DH key for distinct SSL sessions. This

903

improves forward secrecy but requires more computational resources.

904

This option only applies to server sockets.

905

906

New in version 2.7.9.

907

</div>

908

</dd></dl>

909

910

911

912

<code class="descclassname">ssl.</code><code class="descname">OP_SINGLE_ECDH_USE</code><a class="headerlink" href="#ssl.OP_SINGLE_ECDH_USE" title="Permalink to this definition">¶</a></dt>

913

<dd>Prevents re-use of the same ECDH key for distinct SSL sessions. This

914

improves forward secrecy but requires more computational resources.

915

This option only applies to server sockets.

916

917

New in version 2.7.9.

918

</div>

919

</dd></dl>

920

921

922

923

<code class="descclassname">ssl.</code><code class="descname">OP_NO_COMPRESSION</code><a class="headerlink" href="#ssl.OP_NO_COMPRESSION" title="Permalink to this definition">¶</a></dt>

924

<dd>Disable compression on the SSL channel. This is useful if the application

925

protocol supports its own compression scheme.

926

This option is only available with OpenSSL 1.0.0 and later.

927

928

New in version 2.7.9.

929

</div>

930

</dd></dl>

931

932

933

934

935

<dd>Whether the OpenSSL library has built-in support for the Application-Layer

936

Protocol Negotiation TLS extension as described in <a class="rfc reference external" href="https://tools.ietf.org/html/rfc7301.html">RFC 7301</a>.

937

938

New in version 2.7.10.

939

</div>

940

</dd></dl>

941

942

943

944

945

<dd>Whether the OpenSSL library has built-in support for Elliptic Curve-based

946

Diffie-Hellman key exchange. This should be true unless the feature was

947

explicitly disabled by the distributor.

948

949

New in version 2.7.9.

950

</div>

951

</dd></dl>

952

953

954

955

956

<dd>Whether the OpenSSL library has built-in support for the Server Name

957

Indication extension (as defined in <a class="rfc reference external" href="https://tools.ietf.org/html/rfc4366.html">RFC 4366</a>).

958

959

New in version 2.7.9.

960

</div>

961

</dd></dl>

962

963

964

965

966

<dd>Whether the OpenSSL library has built-in support for Next Protocol

967

Negotiation as described in the <a class="reference external" href="https://tools.ietf.org/html/draft-agl-tls-nextprotoneg">NPN draft specification</a>. When true,

968

you can use the <a class="reference internal" href="#ssl.SSLContext.set_npn_protocols" title="ssl.SSLContext.set_npn_protocols"><code class="xref py py-meth docutils literal">SSLContext.set_npn_protocols()</code></a> method to advertise

969

which protocols you want to support.

970

971

New in version 2.7.9.

972

</div>

973

</dd></dl>

974

975

976

977

<code class="descclassname">ssl.</code><code class="descname">CHANNEL_BINDING_TYPES</code><a class="headerlink" href="#ssl.CHANNEL_BINDING_TYPES" title="Permalink to this definition">¶</a></dt>

978

<dd>List of supported TLS channel binding types. Strings in this list

979

can be used as arguments to <a class="reference internal" href="#ssl.SSLSocket.get_channel_binding" title="ssl.SSLSocket.get_channel_binding"><code class="xref py py-meth docutils literal">SSLSocket.get_channel_binding()</code></a>.

980

981

New in version 2.7.9.

982

</div>

983

</dd></dl>

984

985

986

987

<code class="descclassname">ssl.</code><code class="descname">OPENSSL_VERSION</code><a class="headerlink" href="#ssl.OPENSSL_VERSION" title="Permalink to this definition">¶</a></dt>

988

<dd>The version string of the OpenSSL library loaded by the interpreter:

989

<div class="highlight-python"><div class="highlight"><pre>>>> ssl.OPENSSL_VERSION

990

'OpenSSL 0.9.8k 25 Mar 2009'

991

</pre></div>

992

</div>

993

994

New in version 2.7.

995

</div>

996

</dd></dl>

997

998

999

1000

<code class="descclassname">ssl.</code><code class="descname">OPENSSL_VERSION_INFO</code><a class="headerlink" href="#ssl.OPENSSL_VERSION_INFO" title="Permalink to this definition">¶</a></dt>

1001

<dd>A tuple of five integers representing version information about the

1002

OpenSSL library:

1003

<div class="highlight-python"><div class="highlight"><pre>>>> ssl.OPENSSL_VERSION_INFO

1004

(0, 9, 8, 11, 15)

1005

</pre></div>

1006

</div>

1007

1008

New in version 2.7.

1009

</div>

1010

</dd></dl>

1011

1012

1013

1014

<code class="descclassname">ssl.</code><code class="descname">OPENSSL_VERSION_NUMBER</code><a class="headerlink" href="#ssl.OPENSSL_VERSION_NUMBER" title="Permalink to this definition">¶</a></dt>

1015

<dd>The raw version number of the OpenSSL library, as a single integer:

1016

<div class="highlight-python"><div class="highlight"><pre>>>> ssl.OPENSSL_VERSION_NUMBER

1017

9470143L

1018

>>> hex(ssl.OPENSSL_VERSION_NUMBER)

1019

'0x9080bfL'

1020

</pre></div>

1021

</div>

1022

1023

New in version 2.7.

1024

</div>

1025

</dd></dl>

1026

1027

1028

1029

<code class="descclassname">ssl.</code><code class="descname">ALERT_DESCRIPTION_HANDSHAKE_FAILURE</code><a class="headerlink" href="#ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE" title="Permalink to this definition">¶</a></dt>

1030

1031

<code class="descclassname">ssl.</code><code class="descname">ALERT_DESCRIPTION_INTERNAL_ERROR</code><a class="headerlink" href="#ssl.ALERT_DESCRIPTION_INTERNAL_ERROR" title="Permalink to this definition">¶</a></dt>

1032

<dt>

1033

<code class="descname">ALERT_DESCRIPTION_*</code></dt>

1034

<dd>Alert Descriptions from <a class="rfc reference external" href="https://tools.ietf.org/html/rfc5246.html">RFC 5246</a> and others. The <a class="reference external" href="https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6">IANA TLS Alert Registry</a>

1035

contains this list and references to the RFCs where their meaning is defined.

1036

Used as the return value of the callback function in

1037

<a class="reference internal" href="#ssl.SSLContext.set_servername_callback" title="ssl.SSLContext.set_servername_callback"><code class="xref py py-meth docutils literal">SSLContext.set_servername_callback()</code></a>.

1038

1039

New in version 2.7.9.

1040

</div>

1041

</dd></dl>

1042

1043

1044

1045

<code class="descclassname">Purpose.</code><code class="descname">SERVER_AUTH</code><a class="headerlink" href="#ssl.Purpose.SERVER_AUTH" title="Permalink to this definition">¶</a></dt>

1046

<dd>Option for <a class="reference internal" href="#ssl.create_default_context" title="ssl.create_default_context"><code class="xref py py-func docutils literal">create_default_context()</code></a> and

1047

<a class="reference internal" href="#ssl.SSLContext.load_default_certs" title="ssl.SSLContext.load_default_certs"><code class="xref py py-meth docutils literal">SSLContext.load_default_certs()</code></a>. This value indicates that the

1048

context may be used to authenticate Web servers (therefore, it will

1049

be used to create client-side sockets).

1050

1051

New in version 2.7.9.

1052

</div>

1053

</dd></dl>

1054

1055

1056

1057

<code class="descclassname">Purpose.</code><code class="descname">CLIENT_AUTH</code><a class="headerlink" href="#ssl.Purpose.CLIENT_AUTH" title="Permalink to this definition">¶</a></dt>

1058

1059

1060

context may be used to authenticate Web clients (therefore, it will

1061

be used to create server-side sockets).

1062

1063

New in version 2.7.9.

1064

</div>

1065

</dd></dl>

1066

1067

</div>

1068

</div>

1069

1070

<h2>17.3.2. SSL Sockets<a class="headerlink" href="#ssl-sockets" title="Permalink to this headline">¶</a></h2>

1071

SSL sockets provide the following methods of <a class="reference internal" href="socket.html#socket-objects">Socket Objects</a>:

1072

1073

<li><a class="reference internal" href="socket.html#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal">accept()</code></a></li>

1074

1075

<li><a class="reference internal" href="socket.html#socket.socket.close" title="socket.socket.close"><code class="xref py py-meth docutils literal">close()</code></a></li>

1076

<li><a class="reference internal" href="socket.html#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal">connect()</code></a></li>

1077

<li><a class="reference internal" href="socket.html#socket.socket.fileno" title="socket.socket.fileno"><code class="xref py py-meth docutils literal">fileno()</code></a></li>

1078

<li><a class="reference internal" href="socket.html#socket.socket.getpeername" title="socket.socket.getpeername"><code class="xref py py-meth docutils literal">getpeername()</code></a>, <a class="reference internal" href="socket.html#socket.socket.getsockname" title="socket.socket.getsockname"><code class="xref py py-meth docutils literal">getsockname()</code></a></li>

1079

<li><a class="reference internal" href="socket.html#socket.socket.getsockopt" title="socket.socket.getsockopt"><code class="xref py py-meth docutils literal">getsockopt()</code></a>, <a class="reference internal" href="socket.html#socket.socket.setsockopt" title="socket.socket.setsockopt"><code class="xref py py-meth docutils literal">setsockopt()</code></a></li>

1080

<li><a class="reference internal" href="socket.html#socket.socket.gettimeout" title="socket.socket.gettimeout"><code class="xref py py-meth docutils literal">gettimeout()</code></a>, <a class="reference internal" href="socket.html#socket.socket.settimeout" title="socket.socket.settimeout"><code class="xref py py-meth docutils literal">settimeout()</code></a>,

1081

<a class="reference internal" href="socket.html#socket.socket.setblocking" title="socket.socket.setblocking"><code class="xref py py-meth docutils literal">setblocking()</code></a></li>

1082

<li><a class="reference internal" href="socket.html#socket.socket.listen" title="socket.socket.listen"><code class="xref py py-meth docutils literal">listen()</code></a></li>

1083

<li><a class="reference internal" href="socket.html#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal">makefile()</code></a></li>

1084

1085

(but passing a non-zero <code class="docutils literal">flags</code> argument is not allowed)</li>

1086

<li><a class="reference internal" href="socket.html#socket.socket.send" title="socket.socket.send"><code class="xref py py-meth docutils literal">send()</code></a>, <a class="reference internal" href="socket.html#socket.socket.sendall" title="socket.socket.sendall"><code class="xref py py-meth docutils literal">sendall()</code></a> (with

1087

the same limitation)</li>

1088

<li><a class="reference internal" href="socket.html#socket.socket.shutdown" title="socket.socket.shutdown"><code class="xref py py-meth docutils literal">shutdown()</code></a></li>

1089

</ul>

1090

However, since the SSL (and TLS) protocol has its own framing atop

1091

of TCP, the SSL sockets abstraction can, in certain respects, diverge from

1092

the specification of normal, OS-level sockets. See especially the

1093

<a class="reference internal" href="#ssl-nonblocking">notes on non-blocking sockets</a>.

1094

SSL sockets also have the following additional methods and attributes:

1095

1096

1097

<code class="descclassname">SSLSocket.</code><code class="descname">do_handshake</code>()<a class="headerlink" href="#ssl.SSLSocket.do_handshake" title="Permalink to this definition">¶</a></dt>

1098

<dd>Perform the SSL setup handshake.

1099

1100

Changed in version 2.7.9: The handshake method also performs <a class="reference internal" href="#ssl.match_hostname" title="ssl.match_hostname"><code class="xref py py-func docutils literal">match_hostname()</code></a> when the

1101

<a class="reference internal" href="#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code class="xref py py-attr docutils literal">check_hostname</code></a> attribute of the socket’s

1102

<a class="reference internal" href="#ssl.SSLSocket.context" title="ssl.SSLSocket.context"><code class="xref py py-attr docutils literal">context</code></a> is true.

1103

</div>

1104

</dd></dl>

1105

1106

1107

1108

<code class="descclassname">SSLSocket.</code><code class="descname">getpeercert</code>(binary_form=False)<a class="headerlink" href="#ssl.SSLSocket.getpeercert" title="Permalink to this definition">¶</a></dt>

1109

<dd>If there is no certificate for the peer on the other end of the connection,

1110

return <code class="docutils literal">None</code>. If the SSL handshake hasn’t been done yet, raise

1111

<a class="reference internal" href="exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a>.

1112

If the <code class="docutils literal">binary_form</code> parameter is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a>, and a certificate was

1113

received from the peer, this method returns a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal">dict</code></a> instance. If the

1114

certificate was not validated, the dict is empty. If the certificate was

1115

validated, it returns a dict with several keys, amongst them <code class="docutils literal">subject</code>

1116

(the principal for which the certificate was issued) and <code class="docutils literal">issuer</code>

1117

(the principal issuing the certificate). If a certificate contains an

1118

instance of the Subject Alternative Name extension (see <a class="rfc reference external" href="https://tools.ietf.org/html/rfc3280.html">RFC 3280</a>),

1119

there will also be a <code class="docutils literal">subjectAltName</code> key in the dictionary.

1120

The <code class="docutils literal">subject</code> and <code class="docutils literal">issuer</code> fields are tuples containing the sequence

1121

of relative distinguished names (RDNs) given in the certificate’s data

1122

structure for the respective fields, and each RDN is a sequence of

1123

name-value pairs. Here is a real-world example:

1124

<div class="highlight-python"><div class="highlight"><pre>{'issuer': ((('countryName', 'IL'),),

1125

(('organizationName', 'StartCom Ltd.'),),

1126

(('organizationalUnitName',

1127

'Secure Digital Certificate Signing'),),

1128

(('commonName',

1129

'StartCom Class 2 Primary Intermediate Server CA'),)),

1130

'notAfter': 'Nov 22 08:15:19 2013 GMT',

1131

'notBefore': 'Nov 21 03:09:52 2011 GMT',

1132

'serialNumber': '95F0',

1133

'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),

1134

(('countryName', 'US'),),

1135

(('stateOrProvinceName', 'California'),),

1136

(('localityName', 'San Francisco'),),

1137

(('organizationName', 'Electronic Frontier Foundation, Inc.'),),

1138

(('commonName', '*.eff.org'),),

1139

(('emailAddress', 'hostmaster@eff.org'),)),

1140

'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),

1141

'version': 3}

1142

</pre></div>

1143

</div>

1144

1145

Note

1146

To validate a certificate for a particular service, you can use the

1147

<a class="reference internal" href="#ssl.match_hostname" title="ssl.match_hostname"><code class="xref py py-func docutils literal">match_hostname()</code></a> function.

1148

</div>

1149

If the <code class="docutils literal">binary_form</code> parameter is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a>, and a certificate was

1150

provided, this method returns the DER-encoded form of the entire certificate

1151

as a sequence of bytes, or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> if the peer did not provide a

1152

certificate. Whether the peer provides a certificate depends on the SSL

1153

socket’s role:

1154

1155

<li>for a client SSL socket, the server will always provide a certificate,

1156

regardless of whether validation was required;</li>

1157

<li>for a server SSL socket, the client will only provide a certificate

1158

when requested by the server; therefore <a class="reference internal" href="#ssl.SSLSocket.getpeercert" title="ssl.SSLSocket.getpeercert"><code class="xref py py-meth docutils literal">getpeercert()</code></a> will return

1159

<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> if you used <a class="reference internal" href="#ssl.CERT_NONE" title="ssl.CERT_NONE"><code class="xref py py-const docutils literal">CERT_NONE</code></a> (rather than

1160

<a class="reference internal" href="#ssl.CERT_OPTIONAL" title="ssl.CERT_OPTIONAL"><code class="xref py py-const docutils literal">CERT_OPTIONAL</code></a> or <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-const docutils literal">CERT_REQUIRED</code></a>).</li>

1161

</ul>

1162

1163

Changed in version 2.7.9: The returned dictionary includes additional items such as <code class="docutils literal">issuer</code> and

1164

<code class="docutils literal">notBefore</code>. Additionall <a class="reference internal" href="exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised when the handshake

1165

isn’t done. The returned dictionary includes additional X509v3 extension

1166

items such as <code class="docutils literal">crlDistributionPoints</code>, <code class="docutils literal">caIssuers</code> and <code class="docutils literal">OCSP</code> URIs.

1167

</div>

1168

</dd></dl>

1169

1170

1171

1172

<code class="descclassname">SSLSocket.</code><code class="descname">cipher</code>()<a class="headerlink" href="#ssl.SSLSocket.cipher" title="Permalink to this definition">¶</a></dt>

1173

<dd>Returns a three-value tuple containing the name of the cipher being used, the

1174

version of the SSL protocol that defines its use, and the number of secret

1175

bits being used. If no connection has been established, returns <code class="docutils literal">None</code>.

1176

</dd></dl>

1177

1178

1179

1180

<code class="descclassname">SSLSocket.</code><code class="descname">compression</code>()<a class="headerlink" href="#ssl.SSLSocket.compression" title="Permalink to this definition">¶</a></dt>

1181

<dd>Return the compression algorithm being used as a string, or <code class="docutils literal">None</code>

1182

if the connection isn’t compressed.

1183

If the higher-level protocol supports its own compression mechanism,

1184

you can use <a class="reference internal" href="#ssl.OP_NO_COMPRESSION" title="ssl.OP_NO_COMPRESSION"><code class="xref py py-data docutils literal">OP_NO_COMPRESSION</code></a> to disable SSL-level compression.

1185

1186

New in version 2.7.9.

1187

</div>

1188

</dd></dl>

1189

1190

1191

1192

<code class="descclassname">SSLSocket.</code><code class="descname">get_channel_binding</code>(cb_type="tls-unique")<a class="headerlink" href="#ssl.SSLSocket.get_channel_binding" title="Permalink to this definition">¶</a></dt>

1193

<dd>Get channel binding data for current connection, as a bytes object. Returns

1194

<code class="docutils literal">None</code> if not connected or the handshake has not been completed.

1195

The cb_type parameter allow selection of the desired channel binding

1196

type. Valid channel binding types are listed in the

1197

<a class="reference internal" href="#ssl.CHANNEL_BINDING_TYPES" title="ssl.CHANNEL_BINDING_TYPES"><code class="xref py py-data docutils literal">CHANNEL_BINDING_TYPES</code></a> list. Currently only the ‘tls-unique’ channel

1198

binding, defined by <a class="rfc reference external" href="https://tools.ietf.org/html/rfc5929.html">RFC 5929</a>, is supported. <a class="reference internal" href="exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> will be

1199

raised if an unsupported channel binding type is requested.

1200

1201

New in version 2.7.9.

1202

</div>

1203

</dd></dl>

1204

1205

1206

1207

<code class="descclassname">SSLSocket.</code><code class="descname">selected_alpn_protocol</code>()<a class="headerlink" href="#ssl.SSLSocket.selected_alpn_protocol" title="Permalink to this definition">¶</a></dt>

1208

<dd>Return the protocol that was selected during the TLS handshake. If

1209

<a class="reference internal" href="#ssl.SSLContext.set_alpn_protocols" title="ssl.SSLContext.set_alpn_protocols"><code class="xref py py-meth docutils literal">SSLContext.set_alpn_protocols()</code></a> was not called, if the other party does

1210

not support ALPN, if this socket does not support any of the client’s

1211

proposed protocols, or if the handshake has not happened yet, <code class="docutils literal">None</code> is

1212

returned.

1213

1214

New in version 2.7.10.

1215

</div>

1216

</dd></dl>

1217

1218

1219

1220

<code class="descclassname">SSLSocket.</code><code class="descname">selected_npn_protocol</code>()<a class="headerlink" href="#ssl.SSLSocket.selected_npn_protocol" title="Permalink to this definition">¶</a></dt>

1221

<dd>Return the higher-level protocol that was selected during the TLS/SSL

1222

handshake. If <a class="reference internal" href="#ssl.SSLContext.set_npn_protocols" title="ssl.SSLContext.set_npn_protocols"><code class="xref py py-meth docutils literal">SSLContext.set_npn_protocols()</code></a> was not called, or

1223

if the other party does not support NPN, or if the handshake has not yet

1224

happened, this will return <code class="docutils literal">None</code>.

1225

1226

New in version 2.7.9.

1227

</div>

1228

</dd></dl>

1229

1230

1231

1232

<code class="descclassname">SSLSocket.</code><code class="descname">unwrap</code>()<a class="headerlink" href="#ssl.SSLSocket.unwrap" title="Permalink to this definition">¶</a></dt>

1233

<dd>Performs the SSL shutdown handshake, which removes the TLS layer from the

1234

underlying socket, and returns the underlying socket object. This can be

1235

used to go from encrypted operation over a connection to unencrypted. The

1236

returned socket should always be used for further communication with the

1237

other side of the connection, rather than the original socket.

1238

</dd></dl>

1239

1240

1241

1242

<code class="descclassname">SSLSocket.</code><code class="descname">version</code>()<a class="headerlink" href="#ssl.SSLSocket.version" title="Permalink to this definition">¶</a></dt>

1243

<dd>Return the actual SSL protocol version negotiated by the connection

1244

as a string, or <code class="docutils literal">None</code> is no secure connection is established.

1245

As of this writing, possible return values include <code class="docutils literal">"SSLv2"</code>,

1246

<code class="docutils literal">"SSLv3"</code>, <code class="docutils literal">"TLSv1"</code>, <code class="docutils literal">"TLSv1.1"</code> and <code class="docutils literal">"TLSv1.2"</code>.

1247

Recent OpenSSL versions may define more return values.

1248

1249

New in version 2.7.9.

1250

</div>

1251

</dd></dl>

1252

1253

1254

1255

<code class="descclassname">SSLSocket.</code><code class="descname">context</code><a class="headerlink" href="#ssl.SSLSocket.context" title="Permalink to this definition">¶</a></dt>

1256

<dd>The <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> object this SSL socket is tied to. If the SSL

1257

socket was created using the top-level <a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a> function

1258

(rather than <a class="reference internal" href="#ssl.SSLContext.wrap_socket" title="ssl.SSLContext.wrap_socket"><code class="xref py py-meth docutils literal">SSLContext.wrap_socket()</code></a>), this is a custom context

1259

object created for this SSL socket.

1260

1261

New in version 2.7.9.

1262

</div>

1263

</dd></dl>

1264

1265

</div>

1266

1267

<h2>17.3.3. SSL Contexts<a class="headerlink" href="#ssl-contexts" title="Permalink to this headline">¶</a></h2>

1268

1269

New in version 2.7.9.

1270

</div>

1271

An SSL context holds various data longer-lived than single SSL connections,

1272

such as SSL configuration options, certificate(s) and private key(s).

1273

It also manages a cache of SSL sessions for server-side sockets, in order

1274

to speed up repeated connections from the same clients.

1275

1276

1277

class <code class="descclassname">ssl.</code><code class="descname">SSLContext</code>(protocol)<a class="headerlink" href="#ssl.SSLContext" title="Permalink to this definition">¶</a></dt>

1278

<dd>Create a new SSL context. You must pass protocol which must be one

1279

of the <code class="docutils literal">PROTOCOL_*</code> constants defined in this module.

1280

1281

interoperability.

1282

1283

See also

1284

<a class="reference internal" href="#ssl.create_default_context" title="ssl.create_default_context"><code class="xref py py-func docutils literal">create_default_context()</code></a> lets the <a class="reference internal" href="#module-ssl" title="ssl: TLS/SSL wrapper for socket objects"><code class="xref py py-mod docutils literal">ssl</code></a> module choose

1285

security settings for a given purpose.

1286

</div>

1287

</dd></dl>

1288

1289

<a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> objects have the following methods and attributes:

1290

1291

1292

<code class="descclassname">SSLContext.</code><code class="descname">cert_store_stats</code>()<a class="headerlink" href="#ssl.SSLContext.cert_store_stats" title="Permalink to this definition">¶</a></dt>

1293

<dd>Get statistics about quantities of loaded X.509 certificates, count of

1294

X.509 certificates flagged as CA certificates and certificate revocation

1295

lists as dictionary.

1296

Example for a context with one CA cert and one other cert:

1297

<div class="highlight-python"><div class="highlight"><pre>>>> context.cert_store_stats()

1298

{'crl': 0, 'x509_ca': 1, 'x509': 2}

1299

</pre></div>

1300

</div>

1301

</dd></dl>

1302

1303

1304

1305

<code class="descclassname">SSLContext.</code><code class="descname">load_cert_chain</code>(certfile, keyfile=None, password=None)<a class="headerlink" href="#ssl.SSLContext.load_cert_chain" title="Permalink to this definition">¶</a></dt>

1306

<dd>Load a private key and the corresponding certificate. The certfile

1307

string must be the path to a single file in PEM format containing the

1308

certificate as well as any number of CA certificates needed to establish

1309

the certificate’s authenticity. The keyfile string, if present, must

1310

point to a file containing the private key in. Otherwise the private

1311

key will be taken from certfile as well. See the discussion of

1312

<a class="reference internal" href="#ssl-certificates">Certificates</a> for more information on how the certificate

1313

is stored in the certfile.

1314

The password argument may be a function to call to get the password for

1315

decrypting the private key. It will only be called if the private key is

1316

encrypted and a password is necessary. It will be called with no arguments,

1317

and it should return a string, bytes, or bytearray. If the return value is

1318

a string it will be encoded as UTF-8 before using it to decrypt the key.

1319

Alternatively a string, bytes, or bytearray value may be supplied directly

1320

as the password argument. It will be ignored if the private key is not

1321

encrypted and no password is needed.

1322

If the password argument is not specified and a password is required,

1323

OpenSSL’s built-in password prompting mechanism will be used to

1324

interactively prompt the user for a password.

1325

An <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-class docutils literal">SSLError</code></a> is raised if the private key doesn’t

1326

match with the certificate.

1327

</dd></dl>

1328

1329

1330

1331

<code class="descclassname">SSLContext.</code><code class="descname">load_default_certs</code>(purpose=Purpose.SERVER_AUTH)<a class="headerlink" href="#ssl.SSLContext.load_default_certs" title="Permalink to this definition">¶</a></dt>

1332

<dd>Load a set of default “certification authority” (CA) certificates from

1333

default locations. On Windows it loads CA certs from the <code class="docutils literal">CA</code> and

1334

<code class="docutils literal">ROOT</code> system stores. On other systems it calls

1335

1336

load CA certificates from other locations, too.

1337

The purpose flag specifies what kind of CA certificates are loaded. The

1338

default settings <a class="reference internal" href="#ssl.Purpose.SERVER_AUTH" title="ssl.Purpose.SERVER_AUTH"><code class="xref py py-data docutils literal">Purpose.SERVER_AUTH</code></a> loads certificates, that are

1339

flagged and trusted for TLS web server authentication (client side

1340

sockets). <a class="reference internal" href="#ssl.Purpose.CLIENT_AUTH" title="ssl.Purpose.CLIENT_AUTH"><code class="xref py py-data docutils literal">Purpose.CLIENT_AUTH</code></a> loads CA certificates for client

1341

certificate verification on the server side.

1342

</dd></dl>

1343

1344

1345

1346

<code class="descclassname">SSLContext.</code><code class="descname">load_verify_locations</code>(cafile=None, capath=None, cadata=None)<a class="headerlink" href="#ssl.SSLContext.load_verify_locations" title="Permalink to this definition">¶</a></dt>

1347

<dd>Load a set of “certification authority” (CA) certificates used to validate

1348

other peers’ certificates when <a class="reference internal" href="#ssl.SSLContext.verify_mode" title="ssl.SSLContext.verify_mode"><code class="xref py py-data docutils literal">verify_mode</code></a> is other than

1349

1350

This method can also load certification revocation lists (CRLs) in PEM or

1351

DER format. In order to make use of CRLs, <a class="reference internal" href="#ssl.SSLContext.verify_flags" title="ssl.SSLContext.verify_flags"><code class="xref py py-attr docutils literal">SSLContext.verify_flags</code></a>

1352

must be configured properly.

1353

The cafile string, if present, is the path to a file of concatenated

1354

CA certificates in PEM format. See the discussion of

1355

<a class="reference internal" href="#ssl-certificates">Certificates</a> for more information about how to arrange the

1356

certificates in this file.

1357

The capath string, if present, is

1358

the path to a directory containing several CA certificates in PEM format,

1359

following an <a class="reference external" href="https://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html">OpenSSL specific layout</a>.

1360

The cadata object, if present, is either an ASCII string of one or more

1361

PEM-encoded certificates or a bytes-like object of DER-encoded

1362

certificates. Like with capath extra lines around PEM-encoded

1363

certificates are ignored but at least one certificate must be present.

1364

</dd></dl>

1365

1366

1367

1368

<code class="descclassname">SSLContext.</code><code class="descname">get_ca_certs</code>(binary_form=False)<a class="headerlink" href="#ssl.SSLContext.get_ca_certs" title="Permalink to this definition">¶</a></dt>

1369

<dd>Get a list of loaded “certification authority” (CA) certificates. If the

1370

<code class="docutils literal">binary_form</code> parameter is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> each list

1371

entry is a dict like the output of <a class="reference internal" href="#ssl.SSLSocket.getpeercert" title="ssl.SSLSocket.getpeercert"><code class="xref py py-meth docutils literal">SSLSocket.getpeercert()</code></a>. Otherwise

1372

the method returns a list of DER-encoded certificates. The returned list

1373

does not contain certificates from capath unless a certificate was

1374

requested and loaded by a SSL connection.

1375

</dd></dl>

1376

1377

1378

1379

<code class="descclassname">SSLContext.</code><code class="descname">set_default_verify_paths</code>()<a class="headerlink" href="#ssl.SSLContext.set_default_verify_paths" title="Permalink to this definition">¶</a></dt>

1380

<dd>Load a set of default “certification authority” (CA) certificates from

1381

a filesystem path defined when building the OpenSSL library. Unfortunately,

1382

there’s no easy way to know whether this method succeeds: no error is

1383

returned if no certificates are to be found. When the OpenSSL library is

1384

provided as part of the operating system, though, it is likely to be

1385

configured properly.

1386

</dd></dl>

1387

1388

1389

1390

<code class="descclassname">SSLContext.</code><code class="descname">set_ciphers</code>(ciphers)<a class="headerlink" href="#ssl.SSLContext.set_ciphers" title="Permalink to this definition">¶</a></dt>

1391

<dd>Set the available ciphers for sockets created with this context.

1392

It should be a string in the <a class="reference external" href="https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT">OpenSSL cipher list format</a>.

1393

If no cipher can be selected (because compile-time options or other

1394

configuration forbids use of all the specified ciphers), an

1395

<a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-class docutils literal">SSLError</code></a> will be raised.

1396

1397

Note

1398

when connected, the <a class="reference internal" href="#ssl.SSLSocket.cipher" title="ssl.SSLSocket.cipher"><code class="xref py py-meth docutils literal">SSLSocket.cipher()</code></a> method of SSL sockets will

1399

give the currently selected cipher.

1400

</div>

1401

</dd></dl>

1402

1403

1404

1405

<code class="descclassname">SSLContext.</code><code class="descname">set_alpn_protocols</code>(protocols)<a class="headerlink" href="#ssl.SSLContext.set_alpn_protocols" title="Permalink to this definition">¶</a></dt>

1406

<dd>Specify which protocols the socket should advertise during the SSL/TLS

1407

handshake. It should be a list of ASCII strings, like <code class="docutils literal">['http/1.1',

1408

'spdy/2']</code>, ordered by preference. The selection of a protocol will happen

1409

during the handshake, and will play out according to <a class="rfc reference external" href="https://tools.ietf.org/html/rfc7301.html">RFC 7301</a>. After a

1410

successful handshake, the <a class="reference internal" href="#ssl.SSLSocket.selected_alpn_protocol" title="ssl.SSLSocket.selected_alpn_protocol"><code class="xref py py-meth docutils literal">SSLSocket.selected_alpn_protocol()</code></a> method will

1411

return the agreed-upon protocol.

1412

This method will raise <a class="reference internal" href="exceptions.html#exceptions.NotImplementedError" title="exceptions.NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a> if <a class="reference internal" href="#ssl.HAS_ALPN" title="ssl.HAS_ALPN"><code class="xref py py-data docutils literal">HAS_ALPN</code></a> is

1413

False.

1414

OpenSSL 1.1.0+ will abort the handshake and raise <a class="reference internal" href="#ssl.SSLError" title="ssl.SSLError"><code class="xref py py-exc docutils literal">SSLError</code></a> when

1415

both sides support ALPN but cannot agree on a protocol.

1416

1417

New in version 2.7.10.

1418

</div>

1419

</dd></dl>

1420

1421

1422

1423

<code class="descclassname">SSLContext.</code><code class="descname">set_npn_protocols</code>(protocols)<a class="headerlink" href="#ssl.SSLContext.set_npn_protocols" title="Permalink to this definition">¶</a></dt>

1424

<dd>Specify which protocols the socket should advertise during the SSL/TLS

1425

handshake. It should be a list of strings, like <code class="docutils literal">['http/1.1', 'spdy/2']</code>,

1426

ordered by preference. The selection of a protocol will happen during the

1427

handshake, and will play out according to the <a class="reference external" href="https://tools.ietf.org/html/draft-agl-tls-nextprotoneg">NPN draft specification</a>. After a

1428

successful handshake, the <a class="reference internal" href="#ssl.SSLSocket.selected_npn_protocol" title="ssl.SSLSocket.selected_npn_protocol"><code class="xref py py-meth docutils literal">SSLSocket.selected_npn_protocol()</code></a> method will

1429

return the agreed-upon protocol.

1430

This method will raise <a class="reference internal" href="exceptions.html#exceptions.NotImplementedError" title="exceptions.NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a> if <a class="reference internal" href="#ssl.HAS_NPN" title="ssl.HAS_NPN"><code class="xref py py-data docutils literal">HAS_NPN</code></a> is

1431

False.

1432

</dd></dl>

1433

1434

1435

1436

<code class="descclassname">SSLContext.</code><code class="descname">set_servername_callback</code>(server_name_callback)<a class="headerlink" href="#ssl.SSLContext.set_servername_callback" title="Permalink to this definition">¶</a></dt>

1437

<dd>Register a callback function that will be called after the TLS Client Hello

1438

handshake message has been received by the SSL/TLS server when the TLS client

1439

specifies a server name indication. The server name indication mechanism

1440

is specified in <a class="rfc reference external" href="https://tools.ietf.org/html/rfc6066.html">RFC 6066</a> section 3 - Server Name Indication.

1441

Only one callback can be set per <code class="docutils literal">SSLContext</code>. If server_name_callback

1442

is <code class="docutils literal">None</code> then the callback is disabled. Calling this function a

1443

subsequent time will disable the previously registered callback.

1444

The callback function, server_name_callback, will be called with three

1445

arguments; the first being the <code class="xref py py-class docutils literal">ssl.SSLSocket</code>, the second is a string

1446

that represents the server name that the client is intending to communicate

1447

(or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> if the TLS Client Hello does not contain a server name)

1448

and the third argument is the original <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a>. The server name

1449

argument is the IDNA decoded server name.

1450

A typical use of this callback is to change the <code class="xref py py-class docutils literal">ssl.SSLSocket</code>‘s

1451

<a class="reference internal" href="#ssl.SSLSocket.context" title="ssl.SSLSocket.context"><code class="xref py py-attr docutils literal">SSLSocket.context</code></a> attribute to a new object of type

1452

1453

name.

1454

Due to the early negotiation phase of the TLS connection, only limited

1455

methods and attributes are usable like

1456

<a class="reference internal" href="#ssl.SSLSocket.selected_alpn_protocol" title="ssl.SSLSocket.selected_alpn_protocol"><code class="xref py py-meth docutils literal">SSLSocket.selected_alpn_protocol()</code></a> and <a class="reference internal" href="#ssl.SSLSocket.context" title="ssl.SSLSocket.context"><code class="xref py py-attr docutils literal">SSLSocket.context</code></a>.

1457

<a class="reference internal" href="#ssl.SSLSocket.getpeercert" title="ssl.SSLSocket.getpeercert"><code class="xref py py-meth docutils literal">SSLSocket.getpeercert()</code></a>, <a class="reference internal" href="#ssl.SSLSocket.getpeercert" title="ssl.SSLSocket.getpeercert"><code class="xref py py-meth docutils literal">SSLSocket.getpeercert()</code></a>,

1458

<a class="reference internal" href="#ssl.SSLSocket.cipher" title="ssl.SSLSocket.cipher"><code class="xref py py-meth docutils literal">SSLSocket.cipher()</code></a> and <code class="xref py py-meth docutils literal">SSLSocket.compress()</code> methods require that

1459

the TLS connection has progressed beyond the TLS Client Hello and therefore

1460

will not contain return meaningful values nor can they be called safely.

1461

The server_name_callback function must return <code class="docutils literal">None</code> to allow the

1462

TLS negotiation to continue. If a TLS failure is required, a constant

1463

<a class="reference internal" href="#ssl.ALERT_DESCRIPTION_INTERNAL_ERROR" title="ssl.ALERT_DESCRIPTION_INTERNAL_ERROR"><code class="xref py py-const docutils literal">ALERT_DESCRIPTION_*</code></a> can be

1464

returned. Other return values will result in a TLS fatal error with

1465

1466

If there is an IDNA decoding error on the server name, the TLS connection

1467

will terminate with an <a class="reference internal" href="#ssl.ALERT_DESCRIPTION_INTERNAL_ERROR" title="ssl.ALERT_DESCRIPTION_INTERNAL_ERROR"><code class="xref py py-const docutils literal">ALERT_DESCRIPTION_INTERNAL_ERROR</code></a> fatal TLS

1468

alert message to the client.

1469

If an exception is raised from the server_name_callback function the TLS

1470

connection will terminate with a fatal TLS alert message

1471

<a class="reference internal" href="#ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE" title="ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE"><code class="xref py py-const docutils literal">ALERT_DESCRIPTION_HANDSHAKE_FAILURE</code></a>.

1472

1473

had OPENSSL_NO_TLSEXT defined when it was built.

1474

</dd></dl>

1475

1476

1477

1478

<code class="descclassname">SSLContext.</code><code class="descname">load_dh_params</code>(dhfile)<a class="headerlink" href="#ssl.SSLContext.load_dh_params" title="Permalink to this definition">¶</a></dt>

1479

<dd>Load the key generation parameters for Diffie-Helman (DH) key exchange.

1480

Using DH key exchange improves forward secrecy at the expense of

1481

computational resources (both on the server and on the client).

1482

The dhfile parameter should be the path to a file containing DH

1483

parameters in PEM format.

1484

This setting doesn’t apply to client sockets. You can also use the

1485

<a class="reference internal" href="#ssl.OP_SINGLE_DH_USE" title="ssl.OP_SINGLE_DH_USE"><code class="xref py py-data docutils literal">OP_SINGLE_DH_USE</code></a> option to further improve security.

1486

</dd></dl>

1487

1488

1489

1490

<code class="descclassname">SSLContext.</code><code class="descname">set_ecdh_curve</code>(curve_name)<a class="headerlink" href="#ssl.SSLContext.set_ecdh_curve" title="Permalink to this definition">¶</a></dt>

1491

<dd>Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key

1492

exchange. ECDH is significantly faster than regular DH while arguably

1493

as secure. The curve_name parameter should be a string describing

1494

a well-known elliptic curve, for example <code class="docutils literal">prime256v1</code> for a widely

1495

supported curve.

1496

This setting doesn’t apply to client sockets. You can also use the

1497

<a class="reference internal" href="#ssl.OP_SINGLE_ECDH_USE" title="ssl.OP_SINGLE_ECDH_USE"><code class="xref py py-data docutils literal">OP_SINGLE_ECDH_USE</code></a> option to further improve security.

1498

This method is not available if <a class="reference internal" href="#ssl.HAS_ECDH" title="ssl.HAS_ECDH"><code class="xref py py-data docutils literal">HAS_ECDH</code></a> is <code class="docutils literal">False</code>.

1499

1500

See also

1501

1502

<dt><a class="reference external" href="http://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-secrecy.html">SSL/TLS & Perfect Forward Secrecy</a></dt>

1503

<dd>Vincent Bernat.</dd>

1504

</dl>

1505

</div>

1506

</dd></dl>

1507

1508

1509

1510

<code class="descclassname">SSLContext.</code><code class="descname">wrap_socket</code>(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None)<a class="headerlink" href="#ssl.SSLContext.wrap_socket" title="Permalink to this definition">¶</a></dt>

1511

<dd>Wrap an existing Python socket sock and return an <code class="xref py py-class docutils literal">SSLSocket</code>

1512

object. sock must be a <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-data docutils literal">SOCK_STREAM</code></a> socket; other socket

1513

types are unsupported.

1514

The returned SSL socket is tied to the context, its settings and

1515

certificates. The parameters server_side, do_handshake_on_connect

1516

and suppress_ragged_eofs have the same meaning as in the top-level

1517

<a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a> function.

1518

On client connections, the optional parameter server_hostname specifies

1519

the hostname of the service which we are connecting to. This allows a

1520

single server to host multiple SSL-based services with distinct certificates,

1521

quite similarly to HTTP virtual hosts. Specifying server_hostname will

1522

raise a <a class="reference internal" href="exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> if server_side is true.

1523

1524

Changed in version 2.7.9: Always allow a server_hostname to be passed, even if OpenSSL does not

1525

have SNI.

1526

</div>

1527

</dd></dl>

1528

1529

1530

1531

<code class="descclassname">SSLContext.</code><code class="descname">session_stats</code>()<a class="headerlink" href="#ssl.SSLContext.session_stats" title="Permalink to this definition">¶</a></dt>

1532

<dd>Get statistics about the SSL sessions created or managed by this context.

1533

A dictionary is returned which maps the names of each <a class="reference external" href="https://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html">piece of information</a> to their

1534

numeric values. For example, here is the total number of hits and misses

1535

in the session cache since the context was created:

1536

<div class="highlight-python"><div class="highlight"><pre>>>> stats = context.session_stats()

1537

>>> stats['hits'], stats['misses']

1538

(0, 0)

1539

</pre></div>

1540

</div>

1541

</dd></dl>

1542

1543

1544

<dt>

1545

<code class="descclassname">SSLContext.</code><code class="descname">get_ca_certs</code>(binary_form=False)</dt>

1546

<dd>Returns a list of dicts with information of loaded CA certs. If the

1547

optional argument is true, returns a DER-encoded copy of the CA

1548

certificate.

1549

1550

Note

1551

Certificates in a capath directory aren’t loaded unless they have

1552

been used at least once.

1553

</div>

1554

</dd></dl>

1555

1556

1557

1558

<code class="descclassname">SSLContext.</code><code class="descname">check_hostname</code><a class="headerlink" href="#ssl.SSLContext.check_hostname" title="Permalink to this definition">¶</a></dt>

1559

<dd>Wether to match the peer cert’s hostname with <a class="reference internal" href="#ssl.match_hostname" title="ssl.match_hostname"><code class="xref py py-func docutils literal">match_hostname()</code></a> in

1560

1561

<a class="reference internal" href="#ssl.SSLContext.verify_mode" title="ssl.SSLContext.verify_mode"><code class="xref py py-attr docutils literal">verify_mode</code></a> must be set to <a class="reference internal" href="#ssl.CERT_OPTIONAL" title="ssl.CERT_OPTIONAL"><code class="xref py py-data docutils literal">CERT_OPTIONAL</code></a> or

1562

<a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-data docutils literal">CERT_REQUIRED</code></a>, and you must pass server_hostname to

1563

<a class="reference internal" href="#ssl.SSLContext.wrap_socket" title="ssl.SSLContext.wrap_socket"><code class="xref py py-meth docutils literal">wrap_socket()</code></a> in order to match the hostname.

1564

Example:

1565

<div class="highlight-python"><div class="highlight"><pre>import socket, ssl

1566

1567

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)

1568

context.verify_mode = ssl.CERT_REQUIRED

1569

context.check_hostname = True

1570

context.load_default_certs()

1571

1572

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

1573

ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')

1574

ssl_sock.connect(('www.verisign.com', 443))

1575

</pre></div>

1576

</div>

1577

1578

Note

1579

This features requires OpenSSL 0.9.8f or newer.

1580

</div>

1581

</dd></dl>

1582

1583

1584

1585

<code class="descclassname">SSLContext.</code><code class="descname">options</code><a class="headerlink" href="#ssl.SSLContext.options" title="Permalink to this definition">¶</a></dt>

1586

<dd>An integer representing the set of SSL options enabled on this context.

1587

The default value is <a class="reference internal" href="#ssl.OP_ALL" title="ssl.OP_ALL"><code class="xref py py-data docutils literal">OP_ALL</code></a>, but you can specify other options

1588

such as <a class="reference internal" href="#ssl.OP_NO_SSLv2" title="ssl.OP_NO_SSLv2"><code class="xref py py-data docutils literal">OP_NO_SSLv2</code></a> by ORing them together.

1589

1590

Note

1591

With versions of OpenSSL older than 0.9.8m, it is only possible

1592

to set options, not to clear them. Attempting to clear an option

1593

(by resetting the corresponding bits) will raise a <code class="docutils literal">ValueError</code>.

1594

</div>

1595

</dd></dl>

1596

1597

1598

1599

<code class="descclassname">SSLContext.</code><code class="descname">protocol</code><a class="headerlink" href="#ssl.SSLContext.protocol" title="Permalink to this definition">¶</a></dt>

1600

<dd>The protocol version chosen when constructing the context. This attribute

1601

is read-only.

1602

</dd></dl>

1603

1604

1605

1606

<code class="descclassname">SSLContext.</code><code class="descname">verify_flags</code><a class="headerlink" href="#ssl.SSLContext.verify_flags" title="Permalink to this definition">¶</a></dt>

1607

<dd>The flags for certificate verification operations. You can set flags like

1608

<a class="reference internal" href="#ssl.VERIFY_CRL_CHECK_LEAF" title="ssl.VERIFY_CRL_CHECK_LEAF"><code class="xref py py-data docutils literal">VERIFY_CRL_CHECK_LEAF</code></a> by ORing them together. By default OpenSSL

1609

does neither require nor verify certificate revocation lists (CRLs).

1610

Available only with openssl version 0.9.8+.

1611

</dd></dl>

1612

1613

1614

1615

<code class="descclassname">SSLContext.</code><code class="descname">verify_mode</code><a class="headerlink" href="#ssl.SSLContext.verify_mode" title="Permalink to this definition">¶</a></dt>

1616

<dd>Whether to try to verify other peers’ certificates and how to behave

1617

if verification fails. This attribute must be one of

1618

<a class="reference internal" href="#ssl.CERT_NONE" title="ssl.CERT_NONE"><code class="xref py py-data docutils literal">CERT_NONE</code></a>, <a class="reference internal" href="#ssl.CERT_OPTIONAL" title="ssl.CERT_OPTIONAL"><code class="xref py py-data docutils literal">CERT_OPTIONAL</code></a> or <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-data docutils literal">CERT_REQUIRED</code></a>.

1619

</dd></dl>

1620

1621

</div>

1622

1623

<h2>17.3.4. Certificates<a class="headerlink" href="#certificates" title="Permalink to this headline">¶</a></h2>

1624

Certificates in general are part of a public-key / private-key system. In this

1625

system, each principal, (which may be a machine, or a person, or an

1626

organization) is assigned a unique two-part encryption key. One part of the key

1627

is public, and is called the public key; the other part is kept secret, and is

1628

called the private key. The two parts are related, in that if you encrypt a

1629

message with one of the parts, you can decrypt it with the other part, and

1630

only with the other part.

1631

A certificate contains information about two principals. It contains the name

1632

of a subject, and the subject’s public key. It also contains a statement by a

1633

second principal, the issuer, that the subject is who he claims to be, and

1634

that this is indeed the subject’s public key. The issuer’s statement is signed

1635

with the issuer’s private key, which only the issuer knows. However, anyone can

1636

verify the issuer’s statement by finding the issuer’s public key, decrypting the

1637

statement with it, and comparing it to the other information in the certificate.

1638

The certificate also contains information about the time period over which it is

1639

valid. This is expressed as two fields, called “notBefore” and “notAfter”.

1640

In the Python use of certificates, a client or server can use a certificate to

1641

prove who they are. The other side of a network connection can also be required

1642

to produce a certificate, and that certificate can be validated to the

1643

satisfaction of the client or server that requires such validation. The

1644

connection attempt can be set to raise an exception if the validation fails.

1645

Validation is done automatically, by the underlying OpenSSL framework; the

1646

application need not concern itself with its mechanics. But the application

1647

does usually need to provide sets of certificates to allow this process to take

1648

place.

1649

Python uses files to contain certificates. They should be formatted as “PEM”

1650

(see <a class="rfc reference external" href="https://tools.ietf.org/html/rfc1422.html">RFC 1422</a>), which is a base-64 encoded form wrapped with a header line

1651

and a footer line:

1652

<div class="highlight-python"><div class="highlight"><pre>-----BEGIN CERTIFICATE-----

1653

... (certificate in base64 PEM encoding) ...

1654

-----END CERTIFICATE-----

1655

</pre></div>

1656

</div>

1657

1658

<h3>17.3.4.1. Certificate chains<a class="headerlink" href="#certificate-chains" title="Permalink to this headline">¶</a></h3>

1659

The Python files which contain certificates can contain a sequence of

1660

certificates, sometimes called a certificate chain. This chain should start

1661

with the specific certificate for the principal who “is” the client or server,

1662

and then the certificate for the issuer of that certificate, and then the

1663

certificate for the issuer of that certificate, and so on up the chain till

1664

you get to a certificate which is self-signed, that is, a certificate which

1665

has the same subject and issuer, sometimes called a root certificate. The

1666

certificates should just be concatenated together in the certificate file. For

1667

example, suppose we had a three certificate chain, from our server certificate

1668

to the certificate of the certification authority that signed our server

1669

certificate, to the root certificate of the agency which issued the

1670

certification authority’s certificate:

1671

<div class="highlight-python"><div class="highlight"><pre>-----BEGIN CERTIFICATE-----

1672

... (certificate for your server)...

1673

-----END CERTIFICATE-----

1674

-----BEGIN CERTIFICATE-----

1675

... (the certificate for the CA)...

1676

-----END CERTIFICATE-----

1677

-----BEGIN CERTIFICATE-----

1678

... (the root certificate for the CA's issuer)...

1679

-----END CERTIFICATE-----

1680

</pre></div>

1681

</div>

1682

</div>

1683

1684

<h3>17.3.4.2. CA certificates<a class="headerlink" href="#ca-certificates" title="Permalink to this headline">¶</a></h3>

1685

If you are going to require validation of the other side of the connection’s

1686

certificate, you need to provide a “CA certs” file, filled with the certificate

1687

chains for each issuer you are willing to trust. Again, this file just contains

1688

these chains concatenated together. For validation, Python will use the first

1689

chain it finds in the file which matches. The platform’s certificates file can

1690

be used by calling <a class="reference internal" href="#ssl.SSLContext.load_default_certs" title="ssl.SSLContext.load_default_certs"><code class="xref py py-meth docutils literal">SSLContext.load_default_certs()</code></a>, this is done

1691

automatically with <a class="reference internal" href="#ssl.create_default_context" title="ssl.create_default_context"><code class="xref py py-func docutils literal">create_default_context()</code></a>.

1692

</div>

1693

1694

<h3>17.3.4.3. Combined key and certificate<a class="headerlink" href="#combined-key-and-certificate" title="Permalink to this headline">¶</a></h3>

1695

Often the private key is stored in the same file as the certificate; in this

1696

case, only the <code class="docutils literal">certfile</code> parameter to <a class="reference internal" href="#ssl.SSLContext.load_cert_chain" title="ssl.SSLContext.load_cert_chain"><code class="xref py py-meth docutils literal">SSLContext.load_cert_chain()</code></a>

1697

and <a class="reference internal" href="#ssl.wrap_socket" title="ssl.wrap_socket"><code class="xref py py-func docutils literal">wrap_socket()</code></a> needs to be passed. If the private key is stored

1698

with the certificate, it should come before the first certificate in

1699

the certificate chain:

1700

<div class="highlight-python"><div class="highlight"><pre>-----BEGIN RSA PRIVATE KEY-----

1701

... (private key in base64 encoding) ...

1702

-----END RSA PRIVATE KEY-----

1703

-----BEGIN CERTIFICATE-----

1704

... (certificate in base64 PEM encoding) ...

1705

-----END CERTIFICATE-----

1706

</pre></div>

1707

</div>

1708

</div>

1709

1710

<h3>17.3.4.4. Self-signed certificates<a class="headerlink" href="#self-signed-certificates" title="Permalink to this headline">¶</a></h3>

1711

If you are going to create a server that provides SSL-encrypted connection

1712

services, you will need to acquire a certificate for that service. There are

1713

many ways of acquiring appropriate certificates, such as buying one from a

1714

certification authority. Another common practice is to generate a self-signed

1715

certificate. The simplest way to do this is with the OpenSSL package, using

1716

something like the following:

1717

<div class="highlight-python"><div class="highlight"><pre>% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem

1718

Generating a 1024 bit RSA private key

1719

.......++++++

1720

.............................++++++

1721

writing new private key to 'cert.pem'

1722

-----

1723

You are about to be asked to enter information that will be incorporated

1724

into your certificate request.

1725

What you are about to enter is what is called a Distinguished Name or a DN.

1726

There are quite a few fields but you can leave some blank

1727

For some fields there will be a default value,

1728

If you enter '.', the field will be left blank.

1729

-----

1730

Country Name (2 letter code) [AU]:US

1731

State or Province Name (full name) [Some-State]:MyState

1732

Locality Name (eg, city) []:Some City

1733

Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.

1734

Organizational Unit Name (eg, section) []:My Group

1735

Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com

1736

Email Address []:ops@myserver.mygroup.myorganization.com

1737

1738

</pre></div>

1739

</div>

1740

The disadvantage of a self-signed certificate is that it is its own root

1741

certificate, and no one else will have it in their cache of known (and trusted)

1742

root certificates.

1743

</div>

1744

</div>

1745

1746

<h2>17.3.5. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>

1747

1748

<h3>17.3.5.1. Testing for SSL support<a class="headerlink" href="#testing-for-ssl-support" title="Permalink to this headline">¶</a></h3>

1749

To test for the presence of SSL support in a Python installation, user code

1750

should use the following idiom:

1751

<div class="highlight-python"><div class="highlight"><pre>try:

1752

import ssl

1753

except ImportError:

1754

pass

1755

else:

1756

... # do something that requires SSL support

1757

</pre></div>

1758

</div>

1759

</div>

1760

1761

<h3>17.3.5.2. Client-side operation<a class="headerlink" href="#client-side-operation" title="Permalink to this headline">¶</a></h3>

1762

This example creates a SSL context with the recommended security settings

1763

for client sockets, including automatic certificate verification:

1764

<div class="highlight-python"><div class="highlight"><pre>>>> context = ssl.create_default_context()

1765

</pre></div>

1766

</div>

1767

If you prefer to tune security settings yourself, you might create

1768

a context from scratch (but beware that you might not get the settings

1769

right):

1770

<div class="highlight-python"><div class="highlight"><pre>>>> context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)

1771

>>> context.verify_mode = ssl.CERT_REQUIRED

1772

>>> context.check_hostname = True

1773

>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

1774

</pre></div>

1775

</div>

1776

(this snippet assumes your operating system places a bundle of all CA

1777

certificates in <code class="docutils literal">/etc/ssl/certs/ca-bundle.crt</code>; if not, you’ll get an

1778

error and have to adjust the location)

1779

When you use the context to connect to a server, <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-const docutils literal">CERT_REQUIRED</code></a>

1780

validates the server certificate: it ensures that the server certificate

1781

was signed with one of the CA certificates, and checks the signature for

1782

correctness:

1783

<div class="highlight-python"><div class="highlight"><pre>>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),

1784

... server_hostname="www.python.org")

1785

>>> conn.connect(("www.python.org", 443))

1786

</pre></div>

1787

</div>

1788

You may then fetch the certificate:

1789

1790

</pre></div>

1791

</div>

1792

Visual inspection shows that the certificate does identify the desired service

1793

(that is, the HTTPS host <code class="docutils literal">www.python.org</code>):

1794

<div class="highlight-python"><div class="highlight"><pre>>>> pprint.pprint(cert)

1795

{'OCSP': ('http://ocsp.digicert.com',),

1796

'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),

1797

'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',

1798

'http://crl4.digicert.com/sha2-ev-server-g1.crl'),

1799

'issuer': ((('countryName', 'US'),),

1800

(('organizationName', 'DigiCert Inc'),),

1801

(('organizationalUnitName', 'www.digicert.com'),),

1802

(('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),

1803

'notAfter': 'Sep 9 12:00:00 2016 GMT',

1804

'notBefore': 'Sep 5 00:00:00 2014 GMT',

1805

'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',

1806

'subject': ((('businessCategory', 'Private Organization'),),

1807

(('1.3.6.1.4.1.311.60.2.1.3', 'US'),),

1808

(('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),

1809

(('serialNumber', '3359300'),),

1810

(('streetAddress', '16 Allen Rd'),),

1811

(('postalCode', '03894-4801'),),

1812

(('countryName', 'US'),),

1813

(('stateOrProvinceName', 'NH'),),

1814

(('localityName', 'Wolfeboro,'),),

1815

(('organizationName', 'Python Software Foundation'),),

1816

(('commonName', 'www.python.org'),)),

1817

'subjectAltName': (('DNS', 'www.python.org'),

1818

('DNS', 'python.org'),

1819

('DNS', 'pypi.python.org'),

1820

('DNS', 'docs.python.org'),

1821

('DNS', 'testpypi.python.org'),

1822

('DNS', 'bugs.python.org'),

1823

('DNS', 'wiki.python.org'),

1824

('DNS', 'hg.python.org'),

1825

('DNS', 'mail.python.org'),

1826

('DNS', 'packaging.python.org'),

1827

('DNS', 'pythonhosted.org'),

1828

('DNS', 'www.pythonhosted.org'),

1829

('DNS', 'test.pythonhosted.org'),

1830

('DNS', 'us.pycon.org'),

1831

('DNS', 'id.python.org')),

1832

'version': 3}

1833

</pre></div>

1834

</div>

1835

Now the SSL channel is established and the certificate verified, you can

1836

proceed to talk with the server:

1837

<div class="highlight-python"><div class="highlight"><pre>>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")

1838

>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))

1839

[b'HTTP/1.1 200 OK',

1840

b'Date: Sat, 18 Oct 2014 18:27:20 GMT',

1841

b'Server: nginx',

1842

b'Content-Type: text/html; charset=utf-8',

1843

b'X-Frame-Options: SAMEORIGIN',

1844

b'Content-Length: 45679',

1845

b'Accept-Ranges: bytes',

1846

b'Via: 1.1 varnish',

1847

b'Age: 2188',

1848

b'X-Served-By: cache-lcy1134-LCY',

1849

b'X-Cache: HIT',

1850

b'X-Cache-Hits: 11',

1851

b'Vary: Cookie',

1852

b'Strict-Transport-Security: max-age=63072000; includeSubDomains',

1853

b'Connection: close',

1854

b'',

1855

b'']

1856

</pre></div>

1857

</div>

1858

See the discussion of <a class="reference internal" href="#ssl-security">Security considerations</a> below.

1859

</div>

1860

1861

<h3>17.3.5.3. Server-side operation<a class="headerlink" href="#server-side-operation" title="Permalink to this headline">¶</a></h3>

1862

For server operation, typically you’ll need to have a server certificate, and

1863

private key, each in a file. You’ll first create a context holding the key

1864

and the certificate, so that clients can check your authenticity. Then

1865

you’ll open a socket, bind it to a port, call <code class="xref py py-meth docutils literal">listen()</code> on it, and start

1866

waiting for clients to connect:

1867

<div class="highlight-python"><div class="highlight"><pre>import socket, ssl

1868

1869

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)

1870

context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

1871

1872

bindsocket = socket.socket()

1873

bindsocket.bind(('myaddr.mydomain.com', 10023))

1874

bindsocket.listen(5)

1875

</pre></div>

1876

</div>

1877

When a client connects, you’ll call <code class="xref py py-meth docutils literal">accept()</code> on the socket to get the

1878

new socket from the other end, and use the context’s <a class="reference internal" href="#ssl.SSLContext.wrap_socket" title="ssl.SSLContext.wrap_socket"><code class="xref py py-meth docutils literal">SSLContext.wrap_socket()</code></a>

1879

method to create a server-side SSL socket for the connection:

1880

<div class="highlight-python"><div class="highlight"><pre>while True:

1881

newsocket, fromaddr = bindsocket.accept()

1882

connstream = context.wrap_socket(newsocket, server_side=True)

1883

try:

1884

deal_with_client(connstream)

1885

finally:

1886

connstream.shutdown(socket.SHUT_RDWR)

1887

connstream.close()

1888

</pre></div>

1889

</div>

1890

Then you’ll read data from the <code class="docutils literal">connstream</code> and do something with it till you

1891

are finished with the client (or the client is finished with you):

1892

<div class="highlight-python"><div class="highlight"><pre>def deal_with_client(connstream):

1893

data = connstream.read()

1894

# null data means the client is finished with us

1895

while data:

1896

if not do_something(connstream, data):

1897

# we'll assume do_something returns False

1898

# when we're finished with client

1899

break

1900

data = connstream.read()

1901

# finished with client

1902

</pre></div>

1903

</div>

1904

And go back to listening for new client connections (of course, a real server

1905

would probably handle each client connection in a separate thread, or put

1906

the sockets in non-blocking mode and use an event loop).

1907

</div>

1908

</div>

1909

1910

<h2>17.3.6. Notes on non-blocking sockets<a class="headerlink" href="#notes-on-non-blocking-sockets" title="Permalink to this headline">¶</a></h2>

1911

When working with non-blocking sockets, there are several things you need

1912

to be aware of:

1913

<ul>

1914

<li>Calling <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal">select()</code></a> tells you that the OS-level socket can be

1915

read from (or written to), but it does not imply that there is sufficient

1916

data at the upper SSL layer. For example, only part of an SSL frame might

1917

have arrived. Therefore, you must be ready to handle <code class="xref py py-meth docutils literal">SSLSocket.recv()</code>

1918

and <code class="xref py py-meth docutils literal">SSLSocket.send()</code> failures, and retry after another call to

1919

<a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal">select()</code></a>.

1920

</li>

1921

<li>Conversely, since the SSL layer has its own framing, a SSL socket may

1922

still have data available for reading without <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal">select()</code></a>

1923

being aware of it. Therefore, you should first call

1924

<code class="xref py py-meth docutils literal">SSLSocket.recv()</code> to drain any potentially available data, and then

1925

only block on a <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal">select()</code></a> call if still necessary.

1926

(of course, similar provisions apply when using other primitives such as

1927

<a class="reference internal" href="select.html#select.poll" title="select.poll"><code class="xref py py-func docutils literal">poll()</code></a>, or those in the <code class="xref py py-mod docutils literal">selectors</code> module)

1928

</li>

1929

<li>The SSL handshake itself will be non-blocking: the

1930

1931

successfully. Here is a synopsis using <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal">select()</code></a> to wait for

1932

the socket’s readiness:

1933

<div class="highlight-python"><div class="highlight"><pre>while True:

1934

try:

1935

sock.do_handshake()

1936

break

1937

except ssl.SSLWantReadError:

1938

select.select([sock], [], [])

1939

except ssl.SSLWantWriteError:

1940

select.select([], [sock], [])

1941

</pre></div>

1942

</div>

1943

</li>

1944

</ul>

1945

</div>

1946

1947

<h2>17.3.7. Security considerations<a class="headerlink" href="#security-considerations" title="Permalink to this headline">¶</a></h2>

1948

1949

<h3>17.3.7.1. Best defaults<a class="headerlink" href="#best-defaults" title="Permalink to this headline">¶</a></h3>

1950

For client use, if you don’t have any special requirements for your

1951

security policy, it is highly recommended that you use the

1952

<a class="reference internal" href="#ssl.create_default_context" title="ssl.create_default_context"><code class="xref py py-func docutils literal">create_default_context()</code></a> function to create your SSL context.

1953

It will load the system’s trusted CA certificates, enable certificate

1954

validation and hostname checking, and try to choose reasonably secure

1955

protocol and cipher settings.

1956

If a client certificate is needed for the connection, it can be added with

1957

<a class="reference internal" href="#ssl.SSLContext.load_cert_chain" title="ssl.SSLContext.load_cert_chain"><code class="xref py py-meth docutils literal">SSLContext.load_cert_chain()</code></a>.

1958

By contrast, if you create the SSL context by calling the <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a>

1959

constructor yourself, it will not have certificate validation nor hostname

1960

checking enabled by default. If you do so, please read the paragraphs below

1961

to achieve a good security level.

1962

</div>

1963

1964

<h3>17.3.7.2. Manual settings<a class="headerlink" href="#manual-settings" title="Permalink to this headline">¶</a></h3>

1965

1966

<h4>17.3.7.2.1. Verifying certificates<a class="headerlink" href="#verifying-certificates" title="Permalink to this headline">¶</a></h4>

1967

When calling the <a class="reference internal" href="#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> constructor directly,

1968

<a class="reference internal" href="#ssl.CERT_NONE" title="ssl.CERT_NONE"><code class="xref py py-const docutils literal">CERT_NONE</code></a> is the default. Since it does not authenticate the other

1969

peer, it can be insecure, especially in client mode where most of time you

1970

would like to ensure the authenticity of the server you’re talking to.

1971

Therefore, when in client mode, it is highly recommended to use

1972

<a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-const docutils literal">CERT_REQUIRED</code></a>. However, it is in itself not sufficient; you also

1973

have to check that the server certificate, which can be obtained by calling

1974

1975

protocols and applications, the service can be identified by the hostname;

1976

in this case, the <a class="reference internal" href="#ssl.match_hostname" title="ssl.match_hostname"><code class="xref py py-func docutils literal">match_hostname()</code></a> function can be used. This common

1977

check is automatically performed when <a class="reference internal" href="#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code class="xref py py-attr docutils literal">SSLContext.check_hostname</code></a> is

1978

enabled.

1979

In server mode, if you want to authenticate your clients using the SSL layer

1980

(rather than using a higher-level authentication mechanism), you’ll also have

1981

to specify <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-const docutils literal">CERT_REQUIRED</code></a> and similarly check the client certificate.

1982

1983

1984

Note

1985

In client mode, <a class="reference internal" href="#ssl.CERT_OPTIONAL" title="ssl.CERT_OPTIONAL"><code class="xref py py-const docutils literal">CERT_OPTIONAL</code></a> and <a class="reference internal" href="#ssl.CERT_REQUIRED" title="ssl.CERT_REQUIRED"><code class="xref py py-const docutils literal">CERT_REQUIRED</code></a> are

1986

equivalent unless anonymous ciphers are enabled (they are disabled

1987

by default).

1988

</div>

1989

</div></blockquote>

1990

</div>

1991

1992

<h4>17.3.7.2.2. Protocol versions<a class="headerlink" href="#protocol-versions" title="Permalink to this headline">¶</a></h4>

1993

SSL versions 2 and 3 are considered insecure and are therefore dangerous to

1994

use. If you want maximum compatibility between clients and servers, it is

1995

recommended to use <a class="reference internal" href="#ssl.PROTOCOL_SSLv23" title="ssl.PROTOCOL_SSLv23"><code class="xref py py-const docutils literal">PROTOCOL_SSLv23</code></a> as the protocol version and then

1996

disable SSLv2 and SSLv3 explicitly using the <a class="reference internal" href="#ssl.SSLContext.options" title="ssl.SSLContext.options"><code class="xref py py-data docutils literal">SSLContext.options</code></a>

1997

attribute:

1998

<div class="highlight-python"><div class="highlight"><pre>context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)

1999

context.options |= ssl.OP_NO_SSLv2

2000

context.options |= ssl.OP_NO_SSLv3

2001

</pre></div>

2002

</div>

2003

The SSL context created above will only allow TLSv1 and later (if

2004

supported by your system) connections.

2005

</div>

2006

2007

<h4>17.3.7.2.3. Cipher selection<a class="headerlink" href="#cipher-selection" title="Permalink to this headline">¶</a></h4>

2008

If you have advanced security requirements, fine-tuning of the ciphers

2009

enabled when negotiating a SSL session is possible through the

2010

<a class="reference internal" href="#ssl.SSLContext.set_ciphers" title="ssl.SSLContext.set_ciphers"><code class="xref py py-meth docutils literal">SSLContext.set_ciphers()</code></a> method. Starting from Python 2.7.9, the

2011

ssl module disables certain weak ciphers by default, but you may want

2012

to further restrict the cipher choice. Be sure to read OpenSSL’s documentation

2013

about the <a class="reference external" href="https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT">cipher list format</a>.

2014

If you want to check which ciphers are enabled by a given cipher list, use the

2015

<code class="docutils literal">openssl ciphers</code> command on your system.

2016

</div>

2017

</div>

2018

2019

<h3>17.3.7.3. Multi-processing<a class="headerlink" href="#multi-processing" title="Permalink to this headline">¶</a></h3>

2020

If using this module as part of a multi-processed application (using,

2021

for example the <a class="reference internal" href="multiprocessing.html#module-multiprocessing" title="multiprocessing: Process-based "threading" interface."><code class="xref py py-mod docutils literal">multiprocessing</code></a> or <code class="xref py py-mod docutils literal">concurrent.futures</code> modules),

2022

be aware that OpenSSL’s internal random number generator does not properly

2023

handle forked processes. Applications must change the PRNG state of the

2024

parent process if they use any SSL feature with <a class="reference internal" href="os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal">os.fork()</code></a>. Any

2025

successful call of <a class="reference internal" href="#ssl.RAND_add" title="ssl.RAND_add"><code class="xref py py-func docutils literal">RAND_add()</code></a>, <code class="xref py py-func docutils literal">RAND_bytes()</code> or

2026

<code class="xref py py-func docutils literal">RAND_pseudo_bytes()</code> is sufficient.

2027

2028

See also

2029

2030

<dt>Class <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a></dt>

2031

<dd>Documentation of underlying <a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal">socket</code></a> class</dd>

2032

<dt><a class="reference external" href="https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html">SSL/TLS Strong Encryption: An Introduction</a></dt>

2033

<dd>Intro from the Apache webserver documentation</dd>

2034

<dt><a class="reference external" href="https://www.ietf.org/rfc/rfc1422">RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management</a></dt>

2035

<dd>Steve Kent</dd>

2036

<dt><a class="reference external" href="https://www.ietf.org/rfc/rfc1750">RFC 1750: Randomness Recommendations for Security</a></dt>

2037

<dd>D. Eastlake et. al.</dd>

2038

<dt><a class="reference external" href="https://www.ietf.org/rfc/rfc3280">RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile</a></dt>

2039

<dd>Housley et. al.</dd>

2040

<dt><a class="reference external" href="https://www.ietf.org/rfc/rfc4366">RFC 4366: Transport Layer Security (TLS) Extensions</a></dt>

2041

<dd>Blake-Wilson et. al.</dd>

2042

<dt><a class="reference external" href="https://tools.ietf.org/html/rfc5246">RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2</a></dt>

2043

<dd>T. Dierks et. al.</dd>

2044

<dt><a class="reference external" href="https://tools.ietf.org/html/rfc6066">RFC 6066: Transport Layer Security (TLS) Extensions</a></dt>

2045

<dd>D. Eastlake</dd>

2046

<dt><a class="reference external" href="https://www.iana.org/assignments/tls-parameters/tls-parameters.xml">IANA TLS: Transport Layer Security (TLS) Parameters</a></dt>

2047

2048

</dl>

2049

</div>

2050

</div>

2051

</div>

2052

</div>

2053

2054

2055

</div>

2056

</div>

2057

</div>

2058

2059

2060

<h3><a href="../contents.html">Table Of Contents</a></h3>

2061

<ul>

2062

<li><a class="reference internal" href="#">17.3. <code class="docutils literal">ssl</code> — TLS/SSL wrapper for socket objects</a><ul>

2063

<li><a class="reference internal" href="#functions-constants-and-exceptions">17.3.1. Functions, Constants, and Exceptions</a><ul>

2064

<li><a class="reference internal" href="#socket-creation">17.3.1.1. Socket creation</a></li>

2065

<li><a class="reference internal" href="#context-creation">17.3.1.2. Context creation</a></li>

2066

<li><a class="reference internal" href="#random-generation">17.3.1.3. Random generation</a></li>

2067

<li><a class="reference internal" href="#certificate-handling">17.3.1.4. Certificate handling</a></li>

2068

<li><a class="reference internal" href="#constants">17.3.1.5. Constants</a></li>

2069

</ul>

2070

</li>

2071

<li><a class="reference internal" href="#ssl-sockets">17.3.2. SSL Sockets</a></li>

2072

<li><a class="reference internal" href="#ssl-contexts">17.3.3. SSL Contexts</a></li>

2073

<li><a class="reference internal" href="#certificates">17.3.4. Certificates</a><ul>

2074

<li><a class="reference internal" href="#certificate-chains">17.3.4.1. Certificate chains</a></li>

2075

<li><a class="reference internal" href="#ca-certificates">17.3.4.2. CA certificates</a></li>

2076

<li><a class="reference internal" href="#combined-key-and-certificate">17.3.4.3. Combined key and certificate</a></li>

2077

<li><a class="reference internal" href="#self-signed-certificates">17.3.4.4. Self-signed certificates</a></li>

2078

</ul>

2079

</li>

2080

<li><a class="reference internal" href="#examples">17.3.5. Examples</a><ul>

2081

<li><a class="reference internal" href="#testing-for-ssl-support">17.3.5.1. Testing for SSL support</a></li>

2082

<li><a class="reference internal" href="#client-side-operation">17.3.5.2. Client-side operation</a></li>

2083

<li><a class="reference internal" href="#server-side-operation">17.3.5.3. Server-side operation</a></li>

2084

</ul>

2085

</li>

2086

<li><a class="reference internal" href="#notes-on-non-blocking-sockets">17.3.6. Notes on non-blocking sockets</a></li>

2087

<li><a class="reference internal" href="#security-considerations">17.3.7. Security considerations</a><ul>

2088

<li><a class="reference internal" href="#best-defaults">17.3.7.1. Best defaults</a></li>

2089

<li><a class="reference internal" href="#manual-settings">17.3.7.2. Manual settings</a><ul>

2090

<li><a class="reference internal" href="#verifying-certificates">17.3.7.2.1. Verifying certificates</a></li>

2091

<li><a class="reference internal" href="#protocol-versions">17.3.7.2.2. Protocol versions</a></li>

2092

<li><a class="reference internal" href="#cipher-selection">17.3.7.2.3. Cipher selection</a></li>

2093

</ul>

2094

</li>

2095

<li><a class="reference internal" href="#multi-processing">17.3.7.3. Multi-processing</a></li>

2096

</ul>

2097

</li>

2098

</ul>

2099

</li>

2100

</ul>

2101

2102

<h4>Previous topic</h4>

2103

<a href="socket.html"

2104

title="previous chapter">17.2. <code class="docutils literal">socket</code> — Low-level networking interface</a>

2105

<h4>Next topic</h4>

2106

<a href="signal.html"

2107

title="next chapter">17.4. <code class="docutils literal">signal</code> — Set handlers for asynchronous events</a>

2108

2109

2110

<li><a href="../bugs.html">Report a Bug</a></li>

2111

<li><a href="../_sources/library/ssl.txt"

2112

rel="nofollow">Show Source</a></li>

2113

</ul>

2114

2115

2116

<h3>Quick search</h3>

2117

2118

2119

2120

2121

2122

</form>

2123

2124

Enter search terms or a module, class or function name.

2125

2126

</div>

2127

2128

</div>

2129

</div>

2130

2131

</div>

2132

2133

<h3>Navigation</h3>

2134

<ul>

2135

2136

<a href="../genindex.html" title="General Index"

2137

>index</a></li>

2138

2139

<a href="../py-modindex.html" title="Python Module Index"

2140

>modules</a> |</li>

2141

2142

<a href="signal.html" title="17.4. signal — Set handlers for asynchronous events"

2143

>next</a> |</li>

2144

2145

<a href="socket.html" title="17.2. socket — Low-level networking interface"

2146

>previous</a> |</li>

2147

<li><img src="../_static/py.png" alt=""

2148

style="vertical-align: middle; margin-top: -1px"/></li>

2149

<li><a href="https://www.python.org/">Python</a> »</li>

2150

<li>

2151

2.7.12

2152

<a href="../index.html">Documentation</a> »

2153

</li>

2154

2155

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

2156

<li class="nav-item nav-item-2"><a href="ipc.html" >17. Interprocess Communication and Networking</a> »</li>

2157

</ul>

2158

</div>

2159

2160

2161

2162

The Python Software Foundation is a non-profit corporation.

2163

<a href="https://www.python.org/psf/donations/">Please donate.</a>

2164

2165

Last updated on Oct 19, 2016.

2166

<a href="../bugs.html">Found a bug</a>?

2167

2168

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

2169

</div>

2170

2171

</body>

2172

</html>

b'\\ No newline at end of file'

Older »