7.2. DESFire Card Template XML Specifications

Transcription

1 7.2 DESFire Card Template XML Specifications

2 Lenel OnGuard 7.2 DESFire Card Template XML Specifications This guide is item number DOC-1101, revision 6.005, November United Technologies Corporation, Inc. All rights reserved. Lenel and OnGuard (Registered trademarks of UTC Fire & Security Americas Corporation, Inc.) Lenel is a part of UTC Building & Industrial Systems, a unit of United Technologies Corporation. All trademarks are the property of their respective owners. Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of UTC Fire & Security Americas Corporation, Inc. Non-English versions of Lenel documents are offered as a service to our global audiences. We have attempted to provide an accurate translation of the text, but the official text is the English text, and any differences in the translation are not binding and have no legal effect. The software described in this document is furnished under a license agreement and may only be used in accordance with the terms of that agreement. Crystal Reports for Windows is a trademark of Crystal Computer Services, Inc. OnGuard includes ImageStream Graphic Filters ebt International, Inc. (f/k/a Inso Corporation). All rights reserved. ImageStream Graphic Filters and ImageStream are registered trademarks of ebt International, Inc. (f/k/a Inso Corporation). Integral and FlashPoint are trademarks of Integral Technologies, Inc. Portions of this product were created using LEADTOOLS , LEAD Technologies, Inc. ALL RIGHTS RESERVED. Portions of this product are licensed under US patent 5,327,254 and foreign counterparts. Active Directory, Microsoft, SQL Server, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Other product names mentioned may be trademarks or registered trademarks of their respective companies and are hereby acknowledged.

3 Table of Contents Table of Contents CHAPTER 1 Overview Custom DESFire Samples CHAPTER 2 Overall Card Template Structure CHAPTER 3 Card Template Description (Optional) Behavior (Optional) Card Master Key (Required) Key Type Key Value Example Changing the Card Master Key Card Key Settings (Optional) Applications (Required) Example CHAPTER 4 Application Definition Application ID (Required) Key Type (Required) Behavior (Optional) Application Keys (Required) Key Number Key Type Key Value Application Key Settings (Optional) Application Files (Required) Example CHAPTER 5 File Definition File ID (Required) Behavior (Optional) File Access Rights (Optional) File Communication Mode (Required) File Data (Required) Example DESFire Card Template XML Specifications 3

4 Table of Contents CHAPTER 6 Field Definition Common Field Properties Type Encoding Length and Padding Byte Order Defining the Various Field Types Wiegand Field Type UDF Field Type Length Field Type Text Field Type Binary Field Type Biometric Field Type FieldSet Field Type Defining Rules for Fields Require Only One of a Group of Fields Require at Least One of a Group of Fields The Existence of One Field Depends on Another The Value of One Field Depends on Another CHAPTER 7 Complete Card Template Example Appendices APPENDIX A Data Formatting Codes Examples Index DESFire Card Template XML Specifications

5 CHAPTER 1 Overview The DESFire card template XML allows for a flexible user-provided definition of custom applications and files to be encoded to DESFire credentials. This definition allows for the keys, key settings, file access rights, and other settings to be specified. The contents of the files to be encoded consists of a collection of fields of various types. These fields allow dynamic access control data (Wiegand, badge ID, issue code, facility code), User Defined Fields, and biometrics to be generated and written as the files to credentials. Additionally, static data (text, numbers, and binary data) can also be included in the data to be written to the card. Since the data to be written to credentials needs to be encoded in a way that is suitable for the software that reads it, each field allows for flexibility in how the data is formatted. Options such as the encoding (binary, text, and numeric), byte order (little and big endian), length, and padding can be customized to format the data as desired. Rules can also be defined for fields to describe the behavior associated between fields. Custom DESFire Samples This documentation package also provides sample XML card templates and instructions within the Custom DESFire Samples folder. The following is a list of the contents: HID-W: This folder includes a sample OnGuard Custom Data Object (DESFire) card template XML for an HID-W reader as well as instructions for creating a configuration card in Asure ID. IDESCO: This folder includes a sample OnGuard Custom Data Object (DESFire) card template XML for an IDESCO reader as well as instructions for creating a configuration card in IDESCO DESCoder. OnGuardCustomCardTemplateANSI378Fingerprints.xml: A sample OnGuard Custom Data Object (DESFire) card template XML for encoding an ANSI 378 fingerprint template with primary and secondary templates combined into a single template. OnGuardCustomCardTemplateWiegand.xml: A sample OnGuard Custom Data Object (DESFire) card template XML for encoding Wiegand data. DESFire Card Template XML Specifications 5

6 Overview 6 DESFire Card Template XML Specifications

7 CHAPTER 2 Overall Card Template Structure As you can see in the DESFire Card Template XML File Structure on page 8, the card (PICC) level key, key settings, and a set of one or more applications can be defined. Each application consists of the definition of its ID, keys, key settings, and one or more files. Each file is defined by its ID, file access rights, communication mode, and data. The data is constructed by concatenating one or more fields together. DESFire Card Template XML Specifications 7

8 Overall Card Template Structure DESFire Card Template XML File Structure <?xml version="1.0" encoding="utf-8"?> <Card> <Description> </Description> <Behavior> </Behavior> <Key> </Key> <KeySettings> </KeySettings> <Applications> <Application> <Id> </Id> <Behavior> </Behavior> <Keys> <Key> </Key> <Key> </Key> </Keys> <KeySettings> </KeySettings> <Files> <File> <Id> </Id> <Behavior> </Behavior> <AccessRights> </AccessRights> <CommunicationMode> </CommunicationMode> <Data> <Fields>... </Fields> </Data> </File> </Files> </Application> </Applications> </Card> The sections that follow describe in detail how the card, application, file, and fields are defined. 8 DESFire Card Template XML Specifications

9 CHAPTER 3 Card Template The template of a DESFire credential consists of a description, behavior, key, key settings, and a set of applications. It is structured as follows: <Card> <Description> </Description> <!-- Optional --> <Behavior> </Behavior> <!-- Optional --> <Key> </Key> <KeySettings> </KeySettings> <!-- Optional --> <Applications> <Application>...</Application> <Application>...</Application>... </Applications> </Card> Description (Optional) The <Description> element allows you to add any helpful information about the card template to be displayed at the top of the rendered card format window in the System Administration Card Formats form. Behavior (Optional) It is possible to format the card before encoding the new application(s) to it. The card <Behavior> element allows you to define this behavior. Two options are available: Format - to format the card before encoding, specify Format as the behavior. DESFire Card Template XML Specifications 9

10 Card Template Do Not Format (default) - to leave the card "as-is", specify DoNotFormat for the encoding or omit the <Behavior> element. This is the default behavior. Card Master Key (Required) The card level master key, used to authenticate with the card, consists of the key type and value. Key Type Key types include: 3DES 3K3DES AES Key Value Key values are formatted as hexadecimal strings with the prefix "0x". For example, a 16-byte key is represented as 32 hexadecimal characters prefixed with "0x": 0x AABBCCDDEEFF00 Keys must be specified with the appropriate length. 3DES and AES keys are 16 bytes (32 characters plus the "0x" prefix). 3K3DES keys are 24 bytes (48 characters plus the "0x" prefix). Example The following is an example key definition: <Key> <Type>3DES</Type> <Value>0x AABBCCDDEEFF00</Value> </Key> Changing the Card Master Key It is possible to change the master key on the card. In many cases this is very desirable because many cards come with a default 3DES key of 0x However, some pre-encoded cards may have a custom key that you do not need to change. In order to change the key, add a new key element called <NewKey> along with its type and value. 10 DESFire Card Template XML Specifications

11 Card Key Settings (Optional) The current key must also be specified; this is done with the <Key> element. For example, to change the key on a card from its default 3DES key to a new AES key, use the following XML: <Card> <Behavior> </Behavior> <!-- Current key --> <Key> <Type>3DES</Type> <Value>0x </Value> </Key> <!-- New key to change to --> <NewKey> <Type>AES</Type> <Value>0x AABBCCDDEEFF00</Value> </NewKey> <KeySettings> </KeySettings> <!-- Optional --> <Applications> <Application> </Application> <Application> </Application>... </Applications> </Card> Card Key Settings (Optional) The key settings are specified as follows: <KeySettings> <ConfigurationChangeable>true</ConfigurationChangeable> <AllowCreateDelete>false</AllowCreateDelete> <AllowDirectoryList>true</AllowDirectoryList> <AllowChangeMasterKey>true</AllowChangeMasterKey> </KeySettings> Possible values for each element include true or false. Key settings determine the security conditions of the card after it is encoded. The key settings are optional. By specifying them, the key settings will be changed when the card is encoded. If key settings are omitted, then the existing key settings on the card remain as they were prior to encoding. Master key settings descriptions: Configuration changeable - The <ConfigurationChangeable> element indicates whether or not the key settings themselves can be modified. If set to false, the key settings will be permanently frozen. DESFire Card Template XML Specifications 11

