ssl — TLS/SSL-omslag för socket-objekt

Källkod: Lib/ssl.py

Den här modulen ger tillgång till Transport Layer Security (ofta kallat ”Secure Sockets Layer”) kryptering och peer authentication för nätverksuttag, både på klient- och serversidan. Den här modulen använder OpenSSL-biblioteket. Det är tillgängligt på alla moderna Unix-system, Windows, macOS och förmodligen ytterligare plattformar, så länge OpenSSL är installerat på den plattformen.

Anteckning

Vissa beteenden kan vara plattformsberoende, eftersom anrop görs till operativsystemets socket-API:er. Den installerade versionen av OpenSSL kan också orsaka variationer i beteendet. TLSv1.3 levereras till exempel med OpenSSL version 1.1.1.

Varning

Använd inte den här modulen utan att läsa Överväganden om säkerhet. Detta kan leda till en falsk känsla av säkerhet, eftersom standardinställningarna för ssl-modulen inte nödvändigtvis är lämpliga för din applikation.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Detta avsnitt dokumenterar objekten och funktionerna i modulen ssl; för mer allmän information om TLS, SSL och certifikat hänvisas läsaren till dokumenten i avsnittet ”Se även” längst ned.

Den här modulen tillhandahåller en klass, ssl.SSLSocket, som härrör från typen socket.socket och ger en socket-liknande omslag som också krypterar och dekrypterar data som går över sockeln med SSL. Den stöder ytterligare metoder som getpeercert(), som hämtar certifikatet för den andra sidan av anslutningen, cipher(), som hämtar det chiffer som används för den säkra anslutningen eller get_verified_chain(), get_unverified_chain() som hämtar certifikatkedjan.

För mer sofistikerade applikationer hjälper klassen ssl.SSLContext till att hantera inställningar och certifikat, som sedan kan ärvas av SSL-uttag som skapas genom metoden SSLContext.wrap_socket().

Ändrad i version 3.5.3: Uppdaterad för att stödja länkning med OpenSSL 1.1.0

Ändrad i version 3.6: OpenSSL 0.9.8, 1.0.0 och 1.0.1 är föråldrade och stöds inte längre. I framtiden kommer ssl-modulen att kräva minst OpenSSL 1.0.2 eller 1.1.0.

Ändrad i version 3.10: PEP 644 har implementerats. Modulen ssl kräver OpenSSL 1.1.1 eller nyare.

Användning av föråldrade konstanter och funktioner resulterar i varningar om föråldring.

Funktioner, konstanter och undantag

Skapande av uttag

Instanser av SSLSocket måste skapas med hjälp av metoden SSLContext.wrap_socket(). Hjälpfunktionen create_default_context() returnerar en ny kontext med säkra standardinställningar.

Exempel på klientuttag med standardkontext och IPv4/IPv6 dual stack:

import socket
import ssl

hostname = 'www.python.org'
context = ssl.create_default_context()

with socket.create_connection((hostname, 443)) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

Exempel på klientuttag med anpassad kontext och IPv4:

värdnamn = 'www.python.org'
# PROTOCOL_TLS_CLIENT kräver giltig certkedja och värdnamn
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')

med socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) som sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

Serveruttag exempel lyssnar på localhost IPv4:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

med socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) som sock:
    sock.bind(('127.0.0.1', 8443))
    sock.lyssna(5)
    med context.wrap_socket(sock, server_side=True) som ssock:
        conn, addr = ssock.accept()
        ...

Skapande av kontext

En bekvämlighetsfunktion som hjälper till att skapa SSLContext-objekt för vanliga ändamål.

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)

Returnerar ett nytt SSLContext-objekt med standardinställningar för det angivna syftet. Inställningarna väljs av modulen ssl och representerar vanligtvis en högre säkerhetsnivå än när man anropar konstruktören SSLContext direkt.

cafile, capath, cadata representerar valfria CA-certifikat att lita på för certifikatverifiering, som i SSLContext.load_verify_locations(). Om alla tre är None kan den här funktionen välja att lita på systemets standardcertifikat från CA i stället.

Inställningarna är: PROTOCOL_TLS_CLIENT eller PROTOCOL_TLS_SERVER, OP_NO_SSLv2 och OP_NO_SSLv3 med chiffersviter med hög kryptering utan RC4 och utan oautentiserade chiffersviter. Genom att ange SERVER_AUTH som purpose sätts verify_mode till CERT_REQUIRED och antingen laddas CA-certifikat (när minst en av cafile, capath eller cadata anges) eller så används SSLContext.load_default_certs() för att ladda standard CA-certifikat.

När keylog_filename stöds och miljövariabeln SSLKEYLOGFILE är inställd, aktiverar create_default_context() nyckelloggning.

Standardinställningarna för detta sammanhang inkluderar VERIFY_X509_PARTIAL_CHAIN och VERIFY_X509_STRICT. Dessa gör att den underliggande OpenSSL-implementeringen beter sig mer som en överensstämmande implementering av RFC 5280, i utbyte mot en liten mängd inkompatibilitet med äldre X.509-certifikat.

Anteckning

Protokoll, alternativ, chiffer och andra inställningar kan ändras till mer restriktiva värden när som helst utan föregående avskrivning. Värdena representerar en rättvis balans mellan kompatibilitet och säkerhet.

Om din applikation behöver specifika inställningar bör du skapa en SSLContext och tillämpa inställningarna själv.

Anteckning

Om du upptäcker att när vissa äldre klienter eller servrar försöker ansluta med en SSLContext som skapats av den här funktionen får de felmeddelandet ”Protocol or cipher suite mismatch”, kan det bero på att de endast stöder SSL3.0 som den här funktionen utesluter med OP_NO_SSLv3. SSL3.0 anses allmänt vara helt trasigt. Om du fortfarande vill fortsätta att använda den här funktionen men ändå tillåta SSL 3.0-anslutningar kan du återaktivera dem med hjälp av:

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

Anteckning

Detta sammanhang aktiverar VERIFY_X509_STRICT som standard, vilket kan avvisa pre-RFC 5280 eller missbildade certifikat som den underliggande OpenSSL-implementationen annars skulle acceptera. Det är inte rekommenderat att inaktivera detta, men du kan göra det med hjälp av:

ctx = ssl.create_default_context()
ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT

Tillagd i version 3.4.

Ändrad i version 3.4.4: RC4 togs bort från standardchiffersträngen.

Ändrad i version 3.6: ChaCha20/Poly1305 har lagts till i standardchiffersträngen.

3DES togs bort från standardchiffersträngen.

Ändrad i version 3.8: Stöd för nyckelloggning till SSLKEYLOGFILE har lagts till.

Ändrad i version 3.10: Kontexten använder nu protokollet PROTOCOL_TLS_CLIENT eller PROTOCOL_TLS_SERVER i stället för det generiska protokollet PROTOCOL_TLS.

Ändrad i version 3.13: Kontexten använder nu VERIFY_X509_PARTIAL_CHAIN och VERIFY_X509_STRICT i sina standardverifieringsflaggor.

Undantag

exception ssl.SSLError

Utlöses för att signalera ett fel från den underliggande SSL-implementeringen (som för närvarande tillhandahålls av OpenSSL-biblioteket). Detta innebär något problem i krypterings- och autentiseringslagret på högre nivå som läggs ovanpå den underliggande nätverksanslutningen. Det här felet är en subtyp av OSError. Felkoden och meddelandet för SSLError-instanser tillhandahålls av OpenSSL-biblioteket.

Ändrad i version 3.3: SSLError brukade vara en subtyp av socket.error.

library

En sträng som betecknar den OpenSSL-submodul där felet inträffade, t.ex. SSL, PEM eller X509. Mängden möjliga värden beror på OpenSSL-versionen.

Tillagd i version 3.3.

reason

En sträng som anger orsaken till att felet uppstod, till exempel CERTIFICATE_VERIFY_FAILED. Mängden möjliga värden beror på OpenSSL-versionen.

Tillagd i version 3.3.

exception ssl.SSLZeroReturnError

En underklass av SSLError som uppstår när man försöker läsa eller skriva och SSL-anslutningen har stängts på ett korrekt sätt. Observera att detta inte betyder att den underliggande transporten (läs TCP) har stängts.

Tillagd i version 3.3.

exception ssl.SSLWantReadError

En underklass till SSLError som orsakas av en icke-blockerande SSL-socket när den försöker läsa eller skriva data, men mer data måste tas emot på den underliggande TCP-transporten innan begäran kan uppfyllas.

Tillagd i version 3.3.

exception ssl.SSLWantWriteError

En underklass till SSLError som uppstår när ett icke-blockerande SSL-uttag försöker läsa eller skriva data, men mer data måste skickas på den underliggande TCP-transporten innan begäran kan uppfyllas.

Tillagd i version 3.3.

exception ssl.SSLSyscallError

En underklass till SSLError som uppstår när ett systemfel uppstår när man försöker utföra en åtgärd på ett SSL-uttag. Tyvärr finns det inget enkelt sätt att inspektera det ursprungliga errno-numret.

Tillagd i version 3.3.

exception ssl.SSLEOFError

En underklass till SSLError som uppstår när SSL-anslutningen har avslutats abrupt. Generellt sett bör du inte försöka återanvända den underliggande transporten när detta fel uppstår.

Tillagd i version 3.3.

exception ssl.SSLCertVerificationError

En underklass av SSLError som uppstår när certifikatvalideringen misslyckats.

Tillagd i version 3.7.

verify_code

Ett numeriskt felnummer som anger verifieringsfelet.

verify_message

En mänskligt läsbar sträng av verifieringsfelet.

exception ssl.CertificateError

Ett alias för SSLCertVerificationError.

Ändrad i version 3.7: Undantaget är nu ett alias för SSLCertVerificationError.

Slumpmässig generering

ssl.RAND_bytes(num)

Returnerar num kryptografiskt starka pseudoslumpmässiga bytes. Utlöser ett SSLError om PRNG inte har laddats med tillräckligt med data eller om operationen inte stöds av den aktuella RAND-metoden. RAND_status() kan användas för att kontrollera statusen för PRNG och RAND_add() kan användas för att ladda PRNG.

För nästan alla tillämpningar är os.urandom() att föredra.

Läs Wikipedia-artikeln Cryptographically secure pseudorandom number generator (CSPRNG) för att få information om kraven på en kryptografiskt stark generator.

Tillagd i version 3.3.

ssl.RAND_status()

Returnerar True om SSL:s pseudoslumptalsgenerator har försetts med ”tillräckligt” med slumpmässighet, och False annars. Du kan använda ssl.RAND_egd() och ssl.RAND_add() för att öka slumpmässigheten i pseudoslumptalsgeneratorn.

ssl.RAND_add(bytes, entropy)

Blanda de angivna bytes i SSL:s pseudoslumpmässiga nummergenerator. Parametern entropy (en float) är en nedre gräns för entropin i strängen (så du kan alltid använda 0.0). Se RFC 1750 för mer information om källor till entropi.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

Hantering av certifikat

ssl.cert_time_to_seconds(cert_time)

Returnerar tiden i sekunder sedan epoken, givet strängen cert_time som representerar ”notBefore”- eller ”notAfter”-datumet från ett certifikat i "%b %d %H:%M:%S %Y %Z" strptime-format (C-läge).

Här är ett exempel:

>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))
2018-01-05 09:34:43

”notBefore”- eller ”notAfter”-datum måste använda GMT (RFC 5280).

Ändrad i version 3.5: Tolkar inmatningstiden som en tid i UTC enligt tidszonen ”GMT” i inmatningssträngen. Lokal tidszon användes tidigare. Returnera ett heltal (inga bråkdelar av en sekund i inmatningsformatet)

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])

