/* -*- 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"
#include "nsIVariant.idl"

/**
 * Callback type used to notify callers that an operation performed by
 * nsICertStorage has completed. Indicates the result of the requested
 * operation, as well as any data returned by the operation.
 */
[scriptable, function, uuid(3f8fe26a-a436-4ad4-9c1c-a53c60973c31)]
interface nsICertStorageCallback : nsISupports {
  [must_use]
  void done(in nsresult rv, in nsIVariant result);
};

/**
 * A base interface for representing the revocation state of a certificate.
 * Implementing this interface by itself is insufficient; your type must
 * implement an inheriting interface that specifies the certificate by issuer
 * and serial number or by subject and public key hash.
 * Set state to nsICertStorage.STATE_UNSET to mark the certificate as not revoked.
 * Set state to nsICertStorage.STATE_ENFORCE to mark the certificate as revoked.
 */
[scriptable, uuid(96db6fd7-6b64-4a5a-955d-310bd9ca4234)]
interface nsIRevocationState : nsISupports {
  readonly attribute short state;
};

/**
 * An interface representing the revocation state of a certificate by issuer
 * and serial number. Both issuer name and serial number are base64-encoded.
 */
[scriptable, uuid(23ce3546-f1b9-46f6-8de3-77704da5702f)]
interface nsIIssuerAndSerialRevocationState : nsIRevocationState {
    readonly attribute ACString issuer;
    readonly attribute ACString serial;
};

/**
 * An interface representing the revocation state of a certificate by subject
 * and pub key hash (the hash algorithm should be SHA-256). Both subject name
 * and public key hash are base64-encoded.
 */
[scriptable, uuid(e78b51b4-6fa4-41e2-92ce-e9404f541e96)]
interface nsISubjectAndPubKeyRevocationState : nsIRevocationState {
    readonly attribute ACString subject;
    readonly attribute ACString pubKey;
};

/**
 * An interface representing the id and timestamp fields from an RFC 6962
 * SignedCertificateTimestamp struct.
 * logID is the id field.
 * timestamp is the timestamp field.
 */
[uuid(9676cfc4-6e84-11ec-a30d-d3cd0af86e01)]
interface nsICRLiteTimestamp: nsISupports {
    readonly attribute Array<octet> logID;
    readonly attribute unsigned long long timestamp;
};

/**
 * An interface representing a certificate to add to storage. Consists of the
 * base64-encoded DER bytes of the certificate (cert), the base64-encoded DER
 * bytes of the subject distinguished name of the certificate (subject), and the
 * trust of the certificate (one of the nsICertStorage.TRUST_* constants).
 * (Note that this implementation does not validate that the given subject DN
 * actually matches the subject DN of the certificate, nor that the given cert
 * is a valid DER X.509 certificate.)
 */
[scriptable, uuid(27b66f5e-0faf-403b-95b4-bc11691ac50d)]
interface nsICertInfo : nsISupports {
  readonly attribute ACString cert;
  readonly attribute ACString subject;
  readonly attribute short trust;
};

[scriptable, uuid(327100a7-3401-45ef-b160-bf880f1016fd)]
interface nsICertStorage : nsISupports {
  const octet DATA_TYPE_REVOCATION = 1;
  const octet DATA_TYPE_CERTIFICATE = 2;
  const octet DATA_TYPE_CRLITE = 3;
  const octet DATA_TYPE_CRLITE_FILTER_FULL = 4;
  const octet DATA_TYPE_CRLITE_FILTER_INCREMENTAL = 5;

  /**
   * Asynchronously check if the backing storage has stored data of the given
   * type in the past. This is useful if the backing storage may have had to
   * have been deleted and recreated (as in bug 1546361 when we discovered that
   * moving from a 32-bit binary to a 64-bit binary caused the DB to become
   * unreadable, thus necessitating its deletion and recreation).
   */
  [must_use]
  void hasPriorData(in octet type, in nsICertStorageCallback callback);

  const short STATE_UNSET = 0;
  const short STATE_ENFORCE = 1;
  const short STATE_NOT_ENROLLED = 2;
  const short STATE_NOT_COVERED = 3;
  const short STATE_NO_FILTER = 4;

  /**
   * Asynchronously set the revocation states of a set of certificates.
   * The given callback is called with the result of the operation when it
   * completes.
   * Must only be called from the main thread.
   */
  [must_use]
  void setRevocations(in Array<nsIRevocationState> revocations,
                      in nsICertStorageCallback callback);

  /**
   * Get the revocation state of a certificate. STATE_UNSET indicates the
   * certificate is not revoked. STATE_ENFORCE indicates the certificate is
   * revoked.
   * issuer - issuer name, DER encoded
   * serial - serial number, DER encoded
   * subject - subject name, DER encoded
   * pubkey - public key, DER encoded
   * In gecko, must not be called from the main thread. See bug 1541212.
   * xpcshell tests may call this from the main thread.
   */
  [must_use]
  short getRevocationState(in Array<octet> issuer,
                           in Array<octet> serial,
                           in Array<octet> subject,
                           in Array<octet> pubkey);