12 Card Template Allow create and delete of applications without master key authentication - The <AllowCreateDelete> element indicates whether or not applications can be created or deleted without authenticating with the card master key. If set to false, authentication with the card master key must occur prior to being able to create or delete applications. Allow application directory list access without master key authentication - The <AllowDirectoryList> element determines whether or not application IDs can be listed and whether or not these key settings can be viewed without authenticating with the card master key. If set to false, application IDs cannot be listed and these key settings cannot be viewed without authenticating with the card master key. Allow changing of master key - The <AllowChangeMasterKey> element indicates whether or not the card master key can be changed. If set to false, the card master key cannot be changed even if authenticated with the card master key. This setting can be changed. However, in order to change the card master key, this setting must be set to true and authentication with the card master key must have occurred. Applications (Required) The <Applications> element consists of a set of <Application> elements where each <Application> element defines a DESFire application to be encoded. Multiple applications can be defined. Each application must have a unique ID. See Application Definition on page 15 for information on how to define an application. 12 DESFire Card Template XML Specifications

13 Example Example <Card> <Description>A sample card definition.</description> <Behavior>DoNotFormat</Behavior> <!-- Current key --> <Key> <Type>3DES</Type> <Value>0x </Value> </Key> <!-- New key to change to --> <NewKey> <Type>AES</Type> <Value>0x AABBCCDDEEFF00</Value> </NewKey> <KeySettings> <ConfigurationChangeable>true</ConfigurationChangeable> <AllowCreateDelete>false</AllowCreateDelete> <AllowDirectoryList>true</AllowDirectoryList> <AllowChangeMasterKey>true</AllowChangeMasterKey> </KeySettings> <Applications> <Application>...</Application> <Application>...</Application>... </Applications> </Card> See the Complete Card Template Example on page 51 for a full example of a card template with an application, files, and fields. DESFire Card Template XML Specifications 13

14 Card Template 14 DESFire Card Template XML Specifications

15 CHAPTER 4 Application Definition The definition of a DESFire application consists of an ID, behavior, a set of keys, key settings, and a set of files. It is structured as follows: <Application> <Id>0x112233</Id> <Behavior> </Behavior> <!-- Optional --> <Keys> <Key> </Key> <Key> </Key> </Keys> <KeySettings> </KeySettings> <Files> <File>...</File> <File>...</File>... </Files> </Application> Application ID (Required) The application ID must be defined as a 6-character hexadecimal string prefixed with "0x" such as 0x Be mindful of the ID that is used for your application. If a card already has an application encoded with the same ID, then depending on the behavior specified, the application on the card may be overwritten by the application defined here. DESFire Card Template XML Specifications 15

16 Application Definition Key Type (Required) All keys within an application must be of the same type. This key type is defined at the application level using the <KeyType> element. Specify the key type of 3DES, 3K3DES, or AES. When defining the actual keys within the <Keys> element, the key type should be omitted. Behavior (Optional) It is possible to control how encoding behaves when an application with the same Id already exists on the card. The application <Behavior> element allows for this behavior to be defined. Three options are available: Fail if application exists (default) - if an application with the same Id already exists, a failure will occur. If there is no application with the same id, then encoding will proceed without error. This is the default behavior and is specified by entering the value FailOnExisting. Overwrite existing application - if an application with the same Id already exists, the existing application and its files will be deactivated. A new application will be created with the provided settings and files. If an application with the same Id does not exist, then encoding will continue without failure. Beware that with DESFire it is not possible to delete an application (or file) freeing its memory. Applications and files are instead "deactivated" which allows a new application with the same ID to be used. However, it does not free the application's memory from the card. This behavior is specified by using the value OverwriteExisting. Use existing application - will use the existing application with the specified Id that is already on the card and add to it. This behavior is configured by using the value UseExisting. The existing application key settings may be used by omitting the <KeySettings> element from the application. The key settings may also be overwritten by specifying the <KeySettings>. New files may be added to this application by using new unique file Ids. Additionally, existing files may be overwritten by defining the file behavior as OverwriteExisting. (For more information, see File Definition Behavior (Optional) on page 21.) Any pre-existing keys entered must match the existing keys on the card revision 6

17 Application Keys (Required) Application Keys (Required) The <Keys> element is defined as a list of <Key> elements indicating their number and value but not the type. The key type is specified at the application level using the <KeyType> element. Here is how to define application keys: <Application>... <KeyType>3DES</KeyType> <Keys> <Key> <Number>0</Number> <Value>0x </Value> </Key> <Key> <Number>1</Number> <Value>0x </Value> </Key> </Keys>... </Application> Key Number A maximum of 14 application keys are allowed. The key number is a numeric value ranging from Key Type The <Key>'s <Type> element should be omitted. Instead, the <Application>'s <KeyType> element should include the key type for all application keys. Key Value Key values are formatted as hexadecimal strings with the prefix "0x". For example, a 16-byte key is represented as 32 hexadecimal characters plus the prefix "0x": 0x AABBCCDDEEFF0 Keys must be specified with the appropriate length. 3DES and AES keys are 16 bytes (32 characters plus "0x" prefix). 3K3DES keys are 24 bytes (48 characters plus "0x" prefix). DESFire Card Template XML Specifications 17

18 Application Definition Application Key Settings (Optional) The application key settings are defined as follows: <KeySettings> <ChangeKey>0x00</ChangeKey> <ConfigurationChangeable>true</ConfigurationChangeable> <AllowCreateDelete>false</AllowCreateDelete> <AllowDirectoryList>true</AllowDirectoryList> <AllowChangeMasterKey>true</AllowChangeMasterKey> </KeySettings> Aside from the ChangeKey setting, possible values for each element include true or false. The key settings determine the security conditions of the card after it is encoded. The key settings are optional. This allows existing key settings to be used when re-using an existing application. If the key settings are omitted, then the existing key settings on the card will remain as they were prior to encoding. By specifying them, the key settings will be changed when the card is encoded. Here is a description of the application key settings: Change Key Access Rights - The <ChangeKey> element indicates the access rights for modifying application keys. The following access rights are valid: 0x00 (default): Indicates that authentication with the application master key is required before any key of this application can be changed. 0x01-0x0D: Indicates the key number that must be authenticated with in order to change any key of this application. However, in order to change the application master key or the key specified here (referred to as "change key"), authentication with the application master key is required. See the example that follows for further clarification. 0x0E: Indicates that in order to change an application key, a successful authentication with the key you want to change must have occurred prior to changing the key. 0x0F: Indicates that all keys, except for the application master key, are frozen and cannot be changed. For example, assume an existing application has four (4) keys: Key # Description 0 Application Master Key 1 ApplicationKey1 2 ApplicationKey2 3 ApplicationKey3 With a <ChangeKey> value of 0x00, in order to change Key 0, 1, 2, or 3, authentication with the application master key must have occurred. With a <ChangeKey> value of 0x01, in order to change Key 2 or 3, authentication with Key 1 must have occurred. In order to change Key 0 (application master key) or 1 (change revision 6

19 Application Files (Required) key), authentication with the application master key must have occurred. With a <ChangeKey> value of 0x0E, in order to change Key 0, authentication with Key 0 must have occurred. In order to change Key 1, authentication with Key 1 must have occurred. In order to change Key 2, authentication with Key 2 must have occurred. In order to change Key 3, authentication with Key 3 must have occurred. With a <ChangeKey> value of 0x0F, in order to change Key 0, authentication with Key 0 must have occurred. It is not possible to change Key 1, 2, or 3. Configuration changeable - The <ConfigurationChangeable> element indicates whether or not these key settings themselves can be changed. If set to false, the key settings will be permanently frozen. Allow create and delete of applications without master key authentication - The <AllowCreateDelete> element indicates whether or not files can be created or deleted without authenticating with the application master key. If set to false, authentication with the application master key must occur prior to being able to create or delete files. Allow file directory list access without master key authentication - The <AllowDirectoryList> element determines whether or not file IDs can be listed and whether or not the file settings and these key settings can be viewed without authenticating with the application master key. If set to false, file IDs cannot be listed and the file settings and these key settings cannot be viewed without authenticating with the application master key. Allow changing of master key - The <AllowChangeMasterKey> element indicates whether or not the application master key can be changed. If set to false, the application master key cannot be changed even if authenticated with the application master key. Application Files (Required) The <Files> element consists of a set of <File> elements where each <File> element defines a DESFire file to be encoded. Multiple files can be defined. Each file must have a unique ID. See File Definition on page 21 section for more details about defining a file. DESFire Card Template XML Specifications 19