Givet adressen addr till en SSL-skyddad server, som ett (hostname, port-number)-par, hämtar serverns certifikat och returnerar det som en PEM-kodad sträng. Om ssl_version anges, används den versionen av SSL-protokollet för att försöka ansluta till servern. Om ca_certs anges bör det vara en fil som innehåller en lista över rotcertifikat, i samma format som används för parametern cafile i SSLContext.load_verify_locations(). Anropet kommer att försöka validera servercertifikatet mot denna uppsättning rotcertifikat, och misslyckas om valideringsförsöket misslyckas. En timeout kan anges med parametern timeout.

Ändrad i version 3.3: Denna funktion är nu IPv6-kompatibel.

Ändrad i version 3.5: Standard ssl_version ändras från PROTOCOL_SSLv3 till PROTOCOL_TLS för maximal kompatibilitet med moderna servrar.

Ändrad i version 3.10: Parametern timeout har lagts till.

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)

Om ett certifikat ges som en DER-kodad blob med bytes, returneras en PEM-kodad strängversion av samma certifikat.

ssl.PEM_cert_to_DER_cert(PEM_cert_string)

Om ett certifikat anges som en ASCII PEM-sträng returneras en DER-kodad sekvens av bytes för samma certifikat.

ssl.get_default_verify_paths()

Returnerar en namngiven tupel med sökvägar till OpenSSL:s standardcafile och -capath. Sökvägarna är samma som används av SSLContext.set_default_verify_paths(). Returvärdet är en named tuple DefaultVerifyPaths:

  • cafile - upplöst sökväg till cafile eller None om filen inte finns,

  • capath - upplöst sökväg till capath eller None om katalogen inte finns,

  • openssl_cafile_env - OpenSSL:s miljönyckel som pekar på en cafile,

  • openssl_cafile - hårdkodad sökväg till en cafile,

  • openssl_capath_env - OpenSSL:s miljönyckel som pekar på en capath,

  • openssl_capath - hårdkodad sökväg till en capath-katalog

Tillagd i version 3.4.

ssl.enum_certificates(store_name)

Hämtar certifikat från Windows system cert store. store_name kan vara en av CA, ROOT eller MY. Windows kan också tillhandahålla ytterligare certifikatlager.

Funktionen returnerar en lista med (cert_bytes, encoding_type, trust)-tupler. Encoding_type anger kodningen av cert_bytes. Den är antingen x509_asn för X.509 ASN.1-data eller pkcs_7_asn för PKCS#7 ASN.1-data. Trust anger syftet med certifikatet som en uppsättning OIDS eller exakt True om certifikatet är pålitligt för alla ändamål.

Exempel:

>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
 (b'data...', 'x509_asn', True)]

Tillgänglighet: Windows.

Tillagd i version 3.4.

ssl.enum_crls(store_name)

Hämtar CRL:er från Windows systemets cert-arkiv. store_name kan vara en av CA, ROOT eller MY. Windows kan också tillhandahålla ytterligare cert-arkiv.

Funktionen returnerar en lista med (cert_bytes, encoding_type, trust)-tupler. Encoding_type anger kodningen av cert_bytes. Den är antingen x509_asn för X.509 ASN.1-data eller pkcs_7_asn för PKCS#7 ASN.1-data.

Tillgänglighet: Windows.

Tillagd i version 3.4.

Konstanter

Alla konstanter är nu enum.IntEnum eller enum.IntFlag samlingar.

Tillagd i version 3.6.

ssl.CERT_NONE

Möjligt värde för SSLContext.verify_mode. Med undantag för PROTOCOL_TLS_CLIENT är detta standardläget. Med sockets på klientsidan accepteras i stort sett alla certifikat. Valideringsfel, t.ex. icke betrodda eller utgångna certifikat, ignoreras och avbryter inte TLS/SSL-handskakningen.

I serverläge begärs inget certifikat från klienten, så klienten skickar inte något för autentisering med klientcertifikat.

Se diskussionen om Överväganden om säkerhet nedan.

ssl.CERT_OPTIONAL

Möjligt värde för SSLContext.verify_mode. I klientläge har CERT_OPTIONAL samma betydelse som CERT_REQUIRED. Vi rekommenderar att du använder CERT_REQUIRED för sockets på klientsidan i stället.

I serverläge skickas en begäran om klientcertifikat till klienten. Klienten kan antingen ignorera begäran eller skicka ett certifikat för att utföra TLS-klientcertifikatsautentisering. Om klienten väljer att skicka ett certifikat verifieras det. Om ett verifieringsfel uppstår avbryts TLS-handskakningen omedelbart.

Om denna inställning används krävs att en giltig uppsättning CA-certifikat skickas till SSLContext.load_verify_locations().

ssl.CERT_REQUIRED

Möjligt värde för SSLContext.verify_mode. I detta läge krävs certifikat från den andra sidan av socket-anslutningen; ett SSLError kommer att uppstå om inget certifikat tillhandahålls, eller om dess validering misslyckas. Detta läge är inte tillräckligt för att verifiera ett certifikat i klientläge eftersom det inte matchar värdnamn. check_hostname måste också aktiveras för att verifiera äktheten hos ett certifikat. PROTOCOL_TLS_CLIENT använder CERT_REQUIRED och aktiverar check_hostname som standard.

Med serveruttag ger detta läge obligatorisk TLS-klientcertifikatsautentisering. En begäran om klientcertifikat skickas till klienten och klienten måste tillhandahålla ett giltigt och betrott certifikat.

Om denna inställning används krävs att en giltig uppsättning CA-certifikat skickas till SSLContext.load_verify_locations().

class ssl.VerifyMode

enum.IntEnum samling av CERT_*-konstanter.

Tillagd i version 3.6.

ssl.VERIFY_DEFAULT

Möjligt värde för SSLContext.verify_flags. I det här läget kontrolleras inte CRL:er (Certificate Revocation List). Som standard varken kräver eller verifierar OpenSSL CRL:er.

Tillagd i version 3.4.

ssl.VERIFY_CRL_CHECK_LEAF

Möjligt värde för SSLContext.verify_flags. I det här läget kontrolleras endast peer-certifikatet, men inga mellanliggande CA-certifikat. Läget kräver en giltig CRL som är signerad av peer-certifikatets utfärdare (dess direkta förfader CA). Om ingen korrekt CRL har laddats med SSLContext.load_verify_locations, kommer valideringen att misslyckas.

Tillagd i version 3.4.

ssl.VERIFY_CRL_CHECK_CHAIN

Möjligt värde för SSLContext.verify_flags. I det här läget kontrolleras CRL för alla certifikat i peer-certifikatkedjan.

Tillagd i version 3.4.

ssl.VERIFY_X509_STRICT

Möjligt värde för SSLContext.verify_flags för att inaktivera lösningar för trasiga X.509-certifikat.

Tillagd i version 3.4.

ssl.VERIFY_ALLOW_PROXY_CERTS

Möjligt värde för SSLContext.verify_flags för att aktivera verifiering av proxycertifikat.

Tillagd i version 3.10.

ssl.VERIFY_X509_TRUSTED_FIRST

Möjligt värde för SSLContext.verify_flags. Instruerar OpenSSL att föredra betrodda certifikat när förtroendekedjan byggs upp för att validera ett certifikat. Denna flagga är aktiverad som standard.

Tillagd i version 3.4.4.

ssl.VERIFY_X509_PARTIAL_CHAIN

Möjligt värde för SSLContext.verify_flags. Instruerar OpenSSL att acceptera att mellanliggande CA:er i trust store behandlas som trust-anchors, på samma sätt som självsignerade root CA-certifikat. Detta gör det möjligt att lita på certifikat som utfärdats av en mellanliggande CA utan att behöva lita på dess förfader rot-CA.

Tillagd i version 3.10.

class ssl.VerifyFlags

enum.IntFlag samling av VERIFY_*-konstanter.

Tillagd i version 3.6.

ssl.PROTOCOL_TLS

Väljer den högsta protokollversionen som både klienten och servern stöder. Trots namnet kan det här alternativet välja både ”SSL”- och ”TLS”-protokoll.

Tillagd i version 3.6.

Föråldrad sedan version 3.10: TLS-klienter och -servrar kräver olika standardinställningar för säker kommunikation. Den generiska TLS-protokollkonstanten är föråldrad till förmån för PROTOCOL_TLS_CLIENT och PROTOCOL_TLS_SERVER.

ssl.PROTOCOL_TLS_CLIENT

Förhandla automatiskt om den högsta protokollversionen som både klienten och servern stöder och konfigurera kontextanslutningarna på klientsidan. Protokollet aktiverar CERT_REQUIRED och check_hostname som standard.

Tillagd i version 3.6.

ssl.PROTOCOL_TLS_SERVER

Autoförhandla den högsta protokollversionen som både klienten och servern stöder och konfigurera kontexten för anslutningar på serversidan.

Tillagd i version 3.6.

ssl.PROTOCOL_SSLv23

Alias för PROTOCOL_TLS.

Föråldrad sedan version 3.6: Använd PROTOCOL_TLS istället.

ssl.PROTOCOL_SSLv3

Väljer SSL version 3 som protokoll för kryptering av kanalen.

Detta protokoll är inte tillgängligt om OpenSSL kompileras med alternativet no-ssl3.

Varning

SSL version 3 är osäkert. Dess användning är starkt avrådd.

Föråldrad sedan version 3.6: OpenSSL har utgått från alla versionsspecifika protokoll. Använd standardprotokollet PROTOCOL_TLS_SERVER eller PROTOCOL_TLS_CLIENT med SSLContext.minimum_version och SSLContext.maximum_version istället.

ssl.PROTOCOL_TLSv1

Väljer TLS version 1.0 som krypteringsprotokoll för kanalen.

Föråldrad sedan version 3.6: OpenSSL har avskaffat alla versionsspecifika protokoll.

ssl.PROTOCOL_TLSv1_1

Väljer TLS version 1.1 som krypteringsprotokoll för kanalen. Endast tillgängligt med openssl version 1.0.1+.

Tillagd i version 3.4.

Föråldrad sedan version 3.6: OpenSSL har avskaffat alla versionsspecifika protokoll.

ssl.PROTOCOL_TLSv1_2

Väljer TLS version 1.2 som krypteringsprotokoll för kanalen. Endast tillgängligt med openssl version 1.0.1+.

Tillagd i version 3.4.

Föråldrad sedan version 3.6: OpenSSL har avskaffat alla versionsspecifika protokoll.

ssl.OP_ALL

Möjliggör lösningar för olika buggar som finns i andra SSL-implementeringar. Detta alternativ är inställt som standard. Det sätter inte nödvändigtvis samma flaggor som OpenSSL:s konstant SSL_OP_ALL.

Tillagd i version 3.2.

ssl.OP_NO_SSLv2

Förhindrar en SSLv2-anslutning. Detta alternativ är endast tillämpligt i kombination med PROTOCOL_TLS. Det hindrar motparterna från att välja SSLv2 som protokollversion.

Tillagd i version 3.2.

Föråldrad sedan version 3.6: SSLv2 är föråldrat

ssl.OP_NO_SSLv3

Förhindrar en SSLv3-anslutning. Detta alternativ är endast tillämpligt i kombination med PROTOCOL_TLS. Det hindrar motparterna från att välja SSLv3 som protokollversion.

Tillagd i version 3.2.

Föråldrad sedan version 3.6: SSLv3 är föråldrad

ssl.OP_NO_TLSv1

Förhindrar en TLSv1-anslutning. Detta alternativ är endast tillämpligt i kombination med PROTOCOL_TLS. Det hindrar peers från att välja TLSv1 som protokollversion.

Tillagd i version 3.2.

Föråldrad sedan version 3.7: Alternativet är föråldrat sedan OpenSSL 1.1.0, använd de nya SSLContext.minimum_version och SSLContext.maximum_version istället.

ssl.OP_NO_TLSv1_1

