Manifest capabilities and extensions (Windows Runtime apps)

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

A manifest file is required during installation of your app. The manifest defines the application identity, metadata, capabilities, extensions, and other attributes. Capabilities and extensions are of particular importance to certificates used with apps. Capabilities can be used to define whether an app can share certificate stores outside of the app container in which it is running. Extensions can be used to install certificates along with the application, specify whether to inherit from system trust, and set certificate selection criteria.

Capabilities

You can use the Capabilities element in your manifest file to indicate what actions your app is allowed to take. The sharedUserCertificates capability, in particular, must be specified if you want your application to be able to read certificates and keys from the trusted user store or from a smart card. These certificates are contained in the trusted user MY store and the Smart Card Trusted Roots store. The following example shows you how to specify the sharedUserCertificates capability.

Note  The sharedUserCertificates capability is case-sensitive.

 

  <Capabilities>
    <Capability Name="internetClient" />
    <Capability Name="privateNetworkClientServer" />
    <Capability Name="sharedUserCertificates" />
  </Capabilities>

Extensions

The Certificates extension enables you to install certificates with the application, specify whether to inherit from system trust, and set certificate selection criteria.

Certificates extension schema

<!--CERTIFICATES EXTENSION SCHEMA-->
<xs:complexType name="CT_Certificates">
     <xs:sequence>
          <xs:element name="Certificate" type="CT_CertificateContent" minOccurs="0" maxOccurs="100"/>
          <xs:element name="TrustFlags" type="CT_CertificateTrustFlags" minOccurs="0"/>
          <xs:element name="SelectionCriteria" type="CT_CertificateSelectionCriteria" minOccurs="0"/>
     </xs:sequence>
</xs:complexType>

<xs:complexType name="CT_CertificateContent">
     <xs:attribute name="StoreName" type="ST_CertificateStoreName" use="required"/>
     <xs:attribute name="Content" type="ST_FileName" use="required"/>
</xs:complexType>

<xs:complexType name="CT_CertificateTrustFlags">
     <xs:attribute name="ExclusiveTrust" type="xs:boolean" use="required "/>
</xs:complexType>

<xs:complexType name="CT_CertificateSelectionCriteria ">
     <xs:attribute name="HardwareOnly" type="xs:boolean" use="optional"/>
     <xs:attribute name="AutoSelect" type="xs:boolean" use="optional"/>
</xs:complexType>

<xs:simpleType name="ST_CertificateStoreName">
     <xs:restriction base="xs:string">
          <xs:pattern value="[-_A-Za-z0-9]+"/>
          <xs:maxLength value="50"/>
     </xs:restriction>
</xs:simpleType>

Certificates extension content

Element Attribute Description Allowed text Optional

Certificate

The certificate to be installed in the app container specific certificate store. The store is specified by the StoreName attribute. The certificate is specified by the Content attribute.

Yes

StoreName

Specifies the name of the certificate store. This can be a well-known store such as Root, CA, or TrustedPeople or a custom name.

A special store named Issuer can contain a name list of issuers to be used for certificate selection.

Can contain alphanumeric characters, "-", "_", and white space.

This can be any name allowed as a registry key name.

No

Content

File path of the certificate to be added to the store.

Can be any valid file path.

The certificate file must be in a format supported by Windows.

No

TrustFlags

Flags that define certificate validation behavior.

Yes

ExclusiveTrust

True specifies that the application will not inherit from system trust.

True

False

Yes

SelectionCriteria

Flags that specify certificate selection criteria.

Yes

HardwareOnly

True specifies that the selected certificate must be hardware-based.

True

False

Yes

AutoSelect

True specifies that the selected certificate be automatically selected from within the app container.

True

False

Yes

 

Certificates extension sample #1

<Extensions>
  <!--Certificates Extension-->
  <Extension Category="Microsoft.Windows.Certificates">
    <Certificates>
        <Certificate StoreName="Root" Content="Certificates\Root\myroot1.cer"/>
        <Certificate StoreName="Root" Content="myroot2.cer"/>
        <Certificate StoreName="TrustedPeople" Content="mypeer1.sst"/>
        <Certificate StoreName="Issuer" Content="myissuer.cer"/>
        <TrustFlags ExclusiveTrust="true"/>
        <SelectionCriteria HardwareOnly="true" AutoSelect="true"/>
    </Certificates>
  </Extension>
</Extensions>

Certificates extension sample #2

<Extensions>
  <!--Certificates Extension-->
  <Extension Category="windows.certificates">
    <Certificates>
        <Certificate StoreName="Root" Content="myroot.cer" />
        <Certificate StoreName="CA" Content="mystandca.cer"/>
        <TrustFlags ExclusiveTrust="true" />
        <SelectionCriteria AutoSelect="true" />
    </Certificates>
  </Extension>
</Extensions>

Cryptography and PKI