20 Application Definition Example <Application> <Id>0x4F4553</Id> <Behavior>FailOnExisting</Behavior> <KeyType>AES</KeyType> <Keys> <Key> <!-- Application master key --> <Number>0</Number> <Value>0x </Value> </Key> <Key> <Number>1</Number> <Value>0x </Value> </Key> <Key> <Number>2</Number> <Value>0x </Value> </Key> </Keys> <KeySettings> <ChangeKey>0x00</ChangeKey> <ConfigurationChangeable>true</ConfigurationChangeable> <AllowCreateDelete>false</AllowCreateDelete> <AllowDirectoryList>true</AllowDirectoryList> <AllowChangeMasterKey>true</AllowChangeMasterKey> </KeySettings> <Files> <File> </File> <File> </File> </Files> </Application> revision 6

21 CHAPTER 5 File Definition The definition of a DESFire file consists of an ID, behavior, file access rights, a communication mode, and data. It is structured as follows: <File> <Id>1</Id> <Behavior> </Behavior> <AccessRights> </AccessRights> <CommunicationMode> </CommunicationMode> <Data> <Fields> </Fields> </Data> </File> File ID (Required) A maximum of 32 files are allowed per application. The file ID must be specified as a numeric value ranging from Behavior (Optional) It is possible to control how encoding behaves when a file with the same Id already exists on the card. The file <Behavior> element allows for this behavior to be defined. Two options are available: DESFire Card Template XML Specifications 21

22 File Definition Fail if file exists (default) - If a file with the same ID already exists, a failure will occur. If there is no file with the same ID, then encoding will proceed without error. This is the default behavior, and is specified by entering the value FailOnExisting. Overwrite existing file - If a file with the same ID already exists, the existing file will be deleted and the new file will be created with the new content specified. If a file with the same ID does not exist, then encoding will continue without failure. Beware that with DESFire it is not possible to delete a file, freeing its memory. Files are instead "deactivated" which allows a new file with the same ID to be used. However, this does not free the file's memory from the card. Such behavior is specified by using the value OverwriteExisting. File Access Rights (Optional) The file access rights determine the read, write, and change access rights for the file. A key number, as defined in the application <Keys> element is used to define which key shall allow the corresponding access. The structure is defined as follows: <AccessRights> <ReadAccessKeyId>1</ReadAccessKeyId> <WriteAccessKeyId>0</WriteAccessKeyId> <ReadWriteAccessKeyId>2</ReadWriteAccessKeyId> <ChangeAccessRightsKeyId>0</ChangeAccessRightsKeyId> </AccessRights> File read access key - The <ReadAccessKeyId> element defines the application key number that, when authenticated with, will allow for read only access to this file. "Free" access can be granted to allow reading of this file without prior authentication by entering the value 14. File write access key - The <WriteAccessKeyId> element defines the application key number that, when authenticated with, will allow for write only access to this file. "Free" access can be granted to allow writing to this file without prior authentication by entering the value 14. "Deny" access can be configured to completely deny write access to this file (after the card is encoded) by entering the value of 15. File read/write access key - The <ReadWriteAccessKeyId> element defines the application key number that, when authenticated with, will allow for both read and write access to this file. "Free" access can be granted to allow both reading and writing of this file without prior authentication by entering the value 14. File change access rights key - The <ChangeAccessRightsKeyId> element defines the application key number that, when authenticated with, will allow for these file access rights to be changed. File Communication Mode (Required) The file communication mode determines the how the data is transferred from the card. Modes include: Plain - No encryption is used when transferring data. Specify Plain to use this mode. 22 DESFire Card Template XML Specifications

23 File Data (Required) Enciphered - DES, 3DES or AES is used to encrypt the transferred data. Enciphered is entered to use this mode. MACed - The data is transferred unencrypted, however a Message Authentication Code (MAC) is added to the message. Enter MACed to use this mode. File Data (Required) The file data is defined by specifying a set of fields of various types that can be encoded and formatted in a flexible manner. The encoded fields are concatenated together to make up the contents of the file that is encoded to the card. There is no restriction on the number of fields that can be used. However, keep in mind the resulting size of the data to ensure it will fit on the card while still allowing room for other application data that may be required. The following example demonstrates the structure used for defining these fields: <Data> <Fields> </Fields> </Data> See the Field Definition on page 25 for more details on how to define each field. DESFire Card Template XML Specifications 23

24 File Definition Example <File> <Id>1</Id> <Behavior>FailOnExisting</Behavior> <AccessRights> <ReadAccessKeyId>1</ReadAccessKeyId> <WriteAccessKeyId>2</WriteAccessKeyId> <ReadWriteAccessKeyId>0</ReadWriteAccessKeyId> <ChangeAccessRightsKeyId>0</ChangeAccessRightsKeyId> </AccessRights> <CommunicationMode>Enciphered</CommunicationMode> <Data> <Fields> </Fields> </Data> </File> 24 DESFire Card Template XML Specifications

25 CHAPTER 6 Field Definition The actual data that each file in an application is composed of is specified with a set of fields that are formatted and combined together. The definition of a field varies based on its type. However, there are several properties that are common to many field types although not usually required. Therefore, the basic structure of a field can be defined as follows: <Type> </Type> <!-- Required --> <!-- Additional properties based on field type, Required --> <!-- --> <!-- Additional common properties, Optional* --> <Encoding> </Encoding> <Length> </Length> <!-- Optional* --> <Padding> </Padding> <!-- Optional* --> <PadCharacter> </PadCharacter> <!-- Optional* --> <ByteOrder> </ByteOrder> <!-- Optional* --> *These properties are sometimes required as is described in the sections that follow. Common Field Properties *These properties are sometimes required as is described in the sections below. There are several properties that are common to the various fields. Although not all of these common properties are valid for all field types: Type (Required) Encoding DESFire Card Template XML Specifications 25

26 Field Definition Length Padding PadCharacter ByteOrder Except for the Type which is required, these are usually optional. Each of these properties are described in detail below. Type The following types of fields are supported. Wiegand UDF Length Biometric Text Binary FieldSet These fields are defined in the XML template as strings exactly as they are shown in the list above. ExampleType is a required property for all fields. <Type>Wiegand</Type> How to define each field type is described in detail below. Encoding The same piece of data can be represented in multiple ways. For example, the number 2 can represented as the string "2" or in binary form as 0b The way in which the data should be represented, or encoded, depends on the system in which it is being used. Therefore, each field provides for the ability to specify its encoding. The following formats are supported: UTF-8 encoding - Universal Coded Character Set Transformation Format-8 (UTF-8) is a character encoding format used to encode characters used in English and many other languages. This format is therefore useful when encoding values such as text and numbers for a cardholder name or their badge ID. Thus, the default encoding for User Defined Fields is UTF-8. It, however, would not make sense to use UTF-8 for encoding Wiegand data. Specify UTF8 as the encoding to use UTF-8 encoding. Binary encoding - Binary encoding encodes values in their "natural" binary format. For example, Wiegand data is a series of bits. It is plain old binary data and thus Wiegand data should be encoding in binary. Biometric data is also represented as a "blob" of binary data. Binary encoding keeps biometric data as-is. Generally, binary encoding does not need to be explicitly specified; it is automatically used for the appropriate types. For example, binary encoding is automatically used by default for Wiegand and biometric data. Binary encoding can be specified by entering Binary as the encoding. Number encoding - Number encoding attempts to convert values to a number. Specify Number as the encoding to use number encoding. 26 DESFire Card Template XML Specifications

