@ndn/packet/lib/security/signed-interest-policy.d.ts

NDNts: Network Layer Packets

import { Interest } from "../interest.js";
import { SigInfo } from "../sig-info.js";
import { Signer, type Verifier } from "./signing.js";
/** Validation policy for SigInfo fields in signed Interest. */
export declare class SignedInterestPolicy {
    private readonly owned;
    private readonly trackedKeys;
    private readonly records;
    private readonly rules;
    /**
     * Constructor.
     * @param opts - Options.
     * @param rules -
     *  One or more rules created from {@link SignedInterestPolicy.Nonce},
     *  {@link SignedInterestPolicy.Time}, {@link SignedInterestPolicy.SeqNum}.
     */
    constructor(opts: SignedInterestPolicy.Options, ...rules: Rule[]);
    /**
     * Constructor.
     * @param rules -
     *  One or more rules created from {@link SignedInterestPolicy.Nonce},
     *  {@link SignedInterestPolicy.Time}, {@link SignedInterestPolicy.SeqNum}.
     */
    constructor(...rules: Rule[]);
    /**
     * Assign SigInfo fields on an Interest before signing.
     * @param key - Signing key object to associate state with; if omitted, use global state.
     */
    update(interest: Interest, key?: object): void;
    /**
     * Check SigInfo of an Interest.
     * @returns A function to save state after the Interest has passed all verifications.
     */
    check({ sigInfo }: Interest): () => void;
    /**
     * Wrap an Interest to update/check SigInfo during signing/verification.
     *
     * @remarks
     * During signing, global state is being used because signer key cannot be detected.
     */
    wrapInterest(interest: Interest): Signer.Signable & Verifier.Verifiable;
    /**
     * Wrap a Signer to update SigInfo when signing an Interest.
     *
     * @remarks
     * State is associated with the provided Signer.
     */
    makeSigner(inner: Signer): Signer;
    /** Wrap a Verifier to check the policy when verifying an Interest. */
    makeVerifier(inner: Verifier, { passData, passUnsignedInterest, }?: SignedInterestPolicy.WrapOptions): Verifier;
}
interface KeyState {
    nonces?: Set<string>;
    time?: number;
    seqNum?: bigint;
}
interface Rule {
    update: (si: SigInfo, state: KeyState) => void;
    check: (si: SigInfo, state: KeyState) => () => void;
}
export declare namespace SignedInterestPolicy {
    /** Constructor options. */
    interface Options {
        /**
         * How many distinct public keys to keep track.
         * Each different KeyLocator Name or KeyDigest is tracked separately.
         * @defaultValue 256
         *
         * @remarks
         * Minimum is 1.
         */
        trackedKeys?: number;
    }
    /** {@link SignedInterestPolicy.makeVerifier} options. */
    interface WrapOptions {
        /**
         * If true, non-Interest packets are passed through to the inner Verifier.
         * If false, non-Interest packets are rejected.
         * @defaultValue true
         */
        passData?: boolean;
        /**
         * If true, Interests without SigInfo are passed through to the inner Verifier.
         * If false, Interests without SigInfo are rejected.
         * @defaultValue false
         */
        passUnsignedInterest?: boolean;
    }
    /** {@link SignedInterestPolicy.Nonce} options. */
    interface NonceOptions {
        /**
         * Length of generated SigNonce.
         * @defaultValue 8
         *
         * @remarks
         * Minimum is 1.
         */
        nonceLength?: number;
        /**
         * Minimum required length of SigNonce.
         * @defaultValue 8
         *
         * @remarks
         * Minimum is 1.
         */
        minNonceLength?: number;
        /**
         * How many distinct SigNonce values to keep track, within each public key.
         * @defaultValue 256
         *
         * @remarks
         * Minimum is 1.
         */
        trackedNonces?: number;
    }
    /**
     * Create a rule to assign or check SigNonce.
     *
     * @remarks
     * This rule assigns a random SigNonce of `nonceLength` octets that does not duplicate
     * last `trackedNonces` values.
     *
     * This rule rejects an Interest on any of these conditions:
     * - SigNonce is absent.
     * - SigNonce has fewer than `minNonceLength` octets.
     * - SigNonce value duplicates any of last `trackedNonces` values.
     */
    function Nonce(opts?: NonceOptions): Rule;
    /** {@link SignedInterestPolicy.Time} options. */
    interface TimeOptions {
        /**
         * Maximum allowed clock offset in milliseconds.
         * @defaultValue 60000
         *
         * @remarks
         * Minimum is 0. However, setting to 0 is inadvisable because it would require consumer and
         * producer to have precisely synchronized clocks.
         */
        maxClockOffset?: number;
    }
    /**
     * Create a rule to assign or check SigTime.
     *
     * @remarks
     * This rule assigns SigTime to be same as current timestamp, but may increment if it
     * duplicates the previous value.
     *
     * This rule rejects an Interest on any of these conditions:
     * - SigTime is absent.
     * - SigTime differs from current timestamp by more than `maxClockOffset` milliseconds.
     * - SigTime value is less than or equal to a previous value.
     *
     * This check logic differs from NDN Packet Format v0.3 specification (as of 2020-September) in
     * that `maxClockOffset` is checked on every Interest rather than only the "initial" Interest.
     * It is the same behavior as ndn-cxx v0.7.1 implementation.
     * This logic offers better consistency as it has less dependency on internal state of the
     * SignedInterestPolicy. However, persistently sending more than 1000 signed Interests per second
     * would eventually push SigTime out of `maxClockOffset` range and cause rejections.
     */
    function Time(opts?: TimeOptions): Rule;
    /** {@link SignedInterestPolicy.SeqNum} options. */
    interface SeqNumOptions {
        /**
         * Initial sequence number.
         * @defaultValue 0n
         */
        initialSeqNum?: bigint;
    }
    /**
     * Create a rule to assign or check SigSeqNum.
     *
     * @remarks
     * This rule assigns SigSeqNum to `initialSegNum`, or increments from previous value.
     *
     * This rule rejects an Interest on any of these conditions:
     * - SigSeqNum is absent.
     * - SigSeqNum value is less than or equal to a previous value.
     */
    function SeqNum(opts?: SeqNumOptions): Rule;
}
export {};