🥮 mooncakes.io

    moonbitlang/core/async/tls does not have a README file

    ConnectionClosed

    source

    Error raised when the peer abnormally close the underlying transport in a TLS connection.

    TlsError

    source

    TLS related error
    impl Show for TlsError

    TlsError::to_string

    source
    fn TlsError::to_string(self : TlsError) -> String

    Tls

    source
    type Tls

    A TLS-encrypted connection
    impl BinaryReader for Tls
    impl BinaryWriter for Tls

    Tls::client

    source

    Create a TLS client that read from write to inner. client will block until TLS handshake to remote server completed.

    trust specifies which servers are trusted and how certificate validation is performed. See TrustedRoot for more details. The default is SystemRoot.

    If host is present, it will be used to verify the peer's certificate.

    If host is present and sni is true (true by default), Server Name Indication (SNI) field of TLS will be set to host. sni=false is currently unsupported on Windows.

    Tls::client_from_pair

    source

    Create a TLS client that read from r and write to w. client_from_pair will block until TLS handshake to remote server completed.

    trust specifies which servers are trusted and how certificate validation is performed. See TrustedRoot for more details. The default is SystemRoot.

    If host is present, it will be used to verify the peer's certificate.

    If host is present and sni is true (true by default), Server Name Indication (SNI) field of TLS will be set to host.

    Tls::close

    source
    fn Tls::close(self : Tls) -> Unit

    Close a TLS connection and release related resource. THIS FUNCTION MUST BE CALLED BEFORE CLOSING UNDERLYING TRANSPORT!!!

    Note that .close() does not provide reliable termination indication for the remote peer. If protected termination is desirable, call .terminate() before .close().

    Tls::drop_all

    source
    async fn Tls::drop_all(self : Tls) -> Int64

    Tls::drop_exactly

    source
    async fn Tls::drop_exactly(self : Tls, len : Int) -> Unit

    Tls::get_peer_certificate

    source
    fn Tls::get_peer_certificate(self : Tls) -> Bytes? raise

    Get the certificate of remote peer for a TLS connection in DER format. Note that even if nothing goes wrong, the certificate may not exist:

    • although rare, some TLS algorithm choice does not have a certificate
    • for connection without client certificate, the server does not have any peer certificate

    Therefore the return type is Bytes? instead of Bytes.

    Tls::peek

    source
    async fn Tls::peek(self : Tls) -> BytesView?

    Tls::peek_at_least

    source
    async fn Tls::peek_at_least(self : Tls, min_len : Int) -> BytesView

    Tls::peek_exactly

    source
    async fn Tls::peek_exactly(self : Tls, len : Int) -> BytesView

    Tls::peek_until

    source
    async fn Tls::peek_until(self : Tls, pattern : BytesView, include_delimiter? : Bool) -> BytesView?

    Tls::read

    source
    async fn Tls::read(self : Tls) -> Bytes?

    Tls::read_all

    source
    async fn Tls::read_all(self : Tls) -> Bytes

    Tls::read_at_least

    source
    async fn Tls::read_at_least(self : Tls, min_len : Int) -> Bytes

    Tls::read_exactly

    source
    async fn Tls::read_exactly(self : Tls, len : Int) -> Bytes

    Tls::read_into

    source
    async fn Tls::read_into(self : Tls, dst : FixedArray[Byte], offset? : Int, max_len? : Int) -> Int

    Tls::read_until

    source
    async fn Tls::read_until(self : Tls, pattern : BytesView, include_delimiter? : Bool) -> Bytes?

    Tls::server

    source
    #internal(internal, "do not use, for internal testing only")
    async fn[Inner : 
    BinaryReader     + 
    BinaryWriter     + 
    BinaryReaderImpl     + 
    BinaryWriterImpl    ] Tls::server(inner : Inner, private_key_file~ : String, private_key_type~ : X509FileType, certificate_file~ : String, certificate_type~ : X509FileType) -> Tls

    WARNING: this API is currently for testing only, it may block the whole thread while reading certificate, and may break any time in the future. DO NOT USE.

    Create a TLS server connection that read from and write to inner. server will block until TLS handshake with client completed.

    private_key_file, private_key_type specifies the private key of the server. certificate_file and certificate_type specifies the certificate of the server.

    Tls::server_endpoint_channel_binding

    source
    fn Tls::server_endpoint_channel_binding(self : Tls) -> Bytes raise

    Return tls-server-endpoint type of channel binding data for this TLS connection, according to RFC 5929. Not all TLS connection has such thing as a server certificate, so tls-unique is the more recommended approach when available.

    Tls::server_from_pair

    source
    #internal(internal, "do not use, for internal testing only")
    async fn[R : 
    BinaryReader     + 
    BinaryReaderImpl    , W : 
    BinaryWriter     + 
    BinaryWriterImpl    ] Tls::server_from_pair(r : R, w : W, private_key_file~ : String, private_key_type~ : X509FileType, certificate_file~ : String, certificate_type~ : X509FileType) -> Tls

    WARNING: this API is currently for testing only, it may block the whole thread while reading certificate, and may break any time in the future. DO NOT USE.

    Create a TLS server connection that read from r and write to w. server_from_pair will block until TLS handshake with client completed.

    private_key_file, private_key_type specifies the private key of the server. certificate_file and certificate_type specifies the certificate of the server.

    Tls::shutdown

    source
    async fn Tls::shutdown(self : Tls) -> Unit

    Shutdown a TLS connection gracefully. This function MUST be called before close, and MUST NOT be called if the TLS connection fail with other error.

    shutdown is used to initiate the closure of a TLS connection. So there is no need to call shutdown if you receive EOF from the peer.

    When calling shutdown, there may still be pending data sent by the peer on the wire. So to close a TLS connection cleanly, make sure you read from the connection until EOF after calling shutdown.

    Note that the main purpose of TLS shutdown is to ensure integrity before closing the underlying transport. So if your application protocol has its own way of ensuring integrity (e.g. Content-Length in HTTP/1.1), it is not necessary to call shutdown.

    Tls::unique_channel_binding

    source
    fn Tls::unique_channel_binding(self : Tls) -> Bytes raise

    Return tls-unique type of channel binding data for this TLS connection, according to RFC 5929

    Tls::write

    source
    async fn Tls::write(self : Tls, data : BytesView) -> Unit

    Tls::write_reader

    source
    async fn Tls::write_reader(self : Tls, reader : &
    BinaryReader    ) -> Unit

    TrustedRoot

    source
    pub(all) enum TrustedRoot {
      NoVerification
      SystemRoot
      CustomPemFile(String)
    }

    Specify the trusted root when performing TLS certificate validation.

    • NoVerification: disable certificate validation. This destroys the whole purpose of using TLS and should only be used for testing purpose.

    • SystemRoot: use the default trusted root of the system

    • CustomPemFile(name): use the certificates in the PEM file name exclusively as trusted root. Useful for connecting to services whose certificates are issued by a private or self-signed root.

    X509FileType

    source
    pub(all) enum X509FileType {
      PEM
      ANS1
    }

    Encoding type for a X509 certificate file

    rand_bytes

    source
    #internal(internal, "for internal use only")
    fn rand_bytes(num : Int) -> Bytes raise

    Generate cryptographically secure random bytes using OpenSSL's RAND_bytes Returns 1 on success, 0 on failure

    sha1

    source
    #internal(internal, "for internal use only")
    fn sha1(src : Bytes) -> Bytes raise

    Source Files