27 Common Field Properties For example, instead of encoding the UDF "Badge ID" as a UTF-8 string, this value can be encoded as a 64-bit number. The 64-bit badge Id, for example , encoded using Number encoding would be encoded as 0x BCD15* (hex) since 64-bit values require 8 bytes of storage. However, if it is known that all badge IDs can fit into a 32-bit field, the Length property (described later) can be used to set the number of bytes to 4. The value, , stored in a 32-bit field would be encoded as 0x075BCD15*. *These numbers are shown with big-endian byte order. The byte order can be modified. Additionally, Number encoding can be combined with a date format with a date UDF to say, encoding the year as a 2-byte number. See the examples of UDF Field Type on page 32 for more information on using UDF date fields. Example <Encoding>UTF8</Encoding> Applicable Encoding Based on Field Type Not all encodings are applicable to each data type. The following table shows which encodings are appropriate for each data type: Data Type UTF8 Binary Number Wiegand No Yes No UDF Yes No Yes* Length Yes No Yes Text Yes No Yes* Binary No Yes No Biometric No Yes No FieldSet** n/a n/a n/a * Value must contain only numeric characters. ** Encoding of FieldSets is determined by the encoding of each of its nested Fields. Length and Padding It may be desirable to set some fields to a fixed length. This can be done using the <Length> field element. Simply specify a number indicating the length in bytes of the field. The length indicates the number of bytes of the encoded field. This will not always be the same as the number of characters in a field. For example, Greek and many other languages require 2 or more bytes to encode a single character in UTF-8. In such cases the size, in bytes, will be at least twice the number of characters. The following example demonstrates how to specify the length of a field. DESFire Card Template XML Specifications 27

28 Field Definition Example <Length>32</Length> When a fixed length field is specified, and the value of the field is greater than the number of bytes the field can hold, then the value will be truncated to fit the field. Therefore, be careful that the lengths chosen for fixed length fields are large enough to fit all values for a particular field. If truncation does occur, an entry in the log file will be created indicating this. However, if the value of the field is less than the number of bytes the field can hold, additional pad characters are added. These characters are specified using the <PadCharacter> element with a single-byte hexadecimal value string prefixed with "0x". For example, to pad any remaining characters from a text field with null characters, the pad character should defined as follows: <PadCharacter>0x00</PadCharacter> The default pad character is 0x00. Padded characters can be added before or after the field value. To add padding before the value, set the padding element to Left. To add padding after the value, set the padding to Right. By default, padding is added to the right (after the value). Padding example: <Padding>Left</Padding> Here is an example that pads a 32-byte Length field with null characters on the left (before the value): <Type>...</Type> <Length>32</Length> <PadCharacter>0x00</PadCharacter> <Padding>Left</Padding> Padding will not occur unless <Length> is specified. If the field length is specified. and the padding and pad character are not, then the field will be padded on the right with null characters (0x00). A field without a fixed length specified will be encoded unpadded with however many bytes the value requires. 28 DESFire Card Template XML Specifications

29 Defining the Various Field Types Byte Order Not all systems will expect the sequencing of bytes for data units. Therefore, both big endian and little endian byte ordering can be specified with the <ByteOrder> element. Supported values include: BigEndian LittleEndian However, "endianness" only makes sense for numbers. The applicability of "endianness" per data type is shown in the following table: Data Type Wiegand UDF Length Text Binary Biometric FieldSet Byte Order Applicable No Yes - numbers Yes Yes - numbers No No No Note: UTF-8 encodes characters in the same order regardless of whether or not they were encoded in a big-endian or little-endian system. Thus, the byte order is not applicable for UTF-8 encoded fields. In addition, a Byte Order Mark (BOM) is not used for the UTF-8 encoded fields. Defining the Various Field Types Wiegand Field Type The Wiegand field type allows Wiegand data to be encoded to the card. It is encoded as a sequence of bits, padded if necessary to fit in the smallest number of bytes. The padding can be configured to be done before or after the actual Wiegand data. In addition, a configurable number of bytes indicating the number of bits in the Wiegand format can also be added prior to the padded Wiegand data. The Wiegand card format to use is defined by the name of the Access Control Card Format configured in System Administration. The following illustrates how to define a Wiegand field type: <Type>Wiegand</Type> <!-- Required --> <CardFormatName>Wiegand (26)</CardFormatName> <!-- Required --> Type (Required) Must be Wiegand. DESFire Card Template XML Specifications 29

30 Field Definition Card Format Name (Required) The <CardFormatName> element must contain the name of the card format as defined in System Administration. It must be a Wiegand card format. Length Byte Size (Optional) The number specified indicates the number of bytes used to indicate the bit length of the Wiegand data. If set to 0 or omitted, the length bytes will not be included. Valid values range from 0-4. When more than 1 byte is used to store the bit length of the Wiegand data, then the ByteOrder property will determine the byte order to use for encoding the length of the Wiegand data. The default value is 0. Biometric Mismatch (Optional) It is possible to configure a Wiegand format to be used for indicating biometric mismatch. In order to use this option, the card format s Issue Code field must contain at least 8 bits. Biometric mismatch works by replacing the Issue Code with a special value that is interpreted a biometric mismatch. To use a Wiegand field for biometric mismatch, simply set the <IsBiometricMismatch> element to true. The default value is false. Padding (Optional) Padding is unique for Wiegand fields in that it represents the padding in bits instead of bytes. The <Padding> element indicates whether the padding should be added before or after the Wiegand data. If set to Left, the padding will be added before the Wiegand data. If set to Right or omitted, the padding will be added after the Wiegand data. Card formats that are byte-aligned (evenly divisible by 8) will have no padding. The default value is Right. Byte Order (Optional) The <ByteOrder> element is only applicable for the included length bytes that indicate the number of bits in the Wiegand stream. For more information, refer to Length Byte Size (Optional) on page 30. Byte order does not change the ordering of the Wiegand bit stream. Encoding (Not Applicable) The <Encoding> element is not applicable for the Wiegand field type. Length (Not Applicable) The <Length> element is not applicable for the Wiegand field type. The number of bytes encoded for Wiegand data is based on the number of bits specified in the Wiegand card format. The least number of bytes sufficient to hold the Wiegand data will be used. For example, for a 26-bit Wiegand card format, 4 bytes (32 bits) are used (assuming the length byte(s) are not included). The additional 6 bits will be set to 0. Pad Character (Not Applicable) The <PadCharacter> element is not applicable for the Wiegand field type. Any padded bits will be set to DESFire Card Template XML Specifications

31 Defining the Various Field Types Examples Wiegand 26-bit Output without Length bytes The following example shows a Wiegand field using a 26-bit Wiegand card format without indicating its bit-length. Since 4 bytes (32 bits) must be used to store the 26 Wiegand bits, the extra 6 bits, by default, will be set to zero and will appear in the last byte of data after Wiegand data bits. <Type>Wiegand</Type> <CardFormatName>Wiegand (26)</CardFormatName> Wiegand 26-bit Output with Length Byte and Left Padding The following example shows a Wiegand field using a 26-bit Wiegand card format with a single byte preceding the Wiegand data indicating the number of bits. For the Wiegand 26 format, this results in 5 total bytes of data: 1 byte indicates the number of bits and 4 bytes of Wiegand data. The extra 6 bits of "padding" will appear prior to (left of) the Wiegand data bits. <Type>Wiegand</Type> <CardFormatName>Wiegand (26)</CardFormatName> <Padding>Left</Padding> <LengthByteSize>1</LengthByteSize> Wiegand 64 Biometric Mismatch with Two Length Bytes Encoded in Little Endian The following example shows a Wiegand field using a 64-bit Wiegand card format with 2 bytes preceding the Wiegand data indicate the number of bits. The 2 preceding bytes are encoded with little endian byte order. The Wiegand output will indicate biometric mismatch. <Type>Wiegand</Type> <CardFormatName>Wiegand (64)</CardFormatName> <LengthByteSize>2</LengthByteSize> <ByteOrder>LittleEndian</ByteOrder> <IsBiometricMismatch>true</IsBiometricMismatch> DESFire Card Template XML Specifications 31

