diff options
Diffstat (limited to '')
-rw-r--r-- | security/manager/ssl/nsIDataStorage.idl | 119 |
1 files changed, 119 insertions, 0 deletions
diff --git a/security/manager/ssl/nsIDataStorage.idl b/security/manager/ssl/nsIDataStorage.idl new file mode 100644 index 0000000000..3fe2c87f77 --- /dev/null +++ b/security/manager/ssl/nsIDataStorage.idl @@ -0,0 +1,119 @@ +/* -*- 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 nsIDataStorage; +interface nsIDataStorageItem; + +[scriptable, uuid(71b49926-fd4e-43e2-ab8d-d9b049413c0b)] +interface nsIDataStorageManager : nsISupports { + // Because of its specialized nature, nsIDataStorage instances are limited to + // the following pre-defined set. To add a new type of data storage, add an + // entry to the enum and get review from someone on the security and privacy + // engineering team. + cenum DataStorage : 8 { + AlternateServices, + ClientAuthRememberList, + SiteSecurityServiceState, + }; + + nsIDataStorage get(in nsIDataStorageManager_DataStorage dataStorage); +}; + +/** + * nsIDataStorage is a threadsafe, generic, narrow string-based hash map that + * persists data on disk and additionally handles private (temporary) data. + * The file format is portable across architectures. If used in a context where + * there is no profile directory, data will not be persisted. + * + * Its lifecycle is as follows: + * - Use nsIDataStorageManager to obtain the nsIDataStorage of a particular + * purpose. Its backing file will be read on a background thread. + * - Should the profile directory not be available, (e.g. in xpcshell), + * nsIDataStorage will not read any persistent data. + * - When data in the nsIDataStorage changes, those changes will be written + * to the backing file on a background thread. If the program crashes or is + * closed unexpectedly before the write completes, the changes may be lost. + * If the changes were an update to previously stored data, the original data + * may be lost as well. A checksum associated with each entry helps identify + * incompletely written entries. + * - nsIDataStorage does not support transactions. Each entry is independent of + * the others. + * - When an nsIDataStorage instance observes the topic "profile-before-change" + * in anticipation of shutdown, no more changes will be written to the + * backing file. To ensure no data is lost, users of nsIDataStorage should + * not attempt to change any data after this point. + * If "profile-before-change" is not observed, this happens upon observing + * "xpcom-shutdown-threads". + * - To prevent unbounded memory and disk use, the number of entries in each + * table is limited to 2048. Evictions are handled in by a modified LRU scheme + * (see implementation comments). + * - Note that instances of nsIDataStorage have long lifetimes because they are + * strong observers of events and won't go away until the observer service + * does. + * + * For each key/value: + * - The key must have a length no more than 256. + * - The value have a length no more than 1024 (24 for the site security + * service state). + * The length limits are to prevent unbounded disk and memory usage, and + * nsIDataStorage will throw/return an error if given keys or values of + * excess length. + * Take care when storing data containing bytes that may be 0. When read + * from disk, all trailing 0 bytes from keys and values are stripped. + */ +[scriptable, uuid(fcbb5ec4-7134-4069-91c6-9378eff51e03)] +interface nsIDataStorage : nsISupports { + /** + * Data that is Persistent is saved on disk. Data that is Private is not + * saved. Private is meant to only be set and accessed from private contexts. + * It will be cleared upon observing the event "last-pb-context-exited". + */ + cenum DataType : 8 { + Persistent, + Private, + }; + + // Given a key and a type of data, returns a value. Returns + // NS_ERROR_NOT_AVAILABLE if the key is not present for that type of data. + // This operation may block the current thread until the background task + // reading the backing file from disk has completed. + ACString get(in ACString key, in nsIDataStorage_DataType type); + + // Give a key, value, and type of data, adds an entry as appropriate. + // Updates existing entries. + // This operation may block the current thread until the background task + // reading the backing file from disk has completed. + void put(in ACString key, in ACString value, in nsIDataStorage_DataType type); + + // Given a key and type of data, removes an entry if present. + // This operation may block the current thread until the background task + // reading the backing file from disk has completed. + void remove(in ACString key, in nsIDataStorage_DataType type); + + // Removes all entries of all types of data. + // This operation may block the current thread until the background task + // reading the backing file from disk has completed. + void clear(); + + // Returns true if this data storage is ready to be used. To avoid blocking + // when calling other nsIDataStorage functions, callers may wish to first + // ensure this function returns true. + bool isReady(); + + // Read all of the data items. + // This operation may block the current thread until the background task + // reading the backing file from disk has completed. + Array<nsIDataStorageItem> getAll(); +}; + +[scriptable, uuid(4501f984-0e3a-4199-a67e-7753649e93f1)] +interface nsIDataStorageItem : nsISupports { + readonly attribute ACString key; + readonly attribute ACString value; + readonly attribute nsIDataStorage_DataType type; +}; |