]>
Commit | Line | Data |
---|---|---|
98995a5a FT |
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 | ||
26 | typedef 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 | **/ | |
94 | typedef | |
95 | EFI_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 | **/ | |
123 | typedef | |
124 | EFI_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 | **/ | |
166 | typedef | |
167 | EFI_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 | **/ | |
210 | typedef | |
211 | EFI_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 | /** | |
222 | This function provides direct access to the reader. | |
223 | ||
224 | This function gives direct control to send commands to the driver or the reader. | |
225 | The ControlCode to use is vendor dependant; the only standard code defined is | |
226 | the one to get PC/SC part 10 features. | |
227 | ||
228 | InBuffer and Outbuffer may be NULL when ControlCode operation does not require | |
229 | them. | |
230 | ||
231 | @param[in] This Indicates a pointer to the calling context. | |
232 | @param[in] ControlCode The control code for the operation to perform. | |
233 | @param[in] InBuffer A pointer to the input parameters. | |
234 | @param[in] InBufferLength Size, in bytes, of input parameters. | |
235 | @param[out] OutBuffer A pointer to the output parameters. | |
236 | @param[in, out] OutBufferLength On input, maximal size, in bytes, to store output | |
237 | parameters. | |
238 | On output, the size, in bytes, of output parameters. | |
239 | ||
240 | @retval EFI_SUCCESS The requested command completed successfully. | |
241 | @retval EFI_INVALID_PARAMETER This is NULL. | |
242 | @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but: | |
243 | InBuffer is NULL or InBufferLenth is NULL or | |
244 | InBuffer is not NULL but InBufferLenth is less than | |
245 | expected. | |
246 | @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL. | |
247 | @retval EFI_UNSUPPORTED ControlCode is not supported. | |
248 | @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output | |
249 | parameters. | |
250 | OutBufferLength has been updated to the required value. | |
251 | @retval EFI_NO_MEDIA There is no card in the reader and the control code | |
252 | specified requires one. | |
253 | @retval EFI_NOT_READY ControlCode requires a powered card to operate. | |
254 | @retval EFI_PROTOCOL_ERROR A protocol error has occurred. | |
255 | @retval EFI_TIMEOUT The reader did not respond. | |
256 | @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. | |
257 | @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. | |
258 | ||
259 | **/ | |
260 | typedef | |
261 | EFI_STATUS | |
262 | (EFIAPI *EFI_SMART_CARD_READER_CONTROL) ( | |
263 | IN EFI_SMART_CARD_READER_PROTOCOL *This, | |
264 | IN UINT32 ControlCode, | |
265 | IN UINT8 *InBuffer OPTIONAL, | |
266 | IN UINTN InBufferLength OPTIONAL, | |
267 | OUT UINT8 *OutBuffer OPTIONAL, | |
268 | IN OUT UINTN *OutBufferLength OPTIONAL | |
269 | ); | |
270 | ||
271 | /** | |
272 | This function retrieves a reader or smart card attribute. | |
273 | ||
274 | Possibly supported attrib values are listed in "PC/SC specification, Part 3: | |
275 | Requirements for PC-Connected Interface Devices". | |
276 | ||
277 | @param[in] This Indicates a pointer to the calling context. | |
278 | @param[in] Attrib Identifier for the attribute to retrieve. | |
279 | @param[out] OutBuffer A pointer to a buffer that will contain | |
280 | attribute data. | |
281 | @param[in, out] OutBufferLength On input, maximal size, in bytes, to store | |
282 | attribute data. | |
283 | On output, the size, in bytes, of attribute | |
284 | data. | |
285 | ||
286 | @retval EFI_SUCCESS The requested command completed successfully. | |
287 | @retval EFI_INVALID_PARAMETER This is NULL. | |
288 | @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0. | |
289 | @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output | |
290 | parameters. | |
291 | OutBufferLength has been updated to the required value. | |
292 | @retval EFI_UNSUPPORTED Attribis not supported | |
293 | @retval EFI_NO_MEDIA There is no card in the reader and Attrib value | |
294 | requires one. | |
295 | @retval EFI_NOT_READY Attrib requires a powered card to operate. | |
296 | @retval EFI_PROTOCOL_ERROR A protocol error has occurred. | |
297 | @retval EFI_TIMEOUT The reader did not respond. | |
298 | @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. | |
299 | ||
300 | **/ | |
301 | typedef | |
302 | EFI_STATUS | |
303 | (EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) ( | |
304 | IN EFI_SMART_CARD_READER_PROTOCOL *This, | |
305 | IN UINT32 Attrib, | |
306 | OUT UINT8 *OutBuffer, | |
307 | IN OUT UINTN *OutBufferLength | |
308 | ); | |
309 | ||
310 | /// | |
311 | /// Smart card aware application invokes this protocol to get access to an inserted | |
312 | /// smart card in the reader or to the reader itself. | |
313 | /// | |
314 | struct _EFI_SMART_CARD_READER_PROTOCOL { | |
315 | EFI_SMART_CARD_READER_CONNECT SCardConnect; | |
316 | EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect; | |
317 | EFI_SMART_CARD_READER_STATUS SCardStatus; | |
318 | EFI_SMART_CARD_READER_TRANSMIT SCardTransmit; | |
319 | EFI_SMART_CARD_READER_CONTROL SCardControl; | |
320 | EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib; | |
321 | }; | |
322 | ||
323 | extern EFI_GUID gEfiSmartCardReaderProtocolGuid; | |
324 | ||
325 | #endif | |
326 |