Förhindrar en TLSv1.1-anslutning. Detta alternativ är endast tillämpligt i kombination med PROTOCOL_TLS. Det hindrar motparterna från att välja TLSv1.1 som protokollversion. Endast tillgängligt med openssl version 1.0.1+.

Tillagd i version 3.4.

Föråldrad sedan version 3.7: Alternativet är föråldrat sedan OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_2

Förhindrar en TLSv1.2-anslutning. Detta alternativ är endast tillämpligt i kombination med PROTOCOL_TLS. Det hindrar motparterna från att välja TLSv1.2 som protokollversion. Endast tillgängligt med openssl version 1.0.1+.

Tillagd i version 3.4.

Föråldrad sedan version 3.7: Alternativet är föråldrat sedan OpenSSL 1.1.0.

ssl.OP_NO_TLSv1_3

Förhindrar en TLSv1.3-anslutning. Detta alternativ är endast tillämpligt i kombination med PROTOCOL_TLS. Det hindrar motparterna från att välja TLSv1.3 som protokollversion. TLS 1.3 är tillgängligt med OpenSSL 1.1.1 eller senare. När Python har kompilerats mot en äldre version av OpenSSL, är flaggan som standard 0.

Tillagd i version 3.6.3.

Föråldrad sedan version 3.7: Alternativet är föråldrat sedan OpenSSL 1.1.0. Det lades till i 2.7.15 och 3.6.3 för bakåtkompatibilitet med OpenSSL 1.0.2.

ssl.OP_NO_RENEGOTIATION

Inaktivera all omförhandling i TLSv1.2 och tidigare. Skicka inte HelloRequest-meddelanden och ignorera begäran om omförhandling via ClientHello.

Detta alternativ är endast tillgängligt med OpenSSL 1.1.0h och senare.

Tillagd i version 3.7.

ssl.OP_CIPHER_SERVER_PREFERENCE

Använd serverns preferens för chifferordning i stället för klientens. Det här alternativet har ingen effekt på klientsocklar och SSLv2-serversocklar.

Tillagd i version 3.3.

ssl.OP_SINGLE_DH_USE

Förhindrar återanvändning av samma DH-nyckel för olika SSL-sessioner. Detta förbättrar forward secrecy men kräver mer beräkningsresurser. Det här alternativet gäller endast för serveruttag.

Tillagd i version 3.3.

ssl.OP_SINGLE_ECDH_USE

Förhindrar återanvändning av samma ECDH-nyckel för olika SSL-sessioner. Detta förbättrar forward secrecy men kräver mer beräkningsresurser. Det här alternativet gäller endast för serveruttag.

Tillagd i version 3.3.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

Skicka falska CCS-meddelanden (Change Cipher Spec) i TLS 1.3-handskakningen för att få en TLS 1.3-anslutning att mer likna en TLS 1.2-anslutning.

Detta alternativ är endast tillgängligt med OpenSSL 1.1.1 och senare.

Tillagd i version 3.8.

ssl.OP_NO_COMPRESSION

Inaktivera komprimering på SSL-kanalen. Detta är användbart om applikationsprotokollet stöder sitt eget komprimeringsschema.

Tillagd i version 3.3.

class ssl.Options

enum.IntFlag samling av OP_*-konstanter.

ssl.OP_NO_TICKET

Förhindra klientsidan från att begära en sessionsbiljett.

Tillagd i version 3.6.

ssl.OP_IGNORE_UNEXPECTED_EOF

Ignorera oväntad avstängning av TLS-anslutningar.

Detta alternativ är endast tillgängligt med OpenSSL 3.0.0 och senare.

Tillagd i version 3.10.

ssl.OP_ENABLE_KTLS

Aktivera användning av TLS i kärnan. För att dra nytta av funktionen måste OpenSSL ha kompilerats med stöd för den, och de förhandlade chiffersviterna och tilläggen måste stödjas av den (en lista över de som stöds kan variera beroende på plattform och kärnversion).

Observera att med aktiverad TLS i kärnan utförs vissa kryptografiska operationer direkt av kärnan och inte via någon tillgänglig OpenSSL-provider. Detta kan vara oönskat om t.ex. applikationen kräver att alla kryptografiska operationer utförs av FIPS-providern.

Detta alternativ är endast tillgängligt med OpenSSL 3.0.0 och senare.

Tillagd i version 3.12.

ssl.OP_LEGACY_SERVER_CONNECT

Tillåt endast äldre, osäkra omförhandlingar mellan OpenSSL och servrar som inte är patchade.

Tillagd i version 3.12.

ssl.HAS_ALPN

Om OpenSSL-biblioteket har inbyggt stöd för TLS-tillägget Application-Layer Protocol Negotiation enligt beskrivningen i RFC 7301.

Tillagd i version 3.5.

ssl.HAS_NEVER_CHECK_COMMON_NAME

Om OpenSSL-biblioteket har inbyggt stöd för att inte kontrollera ämnets gemensamma namn och SSLContext.hostname_checks_common_name är skrivbart.

Tillagd i version 3.7.

ssl.HAS_ECDH

Om OpenSSL-biblioteket har inbyggt stöd för Diffie-Hellman-nyckelutbyte baserat på elliptiska kurvor. Detta bör vara sant om inte funktionen uttryckligen har inaktiverats av distributören.

Tillagd i version 3.3.

ssl.HAS_SNI

Om OpenSSL-biblioteket har inbyggt stöd för tillägget Server Name Indication (enligt definitionen i RFC 6066).

Tillagd i version 3.2.

ssl.HAS_NPN

Om OpenSSL-biblioteket har inbyggt stöd för Next Protocol Negotiation enligt beskrivningen i Application Layer Protocol Negotiation. När det är sant kan du använda metoden SSLContext.set_npn_protocols() för att annonsera vilka protokoll du vill stödja.

Tillagd i version 3.3.

ssl.HAS_SSLv2

Om OpenSSL-biblioteket har inbyggt stöd för SSL 2.0-protokollet.

Tillagd i version 3.7.

ssl.HAS_SSLv3

Om OpenSSL-biblioteket har inbyggt stöd för SSL 3.0-protokollet.

Tillagd i version 3.7.

ssl.HAS_TLSv1

Om OpenSSL-biblioteket har inbyggt stöd för TLS 1.0-protokollet.

Tillagd i version 3.7.

ssl.HAS_TLSv1_1

Om OpenSSL-biblioteket har inbyggt stöd för TLS 1.1-protokollet.

Tillagd i version 3.7.

ssl.HAS_TLSv1_2

Om OpenSSL-biblioteket har inbyggt stöd för TLS 1.2-protokollet.

Tillagd i version 3.7.

ssl.HAS_TLSv1_3

Om OpenSSL-biblioteket har inbyggt stöd för TLS 1.3-protokollet.

Tillagd i version 3.7.

ssl.HAS_PSK

Om OpenSSL-biblioteket har inbyggt stöd för TLS-PSK.

Tillagd i version 3.13.

ssl.HAS_PHA

Om OpenSSL-biblioteket har inbyggt stöd för TLS-PHA.

Tillagd i version 3.14.

ssl.CHANNEL_BINDING_TYPES

Lista över TLS-kanalbindningstyper som stöds. Strängar i den här listan kan användas som argument för SSLSocket.get_channel_binding().

Tillagd i version 3.3.

ssl.OPENSSL_VERSION

Versionssträngen för OpenSSL-biblioteket som läses in av tolken:

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'

Tillagd i version 3.2.

ssl.OPENSSL_VERSION_INFO

En tupel med fem heltal som representerar versionsinformation om OpenSSL-biblioteket:

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

Tillagd i version 3.2.

ssl.OPENSSL_VERSION_NUMBER

Det råa versionsnumret för OpenSSL-biblioteket, som ett enda heltal:

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

Tillagd i version 3.2.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
ssl.ALERT_DESCRIPTION_INTERNAL_ERROR
ALERT_DESCRIPTION_*

Varningsbeskrivningar från RFC 5246 och andra. Registret IANA TLS Alert Registry innehåller denna lista och referenser till de RFC:er där deras betydelse definieras.

Används som returvärde för callback-funktionen i SSLContext.set_servername_callback().

Tillagd i version 3.4.

class ssl.AlertDescription

enum.IntEnum samling av ALERT_DESCRIPTION_*-konstanter.

Tillagd i version 3.6.

Purpose.SERVER_AUTH

Alternativ för create_default_context() och SSLContext.load_default_certs(). Detta värde anger att kontexten kan användas för att autentisera webbservrar (därför kommer den att användas för att skapa sockets på klientsidan).

Tillagd i version 3.4.

Purpose.CLIENT_AUTH

Alternativ för create_default_context() och SSLContext.load_default_certs(). Detta värde indikerar att kontexten kan användas för att autentisera webbklienter (därför kommer den att användas för att skapa sockets på serversidan).

Tillagd i version 3.4.

class ssl.SSLErrorNumber

enum.IntEnum samling av SSL_ERROR_*-konstanter.

Tillagd i version 3.6.

class ssl.TLSVersion

enum.IntEnum samling av SSL- och TLS-versioner för SSLContext.maximum_version och SSLContext.minimum_version.

Tillagd i version 3.7.

TLSVersion.MINIMUM_SUPPORTED
TLSVersion.MAXIMUM_SUPPORTED

Den lägsta eller högsta SSL- eller TLS-versionen som stöds. Dessa är magiska konstanter. Deras värden återspeglar inte de lägsta och högsta tillgängliga TLS/SSL-versionerna.

TLSVersion.SSLv3
TLSVersion.TLSv1
TLSVersion.TLSv1_1
TLSVersion.TLSv1_2
TLSVersion.TLSv1_3

SSL 3.0 till TLS 1.3.

Föråldrad sedan version 3.10: Alla TLSVersion-medlemmar utom TLSVersion.TLSv1_2 och TLSVersion.TLSv1_3 är föråldrade.

SSL-uttag

class ssl.SSLSocket(socket.socket)

SSL-uttag tillhandahåller följande metoder för Socket-objekt:

Men eftersom SSL- (och TLS-) protokollet har sin egen inramning ovanpå TCP, kan abstraktionen för SSL-uttag i vissa avseenden avvika från specifikationen för normala uttag på OS-nivå. Se särskilt anmärkningar om icke-blockerande uttag.

Instanser av SSLSocket måste skapas med hjälp av SSLContext.wrap_socket()-metoden.

Ändrad i version 3.5: Metoden sendfile() lades till.

Ändrad i version 3.5: shutdown() nollställer inte socket timeout varje gång bytes tas emot eller skickas. Socket timeout är nu den maximala totala varaktigheten för avstängningen.

Föråldrad sedan version 3.6: Det är inte längre aktuellt att skapa en SSLSocket-instans direkt, använd SSLContext.wrap_socket() för att omsluta en socket.

Ändrad i version 3.7: SSLSocket-instanser måste skapas med wrap_socket(). I tidigare versioner var det möjligt att skapa instanser direkt. Detta var aldrig dokumenterat eller officiellt stöttat.

Ändrad i version 3.10: Python använder nu SSL_read_ex och SSL_write_ex internt. Funktionerna stöder läsning och skrivning av data som är större än 2 GB. Skrivning av noll-längdsdata misslyckas inte längre med ett protokollöverträdelsefel.

SSL-uttag har också följande ytterligare metoder och attribut:

SSLSocket.read(len=1024, buffer=None)

Läser upp till len byte data från SSL-socket och returnerar resultatet som en bytes-instans. Om buffer anges läses data in i bufferten i stället och antalet lästa byte returneras.

Utlös SSLWantReadError eller SSLWantWriteError om uttaget är icke-blockerande och läsningen skulle blockera.

Eftersom en omförhandling kan ske när som helst kan ett anrop till read() också orsaka skrivoperationer.

Ändrad i version 3.5: Timeouten för uttaget återställs inte längre varje gång byte tas emot eller skickas. Socket timeout är nu den maximala totala tiden det tar att läsa upp till len bytes.

