#Write a configuration into a Master Card

#Role

Write the specified configuration into a Master card.

#Prototype

URL : /master-card

Method : PUT

URL Params : None

Request data :

• either an Address=Value list completed by a reader string and a KEYSET_DATA object,
• or a CONFIG_DATA object also completed by a reader string and a KEYSET_DATA object.

#Request data based on Address=Value list

Request data shall be a JSON associative array. Every entry is a Address-Value pair in the form

"Address of register (hexadecimal)" : "Value of register (hexadecimal)".

Since register addresses are on 2 bytes, the Address field is a 4-character hexadecimal string. The Value field is either an empty string ("") to store a blank value, or an hexadecimal string. The actual length must match the size of the register.

Valid values for register addresses are from 0200 to 03FF and therefore cover the Configuration bank and the Templates bank only.

The name of the PC/SC reader to be used to write the card has to be provided in the Reader string.

The optional Keyset object, with type KEYSET_DATA provides all the keys and parameters that are necessary to format the card.

Data structure

{
	"Reader": "Reader name",
	"Keyset": {
		...
	},
	"Address": "Value",
	...
}

Example

{
	"Reader": "SpringCard Puck Contactless 0",
	"Keyset": {
		"KeyId": "A2A609DD",
		"PrivateKey": "46B9E861B63D3509C88B7817275A30D22D62C8CD8FA6486DDEE35EF0D8E0495F",
		"PublicKey": "2500E7F3FBDDF2842903F544DD (...) 1E772A128A5820A924A2FA05162EB662987A9F",
		"AuthKeyRead": "54DA0BBD5D59F622AB25F442C7E345EC",
		"AuthKeyWrite": "4BF6A0BCA64CDE4E10F7E3D132818070"	
	},
	"0201": "44656D6F2062656E63682C20522644204C6162",    
	"02C0": "02",
	"0310": "12345678",
	"0311": "AB",
	"0327": "00CAFE01FECA02",
	"034C": "48656C6C6F2C20776F726C64"
}

NOTE:

All the Configuration and Templates registers that are not explicitly defined are cleared to their default value, exactly as if they were assigned a null value. There is no way to keep earlier values when writing a new configuration (except for the device-specific values that are kept if specific=preserve is set in the parameters of the request).

#Request data based on a CONFIG_DATA object

A CONFIG_DATA object may store more than the 0200 to 03FF registers allowed by the simple Address=Value format.

In particular, this object must be used to write security keys or to change the key settings in the device’s Secure Elements, or to write X509 certificates in the device’s Certificate Store.

When this methode is used, the Address field is one 1 byte only, therefore a 2-character hexadecimal string. The Value field is either an empty string ("") to store a blank value, or an hexadecimal string. The actual length must match the size of the register, key entry or certificate entry that is targetted.

It is also possible to change the understanding of the Value field by adding a Format modifier in the Address fields; see CONFIG_DATA Format modifier for details.

The name of the PC/SC reader to be used to write the card has to be provided in the Reader string.

The optional Keyset object, with type KEYSET_DATA provides all the keys and parameters that are necessary to format the card.

Data structure

{
	"Reader": "Reader name",
	"Keyset": {
		...
	},
	"config": {
		"Address": "Value,"
		...
	},
	"templates": {
		"Address": "Value,"
		...        
		},
	"samav": {
		"Address": "Value,"
		...        
	},
	"atecc": {
		"Address": "Value,"
		...        
	},
	"certificates": {
		"Address": "Value,"
		...    
	}
}

Example

{
	"Reader": "SpringCard Puck Contactless 0",    
	"Keyset": {
		"KeyId": "A2A609DD",
		"PrivateKey": "46B9E861B63D3509C88B7817275A30D22D62C8CD8FA6486DDEE35EF0D8E0495F",
		"PublicKey": "2500E7F3FBDDF2842903F544DD (...) 1E772A128A5820A924A2FA05162EB662987A9F",
		"AuthKeyRead": "54DA0BBD5D59F622AB25F442C7E345EC",
		"AuthKeyWrite": "4BF6A0BCA64CDE4E10F7E3D132818070"
	},
	"config": {
		"01.string": "Demo bench, R&D Lab",
		"C0": "02"
	},
	"templates": {
		"10": "12345678",
		"11": "AB",
		"27": "00CAFE01FECA02",
		"4C": "48656C6C6F2C20776F726C64"
	},
	"certificates": {
		"0E.base64": "MIID2DCCAsCgAwIBAgIJA (...) 0c6p0I2XkO+oQc0i5oAd229yLg"
	}
}

NOTES:

• All the Configuration and Templates registers that are not explicitly defined are cleared to their default value, exactly as if they were assigned a null value. There is no way to keep earlier values when writing a new configuration (except for the device-specific values that are kept if specific=preserve is set in the parameters of the request).

• On the other-hand, X509 certificates in the Certificate Store and security key in the Secure Elements that are not explicitely set in the CONFIG_DATA object are preserved. Write an empty value for any entry that should be cleared.

#Success Response

Code : 200 OK

Content : a CONFIG-GUID object, as specified below.

#CONFIG-GUID object definition

Field name	Type	Status	Description
Result	string	always	Constant value: success
ConfigId	string	always	The configuration GUID computed from the data

#Example

{
	"Result": "success",
	"ConfigId": "80B4667D-71D0-0BDC-AA81-95DCA20A44E1"
}

#Error Response

See Error Responses.