awscrt.io

I/O library for awscrt.

All networking in awscrt is asynchronous. Long-running event-loop threads are used for concurrency.

class awscrt.io.LogLevel(value)

An enumeration.

NoLogs = 0
Fatal = 1
Error = 2
Warn = 3
Info = 4
Debug = 5
Trace = 6
awscrt.io.init_logging(log_level, file_name)

Initialize logging in awscrt.

Parameters:

  • log_level (LogLevel) – Display messages of this importance and higher. LogLevel.NoLogs will disable logging.

  • file_name (str) – Logging destination. To write to stdout or stderr pass ‘stdout’ or ‘stderr’ as strings. Otherwise, a file path is assumed.

class awscrt.io.EventLoopGroup(num_threads=None, cpu_group=None)

A collection of event-loops.

An event-loop is a thread for doing async work, such as I/O. Classes that need to do async work will ask the EventLoopGroup for an event-loop to use.

Parameters:

  • num_threads (Optional[int]) – Maximum number of event-loops to create. If unspecified, one is created for each processor on the machine.

  • cpu_group (Optional[int]) – Optional processor group to which all threads will be pinned. Useful for systems with non-uniform memory access (NUMA) nodes. If specified, the number of threads will be capped at the number of processors in the group.

shutdown_event

Signals when EventLoopGroup’s threads have all finished shutting down. Shutdown begins when the EventLoopGroup object is destroyed.

Type:

threading.Event

class awscrt.io.HostResolverBase

DNS host resolver.

class awscrt.io.DefaultHostResolver(event_loop_group, max_hosts=16)

Default DNS host resolver.

Parameters:

  • event_loop_group (EventLoopGroup) – EventLoopGroup to use.

  • max_hosts (int) – Max host names to cache.

class awscrt.io.ClientBootstrap(event_loop_group, host_resolver)

Handles creation and setup of client socket connections.

Parameters:
shutdown_event

Signals when the ClientBootstrap’s internal resources finish shutting down. Shutdown begins when the ClientBootstrap object is destroyed.

Type:

threading.Event

class awscrt.io.SocketDomain(value)

An enumeration.

IPv4 = 0
IPv6 = 1
Local = 2

Unix domain sockets (at at least something like them)

class awscrt.io.SocketType(value)

An enumeration.

Stream = 0

A streaming socket sends reliable messages over a two-way connection. This means TCP when used with SocketDomain.IPv4/6, and Unix domain sockets when used with SocketDomain.Local

DGram = 1

A datagram socket is connectionless and sends unreliable messages. This means UDP when used with SocketDomain.IPv4/6. SocketDomain.Local is not compatible with DGram

class awscrt.io.SocketOptions

Socket options.

domain

Socket domain.

Type:

SocketDomain

type

Socket type.

Type:

SocketType

connect_timeout_ms

Connection timeout, in milliseconds.

Type:

int

keep_alive

If set True, periodically transmit keepalive messages for detecting a disconnected peer.

Type:

bool

keep_alive_timeout_secs

Duration, in seconds, between keepalive transmissions in idle condition. If 0, then a default value is used.

Type:

int

keep_alive_interval_secs

Duration, in seconds, between keepalive retransmissions, if acknowledgement of previous keepalive transmission is not received. If 0, then a default value is used.

Type:

int

keep_alive_max_probes

If set, sets the number of keepalive probes allowed to fail before a connection is considered lost.

Type:

int

class awscrt.io.TlsVersion(value)

An enumeration.

SSLv3 = 0
TLSv1 = 1
TLSv1_1 = 2
TLSv1_2 = 3
TLSv1_3 = 4
DEFAULT = 128
class awscrt.io.TlsCipherPref(value)

TLS Cipher Preference.

Each TlsCipherPref represents an ordered list of TLS Ciphers to use when negotiating a TLS Connection. At present, the ability to configure arbitrary orderings of TLS Ciphers is not allowed, and only a curated list of vetted TlsCipherPref’s are exposed.

DEFAULT = 0

The underlying platform’s default TLS Cipher Preference ordering. This is usually the best option, as it will be automatically updated as the underlying OS or platform changes, and will always be supported on all platforms.

PQ_TLSv1_0_2021_05 = 6