  /**
   * Given the contents of a new CRLite filter, replaces any existing filter
   * with the new one. Also clears any previously-set incremental revocation
   * updates ("deltas").
   */
  [must_use]
  void setFullCRLiteFilter(in Array<octet> filter,
                           in nsICertStorageCallback callback);

  /**
   * Given the DER-encoded issuer subject public key info, the bytes of the
   * value of the serial number (so, not including the DER tag and length) of a
   * certificate, and the timestamps from that certificate's embedded SCTs,
   * returns the result of looking up the corresponding entry in the
   * currently-saved CRLite filter (if any).
   * Returns
   *    - STATE_ENFORCE if the lookup indicates the certificate is revoked via CRLite,
   *    - STATE_UNSET if the lookup indicates the certificate is not revoked via CRLite,
   *    - STATE_NOT_ENROLLED if the issuer is not enrolled in CRLite, or
   *    - STATE_NOT_COVERED if the issuer is enrolled but the provided timestamps indicate
   *      that the serial number is not covered by the current CRLite filter.
   *    - STATE_NO_FILTER if there is no (usable) CRLite filter.
   * No lookup is performed in the STATE_NOT_ENROLLED and STATE_NOT_COVERED cases.
   */
  [must_use, noscript]
  short getCRLiteRevocationState(in Array<octet> issuerSPKI,
                                 in Array<octet> serialNumber,
                                 in Array<nsICRLiteTimestamp> timestamps);

  /**
   * Add a new CRLite filter for consideration in revocation checks. This
   * filter is treated as a delta update to the current full filter. Calling
   * this function will not remove the existing full filter, stashes, or delta
   * updates. A copy of the new filter will be written to the user's
   * security_state directory with the given filename.
   */
  [must_use]
  void addCRLiteDelta(in Array<octet> delta, in ACString filename, in nsICertStorageCallback callback);

  /**
   * Mark CRLite filters as fresh. For use in tests only.
   */
  [must_use]
  void testNoteCRLiteUpdateTime(in nsICertStorageCallback callback);

  /**
   * Trust flags to use when adding a adding a certificate.
   * TRUST_INHERIT indicates a certificate inherits trust from another
   * certificate.
   * TRUST_ANCHOR indicates the certificate is a root of trust.
   */
  const short TRUST_INHERIT = 0;
  const short TRUST_ANCHOR = 1;

  /**
   * Asynchronously add a list of certificates to the backing storage.
   * See the documentation for nsICertInfo.
   * The given callback is called with the result of the operation when it
   * completes.
   * Must only be called from the main thread.
   */
  [must_use]
  void addCerts(in Array<nsICertInfo> certs, in nsICertStorageCallback callback);

  /**
   * Synchronously add a certificate to the backing storage.
   * See the documentation for nsICertInfo.
   * This is a helper which should only be called from tests.
   */
  void TestHelperAddCert(in ACString cert, in ACString subject, in short trust);

  /**
   * Asynchronously remove the certificates with the given sha-256 hashes from
   * the backing storage.
   * hashes is an array of base64-encoded bytes of the sha-256 hashes of each
   * certificate's bytes (DER-encoded).
   * The given callback is called with the result of the operation when it
   * completes.
   * Must only be called from the main thread.
   */
  [must_use]
  void removeCertsByHashes(in Array<ACString> hashes,
                           in nsICertStorageCallback callback);

  /**
   * Find all certificates in the backing storage with the given subject
   * distinguished name.
   * subject is the DER-encoded bytes of the subject distinguished name.
   * Returns an array of arrays of bytes, where each inner array corresponds to
   * the DER-encoded bytes of a certificate that has the given subject (although
   * as these certificates were presumably added via addCertBySubject, this
   * aspect is never actually valided by nsICertStorage).
   * Must not be called from the main thread. See bug 1541212.
   */
  [must_use]
  Array<Array<octet> > findCertsBySubject(in Array<octet> subject);

  /**
   * Check for presence of all certificates in backing storage identified
   * by the list of hashes. Returns true or false accordingly.
   * Must not be called from the main thread. See bug 1541212.
   */
  [must_use]
  boolean hasAllCertsByHash(in Array<Array<octet> > hashes);

  /**
   * Finds a certificate in backing storage, identified by SHA256 of the
   * DER-encoded bytes of the certificate. Returns an array of bytes
   * representing the DER-encoded bytes of the certificate.
   * Must not be called from the main thread. See bug 1541212.
   */
  [must_use]
  Array<octet> findCertByHash(in Array<octet> cert_hash);

  /**
   * Get the count of remaining async operations. Called to ensure we don't skip
   * or interrupt any operations during fast shutdown.
   * Must only be called from the main thread.
   */
  [must_use]
  int32_t GetRemainingOperationCount();
};