/* 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;
interface nsISimpleEnumerator;
%{C++
#include "nsStringFwd.h"
#include "nsTArrayForwardDeclare.h"
namespace mozilla
{
namespace pkix
{
class Time;
}
}
%}
[ref] native nsCStringTArrayRef(nsTArray<nsCString>);
[ref] native mozillaPkixTime(mozilla::pkix::Time);
[ref] native const_OriginAttributesRef(const mozilla::OriginAttributes);
// [infallible] attributes are only allowed on [builtinclass]
[scriptable, uuid(31313372-842c-4110-bdf1-6aea17c845ad), builtinclass]
interface nsISiteSecurityState : nsISupports
{
[must_use]
readonly attribute ACString hostname;
[infallible] readonly attribute long long expireTime;
[infallible] readonly attribute short securityPropertyState;
[infallible] readonly attribute boolean includeSubdomains;
[implicit_jscontext, must_use]
readonly attribute jsval originAttributes;
/*
* SECURITY_PROPERTY_SET and SECURITY_PROPERTY_UNSET correspond to indicating
* a site has or does not have the security property in question,
* respectively.
* SECURITY_PROPERTY_KNOCKOUT indicates a value on a preloaded
* list is being overridden, and the associated site does not have the
* security property in question.
* SECURITY_PROPERTY_NEGATIVE is used when we've gotten a negative result from
* HSTS priming.
*/
const short SECURITY_PROPERTY_UNSET = 0;
const short SECURITY_PROPERTY_SET = 1;
const short SECURITY_PROPERTY_KNOCKOUT = 2;
const short SECURITY_PROPERTY_NEGATIVE = 3;
};
// This has to be a builtinclass because it derives from a builtinclass.
[scriptable, uuid(9ff16e40-1029-496c-95c2-bc819872b216), builtinclass]
interface nsISiteHSTSState : nsISiteSecurityState
{
};
// This has to be a builtinclass because it derives from a builtinclass.
[scriptable, uuid(ae395078-c7d0-474d-b147-f4aa203a9b2c), builtinclass]
interface nsISiteHPKPState : nsISiteSecurityState
{
[must_use]
readonly attribute nsISimpleEnumerator sha256Keys;
};
[scriptable, uuid(275127f8-dbd7-4681-afbf-6df0c6587a01)]
interface nsISiteSecurityService : nsISupports
{
const uint32_t HEADER_HSTS = 0;
const uint32_t HEADER_HPKP = 1;
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;
const uint32_t ERROR_MULTIPLE_REPORT_URIS = 10;
const uint32_t ERROR_PINSET_DOES_NOT_MATCH_CHAIN = 11;
const uint32_t ERROR_NO_BACKUP_PIN = 12;
const uint32_t ERROR_COULD_NOT_SAVE_STATE = 13;
const uint32_t ERROR_ROOT_NOT_BUILT_IN = 14;
/**
* nsISiteSecurityService::IsSecureURI can optionally return a flag
* indicating the source of the HSTS cache entry, if it comes from the
* preload list, was seen naturally, or is a result of HSTS priming.
*/
const uint32_t SOURCE_UNKNOWN = 0;
const uint32_t SOURCE_PRELOAD_LIST = 1;
const uint32_t SOURCE_ORGANIC_REQUEST = 2;
/**
* 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 aHeader the HTTP response header specifying security data.
* @param aSSLStatus the SSLStatus of the current channel.
* @param aFlags options for this request as defined in nsISocketProvider:
* NO_PERMANENT_STORAGE
* @param aOriginAttributes the origin attributes that isolate this origin,
* (note that this implementation does not isolate
* by userContextId because of the risk of man-in-
* the-middle attacks before trust-on-second-use
* happens).
* @param aSource the source of the header, whether it was from the preload
* list, an organic header, or HSTS priming, or unknown.
* @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.
*/
[binaryname(ProcessHeader), noscript, must_use]
void processHeaderNative(in uint32_t aType,
in nsIURI aSourceURI,
in ACString aHeader,
in nsISSLStatus aSSLStatus,
in uint32_t aFlags,
in uint32_t aSource,
in const_OriginAttributesRef aOriginAttributes,
[optional] out unsigned long long aMaxAge,
[optional] out boolean aIncludeSubdomains,
[optional] out uint32_t aFailureResult);
[binaryname(ProcessHeaderScriptable), implicit_jscontext, optional_argc,
must_use]
void processHeader(in uint32_t aType,
in nsIURI aSourceURI,
in ACString aHeader,
in nsISSLStatus aSSLStatus,
in uint32_t aFlags,
in uint32_t aSource,
[optional] in jsval aOriginAttributes,
[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.
* @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
* @param aOriginAttributes the origin attributes that isolate this origin,
* (note that this implementation does not isolate
* by userContextId because of the risk of man-in-
* the-middle attacks before trust-on-second-use
* happens).
*/
[implicit_jscontext, optional_argc, must_use]
void removeState(in uint32_t aType,
in nsIURI aURI,
in uint32_t aFlags,
[optional] in jsval aOriginAttributes);
/**
* 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 aOriginAttributes the origin attributes that isolate this origin,
* (note that this implementation does not isolate
* by userContextId because of the risk of man-in-
* the-middle attacks before trust-on-second-use
* happens).
* @param aCached true if we have cached information about this host, even
* if the security state is false.
* @param aSource the source of the HSTS entry. One of SOURCE_PRELOAD_LIST,
* SOURCE_ORGANIC_REQUEST, SOURCE_HSTS_PRIMING, or
* SOURCE_UNKNOWN. Not implemented for HPKP.
*/
[binaryname(IsSecureURI), noscript, must_use]
boolean isSecureURINative(in uint32_t aType, in nsIURI aURI,
in uint32_t aFlags,
in const_OriginAttributesRef aOriginAttributes,
[optional] out boolean aCached,
[optional] out uint32_t aSource);
[binaryname(IsSecureURIScriptable), implicit_jscontext, optional_argc,
must_use]
boolean isSecureURI(in uint32_t aType, in nsIURI aURI, in uint32_t aFlags,
[optional] in jsval aOriginAttributes,
[optional] out boolean aCached,
[optional] out uint32_t aSource);
/**
* Removes all non-preloaded security state by resetting to factory-original
* settings.
*/
[must_use]
void clearAll();
/**
* Removes all preloaded security state.
*/
[must_use]
void clearPreloads();
/**
* Returns an array of sha256-hashed key pins for the given domain, if any.
* If these pins also apply to subdomains of the given domain,
* aIncludeSubdomains will be true. Pins returned are only for non-built-in
* pin entries.
*
* @param aHostname the hostname (punycode) to be queried about
* @param evalTime the time at which the pins should be valid. This is in
mozilla::pkix::Time which uses internally seconds since 0 AD.
* @param aOriginAttributes the origin attributes that isolate this origin,
* (note that this implementation does not isolate
* by userContextId because of the risk of man-in-
* the-middle attacks before trust-on-second-use
* happens).
* @param aPinArray the set of sha256-hashed key pins for the given domain
* @param aIncludeSubdomains true if the pins apply to subdomains of the
* given domain
*/
[noscript, must_use] boolean getKeyPinsForHostname(
in ACString aHostname,
in mozillaPkixTime evalTime,
in const_OriginAttributesRef aOriginAttributes,
out nsCStringTArrayRef aPinArray,
out boolean aIncludeSubdomains);
/**
* Set public-key pins for a host. The resulting pins will be permanent
* and visible from private and non-private contexts. These pins replace
* any already set by this mechanism or those built-in to Gecko.
*
* @param aHost the hostname (punycode) that pins will apply to
* @param aIncludeSubdomains whether these pins also apply to subdomains
* @param aExpires the time this pin should expire (millis since epoch)
* @param aPinCount number of keys being pinnned
* @param aSha256Pins array of hashed key fingerprints (SHA-256, base64)
* @param aIsPreload are these key pins for a preload entry? (false by
* default)
* @param aOriginAttributes the origin attributes that isolate this origin,
* (note that this implementation does not isolate
* by userContextId because of the risk of man-in-
* the-middle attacks before trust-on-second-use
* happens).
*/
[implicit_jscontext, optional_argc, must_use]
boolean setKeyPins(in ACString aHost, in boolean aIncludeSubdomains,
in int64_t aExpires, in unsigned long aPinCount,
[array, size_is(aPinCount)] in string aSha256Pins,
[optional] in boolean aIsPreload,
[optional] in jsval aOriginAttributes);
/**
* Set an HSTS preload entry for a host. The resulting entries will be
* permanent and visible from private and non-private contexts. These
* entries replace any already set by this mechanism or those built-in to
* Gecko.
*
* @param aHost the hostname (punycode) that the entry applies to
* @param aIncludeSubdomains whether this entry also applies to subdomains
* @param aExpires the time this entry should expire (millis since epoch)
*/
[must_use]
boolean setHSTSPreload(in ACString aHost,
in boolean aIncludesSubdomains,
in int64_t aExpires);
/**
* Returns an enumerator of the nsISiteSecurityService storage. Each item in
* the enumeration is a nsISiteSecurityState that can be QueryInterfaced to
* the appropriate nsISiteHSTSState or nsISiteHPKPState, depending on the
* provided type. Doesn't include preloaded entries (either the hard-coded
* ones or the preloaded-delivered-by-kinto ones).
*
* @param aType the type of security state in question.
*/
[must_use]
nsISimpleEnumerator enumerate(in uint32_t aType);
};
%{C++
#define NS_SSSERVICE_CONTRACTID "@mozilla.org/ssservice;1"
%}