/* 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;

[scriptable, uuid(c6138514-f212-4747-98c2-7abfce3be293)]
interface nsIStrictTransportSecurityService : nsISupports
{
    /**
     * Parses a given HTTP header and records the results internally.
     * The format of the STS header is defined by the STS specification:
     * http://tools.ietf.org/html/draft-hodges-strict-transport-sec
     * and allows a host to specify that future requests on port 80 should be
     * upgraded to HTTPS.
     *
     * @param aSourceURI the URI of the resource with the HTTP header.
     * @param aHeader the HTTP response header specifying STS 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.
     * @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 processStsHeader(in nsIURI aSourceURI,
                          in string aHeader,
                          in uint32_t aFlags,
                          [optional] out unsigned long long aMaxAge,
                          [optional] out boolean aIncludeSubdomains);

    /**
     * Removes the STS state of a host, including the includeSubdomains state
     * that would affect subdomains.  This essentially removes STS state for
     * the domain tree rooted at this host.
     * @param aURI    the URI of the target host
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     */
    void removeStsState(in nsIURI aURI,
                        in uint32_t aFlags);

    /**
     * Checks if the given security info is for an STS host with a broken
     * transport layer (certificate errors like invalid CN).
     */
    boolean shouldIgnoreStsHeader(in nsISupports aSecurityInfo);

    /**
     * Checks whether or not the given hostname has STS state set.
     * The host is an STS host if either it has the STS permission, or one of
     * its super-domains has an STS "includeSubdomains" permission set.
     *
     * @param aHost the hostname (punycode) to query for STS state.
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     */
    boolean isStsHost(in string aHost, in uint32_t aFlags);

    /**
     * Checks whether or not the URI's hostname has STS state set.
     * The URI is an STS URI if either the host has the STS permission, or one
     * of its super-domains has an STS "includeSubdomains" permission set.
     * NOTE: this function makes decisions based only on the scheme and
     * host contained in the URI, and disregards other portions of the URI
     * such as path and port.
     *
     * @param aURI the URI to query for STS state.
     * @param aFlags  options for this request as defined in nsISocketProvider:
     *                  NO_PERMANENT_STORAGE
     */
    boolean isStsURI(in nsIURI aURI, in uint32_t aFlags);

};

%{C++
#define NS_STSSERVICE_CONTRACTID "@mozilla.org/stsservice;1"

#define STS_PERMISSION "sts/use"
#define STS_SUBDOMAIN_PERMISSION "sts/subd"
%}