/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIInterfaceRequestor;
interface nsITlsHandshakeCallbackListener;
interface nsITransportSecurityInfo;
interface nsIX509Cert;

%{C++
#include "nsStringFwd.h"
#include "nsTArrayForwardDeclare.h"
%}
[ref] native nsCStringTArrayRef(nsTArray<nsCString>);

// An interface describing an object that controls and holds information about
// a TLS handshake.
// NB: The implementations of this interface may only be used on the socket
// thread (except for asyncGetSecurityInfo);
[scriptable, builtinclass, uuid(418265c8-654e-4fbb-ba62-4eed27de1f03)]
interface nsITLSSocketControl : nsISupports {
    void proxyStartSSL();
    void StartTLS();

    /* NPN (Next Protocol Negotiation) is a mechanism for
       negotiating the protocol to be spoken inside the SSL
       tunnel during the SSL handshake. The NPNList is the list
       of offered client side protocols. setNPNList() needs to
       be called before any data is read or written (including the
       handshake to be setup correctly. The server determines the
       priority when multiple matches occur, but if there is no overlap
       the first protocol in the list is used. */

    [noscript] void setNPNList(in nsCStringTArrayRef aNPNList);

    /* For 0RTT we need to know the alpn protocol selected for the last tls
     * session. This function will return a value if applicable or an error
     * NS_ERROR_NOT_AVAILABLE.
     */
    ACString getAlpnEarlySelection();

    /* If 0RTT handshake was applied and some data has been sent, as soon as
     * the handshake finishes this attribute will be set to appropriate value.
     */
    readonly attribute bool earlyDataAccepted;

    /* When 0RTT is performed, PR_Write will not drive the handshake forward.
     * It must be forced by calling this function.
     */
    void driveHandshake();

    /* Determine if a potential SSL connection to hostname:port with
     * a desired NPN negotiated protocol of npnProtocol can use the socket
     * associated with this object instead of making a new one. And if so, combine
     * them.
     */
    boolean joinConnection(
      in ACString npnProtocol, /* e.g. "h2" */
      in ACString hostname,
      in long port);

    /* just like JoinConnection() except do not mark a successful test as joined.
     */
    boolean testJoinConnection(
      in ACString npnProtocol, /* e.g. "h2" */
      in ACString hostname,
      in long port);

    /* Determine if existing connection should be trusted to convey information about
     * a hostname.
     */
    boolean isAcceptableForHost(in ACString hostname);

    /* The Key Exchange Algorithm is used when determining whether or
       not HTTP/2 can be used.

       After a handshake is complete it can be read from KEAUsed.
       The values correspond to the SSLKEAType enum in NSS or the
       KEY_EXCHANGE_UNKNOWN constant defined below.

       KEAKeyBits is the size/security-level used for the KEA.
    */

    [infallible] readonly attribute short KEAUsed;
    [infallible] readonly attribute unsigned long KEAKeyBits;

    const short KEY_EXCHANGE_UNKNOWN = -1;

    /*
     * The original flags from the socket provider.
     */
    readonly attribute uint32_t providerFlags;

    /* These values are defined by TLS. */
    const short SSL_VERSION_3   = 0x0300;
    const short TLS_VERSION_1   = 0x0301;
    const short TLS_VERSION_1_1 = 0x0302;
    const short TLS_VERSION_1_2 = 0x0303;
    const short TLS_VERSION_1_3 = 0x0304;
    const short SSL_VERSION_UNKNOWN = -1;

    [infallible] readonly attribute short SSLVersionUsed;
    [infallible] readonly attribute short SSLVersionOffered;

    /* These values match the NSS defined values in sslt.h */
    const short SSL_MAC_UNKNOWN = -1;
    const short SSL_MAC_NULL    = 0;
    const short SSL_MAC_MD5     = 1;
    const short SSL_MAC_SHA     = 2;
    const short SSL_HMAC_MD5    = 3;
    const short SSL_HMAC_SHA    = 4;
    const short SSL_HMAC_SHA256 = 5;
    const short SSL_MAC_AEAD    = 6;

    [infallible] readonly attribute short MACAlgorithmUsed;

    /**
     * If set to true before the server requests a client cert
     * no cert will be sent.
     */
    [notxpcom, nostdcall] attribute boolean denyClientCert;

    /**
     * True iff a client cert has been sent to the server - i.e. this
     * socket has been client-cert authenticated.
     */
    [infallible] readonly attribute boolean clientCertSent;

    /*
     * failedVerification is true if any enforced certificate checks have failed.
     * Connections that have not yet tried to verify, or are using acceptable
     * exceptions will all return false.
     */
    [infallible] readonly attribute boolean failedVerification;

    /*
     * esniTxt is a string that consists of the concatenated _esni. TXT records.
     * This is a base64 encoded ESNIKeys structure.
     */
    attribute ACString esniTxt;

    /*
     * echConfig is defined for conveying the ECH configuration.
     * This is encoded in base64.
     */
    attribute ACString echConfig;

    /**
     * The echConfig that should be used to retry for the connection setup.
     */
    readonly attribute ACString retryEchConfig;

    /**
     * Disable early data.
     */
    [noscript] void disableEarlyData();

    [noscript] void setHandshakeCallbackListener(in nsITlsHandshakeCallbackListener callback);

    /**
     * The id used to uniquely identify the connection to the peer.
     */
    readonly attribute ACString peerId;

    /**
     * The securityInfo of the TLS handshake.
     */
    readonly attribute nsITransportSecurityInfo securityInfo;

    /**
     * Asynchronously obtain the securityInfo of the TLS handshake. Resolves
     * with an nsITransportSecurityInfo. This should probably only be used in
     * tests, where JS running on the main thread cannot access any of the
     * other fields of nsITLSSocketControl.
     */
    [implicit_jscontext, must_use]
    Promise asyncGetSecurityInfo();
};