32 Field Definition UDF Field Type The UDF field type allows any UDF (User Defined Field) to be encoded to the card. The UDF to encode is specified by entering the Object name as configured in the FormsDesigner field properties. The following XML is used to define a UDF: <Type>UDF</Type> <!-- Required --> <ObjectName>First Name</ObjectName> <!-- Required --> <!-- Additional common properties, Optional --> Type (Required) Must be UDF. Object Name (Required) The <ObjectName> element indicates which user defined field to encode. The object name must match the Object name as defined in the FormsDesigner field properties. Date Format (Optional) The <DateFormat> element allows the UDF date fields to be formatted in a user-provided manner by using a combination of date formatting codes. For example, in order to indicate the date May 8, 2015 in the format 05/08/2015, the string "%m/%d/%y" would be used where %m = month number (01-12), %d = day number (01-31), and %Y = 4-digit year number. A full list of date formatting codes can be found in the refer to Appendix A: Data Formatting Codes on page 57. The DateFormat can be combined with Number encoding to encode a portion of the date, such as the year, as a number instead of a UTF-8 string. See the Date UDF Examples on page 33 for more information. DateFormat is required in UDF date fields. Include Null Terminator (Optional) A null terminator can be added to the end of the text that is encoded to the card. This is done simply by setting the <IncludeNullTerminator> property to true. Encoding (Optional) The <Encoding> element determines the binary representation of the field. For non-numeric UDFs, the encoding should be UTF8. UTF8 is the default encoding for all UDFs. For numeric UDFs, the encoding could be set to UTF8 to encode the number as a string. Alternatively, the encoding could be set to Number to encode the number in binary. Without specifying the <Length> element, the size of the encoded numeric field will be based on the Forms Designer specified Length of the UDF. Numeric fields with a length of 1-9 will encode in 4 bytes. Numeric fields with a length of will encode in 8 bytes. If the <Length> field is specified, then the number of bytes encoded will be equal to the <Length> specified, even if significant digits will be truncated. 32 DESFire Card Template XML Specifications

33 Defining the Various Field Types For date UDFs, the encoding could be set to UTF8 to encode the date as a string using the <DateFormat> specified. The encoding could also be set to Number to encode the number in binary. The result of the <DateFormat> will be converted to a number. Therefore, the date format must result in a value that includes numeric characters only. See Date Format (Optional) on page 32 for more details as well as the Date UDF Examples on page 33. For UDF drop-downs, the value in the drop-down (not the numeric index) is encoded. The default value, regardless of the UDF type, is UTF8. Length (Optional) The <Length> element determines the length, in bytes, of the encoded user defined field. By using the <Length> field, it is possible to limit the length of text, numeric, and drop-down fields. Text fields can be set to a constant fixed length for all cardholders. With a known set of values, numeric fields can be represented with a fewer number of bytes, if desired. Padding will occur when the value of a field is shorter than its length. Although possible, it does not make sense to limit (truncate) the length of date fields as this will change the value of the date. See Length and Padding on page 27 for more details on how to use the <Length> property. Note: The length of all fields is specified in bytes, not characters. The number of bytes in a field will not always be the same as the number of characters in a field. This is due to the way UTF-8 encodes characters in various languages. Padding (Optional) The location of the padding to use when the <Length> of the field is specified can be optional specified as Left or Right. See Length and Padding on page 27 for more details about using the <Padding> property. PadCharacter (Optional) The pad character to use for padding when the <Length> field is specified can optionally be specified for user defined fields. See Length and Padding on page 27 for more details on how to use the <PadCharacter> property. ByteOrder (Optional) The <ByteOrder> element can be specified for user defined fields with numeric values only. This includes date UDFs with a <DateFormat> whose resulting value contains only numeric characters. To encode a number with big-endian byte ordering, set the <ByteOrder> to BigEndian or omit this element. To use little-endian byte ordering, set the <ByteOrder> to LittleEndian. The default value is BigEndian. Examples The following examples demonstrate how to define a field to encode text, numeric, and date userdefined fields. DESFire Card Template XML Specifications 33

34 Field Definition Text UDF with Dynamic Length The following field will encode the cardholder last name with a dynamic length. Thus there is no padding: <Type>UDF</Type> <ObjectName>Last Name</ObjectName> Text UDF with Fixed Length The following field will encode the cardholder first name with a fixed length of 32 bytes and is padded with null characters on the right (after the name): <Type>UDF</Type> <ObjectName>First Name</ObjectName> <Length>32</Length> <PadCharacter>0x00</PadCharacter> The padding defaults to right, and has therefore been omitted. Numeric UDF The following field will encode the cardholder badge ID as an 8-byte value: <Type>UDF</Type> <ObjectName>Badge ID</ObjectName> <Encoding>Number</Encoding> Since the default encoding for all UDFs is UTF8, the encoding of Number must be specified to encode this as a number. To encode the badge ID as a string, set the encoding to UTF8 or omit the <Encoding> element (the default encoding is UTF-8 for UDFs). 34 DESFire Card Template XML Specifications

35 Defining the Various Field Types Date UDF Encoded as Text The following field will encode the cardholder badge deactivate date as a UTF-8 string in the format of <Month>/<Day>/<Year (4 digits)>, in other words, "07/14/2015": <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%m/%d/%Y</DateFormat> Date UDF Encoded as Numbers The following field will encode the deactivate date in 4 bytes: The first byte indicates the month as decimal number (01-12). The next byte indicates the day of the month as a decimal number (01-31). The last two bytes indicate the 4-digit year (with century). <Type>FieldSet</Type> <!-- Month --> <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%m</DateFormat> <Encoding>Number</Encoding> <Length>1</Length> <!-- Day --> <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%d</DateFormat> <Encoding>Number</Encoding> <Length>1</Length> <!-- Year --> <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%Y</DateFormat> <Encoding>Number</Encoding> <Length>2</Length> FieldSet fields are another type of field described in FieldSet Field Type on page 45. DESFire Card Template XML Specifications 35

36 Field Definition Length Field Type The Length field type is a special field that holds the length of a referenced field. This type of field can be extremely useful for enabling machines to read file data consisting of multiple fields. Rather than having a set of fixed-length fields, each field could be preceded by its length enabling the reading software to know where one field ends and the next one starts. For example, a cardholder first and last name can both be preceded with a length field as depicted in the following example: 8Benjamin4Lark (This is not how the actual binary data would appear but is useful for demonstration purposes only.) In the previous example, the length of the first name is 8 and the length of the last name is 4. The software reading the above data would read the first character, indicating that the first name is 8 characters long, and would know to read the next 8 characters as the first name. Then the software would read the next character, 4, indicating the size of the last name which it can then read. In the example above, the order and existence of the fields is critical in reading the data. For example, a machine reading 8Benjamin4Lark would read a first name of Benjamin. A machine reading 4Lark8Benjamin would read a first name of Lark. The length field, when combined with the Binary, Text, or Number field, can be used to encode each field with a Tag-Length-Value (TLV) structure. The Tag indicates which data is stored in the Value part -- i.e. an identifier indicating the value is a first name. The Length indicates the size of the Value part --- i.e. the size of the first name. The Value stores the actual data -- the actual first name. For example, a cardholder first and last name can be formatted with a TLV structure as follows: 18Benjamin24Lark (This is not how the actual binary data would appear but is useful for demonstration purposes only.) In the above example, the Tag for the first name is 1. The Tag for the second name is 2. The Length of the first name is 8. The Length of the last name is 4. Using this information, the software reading the data would not only know where one value ends and the next starts, but it would also know which data is stored in each of the values. A machine would read the same first and last name (Benjamin Lark) whether the encoded data was 18Benjamin24Lark or 24Lark18Benjamin. The following shows how to define a length field type: <Field ValueDependsOn="ReferencedField"> <Type>Length</Type> <!-- Required --> <Length>2</Length> <!-- Required --> Type (Required) Must be Length. Length (Required) The <Length> property of the Length field indicates the size, in bytes, of the Length field. It can consist of 1-4 bytes. 36 DESFire Card Template XML Specifications

37 Defining the Various Field Types Field to Compute Length of (ValueDependsOn) (Required) The length field describes the length of another field. Therefore, it is necessary to indicate which field that is. This is done by specifying the ValueDependsOn attribute with the reference identifier (RefId) of the field that it depends on. The field that the length is describing must have a RefId attribute specifying the Reference Identifier to be used in the ValueDependsOn attribute. Here is an example of a length field that computes the length of a biometric field: <Field ValueDependsOn="BioPIN"> <Type>Length</Type> <Length>2</Length> <Field RefId="BioPIN"> <Type>Biometric</Type> <BiometricType>BiometricPIN</BiometricType> ByteOrder (Optional) The <ByteOrder> element determines the endianness of the length value. Specify LittleEndian to use little-endian byte ordering. Use BigEndian or omit this element to use big-endian byte ordering. The default byte order is BigEndian. Encoding (Not Applicable) The <Encoding> element is not applicable for this field. The encoding for Length fields is always Number. Padding (Not Applicable) The <Padding> element is not applicable for this field. PadCharacter (Not Applicable) The <PadCharacter> element is not applicable for this field. DESFire Card Template XML Specifications 37