Föråldrad sedan version 3.6: Använd recv() istället för read().

SSLSocket.write(buf)

Skriv buf till SSL-socket och returnera antalet byte som skrivits. Argumentet buf måste vara ett objekt som stöder buffertgränssnittet.

Utlös SSLWantReadError eller SSLWantWriteError om uttaget är non-blocking och skrivningen skulle blockera.

Eftersom en omförhandling kan ske när som helst kan ett anrop till write() också orsaka läsoperationer.

Ändrad i version 3.5: Timeout för socket nollställs inte längre varje gång byte tas emot eller skickas. Timeouten för uttaget är nu den maximala totala tiden det tar att skriva buf.

Föråldrad sedan version 3.6: Använd send() istället för write().

Anteckning

Metoderna read() och write() är lågnivåmetoder som läser och skriver okrypterade data på applikationsnivå och dekrypterar/krypterar dem till krypterade data på trådnivå. Dessa metoder kräver en aktiv SSL-anslutning, dvs. handskakningen har slutförts och SSLSocket.unwrap() har inte anropats.

Normalt bör du använda Socket API-metoder som recv() och send() istället för dessa metoder.

SSLSocket.do_handshake()

Utför handskakningen för SSL-installationen.

Ändrad i version 3.4: Handskakningsmetoden utför också match_hostname() när attributet check_hostname i socketens context är true.

Ändrad i version 3.5: Timeout för socket återställs inte längre varje gång byte tas emot eller skickas. Timeouten för uttaget är nu den maximala totala varaktigheten för handskakningen.

Ändrad i version 3.7: Värdnamn eller IP-adress matchas av OpenSSL under handskakning. Funktionen match_hostname() används inte längre. Om OpenSSL vägrar ett värdnamn eller en IP-adress avbryts handskakningen i förtid och ett TLS-varningsmeddelande skickas till motparten.

SSLSocket.getpeercert(binary_form=False)

Om det inte finns något certifikat för motparten i den andra änden av anslutningen returneras None. Om SSL-handskakningen inte har gjorts ännu, returneras ValueError.

Om parametern binary_form är False, och ett certifikat har mottagits från motparten, returnerar denna metod en dict-instans. Om certifikatet inte validerades är dict tomt. Om certifikatet validerades returneras en dict med flera nycklar, bland annat subject (den huvudman för vilken certifikatet utfärdades) och issuer (den huvudman som utfärdar certifikatet). Om ett certifikat innehåller en instans av tillägget Subject Alternative Name (se RFC 3280), kommer det också att finnas en nyckel subjectAltName i ordlistan.

Fälten subject och issuer är tupler som innehåller den sekvens av RDN (relative distinguished names) som anges i certifikatets datastruktur för respektive fält, och varje RDN är en sekvens av namn-värdepar. Här är ett exempel från den verkliga världen:

{'issuer': ((('countryName', 'IL'),),
            (('organizationName', 'StartCom Ltd.'),),
            (('organizationalUnitName',
              'Säker digital certifikatsignering'),),
            (('commonName',
              'StartCom Class 2 Primary Intermediate Server CA'),)),
 'notAfter': 'Nov 22 08:15:19 2013 GMT',
 'notBefore': 'Nov 21 03:09:52 2011 GMT',
 'serialNumber': '95F0',
 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'Kalifornien'),),
             (('localityName', 'San Francisco'),),
             (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
             (('commonName', '*.eff.org'),),
             (('emailAddress', 'hostmaster@eff.org')),)),
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
 'version': 3}

Om parametern binary_form är True` och ett certifikat har tillhandahållits, returnerar denna metod den DER-kodade formen av hela certifikatet som en sekvens av bytes, eller None om motparten inte har tillhandahållit något certifikat. Om motparten tillhandahåller ett certifikat beror på SSL-uttagets roll:

  • för ett SSL-uttag från en klient kommer servern alltid att tillhandahålla ett certifikat, oavsett om validering krävdes eller inte;

  • för ett SSL-uttag på en server kommer klienten endast att tillhandahålla ett certifikat när servern begär det; därför kommer getpeercert() att returnera None om du använde CERT_NONE (i stället för CERT_OPTIONAL eller CERT_REQUIRED).

Se även SSLContext.check_hostname.

Ändrad i version 3.2: Den returnerade ordlistan innehåller ytterligare objekt som issuer och notBefore.

Ändrad i version 3.4: ValueError utlöses när handskakningen inte är klar. Den returnerade ordlistan innehåller ytterligare X509v3-tilläggsobjekt såsom crlDistributionPoints, caIssuers och OCSP URI:er.

Ändrad i version 3.9: IPv6-adresssträngar har inte längre någon efterföljande ny rad.

SSLSocket.get_verified_chain()

Returnerar verifierad certifikatkedja som tillhandahålls av den andra änden av SSL-kanalen som en lista med DER-kodade byte. Om certifikatverifiering var inaktiverad fungerar metoden på samma sätt som get_unverified_chain().

Tillagd i version 3.13.

SSLSocket.get_unverified_chain()

Returnerar den råa certifikatkedjan som tillhandahålls av den andra änden av SSL-kanalen som en lista med DER-kodade byte.

Tillagd i version 3.13.

SSLSocket.cipher()

Returnerar en tupel med tre värden som innehåller namnet på det chiffer som används, den version av SSL-protokollet som definierar dess användning och antalet hemliga bitar som används. Om ingen anslutning har upprättats, returneras None.

SSLSocket.shared_ciphers()

Returnerar listan över chiffer som är tillgängliga i både klienten och servern. Varje post i den returnerade listan är en tupel med tre värden som innehåller namnet på chiffret, den version av SSL-protokollet som definierar dess användning och antalet hemliga bitar som chiffret använder. shared_ciphers() returnerar None om ingen anslutning har upprättats eller om uttaget är ett klientuttag.

Tillagd i version 3.5.

SSLSocket.compression()

Returnerar den komprimeringsalgoritm som används som en sträng, eller None om anslutningen inte komprimeras.

Om protokollet på högre nivå stöder sin egen komprimeringsmekanism kan du använda OP_NO_COMPRESSION för att inaktivera komprimering på SSL-nivå.

Tillagd i version 3.3.

SSLSocket.get_channel_binding(cb_type='tls-unique')

Hämta kanalbindningsdata för aktuell anslutning, som ett bytesobjekt. Returnerar None om ingen anslutning finns eller om handskakningen inte har slutförts.

Parametern cb_type gör det möjligt att välja önskad kanalbindningstyp. Giltiga kanalbindningstyper listas i listan CHANNEL_BINDING_TYPES. För närvarande stöds endast kanalbindningen ’tls-unique’, definierad av RFC 5929. ValueError kommer att uppstå om en kanalbindningstyp som inte stöds begärs.

Tillagd i version 3.3.

SSLSocket.selected_alpn_protocol()

Returnerar det protokoll som valdes under TLS-handskakningen. Om SSLContext.set_alpn_protocols() inte anropades, om den andra parten inte stöder ALPN, om detta uttag inte stöder något av klientens föreslagna protokoll, eller om handskakningen inte har skett ännu, returneras None.

Tillagd i version 3.5.

SSLSocket.selected_npn_protocol()

Returnerar det protokoll på högre nivå som valdes under TLS/SSL-handskakningen. Om SSLContext.set_npn_protocols() inte anropades, eller om den andra parten inte stöder NPN, eller om handskakningen ännu inte har skett, kommer detta att returnera None.

Tillagd i version 3.3.

Föråldrad sedan version 3.10: NPN har ersatts av ALPN

SSLSocket.unwrap()

Utför SSL-avstängningshandskakningen, som tar bort TLS-lagret från det underliggande uttaget, och returnerar det underliggande uttagsobjektet. Detta kan användas för att gå från krypterad drift över en anslutning till okrypterad. Det returnerade uttaget bör alltid användas för vidare kommunikation med den andra sidan av anslutningen, snarare än det ursprungliga uttaget.

SSLSocket.verify_client_post_handshake()

Begär PHA (post-handshake authentication) från en TLS 1.3-klient. PHA kan endast initieras för en TLS 1.3-anslutning från ett server-sidesockel, efter den inledande TLS-handskakningen och med PHA aktiverat på båda sidor, se SSLContext.post_handshake_auth.

Metoden utför inte ett cert-utbyte omedelbart. Serversidan skickar en CertificateRequest vid nästa skrivhändelse och förväntar sig att klienten svarar med ett certifikat vid nästa läshändelse.

Om något förhandsvillkor inte uppfylls (t.ex. inte TLS 1.3, PHA inte aktiverat), utlöses ett SSLError.

Anteckning

Endast tillgänglig med OpenSSL 1.1.1 och TLS 1.3 aktiverat. Utan stöd för TLS 1.3 ger metoden upphov till NotImplementedError.

Tillagd i version 3.8.

SSLSocket.version()

Returnerar den faktiska SSL-protokollversionen som förhandlats fram av anslutningen som en sträng, eller None om ingen säker anslutning upprättas. I skrivande stund inkluderar möjliga returvärden "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" och "TLSv1.2". Nyare OpenSSL-versioner kan definiera fler returvärden.

Tillagd i version 3.5.

SSLSocket.pending()

Returnerar antalet redan dekrypterade bytes som är tillgängliga för läsning, i väntan på anslutningen.

SSLSocket.context

Det SSLContext-objekt som detta SSL-uttag är knutet till.

Tillagd i version 3.2.

SSLSocket.server_side

En boolean som är True för server-sidans uttag och False för klient-sidans uttag.

Tillagd i version 3.2.

SSLSocket.server_hostname

Värdnamn för servern: str-typ, eller None för server-side socket eller om värdnamnet inte angavs i konstruktören.

Tillagd i version 3.2.

Ändrad i version 3.7: Attributet är nu alltid ASCII-text. När server_hostname är ett internationaliserat domännamn (IDN) lagrar detta attribut nu A-märkningsformen ("xn--pythn-mua.org") i stället för U-märkningsformen ("pythön.org").

SSLSocket.session

SSLSession för denna SSL-anslutning. Sessionen är tillgänglig för uttag på klient- och serversidan efter att TLS-handskakningen har utförts. För klientuttag kan sessionen ställas in innan do_handshake() har anropats för att återanvända en session.

Tillagd i version 3.6.

SSLSocket.session_reused

Tillagd i version 3.6.

SSL-kontexter

Tillagd i version 3.2.

En SSL-kontext innehåller olika data som är mer långlivade än enskilda SSL-anslutningar, t.ex. SSL-konfigurationsalternativ, certifikat och privata nycklar. Den hanterar också en cache för SSL-sessioner för uttag på serversidan, för att snabba upp upprepade anslutningar från samma klienter.

class ssl.SSLContext(protocol=None)

Skapa en ny SSL-kontext. Du kan skicka protocol som måste vara en av PROTOCOL_*-konstanterna som definieras i den här modulen. Parametern anger vilken version av SSL-protokollet som ska användas. Vanligtvis väljer servern en viss protokollversion och klienten måste anpassa sig till serverns val. De flesta av versionerna är inte kompatibla med andra versioner. Om inget anges är standardvärdet PROTOCOL_TLS; det ger störst kompatibilitet med andra versioner.

Här är en tabell som visar vilka versioner i en klient (längst ned på sidan) som kan ansluta till vilka versioner i en server (längst upp):

klient / server

SSLv2

SSLv3

TLS [3] _TLS

TLSv1

TLSv1.1

TLSv1.2

SSLv2

ja

nej

no [1]

nej

nej

nej

SSLv3

nej

ja

no [2]

nej

nej

nej

TLS (SSLv23) [3]

no [1]

no [2]

ja

ja

ja

ja

TLSv1

nej

nej

ja

ja

nej

nej

TLSv1.1

nej

nej

ja

nej

ja

nej

TLSv1.2

nej

nej

ja

nej

nej

ja

Fotnoter

Se även

create_default_context() låter ssl-modulen välja säkerhetsinställningar för ett visst syfte.

Ändrad i version 3.6: Kontexten skapas med säkra standardvärden. Alternativen OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2 och OP_NO_SSLv3 (utom för PROTOCOL_SSLv3) anges som standard. Den ursprungliga listan över chiffersviter innehåller endast chiffer av typen HIGH, inga chiffer av typen NULL och inga chiffer av typen MD5.

Föråldrad sedan version 3.10: SSLContext utan protokollargument är föråldrad. Kontextklassen kommer antingen att kräva PROTOCOL_TLS_CLIENT eller PROTOCOL_TLS_SERVER protokoll i framtiden.

Ändrad i version 3.10: Standardchiffersviterna innehåller nu endast säkra AES- och ChaCha20-chiffer med forward secrecy och säkerhetsnivå 2. RSA- och DH-nycklar med mindre än 2048 bitar och ECC-nycklar med mindre än 224 bitar är förbjudna. PROTOCOL_TLS, PROTOCOL_TLS_CLIENT, och PROTOCOL_TLS_SERVER använder TLS 1.2 som minsta TLS-version.

Anteckning

SSLContext stöder endast begränsad mutation när den har använts av en anslutning. Det är tillåtet att lägga till nya certifikat i det interna förtroendearkivet, men att ändra chiffer, verifieringsinställningar eller mTLS-certifikat kan resultera i överraskande beteende.

Anteckning

SSLContext är utformad för att delas och användas av flera anslutningar. Den är alltså trådsäker så länge den inte konfigureras om efter att ha använts av en anslutning.

SSLContext-objekt har följande metoder och attribut:

SSLContext.cert_store_stats()

Hämta statistik över antal laddade X.509-certifikat, antal X.509-certifikat som markerats som CA-certifikat och spärrlistor som ordlista.

Exempel för en kontext med ett CA-cert och ett annat cert:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

Tillagd i version 3.4.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)

Läser in en privat nyckel och motsvarande certifikat. Strängen certfile måste vara sökvägen till en enda fil i PEM-format som innehåller certifikatet samt valfritt antal CA-certifikat som behövs för att fastställa certifikatets äkthet. Strängen keyfile måste, om den finns, peka på en fil som innehåller den privata nyckeln. I annat fall hämtas den privata nyckeln även från certfile. Se diskussionen i Diplom för mer information om hur certifikatet lagras i certfile.

Argumentet password kan vara en funktion som ska anropas för att få lösenordet för dekryptering av den privata nyckeln. Funktionen anropas endast om den privata nyckeln är krypterad och ett lösenord är nödvändigt. Den anropas utan argument och ska returnera en sträng, bytes eller bytearray. Om returvärdet är en sträng kommer den att kodas som UTF-8 innan den används för att dekryptera nyckeln. Alternativt kan ett värde i form av en sträng, bytes eller bytearray anges direkt som argument för password. Det ignoreras om den privata nyckeln inte är krypterad och inget lösenord behövs.

Om argumentet password inte anges och ett lösenord krävs, kommer OpenSSL:s inbyggda mekanism för lösenordsuppmaning att användas för att interaktivt uppmana användaren att ange ett lösenord.

Ett SSLError uppstår om den privata nyckeln inte stämmer överens med certifikatet.

Ändrad i version 3.3: Nytt valfritt argument password.

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

Ladda en uppsättning standardcertifikat för ”certifikatutfärdare” (CA) från standardplatser. I Windows laddas CA-certifikat från systemlagren CA och ROOT. På alla system anropar den SSLContext.set_default_verify_paths(). I framtiden kan metoden komma att ladda CA-certifikat från andra platser också.

Flaggan purpose anger vilken typ av CA-certifikat som läses in. Standardinställningarna Purpose.SERVER_AUTH laddar certifikat som är flaggade och betrodda för TLS-autentisering av webbservern (sockets på klientsidan). Purpose.CLIENT_AUTH laddar CA-certifikat för verifiering av klientcertifikat på serversidan.

Tillagd i version 3.4.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)

Läser in en uppsättning certifikat från ”Certification Authority” (CA) som används för att validera andra peers certifikat när verify_mode är något annat än CERT_NONE. Åtminstone en av cafile eller capath måste anges.

Den här metoden kan också läsa in CRL:er (Certification Revocation List) i PEM- eller DER-format. För att kunna använda CRL:er måste SSLContext.verify_flags vara korrekt konfigurerad.

Strängen cafile, om den finns, är sökvägen till en fil med sammanlänkade certifikat från certifikatutfärdare i PEM-format. Se diskussionen om Diplom för mer information om hur du ordnar certifikaten i den här filen.

Strängen capath, om den finns, är sökvägen till en katalog som innehåller flera CA-certifikat i PEM-format, enligt en OpenSSL-specifik layout.

Objektet cadata, om det finns, är antingen en ASCII-sträng med ett eller flera PEM-kodade certifikat eller ett bytesliknande objekt med DER-kodade certifikat. Precis som med capath ignoreras extra rader runt PEM-kodade certifikat, men minst ett certifikat måste finnas med.

Ändrad i version 3.4: Nytt valfritt argument cadata

SSLContext.get_ca_certs(binary_form=False)

Hämta en lista med laddade certifikat från certifikatutfärdare (CA). Om parametern binary_form är False` är varje post i listan en dikt som utdata från SSLSocket.getpeercert(). Annars returnerar metoden en lista med DER-kodade certifikat. Den returnerade listan innehåller inte certifikat från capath om inte ett certifikat begärdes och laddades av en SSL-anslutning.

