1import enum
2import socket
3import sys
4from _typeshed import ReadableBuffer, Self, StrPath, WriteableBuffer
5from typing import Any, Callable, ClassVar, Dict, Iterable, List, NamedTuple, Optional, Set, Tuple, Type, Union, overload
6from typing_extensions import Literal
7
8_PCTRTT = Tuple[Tuple[str, str], ...]
9_PCTRTTT = Tuple[_PCTRTT, ...]
10_PeerCertRetDictType = Dict[str, Union[str, _PCTRTTT, _PCTRTT]]
11_PeerCertRetType = Union[_PeerCertRetDictType, bytes, None]
12_EnumRetType = List[Tuple[bytes, str, Union[Set[str], bool]]]
13_PasswordType = Union[Callable[[], Union[str, bytes]], str, bytes]
14
15_SrvnmeCbType = Callable[[Union[SSLSocket, SSLObject], Optional[str], SSLSocket], Optional[int]]
16
17class SSLError(OSError):
18    library: str
19    reason: str
20
21class SSLZeroReturnError(SSLError): ...
22class SSLWantReadError(SSLError): ...
23class SSLWantWriteError(SSLError): ...
24class SSLSyscallError(SSLError): ...
25class SSLEOFError(SSLError): ...
26
27if sys.version_info >= (3, 7):
28    class SSLCertVerificationError(SSLError, ValueError):
29        verify_code: int
30        verify_message: str
31    CertificateError = SSLCertVerificationError
32else:
33    class CertificateError(ValueError): ...
34
35def wrap_socket(
36    sock: socket.socket,
37    keyfile: Optional[str] = ...,
38    certfile: Optional[str] = ...,
39    server_side: bool = ...,
40    cert_reqs: int = ...,
41    ssl_version: int = ...,
42    ca_certs: Optional[str] = ...,
43    do_handshake_on_connect: bool = ...,
44    suppress_ragged_eofs: bool = ...,
45    ciphers: Optional[str] = ...,
46) -> SSLSocket: ...
47def create_default_context(
48    purpose: Any = ..., *, cafile: Optional[str] = ..., capath: Optional[str] = ..., cadata: Union[str, bytes, None] = ...
49) -> SSLContext: ...
50
51if sys.version_info >= (3, 7):
52    def _create_unverified_context(
53        protocol: int = ...,
54        *,
55        cert_reqs: int = ...,
56        check_hostname: bool = ...,
57        purpose: Any = ...,
58        certfile: Optional[str] = ...,
59        keyfile: Optional[str] = ...,
60        cafile: Optional[str] = ...,
61        capath: Optional[str] = ...,
62        cadata: Union[str, bytes, None] = ...,
63    ) -> SSLContext: ...
64
65else:
66    def _create_unverified_context(
67        protocol: int = ...,
68        *,
69        cert_reqs: Optional[int] = ...,
70        check_hostname: bool = ...,
71        purpose: Any = ...,
72        certfile: Optional[str] = ...,
73        keyfile: Optional[str] = ...,
74        cafile: Optional[str] = ...,
75        capath: Optional[str] = ...,
76        cadata: Union[str, bytes, None] = ...,
77    ) -> SSLContext: ...
78
79_create_default_https_context: Callable[..., SSLContext]
80
81def RAND_bytes(__num: int) -> bytes: ...
82def RAND_pseudo_bytes(__num: int) -> Tuple[bytes, bool]: ...
83def RAND_status() -> bool: ...
84def RAND_egd(path: str) -> None: ...
85def RAND_add(__s: bytes, __entropy: float) -> None: ...
86def match_hostname(cert: _PeerCertRetType, hostname: str) -> None: ...
87def cert_time_to_seconds(cert_time: str) -> int: ...
88def get_server_certificate(addr: Tuple[str, int], ssl_version: int = ..., ca_certs: Optional[str] = ...) -> str: ...
89def DER_cert_to_PEM_cert(der_cert_bytes: bytes) -> str: ...
90def PEM_cert_to_DER_cert(pem_cert_string: str) -> bytes: ...
91
92class DefaultVerifyPaths(NamedTuple):
93    cafile: str
94    capath: str
95    openssl_cafile_env: str
96    openssl_cafile: str
97    openssl_capath_env: str
98    openssl_capath: str
99
100def get_default_verify_paths() -> DefaultVerifyPaths: ...
101
102if sys.platform == "win32":
103    def enum_certificates(store_name: str) -> _EnumRetType: ...
104    def enum_crls(store_name: str) -> _EnumRetType: ...
105
106class VerifyMode(enum.IntEnum):
107    CERT_NONE: int
108    CERT_OPTIONAL: int
109    CERT_REQUIRED: int
110
111CERT_NONE: VerifyMode
112CERT_OPTIONAL: VerifyMode
113CERT_REQUIRED: VerifyMode
114
115class VerifyFlags(enum.IntFlag):
116    VERIFY_DEFAULT: int
117    VERIFY_CRL_CHECK_LEAF: int
118    VERIFY_CRL_CHECK_CHAIN: int
119    VERIFY_X509_STRICT: int
120    VERIFY_X509_TRUSTED_FIRST: int
121
122VERIFY_DEFAULT: VerifyFlags
123VERIFY_CRL_CHECK_LEAF: VerifyFlags
124VERIFY_CRL_CHECK_CHAIN: VerifyFlags
125VERIFY_X509_STRICT: VerifyFlags
126VERIFY_X509_TRUSTED_FIRST: VerifyFlags
127
128class _SSLMethod(enum.IntEnum):
129    PROTOCOL_SSLv23: int
130    PROTOCOL_SSLv2: int
131    PROTOCOL_SSLv3: int
132    PROTOCOL_TLSv1: int
133    PROTOCOL_TLSv1_1: int
134    PROTOCOL_TLSv1_2: int
135    PROTOCOL_TLS: int
136    PROTOCOL_TLS_CLIENT: int
137    PROTOCOL_TLS_SERVER: int
138
139PROTOCOL_SSLv23: _SSLMethod
140PROTOCOL_SSLv2: _SSLMethod
141PROTOCOL_SSLv3: _SSLMethod
142PROTOCOL_TLSv1: _SSLMethod
143PROTOCOL_TLSv1_1: _SSLMethod
144PROTOCOL_TLSv1_2: _SSLMethod
145PROTOCOL_TLS: _SSLMethod
146PROTOCOL_TLS_CLIENT: _SSLMethod
147PROTOCOL_TLS_SERVER: _SSLMethod
148
149class Options(enum.IntFlag):
150    OP_ALL: int
151    OP_NO_SSLv2: int
152    OP_NO_SSLv3: int
153    OP_NO_TLSv1: int
154    OP_NO_TLSv1_1: int
155    OP_NO_TLSv1_2: int
156    OP_NO_TLSv1_3: int
157    OP_CIPHER_SERVER_PREFERENCE: int
158    OP_SINGLE_DH_USE: int
159    OP_SINGLE_ECDH_USE: int
160    OP_NO_COMPRESSION: int
161    OP_NO_TICKET: int
162    if sys.version_info >= (3, 7):
163        OP_NO_RENEGOTIATION: int
164    if sys.version_info >= (3, 8):
165        OP_ENABLE_MIDDLEBOX_COMPAT: int
166
167OP_ALL: Options
168OP_NO_SSLv2: Options
169OP_NO_SSLv3: Options
170OP_NO_TLSv1: Options
171OP_NO_TLSv1_1: Options
172OP_NO_TLSv1_2: Options
173OP_NO_TLSv1_3: Options
174OP_CIPHER_SERVER_PREFERENCE: Options
175OP_SINGLE_DH_USE: Options
176OP_SINGLE_ECDH_USE: Options
177OP_NO_COMPRESSION: Options
178OP_NO_TICKET: Options
179if sys.version_info >= (3, 7):
180    OP_NO_RENEGOTIATION: Options
181if sys.version_info >= (3, 8):
182    OP_ENABLE_MIDDLEBOX_COMPAT: Options
183
184if sys.version_info >= (3, 7):
185    HAS_NEVER_CHECK_COMMON_NAME: bool
186    HAS_SSLv2: bool
187    HAS_SSLv3: bool
188    HAS_TLSv1: bool
189    HAS_TLSv1_1: bool
190    HAS_TLSv1_2: bool
191    HAS_TLSv1_3: bool
192HAS_ALPN: bool
193HAS_ECDH: bool
194HAS_SNI: bool
195HAS_NPN: bool
196CHANNEL_BINDING_TYPES: List[str]
197
198OPENSSL_VERSION: str
199OPENSSL_VERSION_INFO: Tuple[int, int, int, int, int]
200OPENSSL_VERSION_NUMBER: int
201
202class AlertDescription(enum.IntEnum):
203    ALERT_DESCRIPTION_ACCESS_DENIED: int
204    ALERT_DESCRIPTION_BAD_CERTIFICATE: int
205    ALERT_DESCRIPTION_BAD_CERTIFICATE_HASH_VALUE: int
206    ALERT_DESCRIPTION_BAD_CERTIFICATE_STATUS_RESPONSE: int
207    ALERT_DESCRIPTION_BAD_RECORD_MAC: int
208    ALERT_DESCRIPTION_CERTIFICATE_EXPIRED: int
209    ALERT_DESCRIPTION_CERTIFICATE_REVOKED: int
210    ALERT_DESCRIPTION_CERTIFICATE_UNKNOWN: int
211    ALERT_DESCRIPTION_CERTIFICATE_UNOBTAINABLE: int
212    ALERT_DESCRIPTION_CLOSE_NOTIFY: int
213    ALERT_DESCRIPTION_DECODE_ERROR: int
214    ALERT_DESCRIPTION_DECOMPRESSION_FAILURE: int
215    ALERT_DESCRIPTION_DECRYPT_ERROR: int
216    ALERT_DESCRIPTION_HANDSHAKE_FAILURE: int
217    ALERT_DESCRIPTION_ILLEGAL_PARAMETER: int
218    ALERT_DESCRIPTION_INSUFFICIENT_SECURITY: int
219    ALERT_DESCRIPTION_INTERNAL_ERROR: int
220    ALERT_DESCRIPTION_NO_RENEGOTIATION: int
221    ALERT_DESCRIPTION_PROTOCOL_VERSION: int
222    ALERT_DESCRIPTION_RECORD_OVERFLOW: int
223    ALERT_DESCRIPTION_UNEXPECTED_MESSAGE: int
224    ALERT_DESCRIPTION_UNKNOWN_CA: int
225    ALERT_DESCRIPTION_UNKNOWN_PSK_IDENTITY: int
226    ALERT_DESCRIPTION_UNRECOGNIZED_NAME: int
227    ALERT_DESCRIPTION_UNSUPPORTED_CERTIFICATE: int
228    ALERT_DESCRIPTION_UNSUPPORTED_EXTENSION: int
229    ALERT_DESCRIPTION_USER_CANCELLED: int
230
231ALERT_DESCRIPTION_HANDSHAKE_FAILURE: AlertDescription
232ALERT_DESCRIPTION_INTERNAL_ERROR: AlertDescription
233ALERT_DESCRIPTION_ACCESS_DENIED: AlertDescription
234ALERT_DESCRIPTION_BAD_CERTIFICATE: AlertDescription
235ALERT_DESCRIPTION_BAD_CERTIFICATE_HASH_VALUE: AlertDescription
236ALERT_DESCRIPTION_BAD_CERTIFICATE_STATUS_RESPONSE: AlertDescription
237ALERT_DESCRIPTION_BAD_RECORD_MAC: AlertDescription
238ALERT_DESCRIPTION_CERTIFICATE_EXPIRED: AlertDescription
239ALERT_DESCRIPTION_CERTIFICATE_REVOKED: AlertDescription
240ALERT_DESCRIPTION_CERTIFICATE_UNKNOWN: AlertDescription
241ALERT_DESCRIPTION_CERTIFICATE_UNOBTAINABLE: AlertDescription
242ALERT_DESCRIPTION_CLOSE_NOTIFY: AlertDescription
243ALERT_DESCRIPTION_DECODE_ERROR: AlertDescription
244ALERT_DESCRIPTION_DECOMPRESSION_FAILURE: AlertDescription
245ALERT_DESCRIPTION_DECRYPT_ERROR: AlertDescription
246ALERT_DESCRIPTION_ILLEGAL_PARAMETER: AlertDescription
247ALERT_DESCRIPTION_INSUFFICIENT_SECURITY: AlertDescription
248ALERT_DESCRIPTION_NO_RENEGOTIATION: AlertDescription
249ALERT_DESCRIPTION_PROTOCOL_VERSION: AlertDescription
250ALERT_DESCRIPTION_RECORD_OVERFLOW: AlertDescription
251ALERT_DESCRIPTION_UNEXPECTED_MESSAGE: AlertDescription
252ALERT_DESCRIPTION_UNKNOWN_CA: AlertDescription
253ALERT_DESCRIPTION_UNKNOWN_PSK_IDENTITY: AlertDescription
254ALERT_DESCRIPTION_UNRECOGNIZED_NAME: AlertDescription
255ALERT_DESCRIPTION_UNSUPPORTED_CERTIFICATE: AlertDescription
256ALERT_DESCRIPTION_UNSUPPORTED_EXTENSION: AlertDescription
257ALERT_DESCRIPTION_USER_CANCELLED: AlertDescription
258
259class _ASN1Object(NamedTuple):
260    nid: int
261    shortname: str
262    longname: str
263    oid: str
264    @classmethod
265    def fromnid(cls: Type[Self], nid: int) -> Self: ...
266    @classmethod
267    def fromname(cls: Type[Self], name: str) -> Self: ...
268
269class Purpose(_ASN1Object, enum.Enum):
270    SERVER_AUTH: _ASN1Object
271    CLIENT_AUTH: _ASN1Object
272
273class SSLSocket(socket.socket):
274    context: SSLContext
275    server_side: bool
276    server_hostname: Optional[str]
277    session: Optional[SSLSession]
278    session_reused: Optional[bool]
279    if sys.version_info < (3, 7):
280        def __init__(
281            self,
282            sock: Optional[socket.socket] = ...,
283            keyfile: Optional[str] = ...,
284            certfile: Optional[str] = ...,
285            server_side: bool = ...,
286            cert_reqs: int = ...,
287            ssl_version: int = ...,
288            ca_certs: Optional[str] = ...,
289            do_handshake_on_connect: bool = ...,
290            family: int = ...,
291            type: int = ...,
292            proto: int = ...,
293            fileno: Optional[int] = ...,
294            suppress_ragged_eofs: bool = ...,
295            npn_protocols: Optional[Iterable[str]] = ...,
296            ciphers: Optional[str] = ...,
297            server_hostname: Optional[str] = ...,
298            _context: Optional[SSLContext] = ...,
299            _session: Optional[Any] = ...,
300        ) -> None: ...
301    else:
302        def __init__(self, *args: Any, **kwargs: Any) -> None: ...
303    def connect(self, addr: Union[socket._Address, bytes]) -> None: ...
304    def connect_ex(self, addr: Union[socket._Address, bytes]) -> int: ...
305    def recv(self, buflen: int = ..., flags: int = ...) -> bytes: ...
306    def recv_into(self, buffer: WriteableBuffer, nbytes: Optional[int] = ..., flags: int = ...) -> int: ...
307    def recvfrom(self, buflen: int = ..., flags: int = ...) -> tuple[bytes, socket._RetAddress]: ...
308    def recvfrom_into(
309        self, buffer: WriteableBuffer, nbytes: Optional[int] = ..., flags: int = ...
310    ) -> tuple[int, socket._RetAddress]: ...
311    def send(self, data: ReadableBuffer, flags: int = ...) -> int: ...
312    def sendall(self, data: ReadableBuffer, flags: int = ...) -> None: ...
313    @overload
314    def sendto(self, data: ReadableBuffer, flags_or_addr: socket._Address) -> int: ...
315    @overload
316    def sendto(
317        self, data: ReadableBuffer, flags_or_addr: Union[int, socket._Address], addr: Optional[socket._Address] = ...
318    ) -> int: ...
319    def shutdown(self, how: int) -> None: ...
320    def read(self, len: int = ..., buffer: Optional[bytearray] = ...) -> bytes: ...
321    def write(self, data: bytes) -> int: ...
322    def do_handshake(self, block: bool = ...) -> None: ...  # block is undocumented
323    @overload
324    def getpeercert(self, binary_form: Literal[False] = ...) -> Optional[_PeerCertRetDictType]: ...
325    @overload
326    def getpeercert(self, binary_form: Literal[True]) -> Optional[bytes]: ...
327    @overload
328    def getpeercert(self, binary_form: bool) -> _PeerCertRetType: ...
329    def cipher(self) -> Optional[Tuple[str, str, int]]: ...
330    def shared_ciphers(self) -> Optional[List[Tuple[str, str, int]]]: ...
331    def compression(self) -> Optional[str]: ...
332    def get_channel_binding(self, cb_type: str = ...) -> Optional[bytes]: ...
333    def selected_alpn_protocol(self) -> Optional[str]: ...
334    def selected_npn_protocol(self) -> Optional[str]: ...
335    def accept(self) -> Tuple[SSLSocket, socket._RetAddress]: ...
336    def unwrap(self) -> socket.socket: ...
337    def version(self) -> Optional[str]: ...
338    def pending(self) -> int: ...
339    if sys.version_info >= (3, 8):
340        def verify_client_post_handshake(self) -> None: ...
341
342if sys.version_info >= (3, 7):
343    class TLSVersion(enum.IntEnum):
344        MINIMUM_SUPPORTED: int
345        MAXIMUM_SUPPORTED: int
346        SSLv3: int
347        TLSv1: int
348        TLSv1_1: int
349        TLSv1_2: int
350        TLSv1_3: int
351
352class SSLContext:
353    check_hostname: bool
354    options: Options
355    verify_flags: VerifyFlags
356    verify_mode: VerifyMode
357    @property
358    def protocol(self) -> _SSLMethod: ...
359    if sys.version_info >= (3, 7):
360        hostname_checks_common_name: bool
361        maximum_version: TLSVersion
362        minimum_version: TLSVersion
363        sni_callback: Optional[Callable[[SSLObject, str, SSLContext], Union[None, int]]]
364        sslobject_class: ClassVar[Type[SSLObject]]
365        sslsocket_class: ClassVar[Type[SSLSocket]]
366    if sys.version_info >= (3, 8):
367        keylog_filename: str
368        post_handshake_auth: bool
369    def __new__(cls, protocol: int = ..., *args: Any, **kwargs: Any) -> SSLContext: ...
370    def __init__(self, protocol: int = ...) -> None: ...
371    def cert_store_stats(self) -> Dict[str, int]: ...
372    def load_cert_chain(
373        self, certfile: StrPath, keyfile: Optional[StrPath] = ..., password: Optional[_PasswordType] = ...
374    ) -> None: ...
375    def load_default_certs(self, purpose: Purpose = ...) -> None: ...
376    def load_verify_locations(
377        self, cafile: Optional[StrPath] = ..., capath: Optional[StrPath] = ..., cadata: Union[str, bytes, None] = ...
378    ) -> None: ...
379    def get_ca_certs(self, binary_form: bool = ...) -> Union[List[_PeerCertRetDictType], List[bytes]]: ...
380    def set_default_verify_paths(self) -> None: ...
381    def set_ciphers(self, __cipherlist: str) -> None: ...
382    def set_alpn_protocols(self, alpn_protocols: Iterable[str]) -> None: ...
383    def set_npn_protocols(self, npn_protocols: Iterable[str]) -> None: ...
384    if sys.version_info >= (3, 7):
385        def set_servername_callback(self, server_name_callback: Optional[_SrvnmeCbType]) -> None: ...
386    else:
387        def set_servername_callback(self, __method: Optional[_SrvnmeCbType]) -> None: ...
388    def load_dh_params(self, __path: str) -> None: ...
389    def set_ecdh_curve(self, __name: str) -> None: ...
390    def wrap_socket(
391        self,
392        sock: socket.socket,
393        server_side: bool = ...,
394        do_handshake_on_connect: bool = ...,
395        suppress_ragged_eofs: bool = ...,
396        server_hostname: Optional[str] = ...,
397        session: Optional[SSLSession] = ...,
398    ) -> SSLSocket: ...
399    def wrap_bio(
400        self,
401        incoming: MemoryBIO,
402        outgoing: MemoryBIO,
403        server_side: bool = ...,
404        server_hostname: Optional[str] = ...,
405        session: Optional[SSLSession] = ...,
406    ) -> SSLObject: ...
407    def session_stats(self) -> Dict[str, int]: ...
408
409class SSLObject:
410    context: SSLContext
411    server_side: bool
412    server_hostname: Optional[str]
413    session: Optional[SSLSession]
414    session_reused: bool
415    if sys.version_info >= (3, 7):
416        def __init__(self, *args: Any, **kwargs: Any) -> None: ...
417    else:
418        def __init__(
419            self, sslobj: Any, owner: Optional[Union[SSLSocket, SSLObject]] = ..., session: Optional[Any] = ...
420        ) -> None: ...
421    def read(self, len: int = ..., buffer: Optional[bytearray] = ...) -> bytes: ...
422    def write(self, data: bytes) -> int: ...
423    @overload
424    def getpeercert(self, binary_form: Literal[False] = ...) -> Optional[_PeerCertRetDictType]: ...
425    @overload
426    def getpeercert(self, binary_form: Literal[True]) -> Optional[bytes]: ...
427    @overload
428    def getpeercert(self, binary_form: bool) -> _PeerCertRetType: ...
429    def selected_alpn_protocol(self) -> Optional[str]: ...
430    def selected_npn_protocol(self) -> Optional[str]: ...
431    def cipher(self) -> Optional[Tuple[str, str, int]]: ...
432    def shared_ciphers(self) -> Optional[List[Tuple[str, str, int]]]: ...
433    def compression(self) -> Optional[str]: ...
434    def pending(self) -> int: ...
435    def do_handshake(self) -> None: ...
436    def unwrap(self) -> None: ...
437    def version(self) -> Optional[str]: ...
438    def get_channel_binding(self, cb_type: str = ...) -> Optional[bytes]: ...
439    if sys.version_info >= (3, 8):
440        def verify_client_post_handshake(self) -> None: ...
441
442class MemoryBIO:
443    pending: int
444    eof: bool
445    def read(self, __size: int = ...) -> bytes: ...
446    def write(self, __buf: bytes) -> int: ...
447    def write_eof(self) -> None: ...
448
449class SSLSession:
450    id: bytes
451    time: int
452    timeout: int
453    ticket_lifetime_hint: int
454    has_ticket: bool
455
456class SSLErrorNumber(enum.IntEnum):
457    SSL_ERROR_EOF: int
458    SSL_ERROR_INVALID_ERROR_CODE: int
459    SSL_ERROR_SSL: int
460    SSL_ERROR_SYSCALL: int
461    SSL_ERROR_WANT_CONNECT: int
462    SSL_ERROR_WANT_READ: int
463    SSL_ERROR_WANT_WRITE: int
464    SSL_ERROR_WANT_X509_LOOKUP: int
465    SSL_ERROR_ZERO_RETURN: int
466
467SSL_ERROR_EOF: SSLErrorNumber  # undocumented
468SSL_ERROR_INVALID_ERROR_CODE: SSLErrorNumber  # undocumented
469SSL_ERROR_SSL: SSLErrorNumber  # undocumented
470SSL_ERROR_SYSCALL: SSLErrorNumber  # undocumented
471SSL_ERROR_WANT_CONNECT: SSLErrorNumber  # undocumented
472SSL_ERROR_WANT_READ: SSLErrorNumber  # undocumented
473SSL_ERROR_WANT_WRITE: SSLErrorNumber  # undocumented
474SSL_ERROR_WANT_X509_LOOKUP: SSLErrorNumber  # undocumented
475SSL_ERROR_ZERO_RETURN: SSLErrorNumber  # undocumented
476
477def get_protocol_name(protocol_code: int) -> str: ...
478
479if sys.version_info < (3, 9):
480    AF_INET: int
481PEM_FOOTER: str
482PEM_HEADER: str
483SOCK_STREAM: int
484SOL_SOCKET: int
485SO_TYPE: int
486