38 Field Definition Examples Length Field with Single Byte The following shows a length field that indicates the length of a Wiegand field of 1 byte: <Field ValueDependsOn="ReaderOutput"> <Type>Length</Type> <Length>1</Length> <Field RefId="ReaderOutput"> <Type>Wiegand</Type> <CardFormatName>Wiegand (64)</CardFormatName> <LengthByteSize>1</LengthByteSize> Length Field with Multiple Bytes Encoded in Little Endian The following example shows a length field that indicates the length of a biometric field using 2 bytes encoded in little-endian byte order: <Field ValueDependsOn="BioPIN"> <Type>Length</Type> <Length>2</Length> <ByteOrder>LittleEndian</ByteOrder> <Field RefId="BioPIN"> <Type>Biometric</Type> <BiometricType>BiometricPIN</BiometricType> Text Field Type The text field type allows static text to be encoded to the card. The text entered would be the same for all badges. A text field is useful for encoding text to badges that will remain the same for all cardholders. For example, the company name or the facility code. Alternatively, a text field can be used as delimiters between fields (a comma ","). Another use may be to concatenate UDF fields by combining the first and last name with a space between them. The text is encoded in UTF-8 by default. However, the encoding may be changed to Number to encode a text value with numeric characters to a number. The following shows how to define a text field type: <Type>Text</Type> <!-- Required --> <Value>My Company Name</Value> <!-- Required --> 38 DESFire Card Template XML Specifications

39 Defining the Various Field Types Type (Required) Must be Text. Value (Required) The <Value> element indicates the actual value of the field. Include Null Terminator (Optional) A null terminator can be added to the end of the text that is encoded to the card. In order to do so, simply set the <IncludeNullTerminator> property to true. Encoding (Optional) The <Encoding> element can be set to either UTF8 or Number. When set to UTF8, the text entered as a UTF-8 string, and is encoded "as-is". When set to Number, a numeric text value can be entered that will encode the string as a number. Length (Optional) The number of bytes encoded for text data, when the encoding is set to UTF8, is based on the characters entered and how they are encoded in UTF-8. Therefore the length is not valid when using UTF8 encoding. However, with an encoding of Number the <Length> element can be specified to determine the number of bytes to use when encoding a numeric value. For example, if the value is "123" and the encoding is Number, the Length can be set to 1 to encode the value "123" into a single byte 0x7B. Byte Order (Optional) The <ByteOrder> element is not applicable for the text field type when the encoding is set to UTF8. However, if the encoding is set to Number and the value is numeric then byte order of the number encoded can be changed. See the examples below for a sample field definition in changing the byte order of a numeric value. Padding (Not Applicable) Padding is not applicable for the Text field type. Pad Character (Not Applicable) The <PadCharacter> element is not applicable for the Text field type. Examples Simple Text Field The following example shows a simple text field that is not null terminated. It will be encoded in UTF8: <Type>Text</Type> <Value>ACME Corporation</Value> DESFire Card Template XML Specifications 39

40 Field Definition Text Field with Null Terminator The following example shows a simple text field that is null terminated. It will be encoded in UTF8: <Type>Text</Type> <Value>Version 1.2</Value> <IncludeNullTerminator>true</IncludeNullTerminator> Text Field Encoded as Number with Big Endian The following example shows a text field value that will be converted to a 2-byte number encoded with big endian byte order: <Type>Text</Type> <Value>8623</Value> <Length>2</Length> <ByteOrder>BigEndian</ByteOrder> Since the default byte order is BigEndian, the <ByteOrder> element can be omitted. Binary Field Type The Binary field type allows static binary data to be encoded to the card. The binary data is entered as a hexadecimal string and is encoded in its binary representation. One use for binary fields is to be used as a tag in Tag-Length-Value structures. The following shows how to define a Binary field type: <Type>Binary</Type> <!-- Required --> <Value>0x01</Value> <!-- Required --> Type (Required) Must be Binary. Value (Required) The <Value> element indicates the actual value of the field. A hexadecimal string value, preceded by "0x" must be entered. For example: 0x686F7065. Encoding (Not Applicable) The <Encoding> element is not applicable for the Binary field type. The data is encoded in binary as represented by its hexadecimal value entered. 40 DESFire Card Template XML Specifications

41 Defining the Various Field Types Length (Not Applicable) The <Length> element is not applicable for the Binary field type. The number of bytes encoded for the data is based on the hexadecimal value entered. Padding (Not Applicable) Padding is not applicable for the Binary field type. Pad Character (Not Applicable) The <PadCharacter> element is not applicable for the Binary field type. Byte Order (Not Applicable) The <ByteOrder> element is not applicable for the Binary field type. Example The following example demonstrates how to encode a 3-byte value. These three bytes could indicate a version number (1.7.2). <Type>Binary</Type> <Value>0x010702</Value> Biometric Field Type The Biometric field type allows biometrics such as the facial photo, fingerprints, and iris templates to be encoded to the card. The following is a complete list of supported biometrics: Facial Photo Hand Geometry Bioscrypt Fingerprints ANSI INCITS 378 Fingerprint Templates PK_COMP Fingerprint Templates LG Iris Templates Biometric PINs The following demonstrates how to define a Biometric field type to encode the primary INCITS 378 template: <Type>Biometric</Type> <!-- Required --> <BiometricType>INCITS378Template</BiometricType> <!-- Required --> <BiometricPart>Primary</BiometricPart> DESFire Card Template XML Specifications 41

42 Field Definition Type Type must be Biometric. BiometricType (Required) The BiometricType defines the type of biometric to use. They are defined in the XML template using the following strings: FacialPhoto HandGeometry BioscryptFingerprint Template INCITS378 Template PK_COMPTemplate LGIrisTemplate BiometricPIN BiometricPart (Optional) The BiometricPart defines the part of the biometric that is desired to be encoded. For example, this may indicate the primary or secondary fingerprint template. Alternatively, this may refer to the left or right iris. The supported parts include: Primary Secondary PrimaryAndSecondary Left Right For example, to indicate that you want to encode an ANSI INCITS 378 template with both the primary and secondary fingerprints combined into a single template, then the following XML should be used: <Type>Biometric</Type> <BiometricType>INCITS378Template</BiometricType> <BiometricPart>PrimaryAndSecondary</BiometricPart> Note: Currently, only the INCITS 378 template can be combined into a single template. 42 DESFire Card Template XML Specifications

43 Defining the Various Field Types For example, to indicate that you want to encode the right LG Iris template, then the following XML should be used: <Type>Biometric</Type> <BiometricType>LGIrisTemplate</BiometricType> <BiometricPart>Right</BiometricPart> The BiometricPart is required for all biometrics except photo, hand geometry, and biometric PIN. Image Properties It is possible to encoding the cardholder facial photo to the card. Due to the large amount of space that these images can take up, combined with the limited space on a card, there are several properties that must be used in order to resize the photo to fit on the card (and leave space for other data). These properties include the JPEG compression quality, image height, and image width. When combined together, reasonable quality images of reasonable dimensions can be created with a size of approximately 4-6 KB. Naturally, the actual size will vary from image to image based upon its compressibility. Take care to ensure that the cardholder photos will fit on the cards while leaving enough room for any additional needed data. All images are encoded in the JPEG image format. ImageQuality (Required for FacialImage) The image quality defines the JPEG image quality to use. The quality is a value ranging from 1 to 100. A value of 1 indicates the worst quality and a value of 100 indicates the best quality. It may not be possible to use a very high quality due to the limited space on the card. The following is an example of how to define the image quality: <ImageQuality>60</ImageQuality> The default value is 50. The ImageQuality is required for the FacialImage biometric. The ImageQuality is not applicable for biometric types other than FacialPhoto. Image Width (Required for FacialImage) The width of the image must be specified using the ImageWidth property. The value is entered in pixels. For example: <ImageWidth>240</ImageWidth> The ImageWidth is required for the FacialImage biometric. The default value is 240. Image Height (Required for FacialImage) The height of the image must be specified using the ImageHeight property. The value is entered in pixels. For example: DESFire Card Template XML Specifications 43

