VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdePkg/Include/Protocol/SmartCardReader.h@ 77662

Last change on this file since 77662 was 77662, checked in by vboxsync, 6 years ago

EFI: First step in UDK2018 merge. Does not build yet.
  • Property svn:eol-style set to native
File size: 15.0 KB
Line 
1/** @file
2 The UEFI Smart Card Reader Protocol provides an abstraction for device to provide
3 smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup
4 specifications and provides an API to applications willing to communicate with a
5 smart card or a smart card reader.
6
7 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
8 This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
12
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15
16**/
17
18#ifndef __SMART_CARD_READER_H__
19#define __SMART_CARD_READER_H__
20
21#define EFI_SMART_CARD_READER_PROTOCOL_GUID \
22 { \
23 0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \
24 }
25
26typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL;
27
28//
29// Codes for access mode
30//
31#define SCARD_AM_READER 0x0001 // Exclusive access to reader
32#define SCARD_AM_CARD 0x0002 // Exclusive access to card
33//
34// Codes for card action
35//
36#define SCARD_CA_NORESET 0x0000 // Don't reset card
37#define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset
38#define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset
39#define SCARD_CA_UNPOWER 0x0003 // Power off the card
40#define SCARD_CA_EJECT 0x0004 // Eject the card
41//
42// Protocol types
43//
44#define SCARD_PROTOCOL_UNDEFINED 0x0000
45#define SCARD_PROTOCOL_T0 0x0001
46#define SCARD_PROTOCOL_T1 0x0002
47#define SCARD_PROTOCOL_RAW 0x0004
48//
49// Codes for state type
50//
51#define SCARD_UNKNOWN 0x0000 /* state is unknown */
52#define SCARD_ABSENT 0x0001 /* Card is absent */
53#define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/
54#define SCARD_ACTIVE 0x0003 /* Card is present and powered */
55//
56// Macro to generate a ControlCode & PC/SC part 10 control code
57//
58#define SCARD_CTL_CODE(code) (0x42000000 + (code))
59#define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400)
60
61/**
62 This function requests connection to the smart card or the reader, using the
63 appropriate reset type and protocol.
64
65 The SCardConnectfunction requests access to the smart card or the reader. Upon
66 success, it is then possible to call SCardTransmit.
67
68 If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to
69 SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function
70 fails with EFI_INVALID_PARAMETER.
71
72 @param[in] This Indicates a pointer to the calling context.
73 @param[in] AccessMode Codes of access mode.
74 @param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or
75 SCARD_CA_WARMRESET.
76 @param[in] PreferredProtocols Bitmask of acceptable protocols.
77 @param[out] ActiveProtocol A flag that indicates the active protocol.
78
79 @retval EFI_SUCCESS The requested command completed successfully.
80 @retval EFI_INVALID_PARAMETER This is NULL
81 @retval EFI_INVALID_PARAMETER AccessMode is not valid.
82 @retval EFI_INVALID_PARAMETER CardAction is not valid.
83 @retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/
84 PreferredProtocols.
85 @retval EFI_NOT_READY A smart card is inserted but failed to return an ATR.
86 @retval EFI_UNSUPPORTED PreferredProtocols does not contain an available
87 protocol to use.
88 @retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is
89 no smart card inserted.
90 @retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall.
91 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
92
93**/
94typedef
95EFI_STATUS
96(EFIAPI *EFI_SMART_CARD_READER_CONNECT) (
97 IN EFI_SMART_CARD_READER_PROTOCOL *This,
98 IN UINT32 AccessMode,
99 IN UINT32 CardAction,
100 IN UINT32 PreferredProtocols,
101 OUT UINT32 *ActiveProtocol
102 );
103
104/**
105 This function releases a connection previously taken by SCardConnect.
106
107 The SCardDisconnect function releases the lock previously taken by SCardConnect.
108 In case the smart card has been removed before this call, thisfunction
109 returns EFI_SUCCESS. If there is no previous call to SCardConnect, this
110 function returns EFI_SUCCESS.
111
112 @param[in] This Indicates a pointer to the calling context.
113 @param[in] CardAction Codes for card action.
114
115 @retval EFI_SUCCESS The requested command completed successfully.
116 @retval EFI_INVALID_PARAMETER This is NULL
117 @retval EFI_INVALID_PARAMETER CardAction value is unknown.
118 @retval EFI_UNSUPPORTED Reader does not support Eject card feature
119 (disconnect was not performed).
120 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
121
122**/
123typedef
124EFI_STATUS
125(EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) (
126 IN EFI_SMART_CARD_READER_PROTOCOL *This,
127 IN UINT32 CardAction
128 );
129
130/**
131 This function retrieves some basic information about the smart card and reader.
132
133 The SCardStatusfunction retrieves basic reader and card information.
134
135 If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but
136 does not fill in such variables.
137
138 If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered
139 as valid.
140
141 @param[in] This Indicates a pointer to the calling context.
142 @param[out] ReaderName A pointer to a NULL terminated string that will
143 contain the reader name.
144 @param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the
145 maximal size, in bytes,of ReaderName.
146 On output, the required size, in bytes, for ReaderName.
147 @param[out] State Current state of the smart card reader.
148 @param[out] CardProtocol Current protocol used to communicate with the smart card.
149 @param[out] Atr A pointer to retrieve the ATR of the smart card.
150 @param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes,
151 of Atr(usually 33).
152 On output, the required size, inbytes, for the smart
153 card ATR.
154
155 @retval EFI_SUCCESS The requested command completed successfully.
156 @retval EFI_INVALID_PARAMETER This is NULL
157 @retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL
158 @retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL
159 @retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name.
160 ReaderNameLength has been updated to the required value.
161 @retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR.
162 AtrLength has been updated to the required value.
163 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
164
165**/
166typedef
167EFI_STATUS
168(EFIAPI *EFI_SMART_CARD_READER_STATUS) (
169 IN EFI_SMART_CARD_READER_PROTOCOL *This,
170 OUT CHAR16 *ReaderName OPTIONAL,
171 IN OUT UINTN *ReaderNameLength OPTIONAL,
172 OUT UINT32 *State OPTIONAL,
173 OUT UINT32 *CardProtocol OPTIONAL,
174 OUT UINT8 *Atr OPTIONAL,
175 IN OUT UINTN *AtrLength OPTIONAL
176 );
177
178/**
179 This function sends a command to the card or reader and returns its response.
180
181 The protocol to use to communicate with the smart card has been selected through
182 SCardConnectcall.
183
184 In case RAPDULength indicates a buffer too small to holdthe response APDU, the
185 function fails with EFI_BUFFER_TOO_SMALL.
186
187 @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance.
188 @param[in] CAPDU A pointer to a byte array thatcontains the Command
189 APDU to send to the smart card or reader.
190 @param[in] CAPDULength Command APDU size, in bytes.
191 @param[out] RAPDU A pointer to a byte array that will contain the
192 Response APDU.
193 @param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response
194 APDU.
195 On output, the size, in bytes, of the Response APDU.
196
197 @retval EFI_SUCCESS The requested command completed successfully.
198 @retval EFI_INVALID_PARAMETER This is NULL.
199 @retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0.
200 @retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU.
201 RAPDULength has been updated to the required value.
202 @retval EFI_NO_MEDIA There is no card in the reader.
203 @retval EFI_NOT_READY Card is not powered.
204 @retval EFI_PROTOCOL_ERROR A protocol error has occurred.
205 @retval EFI_TIMEOUT The reader did not respond.
206 @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending.
207 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
208
209**/
210typedef
211EFI_STATUS
212(EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) (
213 IN EFI_SMART_CARD_READER_PROTOCOL *This,
214 IN UINT8 *CAPDU,
215 IN UINTN CAPDULength,
216 OUT UINT8 *RAPDU,
217 IN OUT UINTN *RAPDULength
218 );
219
220/**
221 This function provides direct access to the reader.
222
223 This function gives direct control to send commands to the driver or the reader.
224 The ControlCode to use is vendor dependant; the only standard code defined is
225 the one to get PC/SC part 10 features.
226
227 InBuffer and Outbuffer may be NULL when ControlCode operation does not require
228 them.
229
230 @param[in] This Indicates a pointer to the calling context.
231 @param[in] ControlCode The control code for the operation to perform.
232 @param[in] InBuffer A pointer to the input parameters.
233 @param[in] InBufferLength Size, in bytes, of input parameters.
234 @param[out] OutBuffer A pointer to the output parameters.
235 @param[in, out] OutBufferLength On input, maximal size, in bytes, to store output
236 parameters.
237 On output, the size, in bytes, of output parameters.
238
239 @retval EFI_SUCCESS The requested command completed successfully.
240 @retval EFI_INVALID_PARAMETER This is NULL.
241 @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but:
242 InBuffer is NULL or InBufferLenth is NULL or
243 InBuffer is not NULL but InBufferLenth is less than
244 expected.
245 @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL.
246 @retval EFI_UNSUPPORTED ControlCode is not supported.
247 @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output
248 parameters.
249 OutBufferLength has been updated to the required value.
250 @retval EFI_NO_MEDIA There is no card in the reader and the control code
251 specified requires one.
252 @retval EFI_NOT_READY ControlCode requires a powered card to operate.
253 @retval EFI_PROTOCOL_ERROR A protocol error has occurred.
254 @retval EFI_TIMEOUT The reader did not respond.
255 @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending.
256 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
257
258**/
259typedef
260EFI_STATUS
261(EFIAPI *EFI_SMART_CARD_READER_CONTROL) (
262 IN EFI_SMART_CARD_READER_PROTOCOL *This,
263 IN UINT32 ControlCode,
264 IN UINT8 *InBuffer OPTIONAL,
265 IN UINTN InBufferLength OPTIONAL,
266 OUT UINT8 *OutBuffer OPTIONAL,
267 IN OUT UINTN *OutBufferLength OPTIONAL
268 );
269
270/**
271 This function retrieves a reader or smart card attribute.
272
273 Possibly supported attrib values are listed in "PC/SC specification, Part 3:
274 Requirements for PC-Connected Interface Devices".
275
276 @param[in] This Indicates a pointer to the calling context.
277 @param[in] Attrib Identifier for the attribute to retrieve.
278 @param[out] OutBuffer A pointer to a buffer that will contain
279 attribute data.
280 @param[in, out] OutBufferLength On input, maximal size, in bytes, to store
281 attribute data.
282 On output, the size, in bytes, of attribute
283 data.
284
285 @retval EFI_SUCCESS The requested command completed successfully.
286 @retval EFI_INVALID_PARAMETER This is NULL.
287 @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0.
288 @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output
289 parameters.
290 OutBufferLength has been updated to the required value.
291 @retval EFI_UNSUPPORTED Attribis not supported
292 @retval EFI_NO_MEDIA There is no card in the reader and Attrib value
293 requires one.
294 @retval EFI_NOT_READY Attrib requires a powered card to operate.
295 @retval EFI_PROTOCOL_ERROR A protocol error has occurred.
296 @retval EFI_TIMEOUT The reader did not respond.
297 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal.
298
299**/
300typedef
301EFI_STATUS
302(EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) (
303 IN EFI_SMART_CARD_READER_PROTOCOL *This,
304 IN UINT32 Attrib,
305 OUT UINT8 *OutBuffer,
306 IN OUT UINTN *OutBufferLength
307 );
308
309///
310/// Smart card aware application invokes this protocol to get access to an inserted
311/// smart card in the reader or to the reader itself.
312///
313struct _EFI_SMART_CARD_READER_PROTOCOL {
314 EFI_SMART_CARD_READER_CONNECT SCardConnect;
315 EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect;
316 EFI_SMART_CARD_READER_STATUS SCardStatus;
317 EFI_SMART_CARD_READER_TRANSMIT SCardTransmit;
318 EFI_SMART_CARD_READER_CONTROL SCardControl;
319 EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib;
320};
321
322extern EFI_GUID gEfiSmartCardReaderProtocolGuid;
323
324#endif
325
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette