Add API for reading/writing PDB Checksum Debug Directory entry

[tmat]

Background

The CodeView debug directory entry in PE/COFF file associates the PE file with one or more PDBs. The CodeView entry and the PDB both store the same PDB ID (for Portable PDB it's 20B for Windows PDB it's 16B of data). Debuggers, symbol servers and other tools use the PDB ID to match the PE file with the PDB.

Although the PDB ID is good enough for finding the right PDB for the PE file it is not good enough for validating that the PDB has not been maliciously modified. PDB Checksum is a new debug directory record that can be used for such validation.

PDB Checksum comprises of crypto hash algorithm name and the hash of the PDB content. See
Specification for details.

Proposed APIs

namespace System.Reflection.PortableExecutable
{
    public enum DebugDirectoryEntryType
    {
        // ...
        PdbChecksum = 19,
        // ...
    }

    public class DebugDirectoryBuilder
    {
        // ...

        // Adds a custom entry - useful for emitting record for which specific API is not available (yet)
        public void AddEntry(DebugDirectoryEntryType type, uint version, uint stamp);

        // Adds a custom entry with data - useful for emitting record for which specific API is not available (yet)
        public void AddEntry<TData>(DebugDirectoryEntryType type, uint version, uint stamp, TData data, Action<BlobBuilder, TData> dataSerializer);

        // Adds PDB Checksum entry
        public void AddPdbChecksumEntry(string algorithmName, ImmutableArray<byte> checksum);

        // ...
   }

    public readonly struct PdbChecksumDebugDirectoryData
    {
        /// <summary>
        /// Checksum algorithm name.
        /// </summary>
        public string AlgorithmName { get; }

        /// <summary>
        /// GUID (Globally Unique Identifier) of the associated PDB.
        /// </summary>
        public ImmutableArray<byte> Checksum { get; }
    }

    public class PEReader
    {
        // ...

        public PdbChecksumDebugDirectoryData ReadPdbChecksumDebugDirectoryData(DebugDirectoryEntry 
entry);
        // ...
    }
}

In addition add the following API to make it easy for the reader of a Portable PDB to determine where the PDB ID is located within the PDB. This information is required when validating PDB checksum.

namespace System.Reflection.Metadata
{
    public sealed class DebugMetadataHeader
    {
        // ...

        /// <summary>
        /// Gets the offset (in bytes) from the start of the metadata blob to the start of the <see cref="Id"/> blob.
        /// </summary>
        public int IdStartOffset { get; }

        // ...
    }
}

[tmat]

@nguerrera

[nguerrera]

Looks good.

readonly struct

Can we go back and add this all over the place or is it a breaking change?

[tmat]

@nguerrera I has already been added all over the place :)

[nguerrera]

Oh, yay!

[tmat]

@karelz When is the next API review session that can pick this up?

[karelz]

@tmat we should be able to review on Tue. Ping Immo just in case (he's back from vacation on Mon). I'll be on vacation starting Tue.

[tmat]

@karelz Cool. Thanks

[terrajobst]

Video

We just took a look. Looks good as proposed. Questions that came up:

• Should the ImmtuableArray<byte> be a ReadOnlySpan<byte>. We assumed the answer to be no, as S.R.M doesn't depend on span yet and you need to ship downlevel. Once you spannify S.R.M we can still add overloads.
• IdStartOffset are 32 bit enough? Assumption is yes, but hey :-)

[tmat]

Should the ImmtuableArray be a ReadOnlySpan. We assumed the answer to be no, as S.R.M doesn't depend on span yet and you need to ship downlevel. Once you spannify S.R.M we can still add overloads.

The assumption is correct.

IdStartOffset are 32 bit enough? Assumption is yes, but hey :-)

Yes, ECMA metadata blob can't be larger than 2GB and Portable PDB is an ECMA metadata blob.

[tmat]

@terrajobst @karelz Thanks for review.

[tmat]

Done: dotnet/corefx#26976