Anteckning

Certifikat i en capath-katalog läses inte in om de inte har använts minst en gång.

Tillagd i version 3.4.

SSLContext.get_ciphers()

Hämta en lista över aktiverade chiffer. Listan är i ordning efter chifferprioritet. Se SSLContext.set_ciphers().

Exempel:

>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()
[{'aead': True,
  'alg_bits': 256,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'digest': None,
  'id': 50380848,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'},
 {'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'}]

Tillagd i version 3.6.

SSLContext.set_default_verify_paths()

Ladda en uppsättning standardcertifikat från en certifikatutfärdare (CA) från en filsystemssökväg som definieras när OpenSSL-biblioteket byggs. Tyvärr finns det inget enkelt sätt att veta om den här metoden lyckas: inget fel returneras om inga certifikat hittas. När OpenSSL-biblioteket tillhandahålls som en del av operativsystemet är det dock troligt att det är korrekt konfigurerat.

SSLContext.set_ciphers(ciphers)

Ange tillgängliga chiffer för uttag som skapats med detta sammanhang. Det bör vara en sträng i formatet OpenSSL cipher list. Om inget chiffer kan väljas (eftersom kompileringstidsalternativ eller annan konfiguration förbjuder användning av alla angivna chiffer), kommer ett SSLError att uppstå.

Anteckning

när du är ansluten kommer SSLSocket.cipher()-metoden för SSL-uttag att ge det aktuella valda chiffret.

TLS 1.3-chiffersviter kan inte inaktiveras med set_ciphers().

SSLContext.set_alpn_protocols(protocols)

Ange vilka protokoll som uttaget ska annonsera under SSL/TLS-handskakningen. Det bör vara en lista med ASCII-strängar, som ['http/1.1', 'spdy/2'], ordnade efter preferens. Valet av protokoll kommer att ske under handskakningen, och kommer att ske enligt RFC 7301. Efter en lyckad handskakning kommer metoden SSLSocket.selected_alpn_protocol() att returnera det överenskomna protokollet.

Denna metod ger upphov till NotImplementedError om HAS_ALPN är False.

Tillagd i version 3.5.

SSLContext.set_npn_protocols(protocols)

Ange vilka protokoll som uttaget ska annonsera under SSL/TLS-handskakningen. Det bör vara en lista med strängar, till exempel ['http/1.1', 'spdy/2'], ordnade efter preferens. Valet av protokoll kommer att ske under handskakningen och kommer att ske i enlighet med Application Layer Protocol Negotiation. Efter en lyckad handskakning kommer metoden SSLSocket.selected_npn_protocol() att returnera det överenskomna protokollet.

Denna metod ger upphov till NotImplementedError om HAS_NPN är False.

Tillagd i version 3.3.

Föråldrad sedan version 3.10: NPN har ersatts av ALPN

SSLContext.sni_callback

Registrera en återuppringningsfunktion som kommer att anropas efter att handskakningsmeddelandet TLS Client Hello har mottagits av SSL/TLS-servern när TLS-klienten anger en servernamnindikation. Mekanismen för indikering av servernamn specificeras i RFC 6066 avsnitt 3 - Server Name Indication.

Endast en återuppringning kan ställas in per SSLContext. Om sni_callback är inställd på None inaktiveras återuppringningen. Anrop av denna funktion en senare gång inaktiverar den tidigare registrerade återuppringningen.

Callback-funktionen anropas med tre argument; det första är ssl.SSLSocket, det andra är en sträng som representerar det servernamn som klienten avser att kommunicera med (eller None om TLS Client Hello inte innehåller något servernamn) och det tredje argumentet är det ursprungliga SSLContext. Argumentet för servernamnet är text. För internationaliserade domännamn är servernamnet en IDN A-label ("xn--pythn-mua.org").

En typisk användning av denna callback är att ändra ssl.SSLSocketSSLSocket.context-attributet till ett nytt objekt av typen SSLContext som representerar en certifikatkedja som matchar servernamnet.

På grund av den tidiga förhandlingsfasen i TLS-anslutningen är endast begränsade metoder och attribut användbara, t.ex. SSLSocket.selected_alpn_protocol() och SSLSocket.context. Metoderna SSLSocket.getpeercert(), SSLSocket.get_verified_chain(), SSLSocket.get_unverified_chain() SSLSocket.cipher() och SSLSocket.compression() kräver att TLS-anslutningen har kommit längre än TLS Client Hello och returnerar därför inte meningsfulla värden och kan inte anropas på ett säkert sätt.

Funktionen sni_callback måste returnera None för att TLS-förhandlingen ska kunna fortsätta. Om ett TLS-fel krävs kan en konstant ALERT_DESCRIPTION_* returneras. Andra returvärden kommer att resultera i ett TLS-fatal error med ALERT_DESCRIPTION_INTERNAL_ERROR.

Om ett undantag uppstår från funktionen sni_callback kommer TLS-anslutningen att avslutas med ett TLS-varningsmeddelande ALERT_DESCRIPTION_HANDSHAKE_FAILURE.

Denna metod kommer att ge upphov till NotImplementedError om OpenSSL-biblioteket hade OPENSSL_NO_TLSEXT definierat när det byggdes.

Tillagd i version 3.7.

SSLContext.set_servername_callback(server_name_callback)

Detta är ett äldre API som behålls för bakåtkompatibilitet. När det är möjligt bör du använda sni_callback istället. Den givna server_name_callback liknar sni_callback, förutom att när serverns värdnamn är ett IDN-kodat internationaliserat domännamn, får server_name_callback en avkodad U-etikett ("pythön.org").

Om det finns ett avkodningsfel på servernamnet kommer TLS-anslutningen att avslutas med ett ALERT_DESCRIPTION_INTERNAL_ERROR fatalt TLS-varningsmeddelande till klienten.

Tillagd i version 3.4.

SSLContext.load_dh_params(dhfile)

Ladda parametrarna för nyckelgenerering för Diffie-Hellman (DH)-nyckelutbyte. Genom att använda DH-nyckelutbyte förbättras forward secrecy på bekostnad av beräkningsresurser (både på servern och på klienten). Parametern dhfile ska vara sökvägen till en fil som innehåller DH-parametrar i PEM-format.

Den här inställningen gäller inte för klientsocklar. Du kan också använda alternativet OP_SINGLE_DH_USE för att ytterligare förbättra säkerheten.

Tillagd i version 3.3.

SSLContext.set_ecdh_curve(curve_name)

Ange kurvans namn för ECDH-nyckelutbyte (Elliptic Curve-based Diffie-Hellman). ECDH är betydligt snabbare än vanlig DH, men förmodligen lika säkert. Parametern curve_name ska vara en sträng som beskriver en välkänd elliptisk kurva, t.ex. prime256v1 för en kurva med brett stöd.

Den här inställningen gäller inte för klientsocklar. Du kan också använda alternativet OP_SINGLE_ECDH_USE för att ytterligare förbättra säkerheten.

Denna metod är inte tillgänglig om HAS_ECDH är False.

Tillagd i version 3.3.

Se även

SSL/TLS & Perfect Forward Secrecy

Vincent Bernat.

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)

