summaryrefslogtreecommitdiffstats
path: root/security/manager/ssl/nsISiteSecurityService.idl
blob: 6677792e8d0fc2413e44d383c29f5d44d940faeb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
/* 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(233908bd-6741-4474-a6e1-f298c6ce9eaf)]
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;

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

    /**
     * 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 hosname (punycode) to be queried about
     * @param the time at which the pins should be valid. This is in
              mozilla::pkix::Time which uses internally seconds since 0 AD.
     * @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] boolean getKeyPinsForHostname(in string aHostname,
                                             in mozillaPkixTime evalTime,
                                             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)
     */
     boolean setKeyPins(in string aHost, in boolean aIncludeSubdomains,
                        in int64_t aExpires, in unsigned long aPinCount,
                        [array, size_is(aPinCount)] in string aSha256Pins,
                        [optional] in boolean aIsPreload);
};

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