3.3.5.15.7 Handling a Content Information Retrieval Request

When the server receives a request that has an SMB2 header with a Command value equal to SMB2 IOCTL and a CtlCode of FSCTL_SRV_READ_HASH, message handling proceeds as follows:

The server MUST fail the SRV_READ_HASH request (section 2.2.31.2) with the error code specified in the following cases:

  • If the server does not support SRV_READ_HASH requests, it MUST fail the request with STATUS_NOT_SUPPORTED.<388>

  • If the server supports SRV_READ_HASH requests but does not have the branch cache feature available, it SHOULD<389> fail the request with STATUS_HASH_NOT_PRESENT.

  • The server MUST fail the request with error STATUS_BUFFER_TOO_SMALL if any of the following cases:

    • InputCount in the request is less than the size of a SRV_READ_HASH request

    • HashRetrievalType is SRV_HASH_RETRIEVE_HASH_BASED and MaxOutputResponse in the request is less than the size of the SRV_HASH_RETRIEVE_HASH_BASED structure

    • HashRetrievalType is SRV_HASH_RETRIEVE_FILE_BASED and MaxOutputResponse in the request is less than the size of the SRV_HASH_RETRIEVE_FILE_BASED structure

  • The server MUST fail the SRV_READ_HASH request with an error of STATUS_INVALID_PARAMETER in the following cases:

    • If the HashType field of the SRV_READ_HASH request is not equal to SRV_HASH_TYPE_PEER_DIST.

    • If the server implements only the SMB 2.1 dialect and the HashVersion field is not equal to SRV_HASH_VER_1.

    • If the server implements the SMB 3.x dialect family and the HashVersion field is not equal to either SRV_HASH_VER_1 or SRV_HASH_VER_2.

    • If the HashRetrievalType field is not equal to SRV_HASH_RETRIEVE_HASH_BASED or SRV_HASH_RETRIEVE_FILE_BASED.

    • If the HashVersion field is equal to SRV_HASH_VER_1 and the HashRetrievalType field is not equal to SRV_HASH_RETRIEVE_HASH_BASED.

    • If the HashVersion field is equal to SRV_HASH_VER_2 and the HashRetrievalType field is not equal to SRV_HASH_RETRIEVE_FILE_BASED.

  • If ServerHashLevel is HashDisableAll, the server MUST fail the SRV_READ_HASH request with error code STATUS_HASH_NOT_SUPPORTED.

  • If the HashRetrievalType is SRV_HASH_RETRIEVE_HASH_BASED the server MUST open the Content Information File from the object store for the object represented by Open.LocalOpen with the specified offset. If the Content Information File open fails, the server MUST fail the request with STATUS_HASH_NOT_PRESENT.

  • If the HashRetrievalType is SRV_HASH_RETRIEVE_FILE_BASED the server MUST open the Content Information File from the object store for the object represented by Open.LocalOpen. If the Content Information File open fails, the server MUST fail the request with STATUS_HASH_NOT_PRESENT.

  • If ServerHashLevel is HashEnableShare and Open.TreeConnect.Share.HashEnabled is FALSE, the server MUST fail the SRV_READ_HASH request with error code STATUS_HASH_NOT_SUPPORTED.

If HashRetrievalType is SRV_HASH_RETRIEVE_HASH_BASED, the Length MUST be set to min[(MaxOutputResponse-16), Length in the request]. If HashRetrievalType is SRV_HASH_RETRIEVE_FILE_BASED, the Length MUST be set to min[(MaxOutputResponse-24), Length in the request].

The server MUST open the Content Information File from the object store for the object represented by Open.LocalOpen and read Length number of bytes at the specified Offset. If the Content Information File open fails, the server MUST fail the SRV_READ_HASH request with the error code returned by object store.

If the Content Information File open succeeds, the server MUST verify the following:

  • If the Content Information File is empty, the server MUST fail the SRV_READ_HASH request with the error code STATUS_HASH_NOT_PRESENT.

  • If HashRetrievalType is SRV_HASH_RETRIEVE_HASH_BASED and the Offset field of the SRV_READ_HASH request is equal to or beyond the end of the Content Information File, the server MUST fail the SRV_READ_HASH request with error code STATUS_END_OF_FILE.

  • If the HashRetrievalType is SRV_HASH_RETRIEVE_FILE_BASED and Offset field of the SRV_READ_HASH request is equal to or beyond the end of the file represented by Open.LocalOpen, the server MUST fail the SRV_READ_HASH request with error code STATUS_END_OF_FILE.

  • The Content Information File MUST start with a valid HASH_HEADER as specified in section 2.2.32.4.1.

    • If the HashType field in the HASH_HEADER is not equal to the HashRetrievalType field of the SRV_READ_HASH request, the server MUST fail the SRV_READ_HASH request with the error code STATUS_HASH_NOT_PRESENT.

    • If the HashVersion field in the HASH_HEADER is not equal to the HashVersion field of the SRV_READ_HASH request, the server MUST fail the SRV_READ_HASH request with the error code STATUS_HASH_NOT_PRESENT.

    • If the Dirty field in the HASH_HEADER is a nonzero value, the server MUST fail the SRV_READ_HASH request with the error code STATUS_HASH_NOT_PRESENT.

    • If the server implements the SMB 3.x dialect family and the HashVersion field in the SRV_READ_HASH Request is SRV_HASH_VER_2, the server MUST set HashBlobLength in the HASH_HEADER to zero.

If the Content Information File is verified successfully, the server MUST construct an SMB2 IOCTL response following the syntax specified in section 2.2.32, with the following values:

  • CtlCode MUST be set to FSCTL_SRV_READ_HASH.

  • FileId.Persistent MUST be set to Open.DurableFileId.

  • FileId.Volatile MUST be set to Open.FileId.

  • InputOffset SHOULD be set to the offset, in bytes, from the beginning of the SMB2 header to the Buffer[] field of the response.

  • InputCount SHOULD be set to 0.

  • OutputOffset MUST be set to InputOffset + InputCount, rounded up to a multiple of 8.

  • OutputCount MUST be set to the size of SRV_READ_HASH Response, including the variable length for Content Information.

  • Flags MUST be set to zero.

  • If the HashRetrievalType is SRV_HASH_RETRIEVE_HASH_BASED, the server MUST copy a SRV_READ_HASH Response following the syntax specified in section 2.2.32.4.2 into the Buffer field at the OutputOffset computed above. The server MUST set the Offset to the Offset field in the SRV_READ_HASH request and BufferLength to the length of the returned content.

  • If the HashRetrievalType is SRV_HASH_RETRIEVE_FILE_BASED, the server MUST copy a SRV_READ_HASH Response following the syntax specified in section 2.2.32.4.3 into the Buffer field at the OutputOffset computed above. The server SHOULD<390> set the FileDataOffset and FileDataLength fields to the offset and length of the region of the object that is covered by the returned content. If the Offset field in the SRV_READ_HASH request is zero, the server MUST also copy the HASH_HEADER from the Content Information File, as specified in section 2.2.32.4.1, at the beginning of the Buffer[] field of the response.