Omfattar en befintlig Python-socket sock och returnerar en instans av SSLContext.sslsocket_class (standard SSLSocket). Det returnerade SSL-uttaget är knutet till kontexten, dess inställningar och certifikat. sock måste vara ett SOCK_STREAM-uttag; andra uttagstyper stöds inte.

Parametern server_side är en boolean som anger om det är server- eller klientsidans beteende som önskas från detta uttag.

För uttag på klientsidan är kontextkonstruktionen lat; om det underliggande uttaget inte är anslutet ännu kommer kontextkonstruktionen att utföras efter att connect() anropas på uttaget. För uttag på serversidan, om uttaget inte har någon fjärrpeer, antas det vara ett lyssnande uttag, och SSL-omslaget på serversidan utförs automatiskt på klientanslutningar som accepteras via metoden accept(). Metoden kan ge upphov till SSLError.

Vid klientanslutningar anger den valfria parametern server_hostname värdnamnet på den tjänst som vi ansluter till. Detta gör att en enda server kan vara värd för flera SSL-baserade tjänster med olika certifikat, på liknande sätt som virtuella HTTP-värdar. Om server_hostname anges kommer ett ValueError att uppstå om server_side är true.

Parametern do_handshake_on_connect anger om SSL-handskakningen ska göras automatiskt efter en socket.connect(), eller om applikationsprogrammet ska göra det explicit genom att anropa metoden SSLSocket.do_handshake(). Genom att anropa SSLSocket.do_handshake() explicit får programmet kontroll över blockeringsbeteendet för socket I/O som är involverat i handskakningen.

Parametern suppress_ragged_eofs anger hur metoden SSLSocket.recv() ska signalera oväntade EOF från den andra änden av anslutningen. Om den anges som True (standard) returnerar den en normal EOF (ett tomt bytesobjekt) som svar på oväntade EOF-fel från den underliggande sockeln; om den anges som False returneras undantagen tillbaka till anroparen.

session, se session.

För att linda in en SSLSocket i en annan SSLSocket, använd SSLContext.wrap_bio().

Ändrad i version 3.5: Tillåt alltid att ett server_hostname skickas med, även om OpenSSL inte har SNI.

Ändrad i version 3.6: session-argumentet har lagts till.

Ändrad i version 3.7: Metoden returnerar en instans av SSLContext.sslsocket_class istället för hårdkodad SSLSocket.

SSLContext.sslsocket_class

Returtyp för SSLContext.wrap_socket(), standard är SSLSocket. Attributet kan åsidosättas på en instans av class för att returnera en anpassad underklass av SSLSocket.

Tillagd i version 3.7.

SSLContext.wrap_bio(incoming, outgoing, server_side=False, server_hostname=None, session=None)

Packa in BIO-objekten incoming och outgoing och returnera en instans av SSLContext.sslobject_class (standard SSLObject). SSL-rutinerna läser inmatningsdata från det inkommande BIO-objektet och skriver data till det utgående BIO-objektet.

Parametrarna server_side, server_hostname och session har samma betydelse som i SSLContext.wrap_socket().

Ändrad i version 3.6: session-argumentet har lagts till.

Ändrad i version 3.7: Metoden returnerar en instans av SSLContext.sslobject_class istället för hårdkodad SSLObject.

SSLContext.sslobject_class

Returtyp för SSLContext.wrap_bio(), standard är SSLObject. Attributet kan åsidosättas på en instans av class för att returnera en anpassad underklass av SSLObject.

Tillagd i version 3.7.

SSLContext.session_stats()

Hämta statistik om de SSL-sessioner som skapats eller hanterats av detta sammanhang. En ordbok returneras som mappar namnen på varje informationsdel till deras numeriska värden. Här visas t.ex. det totala antalet träffar och missar i sessionscachen sedan kontexten skapades:

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)
SSLContext.check_hostname

Huruvida peer-certifikatets värdnamn ska matchas i SSLSocket.do_handshake(). Kontextens verify_mode måste vara inställd på CERT_OPTIONAL eller CERT_REQUIRED, och du måste skicka server_hostname till wrap_socket() för att matcha värdnamnet. Om du aktiverar kontroll av värdnamn ställs verify_mode automatiskt in från CERT_NONE till CERT_REQUIRED. Det kan inte sättas tillbaka till CERT_NONE så länge värdnamnskontrollen är aktiverad. Protokollet PROTOCOL_TLS_CLIENT aktiverar värdnamnskontroll som standard. Med andra protokoll måste värdnamnskontroll aktiveras uttryckligen.

Exempel:

import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))

Tillagd i version 3.4.

Ändrad i version 3.7: verify_mode ändras nu automatiskt till CERT_REQUIRED när kontroll av värdnamn är aktiverat och verify_mode är CERT_NONE. Tidigare skulle samma operation ha misslyckats med ett ValueError.

SSLContext.keylog_filename

Skriv TLS-nycklar till en keylog-fil när nyckelmaterial genereras eller tas emot. Keylog-filen är endast avsedd för felsökningsändamål. Filformatet specificeras av NSS och används av många trafikanalysatorer, t.ex. Wireshark. Loggfilen öppnas i append-only-läge. Skrivningar synkroniseras mellan trådar, men inte mellan processer.

Tillagd i version 3.8.

SSLContext.maximum_version

En TLSVersion enum-medlem som representerar den högsta TLS-versionen som stöds. Standardvärdet är TLSVersion.MAXIMUM_SUPPORTED. Attributet är skrivskyddat för andra protokoll än PROTOCOL_TLS, PROTOCOL_TLS_CLIENT och PROTOCOL_TLS_SERVER.

Attributen maximum_version, minimum_version och SSLContext.options påverkar alla de SSL- och TLS-versioner som stöds av kontexten. Implementationen förhindrar inte ogiltiga kombinationer. Till exempel kommer en kontext med OP_NO_TLSv1_2 i options och maximum_version satt till TLSVersion.TLSv1_2 inte att kunna upprätta en TLS 1.2-anslutning.

Tillagd i version 3.7.

SSLContext.minimum_version

Som SSLContext.maximum_version förutom att det är den lägsta versionen som stöds eller TLSVersion.MINIMUM_SUPPORTED.

Tillagd i version 3.7.

SSLContext.num_tickets

Styr antalet TLS 1.3-sessionsbiljetter för en PROTOCOL_TLS_SERVER-kontext. Inställningen har ingen inverkan på TLS 1.0 till 1.2-anslutningar.

Tillagd i version 3.8.

SSLContext.options

Ett heltal som representerar den uppsättning SSL-alternativ som är aktiverade i detta sammanhang. Standardvärdet är OP_ALL, men du kan ange andra alternativ som t.ex. OP_NO_SSLv2 genom att sätta ihop dem med OR.

Ändrad i version 3.6: SSLContext.options returnerar Options flaggor:

>>> ssl.create_default_context().options
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

Föråldrad sedan version 3.7: Alla OP_NO_SSL* och OP_NO_TLS* alternativ har blivit föråldrade sedan Python 3.7. Använd SSLContext.minimum_version och SSLContext.maximum_version istället.

SSLContext.post_handshake_auth

Aktivera TLS 1.3-klientautentisering efter handskakning. Autentisering efter handskakning är inaktiverad som standard och en server kan bara begära ett TLS-klientcertifikat under den inledande handskakningen. När den är aktiverad kan en server begära ett TLS-klientcertifikat när som helst efter handskakningen.

När den är aktiverad på sockets på klientsidan signalerar klienten till servern att den stöder autentisering efter handskakning.

När det är aktiverat på server-sidans socklar måste SSLContext.verify_mode också vara inställt på CERT_OPTIONAL eller CERT_REQUIRED. Det faktiska utbytet av klientcertifikat fördröjs tills SSLSocket.verify_client_post_handshake() anropas och vissa I/O utförs.

Tillagd i version 3.8.

SSLContext.protocol

Den protokollversion som valdes när kontexten konstruerades. Detta attribut är skrivskyddat.

SSLContext.hostname_checks_common_name

Om check_hostname faller tillbaka för att verifiera certets gemensamma ämnesnamn i avsaknad av ett alternativt ämnesnamnstillägg (standard: true).

Tillagd i version 3.7.

Ändrad i version 3.10: Flaggan hade ingen effekt med OpenSSL före version 1.1.1l. Python 3.8.9, 3.9.3 och 3.10 innehåller lösningar för tidigare versioner.

SSLContext.security_level

Ett heltal som representerar säkerhetsnivån för kontexten. Detta attribut är skrivskyddat.

Tillagd i version 3.10.

SSLContext.verify_flags

Flaggorna för verifiering av certifikat. Du kan ange flaggor som VERIFY_CRL_CHECK_LEAF genom att sätta ihop dem med OR. Som standard varken kräver eller verifierar OpenSSL återkallningslistor för certifikat (CRL).

Tillagd i version 3.4.

Ändrad i version 3.6: SSLContext.verify_flags returnerar VerifyFlags flaggor:

>>> ssl.create_default_context().verify_flags
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>
SSLContext.verify_mode

Om man ska försöka verifiera andra peers certifikat och hur man ska agera om verifieringen misslyckas. Detta attribut måste vara ett av CERT_NONE, CERT_OPTIONAL eller CERT_REQUIRED.

Ändrad i version 3.6: SSLContext.verify_mode returnerar VerifyMode enum:

>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>
SSLContext.set_psk_client_callback(callback)

Aktiverar TLS-PSK-autentisering (pre-shared key) på en anslutning på klientsidan.

I allmänhet bör certifikatbaserad autentisering föredras framför denna metod.

Parametern callback är ett anropbart objekt med signaturen: def callback(hint: str | None) -> tuple[str | None, bytes]. Parametern hint är en valfri identitetshint som skickas av servern. Returvärdet är en tupel i formen (client-identity, psk). Client-identity är en valfri sträng som kan användas av servern för att välja en motsvarande PSK för klienten. Strängen måste vara mindre än eller lika med 256 oktetter när den är UTF-8-kodad. PSK är ett bytesliknande objekt som representerar den fördelade nyckeln. Returnera en PSK med längden noll för att avvisa anslutningen.

Om callback sätts till None tas alla befintliga callbacks bort.

Anteckning

När du använder TLS 1.3:

  • parametern hint är alltid None.

  • client-identity måste vara en icke-tom sträng.

Exempel på användning:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# En enkel lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_client_callback(lambda hint: (None, psk))

# En tabell med hjälp av ledtråden från servern:
psk_table = { 'ServerId_1': bytes.fromhex('c0ffee'),
              'ServerId_2': bytes.fromhex('fasad')
}
def återuppringning(hint):
    return 'ClientId_1', psk_table.get(hint, b'')
context.set_psk_client_callback(callback)

Denna metod ger upphov till NotImplementedError om HAS_PSK är False.

Tillagd i version 3.13.

SSLContext.set_psk_server_callback(callback, identity_hint=None)

Aktiverar TLS-PSK-autentisering (pre-shared key) för en anslutning på serversidan.

