ldap-to-oauth2/node_modules/@ldapjs/asn1/lib/ber/reader.js

'use strict'

const types = require('./types')
const bufferToHexDump = require('../buffer-to-hex-dump')

/**
 * Given a buffer of ASN.1 data encoded according to Basic Encoding Rules (BER),
 * the reader provides methods for iterating that data and decoding it into
 * regular JavaScript types.
 */
class BerReader {
  /**
   * The source buffer as it was passed in when creating the instance.
   *
   * @type {Buffer}
   */
  #buffer

  /**
   * The total bytes in the backing buffer.
   *
   * @type {number}
   */
  #size

  /**
   * An ASN.1 field consists of a tag, a length, and a value. This property
   * records the length of the current field.
   *
   * @type {number}
   */
  #currentFieldLength = 0

  /**
   * Records the offset in the buffer where the most recent {@link readSequence}
   * was invoked. This is used to facilitate slicing of whole sequences from
   * the buffer as a new {@link BerReader} instance.
   *
   * @type {number}
   */
  #currentSequenceStart = 0

  /**
   * As the BER buffer is read, this property records the current position
   * in the buffer.
   *
   * @type {number}
   */
  #offset = 0

  /**
   * @param {Buffer} buffer
   */
  constructor (buffer) {
    if (Buffer.isBuffer(buffer) === false) {
      throw TypeError('Must supply a Buffer instance to read.')
    }

    this.#buffer = buffer.subarray(0)
    this.#size = this.#buffer.length
  }

  get [Symbol.toStringTag] () { return 'BerReader' }

  /**
   * Get a buffer that represents the underlying data buffer.
   *
   * @type {Buffer}
   */
  get buffer () {
    return this.#buffer.subarray(0)
  }

  /**
   * The length of the current field being read.
   *
   * @type {number}
   */
  get length () {
    return this.#currentFieldLength
  }

  /**
   * Current read position in the underlying data buffer.
   *
   * @type {number}
   */
  get offset () {
    return this.#offset
  }

  /**
   * The number of bytes remaining in the backing buffer that have not
   * been read.
   *
   * @type {number}
   */
  get remain () {
    return this.#size - this.#offset
  }

  /**
   * Read the next byte in the buffer without advancing the offset.
   *
   * @return {number | null} The next byte or null if not enough data.
   */
  peek () {
    return this.readByte(true)
  }

  /**
   * Reads a boolean from the current offset and advances the offset.
   *
   * @param {number} [tag] The tag number that is expected to be read.
   *
   * @returns {boolean} True if the tag value represents `true`, otherwise
   * `false`.
   *
   * @throws When there is an error reading the tag.
   */
  readBoolean (tag = types.Boolean) {
    const intBuffer = this.readTag(tag)
    this.#offset += intBuffer.length
    const int = parseIntegerBuffer(intBuffer)

    return (int !== 0)
  }

  /**
   * Reads a single byte and advances offset; you can pass in `true` to make
   * this a "peek" operation (i.e. get the byte, but don't advance the offset).
   *
   * @param {boolean} [peek=false] `true` means don't move the offset.
   * @returns {number | null} The next byte, `null` if not enough data.
   */
  readByte (peek = false) {
    if (this.#size - this.#offset < 1) {
      return null
    }

    const byte = this.#buffer[this.#offset] & 0xff

    if (peek !== true) {
      this.#offset += 1
    }

    return byte
  }

  /**
   * Reads an enumeration (integer) from the current offset and advances the
   * offset.
   *
   * @returns {number} The integer represented by the next sequence of bytes
   * in the buffer from the current offset. The current offset must be at a
   * byte whose value is equal to the ASN.1 enumeration tag.
   *
   * @throws When there is an error reading the tag.
   */
  readEnumeration () {
    const intBuffer = this.readTag(types.Enumeration)
    this.#offset += intBuffer.length

    return parseIntegerBuffer(intBuffer)
  }

  /**
   * Reads an integer from the current offset and advances the offset.
   *
   * @param {number} [tag] The tag number that is expected to be read.
   *
   * @returns {number} The integer represented by the next sequence of bytes
   * in the buffer from the current offset. The current offset must be at a
   * byte whose value is equal to the ASN.1 integer tag.
   *
   * @throws When there is an error reading the tag.
   */
  readInt (tag = types.Integer) {
    const intBuffer = this.readTag(tag)
    this.#offset += intBuffer.length

    return parseIntegerBuffer(intBuffer)
  }

