palemoon-dev/platform/security/manager/ssl/nsISiteSecurityService.idl

/* 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 nsIURI;
interface nsIObserver;
interface nsIHttpChannel;
interface nsISSLStatus;

%{C++
#include "nsTArrayForwardDeclare.h"
class nsCString;
namespace mozilla
{
  namespace pkix
  {
    class Time;
  }
}
%}
[ref] native nsCStringTArrayRef(nsTArray<nsCString>);
[ref] native mozillaPkixTime(mozilla::pkix::Time);

[scriptable, uuid(91ea3803-9c79-45d9-97bf-88bc80269236)]
interface nsISiteSecurityService : nsISupports
{
    const uint32_t HEADER_HSTS = 0;
    const uint32_t HEADER_HPKP = 1; /* no longer used */
    const uint32_t HEADER_OMS = 2;

    const uint32_t Success = 0;
    const uint32_t ERROR_UNKNOWN = 1;
    const uint32_t ERROR_UNTRUSTWORTHY_CONNECTION = 2;
    const uint32_t ERROR_COULD_NOT_PARSE_HEADER = 3;
    const uint32_t ERROR_NO_MAX_AGE = 4;
    const uint32_t ERROR_MULTIPLE_MAX_AGES = 5;
    const uint32_t ERROR_INVALID_MAX_AGE = 6;
    const uint32_t ERROR_MULTIPLE_INCLUDE_SUBDOMAINS = 7;
    const uint32_t ERROR_INVALID_INCLUDE_SUBDOMAINS = 8;
    const uint32_t ERROR_INVALID_PIN = 9; /* no longer used */
    const uint32_t ERROR_MULTIPLE_REPORT_URIS = 10; /* no longer used */
    const uint32_t ERROR_PINSET_DOES_NOT_MATCH_CHAIN = 11; /* no longer used */
    const uint32_t ERROR_NO_BACKUP_PIN = 12; /* no longer used */
    const uint32_t ERROR_COULD_NOT_SAVE_STATE = 13;
    const uint32_t ERROR_ROOT_NOT_BUILT_IN = 14;

    /**
     * Parses a given HTTP header and records the results internally.
     * Currently two header types are supported: HSTS (aka STS) and HPKP
     * The format of the HSTS header is defined by the HSTS specification:
     * https://tools.ietf.org/html/rfc6797
     * and allows a host to specify that future HTTP requests should be
     * upgraded to HTTPS.
     * The format of the HPKP header is defined by the HPKP specification:
     * https://tools.ietf.org/html/rfc7469
     * and allows a host to specify a subset of trusted anchors to be used
     * in future HTTPS connections.
     *
     * @param aType the type of security header in question.
     * @param aSourceURI the URI of the resource with the HTTP header.
     * @param aSSLStatus the SSLStatus of the current channel
     * @param aHeader the HTTP response header specifying security data.
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     * @param aMaxAge the parsed max-age directive of the header.
     * @param aIncludeSubdomains the parsed includeSubdomains directive.
     * @param aFailureResult a more specific failure result if NS_ERROR_FAILURE
                             was returned.
     * @return NS_OK            if it succeeds
     *         NS_ERROR_FAILURE if it can't be parsed
     *         NS_SUCCESS_LOSS_OF_INSIGNIFICANT_DATA
     *                          if there are unrecognized tokens in the header.
     */
    void processHeader(in uint32_t aType,
                       in nsIURI aSourceURI,
                       in string aHeader,
                       in nsISSLStatus aSSLStatus,
                       in uint32_t aFlags,
                       [optional] out unsigned long long aMaxAge,
                       [optional] out boolean aIncludeSubdomains,
                       [optional] out uint32_t aFailureResult);

    /**
     * Same as processHeader but without checking for the security properties
     * of the connection. Use ONLY for testing.
     */
    void unsafeProcessHeader(in uint32_t aType,
                             in nsIURI aSourceURI,
                             in string aHeader,
                             in uint32_t aFlags,
                             [optional] out unsigned long long aMaxAge,
                             [optional] out boolean aIncludeSubdomains,
                             [optional] out uint32_t aFailureResult);

    /**
     * Given a header type, removes state relating to that header of a host,
     * including the includeSubdomains state that would affect subdomains.
     * This essentially removes the state for the domain tree rooted at this
     * host. If any preloaded information is present for that host, that
     * information will then be used instead of any other previously existing
     * state, unless the force parameter is set.
     *
     * @param aType   the type of security state in question
     * @param aURI    the URI of the target host
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     */
    void removeState(in uint32_t aType,
                     in nsIURI aURI,
                     in uint32_t aFlags);

    /**
     * See isSecureURI
     *
     * @param aType the type of security state in question.
     * @param aHost the hostname (punycode) to query for state.
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     * @param aCached true if we have cached information regarding whether or not
     *                  the host is HSTS, false otherwise.
     */
    boolean isSecureHost(in uint32_t aType,
                         in string aHost,
                         in uint32_t aFlags,
                         [optional] out boolean aCached);

    /**
     * Checks whether or not the URI's hostname has a given security state set.
     * For example, for HSTS:
     * The URI is an HSTS URI if either the host has the HSTS state set, or one
     * of its super-domains has the HSTS "includeSubdomains" flag set.
     * NOTE: this function makes decisions based only on the
     * host contained in the URI, and disregards other portions of the URI
     * such as path and port.
     *
     * @param aType the type of security state in question.
     * @param aURI the URI to query for STS state.
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     * @param aCached true if we have cached information regarding whether or not
     *                  the host is HSTS, false otherwise.
     */
    boolean isSecureURI(in uint32_t aType, in nsIURI aURI, in uint32_t aFlags,
                        [optional] out boolean aCached);

    /**
     * Removes all non-preloaded security state by resetting to factory-original
     * settings.
     */
    void clearAll();
};

%{C++
#define NS_SSSERVICE_CONTRACTID "@mozilla.org/ssservice;1"
%}