I allmänhet bör certifikatbaserad autentisering föredras framför denna metod.

Parametern callback är ett anropbart objekt med signaturen: def callback(identity: str | None) -> bytes. Parametern identity är en valfri identitet som skickas av klienten och som kan användas för att välja en motsvarande PSK. Returvärdet är ett bytesliknande objekt som representerar den fördelade nyckeln. Returnera en PSK med noll längd för att avvisa anslutningen.

Om callback sätts till None tas alla befintliga callbacks bort.

Parametern identity_hint är en valfri identitetshintsträng som skickas till klienten. Strängen måste vara mindre än eller lika med 256 oktetter när den är UTF-8-kodad.

Anteckning

Vid användning av TLS 1.3 skickas inte parametern identity_hint till klienten.

Exempel på användning:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# En enkel lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_server_callback(lambda identitet: psk)

# En tabell som använder klientens identitet:
psk_table = { 'ClientId_1': bytes.fromhex('c0ffee'),
              'ClientId_2': bytes.fromhex('facade')
}
def callback(identitet):
    return psk_table.get(identitet, b'')
context.set_psk_server_callback(callback, 'ServerId_1')

Denna metod ger upphov till NotImplementedError om HAS_PSK är False.

Tillagd i version 3.13.

Diplom

Certifikat är i allmänhet en del av ett system med offentliga nycklar och privata nycklar. I detta system tilldelas varje principal (som kan vara en maskin, en person eller en organisation) en unik krypteringsnyckel i två delar. Den ena delen av nyckeln är offentlig och kallas public key; den andra delen hålls hemlig och kallas private key. De två delarna är relaterade på så sätt att om man krypterar ett meddelande med den ena delen kan man dekryptera det med den andra delen, och endast med den andra delen.

Ett certifikat innehåller information om två huvudmän. Det innehåller namnet på en subjekt och subjektets publika nyckel. Det innehåller också ett uttalande från en andra huvudman, utfärdaren, om att subjektet är den hen utger sig för att vara och att detta verkligen är subjektets publika nyckel. Utfärdarens uttalande är signerat med utfärdarens privata nyckel, som endast utfärdaren känner till. Vem som helst kan dock verifiera utfärdarens uttalande genom att hitta utfärdarens publika nyckel, dekryptera uttalandet med den och jämföra det med den övriga informationen i certifikatet. Certifikatet innehåller också information om den tidsperiod under vilken det är giltigt. Detta uttrycks som två fält, kallade ”notBefore” och ”notAfter”.

I Python-användningen av certifikat kan en klient eller server använda ett certifikat för att bevisa vem de är. Den andra sidan av en nätverksanslutning kan också krävas på ett certifikat, och det certifikatet kan valideras på ett sätt som tillfredsställer den klient eller server som kräver sådan validering. Anslutningsförsöket kan ställas in så att ett undantag utlöses om valideringen misslyckas. Valideringen görs automatiskt av det underliggande OpenSSL-ramverket och applikationen behöver inte bekymra sig om hur det fungerar. Men applikationen behöver vanligtvis tillhandahålla uppsättningar av certifikat för att denna process ska kunna äga rum.

Python använder filer för att innehålla certifikat. De bör formateras som ”PEM” (se RFC 1422), vilket är en bas-64-kodad form omsluten av en rubrikrad och en sidfot:

-----BEGIN CERTIFIKAT-----
... (certifikat i base64 PEM-kodning) ...
-----SLUTA CERTIFIKAT-----

Certifikatkedjor

De Python-filer som innehåller certifikat kan innehålla en sekvens av certifikat, ibland kallad en certifikatkedja. Denna kedja bör börja med det specifika certifikatet för den principal som ”är” klienten eller servern, och sedan certifikatet för utfärdaren av det certifikatet, och sedan certifikatet för utfärdaren av det certifikatet, och så vidare upp i kedjan tills man kommer till ett certifikat som är självsignerat, det vill säga ett certifikat som har samma subject och utfärdare, ibland kallat ett rotcertifikat. Certifikaten ska bara sammankopplas i certifikatfilen. Anta till exempel att vi har en kedja med tre certifikat, från vårt servercertifikat till certifikatet för den certifikatutfärdare som signerade vårt servercertifikat, till rotcertifikatet för den myndighet som utfärdade certifikatutfärdarens certifikat:

-----BÖRJA CERTIFIKAT-----
... (certifikat för din server) ...
-----AVSLUTA CERTIFIKAT-----
-----BÖRJAR CERTIFIKAT-----
... (certifikatet för CA) ...
-----AVSLUTA CERTIFIKAT-----
-----BÖRJAR CERTIFIKAT-----
... (rotcertifikatet för CA:s utfärdare)...
-----AVSLUTA CERTIFIKAT-----

CA-certifikat

Om du ska kräva validering av den andra sidan av anslutningens certifikat måste du tillhandahålla en ”CA certs”-fil, fylld med certifikatkedjorna för varje utfärdare som du är villig att lita på. Återigen innehåller den här filen bara dessa kedjor sammankopplade tillsammans. För validering kommer Python att använda den första kedjan som den hittar i filen som matchar. Plattformens certifikatfil kan användas genom att anropa SSLContext.load_default_certs(), detta görs automatiskt med create_default_context().

Kombinerad nyckel och certifikat

Ofta lagras den privata nyckeln i samma fil som certifikatet; i detta fall behöver endast parametern certfile till SSLContext.load_cert_chain() skickas. Om den privata nyckeln lagras med certifikatet bör den komma före det första certifikatet i certifikatkedjan:

-----BEGIN RSA PRIVAT NYCKEL-----
... (privat nyckel i base64-kodning) ...
-----AVSLUTA RSA PRIVAT NYCKEL-----
-----BEGIN CERTIFIKAT-----
... (certifikat i base64 PEM-kodning) ...
-----AVSLUTA CERTIFIKAT-----

Självsignerade certifikat

Om du ska skapa en server som tillhandahåller SSL-krypterade anslutningstjänster måste du skaffa ett certifikat för den tjänsten. Det finns många sätt att skaffa lämpliga certifikat, t.ex. genom att köpa ett från en certifikatutfärdare. Ett annat vanligt sätt är att skapa ett självsignerat certifikat. Det enklaste sättet att göra detta är med OpenSSL-paketet, genom att använda något i stil med följande:

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generera en 1024 bitars RSA privat nyckel
.......++++++
.............................++++++
skriver ny privat nyckel till 'cert.pem'
-----
Du kommer nu att bli ombedd att ange information som kommer att ingå
i din certifikatbegäran.
Det du ska ange är vad som kallas ett Distinguished Name eller en DN.
Det finns ganska många fält, men du kan lämna vissa tomma
För vissa fält finns det ett standardvärde,
Om du anger '.' lämnas fältet tomt.
-----
Landsnamn (2-bokstavskod) [AU]:US
Delstatens eller provinsens namn (fullständigt namn) [Some-State]:MyState
Namn på lokalitet (t.ex. stad) []:Some City
Organisationsnamn (t.ex. företag) [Internet Widgits Pty Ltd]:My Organization, Inc.
Namn på organisatorisk enhet (t.ex. sektion) []:My Group
Gemensamt namn (t.ex. ditt namn) []:myserver.mygroup.myorganization.com
E-postadress []:ops@myserver.mygroup.myorganization.com
%

Nackdelen med ett självsignerat certifikat är att det är ett eget rotcertifikat, och ingen annan kommer att ha det i sin cache av kända (och betrodda) rotcertifikat.

Exempel

Testning för SSL-stöd

För att testa om det finns SSL-stöd i en Python-installation bör användarkoden använda följande idiom:

try:
    import ssl
except ImportError:
    pass
else:
    ...  # do something that requires SSL support

Operation på klientsidan

I detta exempel skapas en SSL-kontext med rekommenderade säkerhetsinställningar för klientsocklar, inklusive automatisk certifikatverifiering:

>>> context = ssl.create_default_context()

Om du föredrar att göra säkerhetsinställningarna själv kan du skapa ett sammanhang från början (men tänk på att du kanske inte får rätt inställningar):

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

(detta utdrag förutsätter att ditt operativsystem placerar ett paket med alla CA-certifikat i /etc/ssl/certs/ca-bundle.crt; om inte, får du ett fel och måste justera platsen)

Protokollet PROTOCOL_TLS_CLIENT konfigurerar kontexten för validering av certifikat och verifiering av värdnamn. verify_mode är inställd på CERT_REQUIRED och check_hostname är inställd på True. Alla andra protokoll skapar SSL-kontexter med osäkra standardvärden.

När du använder kontexten för att ansluta till en server validerar CERT_REQUIRED och check_hostname servercertifikatet: det säkerställer att servercertifikatet har signerats med ett av CA-certifikaten, kontrollerar att signaturen är korrekt och verifierar andra egenskaper som giltighet och identitet för värdnamnet:

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

Du kan då hämta ut certifikatet:

>>> cert = conn.getpeercert()

En visuell kontroll visar att certifikatet identifierar den önskade tjänsten (dvs. HTTPS-värden www.python.org):

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

Nu när SSL-kanalen har upprättats och certifikatet har verifierats kan du fortsätta att prata med servern:

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

Se diskussionen om Överväganden om säkerhet nedan.

Drift på serversidan

För serverdrift behöver du vanligtvis ha ett servercertifikat och en privat nyckel i varsin fil. Du skapar först en kontext som innehåller nyckeln och certifikatet, så att klienterna kan kontrollera din äkthet. Sedan öppnar du en socket, binder den till en port, anropar listen() på den och börjar vänta på att klienter ska ansluta:

import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

bindsocket = socket.socket()
bindsocket.bind(('myaddr.example.com', 10023))
bindsocket.listen(5)

När en klient ansluter anropar du accept() på sockeln för att hämta den nya sockeln från andra änden och använder kontextens SSLContext.wrap_socket()-metod för att skapa en SSL-socket på serversidan för anslutningen:

medan True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = context.wrap_socket(newsocket, server_side=True)
    försök:
        deal_with_client(connstream)
    slutligen: deal_with_client
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()

Sedan läser du data från connstream och gör något med den tills du är klar med klienten (eller klienten är klar med dig):

def deal_with_client(connstream):
    data = connstream.recv(1024)
    # tomma data betyder att klienten är klar med oss
    while data:
        if not do_something(connstream, data):
            # vi antar att do_something returnerar False
            # när vi är färdiga med klienten
            paus
        data = connstream.recv(1024)
    # färdig med klienten

Och gå tillbaka till att lyssna efter nya klientanslutningar (naturligtvis skulle en riktig server förmodligen hantera varje klientanslutning i en separat tråd, eller sätta socklarna i icke-blockerande läge och använda en händelseslinga).

Anteckningar om icke-blockerande sockets