A TLS Cipher Preference ordering that supports TLS 1.0 through TLS 1.3, and has Kyber Round 3 as its highest priority post-quantum key exchange algorithm. PQ algorithms in this preference list will always be used in hybrid mode, and will be combined with a classical ECDHE key exchange that is performed in addition to the PQ key exchange. This preference makes a best-effort to negotiate a PQ algorithm, but if the peer does not support any PQ algorithms the TLS connection will fall back to a single classical algorithm for key exchange (such as ECDHE or RSA).

NIST has announced that they plan to eventually standardize Kyber. However, the NIST standardization process might introduce minor changes that could cause the final Kyber standard to differ from the Kyber Round 3 implementation available in this preference list.

is_supported()

Return whether this Cipher Preference is available in the underlying platform’s TLS implementation

class awscrt.io.TlsContextOptions

Options to create a TLS context.

The static TlsContextOptions.create_X() methods provide common TLS configurations. A default-initialized TlsContextOptions has verify_peer set True.

min_tls_ver

Minimum TLS version to use. System defaults are used by default.

Type:

TlsVersion

cipher_pref

The TLS Cipher Preference to use. System defaults are used by default.

Type:

TlsCipherPref

verify_peer

Whether to validate the peer’s x.509 certificate.

Type:

bool

alpn_list

If set, names to use in Application Layer Protocol Negotiation (ALPN). ALPN is not supported on all systems, see is_alpn_available(). This can be customized per connection, via TlsConnectionOptions.set_alpn_list().

Type:

Optional[List[str]]

static create_client_with_mtls_from_path(cert_filepath, pk_filepath)

Create options configured for use with mutual TLS in client mode.

Both files are treated as PKCS #7 PEM armored. They are loaded from disk and stored in buffers internally.

Parameters:

  • cert_filepath (str) – Path to certificate file.

  • pk_filepath (str) – Path to private key file.

Returns:

TlsContextOptions

static create_client_with_mtls(cert_buffer, key_buffer)

Create options configured for use with mutual TLS in client mode.

Both buffers are treated as PKCS #7 PEM armored.

Parameters:

  • cert_buffer (bytes) – Certificate contents

  • key_buffer (bytes) – Private key contents.

Returns:

TlsContextOptions

static create_client_with_mtls_pkcs11(*, pkcs11_lib: Pkcs11Lib, user_pin: str | None, slot_id: int | None = None, token_label: str | None = None, private_key_label: str | None = None, cert_file_path: str | None = None, cert_file_contents=None)

Create options configured for use with mutual TLS in client mode, using a PKCS#11 library for private key operations.

NOTE: This configuration only works on Unix devices.

Keyword Arguments:

  • pkcs11_lib (Pkcs11Lib) – Use this PKCS#11 library

  • user_pin (str) – User PIN, for logging into the PKCS#11 token. Pass None to log into a token with a “protected authentication path”.

  • slot_id (Optional[int]) – ID of slot containing PKCS#11 token. If not specified, the token will be chosen based on other criteria (such as token label).

  • token_label (Optional[str]) – Label of the PKCS#11 token to use. If not specified, the token will be chosen based on other criteria (such as slot ID).

  • private_key_label (Optional[str]) – Label of private key object on PKCS#11 token. If not specified, the key will be chosen based on other criteria (such as being the only available private key on the token).

  • cert_file_path (Optional[str]) – Use this X.509 certificate (path to file on disk). The certificate must be PEM-formatted. The certificate may be specified by other means instead (ex: cert_file_contents)

  • cert_file_contents (Optional[Union[str, bytes, bytearray]]) – Use this X.509 certificate (contents in memory). The certificate must be PEM-formatted. The certificate may be specified by other means instead (ex: cert_file_path)

static create_client_with_mtls_pkcs12(pkcs12_filepath, pkcs12_password)

Create options configured for use with mutual TLS in client mode.

NOTE: This configuration only works on Apple devices.

Parameters:

  • pkcs12_filepath (str) – Path to PKCS #12 file. The file is loaded from disk and stored internally.

  • pkcs12_password (str) – Password to PKCS #12 file.

Returns:

TlsContextOptions

static create_client_with_mtls_windows_cert_store_path(cert_path)

Create options configured for use with mutual TLS in client mode, using a certificate in a Windows certificate store.

NOTE: This configuration only works on Windows devices.

Parameters:

cert_path (str) – Path to certificate in a Windows certificate store. The path must use backslashes and end with the certificate’s thumbprint. Example: CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6

Returns:

TlsContextOptions

static create_server_from_path(cert_filepath, pk_filepath)

Create options configured for use in server mode.

