Version: 3
restore

Contents

Method

GetDigitalSignature

ModuleFileSystem
LibraryCore
Action

Returns all non-timestamping certificates used in an authenticode signature.

ParametersFileName (string): The full path of the file.
Return values

FileName (string): The full path of the file.

SignatureStatus (string): Whether or not the file is signed. If it is signed, this is 'Signed' else it is 'Unsigned'.

CertificateIndex (string): This is an index for each certificate chain returned. For example, if you had only one signature on the file, there may be multiple rows returned (as the certificate chain may be long), but all rows returned would have a CertificateIndex of 0. This can be used to isolate a particular certificate chain. This is a zero indexed integer.

Depth (string): The depth of a certificate in a certificate chain. This starts from the certificate used to sign the file, which is 0. The next certificate in the chain is 1, and so on. The depth return value builds a certificate trust chain. This is a zero indexed integer.

If a certificate chain cannot be built on a device, for example if certificates are missing from the certificate store, the chain returned may be incorrect and will reflect this. This will also affect the CertificateType return value.

CertificateType (string): The type of the certificate. Possible values: "Signing", "Intermediate", "Root" and "Self-signed".

The CertificateType return value is inferred from the depth of the certificate in the chain built by the device. A depth 0 certificate can be marked as 'Self-signed' if no other certs in its trust chain can be found.

Issuer (string): The Issuer field of the certificate.

Subject (string): The Subject field of the certificate. This contains the Common Name of the certificate.

Thumbprint (string): This is a SHA1 hash of the certificate content and the certificate serial number.

SerialNumber(string): This is the serial number of the certificate. This is supposed to be (according to RFC5280) a positive integer assigned by the issuing CA that is unique. Its a nice way to identify a cert if you're dealing with a single CA. 

If you're dealing with multiple CAs, this isn't a good way to specify a cert. I've seen a bunch of certs with a SerialNumber of  00. These are considered 'Non-conforming CAs'. RFC's words, not mine!

EffectiveDate (string): This is the date at which the certificate becomes valid. ('NotBefore')

ExpirationDate (string): This is the date at which the certificate is no longer valid. ('NotAfter')

HashAlgorithm (string): This is the hashing algorithm of the hash used to create the digital signature. If the hashing algorithm used is SHA-1, SHA-256, SHA-384 or SHA-512, the return values will be "SHA1", "SHA256", "SHA384" and "SHA512" respectively. Other hashing algorithms will return an OID, such as "1.2.840.113549.1.1.9". These OIDs are searchable online, on sites such as oidref.com

Example
 FileSystem.GetDigitalSignature(FileName:"c:\\tmp\\SomeProgram.exe");
Platforms
  • Windows
Notes

Does not return the time-stamping certificates.

Microsoft authenticode signatures only support one signature at a time. Any other signatures are stores as nested signatures as unauthenticated attributes, along with time stamps and the like. Looking at the unauthenticated attribute array in VS2015 will only show one element, but iterating through  UnauthAttrs.rgAttr  will reveal additional attributes up to  UnauthAttrs.cAttr . In this case, we're only reading the first nested signature, defined as  "1.3.6.1.4.1.311.2.4.1" . We don't currently support multiple nested signatures.

We've seen files with signatures whose nested certificate's chain cannot be built. For these certificates, the crypto api extensions UI only shows one digital signature, which is the actual signature (which verifies okay as the chain can be built). However, the nested signature does not appear in the list of digital signatures as is normal. It does exist, as we can see the nested signature oid in under the unauthenticated attributes of the primary signature. In this case, the UI doesn't show the existence of a second signature, but the agent does report a self signed certificate used as a digital signature. If the nested cert can't be validated, it doesn't show in the UI, but the nested attribute unauthenticated property still exists.