44 Field Definition <ImageHeight>320</ImageHeight> The ImageHeight is required for the FacialImage biometric. The default value is 320. Maintain Aspect Ratio (Optional) To maintain the original photo's aspect ratio, the MaintainAspectRatio property can be set to true. Both the ImageWidth and ImageHeight must be specified, regardless of whether or not it is desired to maintain the aspect ratio. When MaintainAspectRatio is set to true then either the width or height will be automatically sized to maintain the aspect ratio based on the specified width or height. The dimension that is changed to maintain the aspect ratio will vary based on the original image's aspect ratio and the specified image dimensions. The following demonstrates how to set this property: <MaintainAspectRatio>true</MaintainAspectRatio> The default value is true. Required (Optional) The Required attribute allows a biometric field to be set as optional. Meaning that if a cardholder does not have the biometric type captured, then an error will not be given and encoding can still proceed. Set to false to indicate a field is optional. The default value is true. Here is an example: <Field Required="false"> <Type>Biometric</Type> <BiometricType>BiometricPIN</BiometricType> Encoding (Not Applicable) The <Encoding> element is not applicable for the Biometric field type. Biometrics are stored in their native format. Length (Not Applicable) The <Length> element is not applicable for the Biometric field type. The number of bytes encoded is determined by the size of the biometric. Padding (Not Applicable) Padding is not applicable for the Biometric field type. Pad Character (Not Applicable) The <PadCharacter> element is not applicable for the Biometric field type. Byte Order (Not Applicable) The <ByteOrder> element is not applicable for the Biometric field type. 44 DESFire Card Template XML Specifications

45 Defining the Various Field Types Examples ANSI INCITS 378 Combined Primary and Secondary Fingerprint Template The following example demonstrates how to create a biometric field to encode ANSI INCITS 378 primary and secondary templates in a single combined template. <Type>Biometric</Type> <BiometricType>INCITS378Template</BiometricType> <BiometricPart>PrimaryAndSecondary</BiometricPart> PK_COMP Primary Template The following demonstrates how to create a biometric field to encode the primary PK_COMP template: <Type>Biometric</Type> <BiometricType>PK_COMPTemplate</BiometricType> <BiometricPart>Primary</BiometricPart> Facial Photo The following example demonstrates how to define a FacialPhoto biometric field that will have a quality of 60 and will be sized with the same aspect ratio as the original photo using a width or 240 or a height of 320. The dimension that is changed to maintain the aspect ratio will vary based on the original image's aspect ratio. <Type>Biometric</Type> <BiometricType>FacialPhoto</BiometricType> <ImageQuality>60</ImageQuality> <ImageWidth>240</ImageWidth> <ImageHeight>320</ImageHeight> <MaintainAspectRatio>true</MaintainAspectRatio> FieldSet Field Type The FieldSet field type allows fields to be nested within other fields. This is useful when it is desired to use a length field that computes the length of a set of fields rather than only asingle referenced field. A FieldSet field is defined by using the type FieldSet and defining one more DESFire Card Template XML Specifications 45

46 Field Definition fields following the type. A FieldSet can contain other FieldSets, thus supporting multiple levels of nesting. The following shows how to define a FieldSet field type: <Type>FieldSet</Type> <!-- Required --> <!-- 1 or more Fields required --> Type (Required) Must be FieldSet. Encoding (Not Applicable) The <Encoding> element is not applicable for the FieldSet field type. Each field defined within the field set will be encoding with its own encoding. Length (Not Applicable) The <Length> element is not applicable for the FieldSet field type. The number of bytes encoded is determined by the sum of all of the fields within the FieldSet. Padding (Not Applicable) Padding is not applicable for the FieldSet field type. Pad Character (Not Applicable) The <PadCharacter> element is not applicable for the FieldSet field type. Byte Order (Not Applicable) The <ByteOrder> element is not applicable for the FieldSet field type. 46 DESFire Card Template XML Specifications

47 Defining Rules for Fields Example The following example shows how to combine a cardholder first and last name, separated by a space, into a single field. <Type>FieldSet</Type> <Type>UDF</Type> <ObjectName>First Name</ObjectName> <Type>Text</Type> <Value> </Value> <!-- Space ' ' --> <Type>UDF</Type> <ObjectName>Last Name</ObjectName> Defining Rules for Fields Rules can be defined for fields to describe the behavior associated between fields. For example, a rule can be created where only one field amongst a group of fields may be encoded. Another rule could be created to only encode a field when another field contains data. Rules are not limited to a specific file or application. A field in one file or application can be involved in the same rule as a field in another file or application. This means that if you want to have separate applications per file or application then you will need to use unique "group names" (defined below) for the different rules. Here are the rules that are supported: Require Only One of a Group of Fields This rule indicates that for a group of fields, identified by a common group name, only one of those fields may contain data and be encoded. For example, let's say that you want to encode fingerprint biometrics for each person in your company, but some people are not able to capture a usable fingerprint. In place of a fingerprint for those who cannot capture one, a biometric PIN could be used. With this rule, you could indicate that each person must have either a fingerprint template or a biometric PIN, but not both. DESFire Card Template XML Specifications 47

48 Field Definition This rule is defined by adding the attribute RequireOnlyOneOf to each field in a group, where the value of the attribute is a group name. Only one field in that group may have data. Here is an example: <Field RequireOnlyOneOf="Biometric"> <Type>Biometric</Type> <BiometricType>INCITS378Template</BiometricType> <BiometricPart>PrimaryAndSecondary</BiometricPart> <Field RequireOnlyOneOf="Biometric"> <Type>Biometric</Type> <BiometricType>BiometricPIN</BiometricType> Require at Least One of a Group of Fields This rule indicates that for a group of fields, identified by a common group name, at least one of those fields may contain data and be encoded. For example, let's say that you want to encode fingerprint biometrics for each person in your company, but some people are not able to capture a usable fingerprint. In place of a fingerprint for those who cannot capture one, a biometric PIN could be used. With this rule, you could indicate that each person must have either a fingerprint template or a biometric PIN. Unlike the RequireOnlyOneOf rule, this rule would allow for all fields in a group to be encoded instead of just one. This rule is defined by adding the attribute RequireAtLeastOneOf to each field in a group, where the value of the attribute is a group name. One or more fields in that group may have data. Here is an example: <Field RequireAtLeastOneOf="Biometric"> <Type>Biometric</Type> <BiometricType>INCITS378Template</BiometricType> <BiometricPart>PrimaryAndSecondary</BiometricPart> <Field RequireAtLeastOneOf="Biometric"> <Type>Biometric</Type> <BiometricType>BiometricPIN</BiometricType> The Existence of One Field Depends on Another This rule indicates that the existence of a field (whether or not the field is encoded) depends on the existence of another field. For example, let's say that you are encoding a card using a Tag-Length- Value structure. If you do not want the Tag and Length fields to be encoded when the Value field does not contain any data, then you can use this rule by saying the existence of the Tag and Length fields depends on the Value field. This rule is defined by adding the attribute ExistenceDependsOn to a field that depends on another, where the value of the attribute is a reference identifier (RefId) of the field that is being 48 DESFire Card Template XML Specifications

49 Defining Rules for Fields depended upon. The field that is being depended upon needs to have the attribute RefId added with a unique ID that is used as the value of the ExistenceDependsOn attribute. Here is an example: <Field ExistenceDependsOn="BadgeID"> <Type>Binary</Type> <Value>0x02</Value> <Field ValueDependsOn="BadgeID" ExistenceDependsOn="BadgeID"> <Type>Length</Type> <Length>2</Length> <Field RefId="BadgeID"> <Type>UDF</Type> <ObjectName>Badge ID</ObjectName> <Encoding>Number</Encoding> The Value of One Field Depends on Another This rule indicates that the value of a field depends on the existence of another field. Currently, only Length fields support this rule. The value of a length field depends on the size of another field, and therefore requires this rule. Here is an example: <Field ValueDependsOn="BadgeID"> <Type>Length</Type> <Length>2</Length> <Field RefId="BadgeID"> <Type>UDF</Type> <ObjectName>Badge ID</ObjectName> <Encoding>Number</Encoding> DESFire Card Template XML Specifications 49

50 Field Definition 50 DESFire Card Template XML Specifications