Both files are treated as PKCS #7 PEM armored. They are loaded from disk and stored in buffers internally.

Parameters:

  • cert_filepath (str) – Path to certificate file.

  • pk_filepath (str) – Path to private key file.

Returns:

TlsContextOptions

static create_server(cert_buffer, key_buffer)

Create options configured for use in server mode.

Both buffers are treated as PKCS #7 PEM armored.

Parameters:

  • cert_buffer (bytes) – Certificate contents.

  • key_buffer (bytes) – Private key contents.

Returns:

TlsContextOptions

static create_server_pkcs12(pkcs12_filepath, pkcs12_password)

Create options configured for use in server mode.

NOTE: This configuration only works on Apple devices.

Parameters:

  • pkcs12_filepath (str) – Path to PKCS #12 file.

  • pkcs12_password (str) – Password to PKCS #12 file.

Returns:

TlsContextOptions

override_default_trust_store_from_path(ca_dirpath=None, ca_filepath=None)

Override default trust store.

Parameters:

  • ca_dirpath (Optional[str]) – Path to directory containing trusted certificates, which will overrides the default trust store. Only supported on Unix.

  • ca_filepath (Optional[str]) – Path to file containing PEM armored chain of trusted CA certificates.

override_default_trust_store(rootca_buffer)

Override default trust store.

Parameters:

rootca_buffer (bytes) – PEM armored chain of trusted CA certificates.

class awscrt.io.ClientTlsContext(options)

Client TLS context.

A context is expensive, but can be used for the lifetime of the application by all outgoing connections that wish to use the same TLS configuration.

Parameters:

options (TlsContextOptions) – Configuration options.

new_connection_options()

Create a TlsConnectionOptions that makes use of this TLS context.

Returns:

TlsConnectionOptions

class awscrt.io.TlsConnectionOptions(tls_ctx)

Connection-specific TLS options.

Note that, while a TLS context is an expensive object, a TlsConnectionOptions is cheap.

Parameters:

tls_ctx (ClientTlsContext) – TLS context. A context can be shared by many connections.

tls_ctx

TLS context.

Type:

ClientTlsContext

set_alpn_list(alpn_list)

Set names to use in Application Layer Protocol Negotiation (ALPN).

This overrides any ALPN list on the TLS context, see TlsContextOptions.alpn_list. ALPN is not supported on all systems, see is_alpn_available().

Parameters:

alpn_list (List[str]) – List of protocol names.

set_server_name(server_name)

Set server name.

Sets name for TLS Server Name Indication (SNI). Name is also used for x.509 validation.

Parameters:

server_name (str) – Server name.

awscrt.io.is_alpn_available()

Returns True if Application Layer Protocol Negotiation (ALPN) is supported on this system.

class awscrt.io.InputStream(stream)

InputStream allows awscrt native code to read from Python binary I/O classes.

Parameters:

stream (io.IOBase) – Python binary I/O stream to wrap.

classmethod wrap(stream, allow_none=False)

Given some stream type, returns an InputStream.

Parameters:

  • stream (Union[io.IOBase, InputStream, None]) – Binary I/O stream to wrap.

  • allow_none (bool) – Whether to allow stream to be None. If False (default), and stream is None, an exception is raised.

Returns:

Union[InputStream, None] – If stream is already an InputStream, it is returned. Otherwise, an InputStream which wraps the stream is returned. If allow_none is True, and stream is None, then None is returned.

class awscrt.io.Pkcs11Lib(*, file: str, behavior: InitializeFinalizeBehavior | None = None)

Handle to a loaded PKCS#11 library.

For most use cases, a single instance of Pkcs11Lib should be used for the lifetime of your application.

Keyword Arguments:
class InitializeFinalizeBehavior(value)

An enumeration.

Controls how C_Initialize() and C_Finalize() are called on the PKCS#11 library.

DEFAULT = 0

Relaxed behavior that accommodates most use cases.

C_Initialize() is called on creation, and “already-initialized” errors are ignored. C_Finalize() is never called, just in case another part of your application is still using the PKCS#11 library.

OMIT = 1

Skip calling C_Initialize() and C_Finalize().

Use this if your application has already initialized the PKCS#11 library, and you do not want C_Initialize() called again.

STRICT = 2

C_Initialize() is called on creation and C_Finalize() is called on cleanup.

If C_Initialize() reports that’s it’s already initialized, this is treated as an error. Use this if you need perfect cleanup (ex: running valgrind with –leak-check).