GlobalPlatform on Windows Powered Smart Card

The OPEN provides an API interface that Applications may use to get services. The OPEN retains the control of the services and determines whether or not to grant each request.

The following APIs are provided to access OPEN services. They are shown in the standard Visual Basic™

function prototype format.

OpGetCardContentState

Function OpGetCardContentState (ByRef AppState as Byte) as Byte

This API is used to retrieve the Life Cycle State of the currently selected Application. The OPEN locates the AID of the currently selected Application in the GlobalPlatform Registry, and returns the Life Cycle State

In addition to application specific values, the following predefined values may be returned by this function:

• APPLICATION_INSTALLED = &H3

• APPLICATION_SELECTABLE = &H7

• SECURITY_DOMAIN_PERSONALIZED = &HF OpSetCardContentState

Function OpSetCardContentState (ByVal state as Byte) as Byte

This API allows the currently selected Application to set its own Life Cycle State.

An Application may use this function in order to change its own Life Cycle State to an application specific value.

OpSetCardState

Function OpSetCardState (ByVal state as Byte) as Byte This API changes the state of the card to the state specified.

The states may be:

• CARD_LOCKED = &H7F

• CARD_TERMINATED = &HFF

OPEN locates the registry entry of the currently selected Application and verifies that the application has the privilege to change the card state to the specified one.

OpGetCardState

Function OpGetCardState (ByRef CardState as Byte) as Byte This API returns the Life Cycle State of the card

One of the following four states will be returned by this function:

• CARD_OP_READY = &H1

• CARD_INITIALIZED = &H7

• CARD_SECURED = &HF

• CARD_LOCKED = &H7F OpSetATRHistBytes

Function OpSetATRHistBytes (ATRData() as Byte, ByVal offset as Byte, ByVal length as Byte) as Byte Paramenters:

• ATRData() – Buffer byte array containing the ATR historical bytes.

• offset – byte: Offset within the buffer where ATR historical bytes begin.

• length – byte Length of the ATR historical bytes in the buffer.

This function sets the Historical Bytes contained in the ATR. The sequence of bytes will be valid within an ATR on a subsequent reset. This service is granted only if the currently selected Application has the Default Selected privilege.

An Application may call this function in order to set the value of the Historical Bytes of the ATR. This

functionality is only accessible to the implicitly selectable Application. The Application sets the value of up to 15 Historical Bytes as well as the number of Historical Bytes within the ATR. This function may be invoked at any time in the life of the Application subsequent to the Application being set to a selectable state with the Default Selected privilege.

Security Domain API Interface on Windows Powered Smart Card

The following sections describe the API available for an application to obtain services from its associated security domain. There will be mechanism whereby CLA, INS, P1, P2, and LC can be passed back and forth between an application and its security domain. In addition, the security domain will be able to pass back a 2 two-byte ResultCode and a 1 byte CurrentSecurityLevel byte on each call. The CurrentSecurityLevel byte will be encoded as follows: Table A-2: GlobalPlatform on Windows Powered Smart Card: Security Level OpProcessSecureChannel

This function is used by an application to process APDU commands that possibly relate to the security mechanism used by the Security Domain.

As the intention is to allow an applet to be associated with a Security Domain without having any knowledge of the security mechanisms used by the Security Domain, the applet assumes that APDU commands that it does not recognize are part of the security mechanism and will be recognized by the Security Domain.

Note:

• The Security Domain will retrieve the data portion of the APDU command from the card input communication buffer, and will place any command response data in the card output communication buffer.

• The application will be responsible to output the ResultCode that was set by the Security Domain.

OpResetSecurity

This function is used to erase any secure information relating to the current secure session that may have been established.

OpDecryptData

This function is used to decrypt data that an application has placed in the card communication buffer.

Note:

• The Security Domain will retrieve the data to be decrypted from the card input communication buffer and place the results in the card output communication buffer. The decrypted data will then be retrieved by the calling application.

OpUnwrap

This function is used to process and verify the secure messaging of an incoming command.

Note:

• If the class byte indicate secures messaging (ISO/IEC 7816-4), the Security Domain will retrieve the data portion of the APDU command from the input communication buffer and will place the reformatted APDU command data in the output communication buffer. The Security Domain will have reformatted the APDU to have all data relating to the secure messaging removed.

• The Application is responsible for checking the Result Code set by the Security Domain to verify that the Security Domain was able to process the APDU according to the requirements for integrity and

confidentiality that were specified when the secure channel was established.

• If the Security Domain was unable to correctly process the APDU command, the Security Domain will have reset all information relating to the current secure session.

OpWrap

This function is used to apply additional security processing to outgoing response data and status words.

Note:

• The application must place the data to be wrapped into the card output communication buffer.

OpEncryptData

This function is used to encrypt data that an application has placed in the card communication buffer.

Note:

• The Security Domain will retrieve the data to be encrypted from the card input communication buffer and place the results in the card output communication buffer. The encrypted data will then be retrieved by the calling application.