gpg: The option --passphrase= can be empty.
[gnupg.git] / scd / app-common.h
1 /* app-common.h - Common declarations for all card applications
2  * Copyright (C) 2003, 2005, 2008 Free Software Foundation, Inc.
3  *
4  * This file is part of GnuPG.
5  *
6  * GnuPG is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * GnuPG is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, see <https://www.gnu.org/licenses/>.
18  *
19  * $Id$
20  */
21
22 #ifndef GNUPG_SCD_APP_COMMON_H
23 #define GNUPG_SCD_APP_COMMON_H
24
25 #include <npth.h>
26 #include <ksba.h>
27
28 /* Flags used with app_change_pin.  */
29 #define APP_CHANGE_FLAG_RESET    1  /* PIN Reset mode.  */
30 #define APP_CHANGE_FLAG_NULLPIN  2  /* NULL PIN mode.  */
31 #define APP_CHANGE_FLAG_CLEAR    4  /* Clear the given PIN.  */
32
33 /* Flags used with app_genkey.  */
34 #define APP_GENKEY_FLAG_FORCE    1  /* Force overwriting existing key.  */
35
36 /* Flags used with app_writekey.  */
37 #define APP_WRITEKEY_FLAG_FORCE  1  /* Force overwriting existing key.  */
38
39 /* Flags used with app_readkey.  */
40 #define APP_READKEY_FLAG_INFO    1  /* Send also a KEYPAIRINFO line.  */
41
42 /* Bit flags set by the decipher function into R_INFO.  */
43 #define APP_DECIPHER_INFO_NOPAD  1  /* Padding has been removed.  */
44
45
46 /* List of supported card types.  Generic is the usual ISO7817-4
47  * compliant card.  More specific card or token versions can be given
48  * here.  Use strcardtype() to map them to a string. */
49 typedef enum
50   {
51    CARDTYPE_GENERIC = 0,
52    CARDTYPE_YUBIKEY
53
54   } cardtype_t;
55
56 /* List of supported card applications.  The source code for each
57  * application can usually be found in an app-NAME.c file.  Use
58  * strapptype() to map them to a string.  */
59 typedef enum
60   {
61    APPTYPE_NONE = 0,
62    APPTYPE_UNDEFINED,
63    APPTYPE_OPENPGP,
64    APPTYPE_PIV,
65    APPTYPE_NKS,
66    APPTYPE_P15,
67    APPTYPE_GELDKARTE,
68    APPTYPE_DINSIG,
69    APPTYPE_SC_HSM
70   } apptype_t;
71
72
73 /* Forward declarations.  */
74 struct card_ctx_s;
75 struct app_ctx_s;
76 struct app_local_s;  /* Defined by all app-*.c.  */
77
78
79 typedef struct card_ctx_s *card_t;
80 typedef struct app_ctx_s *app_t;
81
82 /* The object describing a card.  */
83 struct card_ctx_s {
84   card_t next;
85
86   npth_mutex_t lock;
87
88   /* Number of connections currently using this application context.  */
89   unsigned int ref_count;
90
91   /* Used reader slot. */
92   int slot;
93
94   cardtype_t cardtype;     /* The token's type.  */
95   unsigned int cardversion;/* Firmware version of the token or 0.  */
96
97   unsigned int card_status;
98
99   /* The serial number is associated with the card and not with a
100    * specific app.  If a card uses different serial numbers for its
101    * applications, our code picks the serial number of a specific
102    * application and uses that.  */
103   unsigned char *serialno; /* Serialnumber in raw form, allocated. */
104   size_t serialnolen;      /* Length in octets of serialnumber. */
105
106   /* A linked list of applications used on this card.  The app at the
107    * head of the list is the currently active app; To work with the
108    * other apps, switching to that app might be needed.  Switching will
109    * put the active app at the head of the list.  */
110   app_t app;
111
112   /* Various flags.  */
113   unsigned int reset_requested:1;
114   unsigned int periodical_check_needed:1;
115 };
116
117
118 /* The object describing a card's applications.  A card may have
119  * several applications and it is usuallay required to explicity
120  * switch between applications.  */
121 struct app_ctx_s {
122   app_t next;
123
124   card_t card;  /* Link back to the card.  */
125
126   apptype_t apptype;       /* The type of the application.  */
127   unsigned int appversion; /* Version of the application or 0.     */
128   unsigned int did_chv1:1;
129   unsigned int force_chv1:1;   /* True if the card does not cache CHV1. */
130   unsigned int did_chv2:1;
131   unsigned int did_chv3:1;
132   struct app_local_s *app_local;  /* Local to the application. */
133   struct {
134     void (*deinit) (app_t app);
135     gpg_error_t (*reselect) (app_t app, ctrl_t ctrl);
136     gpg_error_t (*learn_status) (app_t app, ctrl_t ctrl, unsigned int flags);
137     gpg_error_t (*readcert) (app_t app, const char *certid,
138                      unsigned char **cert, size_t *certlen);
139     gpg_error_t (*readkey) (app_t app, ctrl_t ctrl,
140                             const char *certid, unsigned int flags,
141                             unsigned char **pk, size_t *pklen);
142     gpg_error_t (*getattr) (app_t app, ctrl_t ctrl, const char *name);
143     gpg_error_t (*setattr) (app_t app, const char *name,
144                     gpg_error_t (*pincb)(void*, const char *, char **),
145                     void *pincb_arg,
146                     const unsigned char *value, size_t valuelen);
147     gpg_error_t (*sign) (app_t app,
148                  const char *keyidstr, int hashalgo,
149                  gpg_error_t (*pincb)(void*, const char *, char **),
150                  void *pincb_arg,
151                  const void *indata, size_t indatalen,
152                  unsigned char **outdata, size_t *outdatalen );
153     gpg_error_t (*auth) (app_t app, const char *keyidstr,
154                  gpg_error_t (*pincb)(void*, const char *, char **),
155                  void *pincb_arg,
156                  const void *indata, size_t indatalen,
157                  unsigned char **outdata, size_t *outdatalen);
158     gpg_error_t (*decipher) (app_t app, const char *keyidstr,
159                              gpg_error_t (*pincb)(void*, const char *, char **),
160                              void *pincb_arg,
161                              const void *indata, size_t indatalen,
162                              unsigned char **outdata, size_t *outdatalen,
163                              unsigned int *r_info);
164     gpg_error_t (*writecert) (app_t app, ctrl_t ctrl,
165                               const char *certid,
166                               gpg_error_t (*pincb)(void*,const char *,char **),
167                               void *pincb_arg,
168                               const unsigned char *data, size_t datalen);
169     gpg_error_t (*writekey) (app_t app, ctrl_t ctrl,
170                              const char *keyid, unsigned int flags,
171                              gpg_error_t (*pincb)(void*,const char *,char **),
172                              void *pincb_arg,
173                              const unsigned char *pk, size_t pklen);
174     gpg_error_t (*genkey) (app_t app, ctrl_t ctrl,
175                            const char *keyref, const char *keytype,
176                            unsigned int flags, time_t createtime,
177                            gpg_error_t (*pincb)(void*, const char *, char **),
178                            void *pincb_arg);
179     gpg_error_t (*change_pin) (app_t app, ctrl_t ctrl,
180                        const char *chvnostr, unsigned int flags,
181                        gpg_error_t (*pincb)(void*, const char *, char **),
182                        void *pincb_arg);
183     gpg_error_t (*check_pin) (app_t app, const char *keyidstr,
184                       gpg_error_t (*pincb)(void*, const char *, char **),
185                       void *pincb_arg);
186     gpg_error_t (*with_keygrip) (app_t app, ctrl_t ctrl, int action,
187                                  const char *keygrip_str);
188   } fnc;
189 };
190
191
192 /* Action values for app_do_with_keygrip.  */
193 enum
194  {
195   KEYGRIP_ACTION_SEND_DATA,
196   KEYGRIP_ACTION_WRITE_STATUS,
197   KEYGRIP_ACTION_LOOKUP
198  };
199
200
201 /* Helper to get the slot from an APP object. */
202 static inline int
203 app_get_slot (app_t app)
204 {
205   if (app && app->card)
206     return app->card->slot;
207   return -1;
208 }
209
210
211 /*-- app-help.c --*/
212 unsigned int app_help_count_bits (const unsigned char *a, size_t len);
213 gpg_error_t app_help_get_keygrip_string_pk (const void *pk, size_t pklen,
214                                             char *hexkeygrip);
215 gpg_error_t app_help_get_keygrip_string (ksba_cert_t cert, char *hexkeygrip);
216 gpg_error_t app_help_pubkey_from_cert (const void *cert, size_t certlen,
217                                        unsigned char **r_pk, size_t *r_pklen);
218 size_t app_help_read_length_of_cert (int slot, int fid, size_t *r_certoff);
219
220
221 /*-- app.c --*/
222 const char *strcardtype (cardtype_t t);
223 const char *strapptype (apptype_t t);
224
225 void app_update_priority_list (const char *arg);
226 gpg_error_t app_send_card_list (ctrl_t ctrl);
227 char *card_get_serialno (card_t card);
228 char *app_get_serialno (app_t app);
229
230 void app_dump_state (void);
231 void application_notify_card_reset (int slot);
232 gpg_error_t check_application_conflict (card_t card, const char *name,
233                                         const unsigned char *serialno_bin,
234                                         size_t serialno_bin_len);
235 gpg_error_t card_reset (card_t card, ctrl_t ctrl, int send_reset);
236 gpg_error_t select_application (ctrl_t ctrl, const char *name, card_t *r_app,
237                                 int scan, const unsigned char *serialno_bin,
238                                 size_t serialno_bin_len);
239 gpg_error_t select_additional_application (ctrl_t ctrl, const char *name);
240 char *get_supported_applications (void);
241
242 card_t card_ref (card_t card);
243 void   card_unref (card_t card);
244 void   card_unref_locked (card_t card);
245
246 gpg_error_t app_munge_serialno (card_t card);
247 gpg_error_t app_write_learn_status (card_t card, ctrl_t ctrl,
248                                     unsigned int flags);
249 gpg_error_t app_readcert (card_t card, ctrl_t ctrl, const char *certid,
250                   unsigned char **cert, size_t *certlen);
251 gpg_error_t app_readkey (card_t card, ctrl_t ctrl,
252                          const char *keyid, unsigned int flags,
253                          unsigned char **pk, size_t *pklen);
254 gpg_error_t app_getattr (card_t card, ctrl_t ctrl, const char *name);
255 gpg_error_t app_setattr (card_t card, ctrl_t ctrl, const char *name,
256                          gpg_error_t (*pincb)(void*, const char *, char **),
257                          void *pincb_arg,
258                          const unsigned char *value, size_t valuelen);
259 gpg_error_t app_sign (card_t card, ctrl_t ctrl,
260                       const char *keyidstr, int hashalgo,
261                       gpg_error_t (*pincb)(void*, const char *, char **),
262                       void *pincb_arg,
263                       const void *indata, size_t indatalen,
264                       unsigned char **outdata, size_t *outdatalen);
265 gpg_error_t app_auth (card_t card, ctrl_t ctrl, const char *keyidstr,
266                       gpg_error_t (*pincb)(void*, const char *, char **),
267                       void *pincb_arg,
268                       const void *indata, size_t indatalen,
269                       unsigned char **outdata, size_t *outdatalen);
270 gpg_error_t app_decipher (card_t card, ctrl_t ctrl, const char *keyidstr,
271                           gpg_error_t (*pincb)(void*, const char *, char **),
272                           void *pincb_arg,
273                           const void *indata, size_t indatalen,
274                           unsigned char **outdata, size_t *outdatalen,
275                           unsigned int *r_info);
276 gpg_error_t app_writecert (card_t card, ctrl_t ctrl,
277                            const char *certidstr,
278                            gpg_error_t (*pincb)(void*, const char *, char **),
279                            void *pincb_arg,
280                            const unsigned char *keydata, size_t keydatalen);
281 gpg_error_t app_writekey (card_t card, ctrl_t ctrl,
282                           const char *keyidstr, unsigned int flags,
283                           gpg_error_t (*pincb)(void*, const char *, char **),
284                           void *pincb_arg,
285                           const unsigned char *keydata, size_t keydatalen);
286 gpg_error_t app_genkey (card_t card, ctrl_t ctrl,
287                         const char *keynostr, const char *keytype,
288                         unsigned int flags, time_t createtime,
289                         gpg_error_t (*pincb)(void*, const char *, char **),
290                         void *pincb_arg);
291 gpg_error_t app_get_challenge (card_t card, ctrl_t ctrl, size_t nbytes,
292                                unsigned char *buffer);
293 gpg_error_t app_change_pin (card_t card, ctrl_t ctrl,
294                             const char *chvnostr, unsigned int flags,
295                             gpg_error_t (*pincb)(void*, const char *, char **),
296                             void *pincb_arg);
297 gpg_error_t app_check_pin (card_t card, ctrl_t ctrl, const char *keyidstr,
298                            gpg_error_t (*pincb)(void*, const char *, char **),
299                            void *pincb_arg);
300 card_t app_do_with_keygrip (ctrl_t ctrl, int action, const char *keygrip_str);
301
302
303 /*-- app-openpgp.c --*/
304 gpg_error_t app_select_openpgp (app_t app);
305
306 /*-- app-nks.c --*/
307 gpg_error_t app_select_nks (app_t app);
308
309 /*-- app-dinsig.c --*/
310 gpg_error_t app_select_dinsig (app_t app);
311
312 /*-- app-p15.c --*/
313 gpg_error_t app_select_p15 (app_t app);
314
315 /*-- app-geldkarte.c --*/
316 gpg_error_t app_select_geldkarte (app_t app);
317
318 /*-- app-sc-hsm.c --*/
319 gpg_error_t app_select_sc_hsm (app_t app);
320
321 /*-- app-piv.c --*/
322 gpg_error_t app_select_piv (app_t app);
323
324
325 #endif /*GNUPG_SCD_APP_COMMON_H*/