51 CHAPTER 7 Complete Card Template Example The following card template example includes all of the field types described in this document. It uses the Tag-Length-Value structure to separate and identify each field. <?xml version="1.0" encoding="utf-8"?> <Card> <Description>This is a sample DESFire XML card template.</description> <Behavior>DoNotFormat</Behavior> <!-- Current key --> <Key> <Type>3DES</Type> <Value>0x </Value> </Key> <!-- New key to change to --> <NewKey> <Type>AES</Type> <Value>0x AABBCCDDEEFF00</Value> </NewKey> <KeySettings> <ConfigurationChangeable>true</ConfigurationChangeable> <AllowCreateDelete>false</AllowCreateDelete> <AllowDirectoryList>true</AllowDirectoryList> <AllowChangeMasterKey>true</AllowChangeMasterKey> </KeySettings> <Applications> <Application> <Id>0x4F4553</Id> <Behavior>FailOnExisting</Behavior> <KeyType>AES</KeyType> <Keys> <!-- Application master key --> <Key> <Number>0</Number> <Value>0x </Value> </Key> <Key> <Number>1</Number> DESFire Card Template XML Specifications 51

52 Complete Card Template Example <Value>0x </Value> </Key> <Key> <Number>2</Number> <Value>0x </Value> </Key> </Keys> <KeySettings> <ChangeKey>0x00</ChangeKey> <ConfigurationChangeable>true</ConfigurationChangeable> <AllowCreateDelete>false</AllowCreateDelete> <AllowDirectoryList>true</AllowDirectoryList> <AllowChangeMasterKey>true</AllowChangeMasterKey> </KeySettings> <Files> <File> <Id>1</Id> <Behavior>FailOnExisting</Behavior> <AccessRights> <ReadAccessKeyId>1</ReadAccessKeyId> <WriteAccessKeyId>2</WriteAccessKeyId> <ReadWriteAccessKeyId>0</ReadWriteAccessKeyId> <ChangeAccessRightsKeyId>0</ChangeAccessRightsKeyId> </AccessRights> <CommunicationMode>Enciphered</CommunicationMode> <Data> <Fields> <!-- Pass-through wiegand output --> <Type>Binary</Type> <Value>0x04</Value> <Field ValueDependsOn="ReaderOutput"> <Type>Length</Type> <Length>2</Length> <Field RefId="ReaderOutput"> <Type>Wiegand</Type> <CardFormatName>Wiegand (64)</CardFormatName> <LengthByteSize>2</LengthByteSize> <!-- Pass-through biometric mismatch wiegand output --> <Type>Binary</Type> <Value>0x05</Value> <Field ValueDependsOn="BiomismatchOutput"> <Type>Length</Type> <Length>2</Length> <Field RefId="BiomismatchOutput"> <Type>Wiegand</Type> <CardFormatName>Wiegand (64)</CardFormatName> 52 DESFire Card Template XML Specifications

53 <LengthByteSize>2</LengthByteSize> <IsBiometricMismatch>true</IsBiometricMismatch> <!-- Full Name --> <Type>Binary</Type> <Value>0x08</Value> <Field ValueDependsOn="Name"> <Type>Length</Type> <Length>2</Length> <Field RefId="Name"> <Type>FieldSet</Type> <Type>UDF</Type> <ObjectName>First Name</ObjectName> <Type>Text</Type> <Value> </Value> <!-- space --> <Type>UDF</Type> <ObjectName>Last Name</ObjectName> <!-- Expiration Date --> <Type>Binary</Type> <Value>0x09</Value> <Field ValueDependsOn="ExpDate"> <Type>Length</Type> <Length>2</Length> <Field RefId="ExpDate"> <Type>FieldSet</Type> <!-- Year --> <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%Y</DateFormat> <Encoding>Number</Encoding> <Length>2</Length> <!-- Month --> <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%m</DateFormat> <Encoding>Number</Encoding> DESFire Card Template XML Specifications 53

54 Complete Card Template Example <Length>2</Length> <!-- Day --> <Type>UDF</Type> <ObjectName>Deactivate Date</ObjectName> <DateFormat>%d</DateFormat> <Encoding>Number</Encoding> <Length>2</Length> <!-- Biometric PIN --> <Field ExistenceDependsOn="BioPIN"> <Type>Binary</Type> <Value>0x0A</Value> <Field ValueDependsOn="BioPIN" ExistenceDependsOn="BioPIN"> <Type>Length</Type> <Length>2</Length> <Field RefId="BioPIN" RequireOnlyOneOf="Biometric"> <Type>Biometric</Type> <BiometricType>BiometricPIN</BiometricType> </Fields> </Data> </File> <File> <Id>2</Id> <AccessRights> <ReadAccessKeyId>1</ReadAccessKeyId> <WriteAccessKeyId>2</WriteAccessKeyId> <ReadWriteAccessKeyId>0</ReadWriteAccessKeyId> <ChangeAccessRightsKeyId>0</ChangeAccessRightsKeyId> </AccessRights> <CommunicationMode>Enciphered</CommunicationMode> <Data> <Fields> <!-- INCITS 378 template --> <Field RequireOnlyOneOf="Biometric"> <Type>Biometric</Type> <BiometricType>INCITS378Template</BiometricType> <BiometricPart>PrimaryAndSecondary</BiometricPart> </Fields> </Data> </File> </Files> </Application> </Applications> </Card> 54 DESFire Card Template XML Specifications

55 Appendices

56

57 APPENDIX A Data Formatting Codes Use the following list of date formatting codes to define the way in which dates are formatted when encoding as text. IMPORTANT: Make sure to match the format code exactly. Case matters! Format Code Description Example %a Abbreviated weekday name Sun %A Full weekday name Sunday %b Abbreviated month name Mar %B Full month name March %c Date and time representation appropriate for locale Sun Aug 19 02:56: %d Day of month as decimal number (01-31) 21 %H Hour in 24-hour format (00-23) 15 %I Hour in 12-hour format (01-12) 06 %j Day of year as decimal number ( ) 135 %m Month as decimal number (01-12) 10 %M Minute as decimal number (00-59) 07 %p Current locale's A.M./P.M. indicator for 12-hour clock PM %S Second as decimal number (00-59) 03 %U Week of year as decimal number, with Sunday as first day of week (00-53) %w Weekday as decimal number (0-6; Sunday is 0) 12 2 DESFire Card Template XML Specifications 57

58 Data Formatting Codes Format Code Description Example %W Week of year as decimal number, with Monday as first day of week (00-53) 13 %x Date representation for current locale 08/19/12 %X Time representation for current locale 02:50:06 %y Year without century, as decimal number (00-99) 15 %Y Year with century, as decimal number 2015 %z, %Z Either the time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown CDT %% Percent sign % Examples The following formats demonstrate several different ways to output the date 06/09/2015 5:40 PM: Format Output %m/%d/%y 06/09/2015 %A, %b %d Tuesday, Jun 09 %m-%e-%y %H:%M :40 %b %e, %l:%m %p Jun 9, 5:40 PM %B %Y June 2015 %b %d, %Y Jun 09, 2015 %I:%M:%S %p 05:40:00 PM %H:%M:%S 17:40:00 %A, %d %b %Y %l:%m %p Tuesday, 09 Jun :40 PM 58 DESFire Card Template XML Specifications

59 Index A ANSI INCITS 378 fingerprint templates Application definition application files application ID application key settings application keys behavior element key type Application example XML Application files Application key settings Application key type Application keys Applications B Binary field type Biometric field examples Biometric field type Biometric PINs Bioscrypt fingerprint templates Byte order field property C Card behavior... 9 Card description... 9 Card format template overall structure... 8 Card key settings Card master key Card template applications behavior... 9 card key settings card mater key changing card master key description... 9 Card template example XML... 9, 13 Cardholder photo Changing card master key Common field properties Custom DESFire samples... 5 D Data formatting codes E Encoding field property F Field definition properties byte order encoding length and padding type Field type definitions Binary Biometric FieldSet Length Text UDF Wiegand FieldSet field example XML FieldSet field type File access rights File communication mode File data File definition file access rights DESFire Card Template XML Specifications 59

60 Index file communication mode file data file ID File definition example XML File ID H Hand geometry L Length and padding field property Length field example XML Length field type LG iris templates O Overview of DESFire card template XML.. 5 P PK_COMP fingerprint templates R Rules for defining fields at least one of a group of fields existence of field depends on another 49 only one of a group of fields overview value of one field depends on another 49 T Text field example XML Text field type Type field property U UDF field example XML UDF field type W Wiegand field example XML Wiegand field type DESFire Card Template XML Specifications

61 Index DESFire Card Template XML Specifications 61

62 UTC Fire & Security Americas Corporation, Inc Pittsford-Victor Road Pittsford, New York USA Tel Fax