SSL-uttag beter sig något annorlunda än vanliga uttag i icke-blockerande läge. När du arbetar med icke-blockerande sockets finns det därför flera saker du måste vara medveten om:

  • De flesta SSLSocket-metoder kommer att ge upphov till antingen SSLWantWriteError eller SSLWantReadError istället för BlockingIOError om en I/O-operation skulle blockeras. SSLWantReadError kommer att ges upphov till om en läsoperation på den underliggande sockeln är nödvändig, och SSLWantWriteError för en skrivoperation på den underliggande sockeln. Observera att försök att skriva till ett SSL-uttag kan kräva att man först läser från det underliggande uttaget, och försök att läsa från SSL-uttaget kan kräva att man först skriver till det underliggande uttaget.

    Ändrad i version 3.5: I tidigare Python-versioner returnerade metoden SSLSocket.send() noll istället för att ge upphov till SSLWantWriteError eller SSLWantReadError.

  • Om du anropar select() får du veta att det går att läsa från (eller skriva till) sockeln på OS-nivå, men det innebär inte att det finns tillräckligt med data i det övre SSL-lagret. Det kan t.ex. hända att bara en del av en SSL-ram har kommit fram. Därför måste du vara redo att hantera misslyckanden med SSLSocket.recv() och SSLSocket.send(), och försöka igen efter ett nytt anrop till select().

  • Omvänt, eftersom SSL-lagret har sin egen inramning, kan ett SSL-uttag fortfarande ha data tillgängliga för läsning utan att select() är medveten om det. Därför bör du först anropa SSLSocket.recv() för att tömma alla potentiellt tillgängliga data, och sedan bara blockera på ett select()-anrop om det fortfarande är nödvändigt.

    (Naturligtvis gäller liknande bestämmelser när du använder andra primitiver som poll(), eller de i selectors-modulen)

  • Själva SSL-handskakningen kommer att vara icke-blockerande: metoden SSLSocket.do_handshake() måste prövas igen tills den returneras framgångsrikt. Här är en sammanfattning som använder select() för att vänta på att uttaget är redo:

    medan True:
    try:
        sock.do_handshake()
        bryt
    except ssl.SSLWantReadError:
        select.select([sock], [], [])
    except ssl.SSLWantWriteError:
        select.select([], [sock], [])

Se även

Modulen asyncio stöder non-blocking SSL sockets och tillhandahåller en högre nivå Streams API. Den pollar efter händelser med hjälp av modulen selectors och hanterar undantagen SSLWantWriteError, SSLWantReadError och BlockingIOError. Den kör även SSL-handskakningen asynkront.

Stöd för BIO-minne

Tillagd i version 3.5.

Ända sedan SSL-modulen introducerades i Python 2.6 har SSLSocket-klassen tillhandahållit två relaterade men distinkta områden av funktionalitet:

  • Hantering av SSL-protokoll

  • Nätverk IO

API:et för nätverks-IO är identiskt med det som tillhandahålls av socket.socket, som SSLSocket också ärver från. Detta gör att en SSL-socket kan användas som en drop-in-ersättning för en vanlig socket, vilket gör det mycket enkelt att lägga till SSL-stöd i en befintlig applikation.

Att kombinera SSL-protokollhantering och nätverks-IO fungerar vanligtvis bra, men det finns vissa fall där det inte gör det. Ett exempel är asynkrona IO-ramverk som vill använda en annan IO-multiplexeringsmodell än ”select/poll on a file descriptor”-modellen (beredskapsbaserad) som antas av socket.socket och av de interna OpenSSL-socket IO-rutinerna. Detta är mest relevant för plattformar som Windows där denna modell inte är effektiv. För detta ändamål tillhandahålls en variant med reducerat scope av SSLSocket som kallas SSLObject.

class ssl.SSLObject

En reducerad variant av SSLSocket som representerar en SSL-protokollinstans som inte innehåller några IO-metoder för nätverk. Den här klassen används vanligtvis av ramverksförfattare som vill implementera asynkron IO för SSL via minnesbuffertar.

Den här klassen implementerar ett gränssnitt ovanpå ett SSL-objekt på låg nivå som implementeras av OpenSSL. Detta objekt fångar upp tillståndet för en SSL-anslutning men tillhandahåller inte någon egen nätverks-IO. IO måste utföras genom separata ”BIO”-objekt som är OpenSSL:s abstraktionslager för IO.

Denna klass har ingen offentlig konstruktör. En instans av SSLObject måste skapas med hjälp av metoden wrap_bio(). Denna metod skapar SSLObject-instansen och binder den till ett par BIO:er. Den inkommande BIO används för att skicka data från Python till SSL-protokollinstansen, medan den utgående BIO används för att skicka data åt andra hållet.

Följande metoder finns tillgängliga:

Jämfört med SSLSocket saknar detta objekt följande egenskaper:

  • Alla former av nätverks-IO; recv() och send() läser och skriver endast till de underliggande MemoryBIO-buffertarna.

  • Det finns ingen do_handshake_on_connect-mekanism. Du måste alltid manuellt anropa do_handshake() för att starta handskakningen.

  • Det finns ingen hantering av suppress_ragged_eofs. Alla villkor för filändar som bryter mot protokollet rapporteras via undantaget SSLEOFError.

  • Anropet till metoden unwrap() returnerar ingenting, till skillnad från en SSL-socket där den underliggande sockeln returneras.

  • Den server_name_callback callback som skickas till SSLContext.set_servername_callback() kommer att få en SSLObject-instans istället för en SSLSocket-instans som sin första parameter.

Några anteckningar relaterade till användningen av SSLObject:

Ändrad i version 3.7: SSLObject-instanser måste skapas med wrap_bio(). I tidigare versioner var det möjligt att skapa instanser direkt. Detta har aldrig dokumenterats eller fått officiellt stöd.

Ett SSLObject kommunicerar med omvärlden med hjälp av minnesbuffertar. Klassen MemoryBIO tillhandahåller en minnesbuffert som kan användas för detta ändamål. Den omsluter ett OpenSSL-minne BIO-objekt (Basic IO):

class ssl.MemoryBIO

En minnesbuffert som kan användas för att skicka data mellan Python och en SSL-protokollinstans.

pending

Returnerar antalet bytes som för närvarande finns i minnesbufferten.

eof

En boolean som anger om minnet BIO är aktuellt vid filens slutposition.

read(n=-1)

Läser upp till n bytes från minnesbufferten. Om n inte anges eller är negativ returneras alla byte.

write(buf)

Skriv bytena från buf till minnet BIO. Argumentet buf måste vara ett objekt som stöder buffertprotokollet.

Returvärdet är antalet byte som skrivits, vilket alltid är lika med längden på buf.

write_eof()

Skriver en EOF-markör till minnet BIO. Efter att denna metod har anropats är det olagligt att anropa write(). Attributet eof kommer att bli sant efter att all data som för närvarande finns i bufferten har lästs.

SSL-session

Tillagd i version 3.6.

class ssl.SSLSession

Sessionsobjekt som används av session.

id
time
timeout
ticket_lifetime_hint
has_ticket

Överväganden om säkerhet

Bästa standardvärden

För klientanvändning, om du inte har några särskilda krav på din säkerhetspolicy, rekommenderas starkt att du använder funktionen create_default_context() för att skapa din SSL-kontext. Den kommer att ladda systemets betrodda CA-certifikat, aktivera certifikatvalidering och värdnamnskontroll och försöka välja rimligt säkra protokoll- och chifferinställningar.

Så här kan du till exempel använda klassen smtplib.SMTP för att skapa en betrodd, säker anslutning till en SMTP-server:

>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')

Om det behövs ett klientcertifikat för anslutningen kan det läggas till med SSLContext.load_cert_chain().

Om du däremot skapar SSL-kontexten genom att anropa SSLContext-konstruktören själv, kommer den inte att ha certifikatvalidering eller kontroll av värdnamn aktiverat som standard. Om du gör det bör du läsa nedanstående stycken för att uppnå en bra säkerhetsnivå.

Manuella inställningar

Verifiering av certifikat

Vid direkt anrop av SSLContext-konstruktören är CERT_NONE standard. Eftersom den inte autentiserar den andra motparten kan det vara osäkert, särskilt i klientläge där du för det mesta vill säkerställa att servern du pratar med är äkta. I klientläge rekommenderas därför starkt att använda CERT_REQUIRED. Det är dock inte tillräckligt i sig. Du måste också kontrollera att servercertifikatet, som kan erhållas genom att anropa SSLSocket.getpeercert(), matchar den önskade tjänsten. För många protokoll och applikationer kan tjänsten identifieras med hjälp av värdnamnet. Denna vanliga kontroll utförs automatiskt när SSLContext.check_hostname är aktiverad.

Ändrad i version 3.7: Matchning av värdnamn utförs nu av OpenSSL. Python använder inte längre match_hostname().

Om du i serverläget vill autentisera dina klienter med hjälp av SSL-lagret (i stället för att använda en autentiseringsmekanism på högre nivå) måste du också ange CERT_REQUIRED och kontrollera klientcertifikatet på samma sätt.

Protokollversioner

SSL version 2 och 3 anses vara osäkra och är därför farliga att använda. Om du vill ha maximal kompatibilitet mellan klienter och servrar rekommenderas det att du använder PROTOCOL_TLS_CLIENT eller PROTOCOL_TLS_SERVER som protokollversion. SSLv2 och SSLv3 är inaktiverade som standard.

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

SSL-kontexten som skapades ovan tillåter endast TLSv1.3 och senare (om det stöds av ditt system) anslutningar till en server. PROTOCOL_TLS_CLIENT innebär certifikatvalidering och värdnamnskontroller som standard. Du måste ladda certifikat i kontexten.

Val av chiffer

Om du har avancerade säkerhetskrav är det möjligt att finjustera de chiffer som aktiveras när du förhandlar om en SSL-session genom metoden SSLContext.set_ciphers(). Från och med Python 3.2.3 inaktiverar ssl-modulen vissa svaga chiffer som standard, men du kanske vill begränsa valet av chiffer ytterligare. Se till att läsa OpenSSL:s dokumentation om formatet för cipher list. Om du vill kontrollera vilka chiffer som aktiveras av en viss chifferlista, använd SSLContext.get_ciphers() eller kommandot openssl ciphers på ditt system.

Multiprocessing

Om du använder den här modulen som en del av ett program med flera processer (t.ex. med modulerna multiprocessing eller concurrent.futures), bör du vara medveten om att OpenSSL:s interna slumptalsgenerator inte hanterar förgrenade processer på rätt sätt. Program måste ändra PRNG-tillståndet för den överordnade processen om de använder någon SSL-funktion med os.fork(). Varje lyckat anrop av RAND_add() eller RAND_bytes() är tillräckligt.

TLS 1.3

Tillagd i version 3.7.

Protokollet TLS 1.3 beter sig något annorlunda än tidigare versioner av TLS/SSL. Vissa nya funktioner i TLS 1.3 är ännu inte tillgängliga.

  • TLS 1.3 använder en disjunkt uppsättning chiffersviter. Alla AES-GCM- och ChaCha20-chiffersviter är aktiverade som standard. Metoden SSLContext.set_ciphers() kan inte aktivera eller inaktivera några TLS 1.3-chiffer ännu, men SSLContext.get_ciphers() returnerar dem.

  • Sessionsbiljetter skickas inte längre som en del av den inledande handskakningen och hanteras annorlunda. SSLSocket.session och SSLSession är inte kompatibla med TLS 1.3.

  • Certifikat på klientsidan verifieras inte heller längre under den första handskakningen. En server kan begära ett certifikat när som helst. Klienter behandlar certifikatbegäran medan de skickar eller tar emot programdata från servern.

  • TLS 1.3-funktioner som tidig data, uppskjuten begäran om TLS-klientcertifikat, konfiguration av signaturalgoritm och omkodning stöds inte ännu.

Se även

Klass socket.socket

Dokumentation av den underliggande socket-klassen

SSL/TLS Stark Kryptering: En introduktion

Intro från dokumentationen för Apache HTTP Server

RFC 1422: Förbättrad sekretess för elektronisk post på Internet: Part II: Certificate-Based Key Management

Steve Kent

RFC 4086: Slumpmässighetskrav för säkerhet

Donald E., Jeffrey I. Schiller

RFC 5280: Profil för Internet X.509 Public Key Infrastructure-certifikat och lista över återkallade certifikat (CRL)

D. Cooper

RFC 5246: TLS-protokollet (Transport Layer Security) version 1.2

T. Dierks et. al.

RFC 6066: TLS-tillägg (Transport Layer Security)

D. Eastlake

IANA TLS: Parametrar för TLS (Transport Layer Security)

IANA

RFC 7525: Rekommendationer för säker användning av TLS (Transport Layer Security) och DTLS (Datagram Transport Layer Security)

IETF

Mozillas TLS-rekommendationer för serversidan

Mozilla