  /**
   * Reads a length value from the BER buffer at the given offset. This
   * method is not really meant to be called directly, as callers have to
   * manipulate the internal buffer afterwards.
   *
   * This method does not advance the reader offset.
   *
   * As a result of this method, the `.length` property can be read for the
   * current field until another method invokes `readLength`.
   *
   * Note: we only support up to 4 bytes to describe the length of a value.
   *
   * @param {number} [offset] Read a length value starting at the specified
   * position in the underlying buffer.
   *
   * @return {number | null} The position the buffer should be advanced to in
   * order for the reader to be at the start of the value for the field. See
   * {@link setOffset}. If the offset, or length, exceeds the size of the
   * underlying buffer, `null` will be returned.
   *
   * @throws When an unsupported length value is encountered.
   */
  readLength (offset) {
    if (offset === undefined) { offset = this.#offset }

    if (offset >= this.#size) { return null }

    let lengthByte = this.#buffer[offset++] & 0xff
    // TODO: we are commenting this out because it seems to be unreachable.
    // It is not clear to me how we can ever check `lenB === null` as `null`
    // is a primitive type, and seemingly cannot be represented by a byte.
    // If we find that removal of this line does not affect the larger suite
    // of ldapjs tests, we should just completely remove it from the code.
    /* if (lenB === null) { return null } */

    if ((lengthByte & 0x80) === 0x80) {
      lengthByte &= 0x7f

      // https://www.rfc-editor.org/rfc/rfc4511.html#section-5.1 prohibits
      // indefinite form (0x80).
      if (lengthByte === 0) { throw Error('Indefinite length not supported.') }

      // We only support up to 4 bytes to describe encoding length. So the only
      // valid indicators are 0x81, 0x82, 0x83, and 0x84.
      if (lengthByte > 4) { throw Error('Encoding too long.') }

      if (this.#size - offset < lengthByte) { return null }

      this.#currentFieldLength = 0
      for (let i = 0; i < lengthByte; i++) {
        this.#currentFieldLength = (this.#currentFieldLength << 8) +
          (this.#buffer[offset++] & 0xff)
      }
    } else {
    // Wasn't a variable length
      this.#currentFieldLength = lengthByte
    }

    return offset
  }

  /**
   * At the current offset, read the next tag, length, and value as an
   * object identifier (OID) and return the OID string.
   *
   * @param {number} [tag] The tag number that is expected to be read.
   *
   * @returns {string | null} Will return `null` if the buffer is an invalid
   * length. Otherwise, returns the OID as a string.
   */
  readOID (tag = types.OID) {
    // See https://web.archive.org/web/20221008202056/https://learn.microsoft.com/en-us/windows/win32/seccertenroll/about-object-identifier?redirectedfrom=MSDN
    const oidBuffer = this.readString(tag, true)
    if (oidBuffer === null) { return null }

    const values = []
    let value = 0

    for (let i = 0; i < oidBuffer.length; i++) {
      const byte = oidBuffer[i] & 0xff

      value <<= 7
      value += byte & 0x7f
      if ((byte & 0x80) === 0) {
        values.push(value)
        value = 0
      }
    }

    value = values.shift()
    values.unshift(value % 40)
    values.unshift((value / 40) >> 0)

    return values.join('.')
  }

  /**
   * Get a new {@link Buffer} instance that represents the full set of bytes
   * for a BER representation of a specified tag. For example, this is useful
   * when construction objects from an incoming LDAP message and the object
   * constructor can read a BER representation of itself to create a new
   * instance, e.g. when reading the filter section of a "search request"
   * message.
   *
   * @param {number} tag The expected tag that starts the TLV series of bytes.
   * @param {boolean} [advanceOffset=true] Indicates if the instance's internal
   * offset should be advanced or not after reading the buffer.
   *
   * @returns {Buffer|null} If there is a problem reading the buffer, e.g.
   * the number of bytes indicated by the length do not exist in the value, then
   * `null` will be returned. Otherwise, a new {@link Buffer} of bytes that
   * represents a full TLV.
   */
  readRawBuffer (tag, advanceOffset = true) {
    if (Number.isInteger(tag) === false) {
      throw Error('must specify an integer tag')
    }

    const foundTag = this.peek()
    if (foundTag !== tag) {
      const expected = tag.toString(16).padStart(2, '0')
      const found = foundTag.toString(16).padStart(2, '0')
      throw Error(`Expected 0x${expected}: got 0x${found}`)
    }

    const currentOffset = this.#offset
    const valueOffset = this.readLength(currentOffset + 1)
    if (valueOffset === null) { return null }
    const valueBytesLength = this.length

    const numTagAndLengthBytes = valueOffset - currentOffset

    // Buffer.subarray is not inclusive. We need to account for the
    // tag and length bytes.
    const endPos = currentOffset + valueBytesLength + numTagAndLengthBytes
    if (endPos > this.buffer.byteLength) {
      return null
    }
    const buffer = this.buffer.subarray(currentOffset, endPos)
    if (advanceOffset === true) {
      this.setOffset(currentOffset + (valueBytesLength + numTagAndLengthBytes))
    }

    return buffer
  }

  /**
   * At the current buffer offset, read the next tag as a sequence tag, and
   * advance the offset to the position of the tag of the first item in the
   * sequence.
   *
   * @param {number} [tag] The tag number that is expected to be read.
   *
   * @returns {number|null} The read sequence tag value. Should match the
   * function input parameter value.
   *
   * @throws If the `tag` does not match or if there is an error reading
   * the length of the sequence.
   */
  readSequence (tag) {
    const foundTag = this.peek()
    if (tag !== undefined && tag !== foundTag) {
      const expected = tag.toString(16).padStart(2, '0')
      const found = foundTag.toString(16).padStart(2, '0')
      throw Error(`Expected 0x${expected}: got 0x${found}`)
    }

    this.#currentSequenceStart = this.#offset
    const valueOffset = this.readLength(this.#offset + 1) // stored in `length`
    if (valueOffset === null) { return null }

    this.#offset = valueOffset
    return foundTag
  }

  /**
   * At the current buffer offset, read the next value as a string and advance
   * the offset.
   *
   * @param {number} [tag] The tag number that is expected to be read. Should
   * be `ASN1.String`.
   * @param {boolean} [asBuffer=false] When true, the raw buffer will be
   * returned. Otherwise, a native string.
   *
   * @returns {string | Buffer | null} Will return `null` if the buffer is
   * malformed.
   *
   * @throws If there is a problem reading the length.
   */
  readString (tag = types.OctetString, asBuffer = false) {
    const tagByte = this.peek()

    if (tagByte !== tag) {
      const expected = tag.toString(16).padStart(2, '0')
      const found = tagByte.toString(16).padStart(2, '0')
      throw Error(`Expected 0x${expected}: got 0x${found}`)
    }

    const valueOffset = this.readLength(this.#offset + 1) // stored in `length`
    if (valueOffset === null) { return null }
    if (this.length > this.#size - valueOffset) { return null }

    this.#offset = valueOffset

    if (this.length === 0) { return asBuffer ? Buffer.alloc(0) : '' }

    const str = this.#buffer.subarray(this.#offset, this.#offset + this.length)
    this.#offset += this.length

    return asBuffer ? str : str.toString('utf8')
  }

  /**
   * At the current buffer offset, read the next set of bytes represented
   * by the given tag, and return the resulting buffer. For example, if the
   * BER represents a sequence with a string "foo", i.e.
   * `[0x30, 0x05, 0x04, 0x03, 0x66, 0x6f, 0x6f]`, and the current offset is
   * `0`, then the result of `readTag(0x30)` is the buffer
   * `[0x04, 0x03, 0x66, 0x6f, 0x6f]`.
   *
   * @param {number} tag The tag number that is expected to be read.
   *
   * @returns {Buffer | null} The buffer representing the tag value, or null if
   * the buffer is in some way malformed.
   *
   * @throws When there is an error interpreting the buffer, or the buffer
   * is not formed correctly.
   */
  readTag (tag) {
    if (tag == null) {
      throw Error('Must supply an ASN.1 tag to read.')
    }

    const byte = this.peek()
    if (byte !== tag) {
      const tagString = tag.toString(16).padStart(2, '0')
      const byteString = byte.toString(16).padStart(2, '0')
      throw Error(`Expected 0x${tagString}: got 0x${byteString}`)
    }

    const fieldOffset = this.readLength(this.#offset + 1) // stored in `length`
    if (fieldOffset === null) { return null }

    if (this.length > this.#size - fieldOffset) { return null }
    this.#offset = fieldOffset

    return this.#buffer.subarray(this.#offset, this.#offset + this.length)
  }

  /**
   * Returns the current sequence as a new {@link BerReader} instance. This
   * method relies on {@link readSequence} having been invoked first. If it has
   * not been invoked, the returned reader will represent an undefined portion
   * of the underlying buffer.
   *
   * @returns {BerReader}
   */
  sequenceToReader () {
    // Represents the number of bytes that constitute the "length" portion
    // of the TLV tuple.
    const lengthValueLength = this.#offset - this.#currentSequenceStart
    const buffer = this.#buffer.subarray(
      this.#currentSequenceStart,
      this.#currentSequenceStart + (lengthValueLength + this.#currentFieldLength)
    )
    return new BerReader(buffer)
  }

  /**
   * Set the internal offset to a given position in the underlying buffer.
   * This method is to support manual advancement of the reader.
   *
   * @param {number} position
   *
   * @throws If the given `position` is not an integer.
   */
  setOffset (position) {
    if (Number.isInteger(position) === false) {
      throw Error('Must supply an integer position.')
    }
    this.#offset = position
  }

  /**
   * @param {HexDumpParams} params The `buffer` parameter will be ignored.
   *
   * @see bufferToHexDump
   */
  toHexDump (params) {
    bufferToHexDump({
      ...params,
      buffer: this.buffer
    })
  }
}

/**
 * Given a buffer that represents an integer TLV, parse it and return it
 * as a decimal value. This accounts for signedness.
 *
 * @param {Buffer} integerBuffer
 *
 * @returns {number}
 */
function parseIntegerBuffer (integerBuffer) {
  let value = 0
  let i
  for (i = 0; i < integerBuffer.length; i++) {
    value <<= 8
    value |= (integerBuffer[i] & 0xff)
  }

  if ((integerBuffer[0] & 0x80) === 0x80 && i !== 4) { value -= (1 << (i * 8)) }

  return value >> 0
}

module.exports = BerReader