367b7e2729b6a2c17e627fd10d1d05d317521fe4
[scute.git] / src / agent.h
1 /* agent.h - Interface for talking to gpg-agent.
2    Copyright (C) 2006, 2007 g10 Code GmbH
3
4    This file is part of Scute.
5
6    Scute is free software; you can redistribute it and/or modify it
7    under the terms of the GNU General Public License as published by
8    the Free Software Foundation; either version 2 of the License, or
9    (at your option) any later version.
10
11    Scute is distributed in the hope that it will be useful, but
12    WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    General Public License for more details.
15
16    You should have received a copy of the GNU General Public License
17    along with Scute; if not, write to the Free Software Foundation,
18    Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19
20    In addition, as a special exception, g10 Code GmbH gives permission
21    to link this library: with the Mozilla Foundation's code for
22    Mozilla (or with modified versions of it that use the same license
23    as the "Mozilla" code), and distribute the linked executables.  You
24    must obey the GNU General Public License in all respects for all of
25    the code used other than "Mozilla".  If you modify this file, you
26    may extend this exception to your version of the file, but you are
27    not obligated to do so.  If you do not wish to do so, delete this
28    exception statement from your version.  */
29
30 #ifndef AGENT_H
31 #define AGENT_H 1
32
33 #include <gpg-error.h>
34 #include <stdbool.h>
35
36 #include "cert.h"
37
38 \f
39 /* An object to store information pertaining to a keypair as stored on
40  * a card.  This is commonly used as a linked list of all keys known
41  * for a card.  */
42 struct key_info_s
43 {
44   struct key_info_s *next;
45
46   char grip[41];/* The keygrip as hex encoded string.  */
47
48   unsigned char xflag;   /* Temporary flag to help processing a list. */
49
50   /* The three next items are mostly useful for OpenPGP cards.  */
51   unsigned char fprlen;  /* Use length of the next item.  */
52   unsigned char fpr[32]; /* The binary fingerprint of length FPRLEN.  */
53   unsigned long created; /* The time the key was created.  */
54
55   char keyref[1];        /* String with the keyref (e.g. OPENPGP.1).  */
56 };
57 typedef struct key_info_s *key_info_t;
58
59
60 /* The information structure for a smart card.  */
61 struct agent_card_info_s
62 {
63   char *serialno;       /* Malloced hex string.  */
64   char *cardtype;       /* Null or mallcoed string with the card type.  */
65   char *disp_name;      /* Malloced.  */
66   char *disp_lang;      /* Malloced.  */
67   int  disp_sex;        /* 0 = unspecified, 1 = male, 2 = female.  */
68   char *pubkey_url;     /* Malloced.  */
69   char *login_data;     /* Malloced.  */
70   char *private_do[4];  /* Malloced.  */
71   char cafpr1valid;
72   char cafpr2valid;
73   char cafpr3valid;
74   char cafpr1[20];
75   char cafpr2[20];
76   char cafpr3[20];
77   key_info_t kinfo;     /* Linked list with all keypair related data.  */
78   char fpr1valid;       /* Duplicated info for the legacy parts of the code. */
79   char fpr2valid;
80   char fpr3valid;
81   char fpr1[20];
82   char fpr2[20];
83   char fpr3[20];
84   unsigned int fpr1time;
85   unsigned int fpr2time;
86   unsigned int fpr3time;
87   unsigned long sig_counter;
88   int chv1_cached;      /* True if a PIN is not required for each
89                            signing.  Note that the gpg-agent might
90                            cache it anyway.  */
91   int chvmaxlen[3];     /* Maximum allowed length of a CHV.  */
92   int chvretry[3];      /* Allowed retries for the CHV; 0 = blocked.  */
93   int rng_available;    /* True if the GET CHALLENGE operation
94                            is supported. */
95   int is_piv;           /* True if this is a PIV card.  */
96 };
97 typedef struct agent_card_info_s *agent_card_info_t;
98
99
100 \f
101 /* Try to connect to the agent via socket.  Handle the server's
102    initial greeting.  */
103 gpg_error_t scute_agent_initialize (void);
104
105 /* Return the major and minor version of the agent.  */
106 int scute_agent_get_agent_version (int *minor);
107
108 /* Tear down the agent connection and release all associated
109    resources.  */
110 void scute_agent_finalize (void);
111
112 \f
113 /* Check the agent status.  This returns 0 if a token is present,
114    GPG_ERR_CARD_REMOVED if no token is present, and an error code
115    otherwise.  */
116 gpg_error_t scute_agent_check_status (void);
117
118
119 /* Call the agent to learn about a smartcard.  */
120 gpg_error_t scute_agent_learn (struct agent_card_info_s *info);
121
122 /* Release the card info structure INFO.  */
123 void scute_agent_release_card_info (struct agent_card_info_s *info);
124
125 key_info_t scute_find_kinfo (agent_card_info_t info, const char *keyref);
126
127
128 /* Sign the data DATA of length LEN with the key HEXGRIP and return
129  * the signature in SIG_RESULT and SIG_LEN.  */
130 gpg_error_t scute_agent_sign (const char *hexgrip,
131                               unsigned char *data, int len,
132                               unsigned char *sig_result, unsigned int *sig_len);
133
134 /* Determine if FPR is trusted.  */
135 gpg_error_t scute_agent_is_trusted (char *fpr, bool *is_trusted);
136
137 /* Try to get certificate for key numer NO.  */
138 gpg_error_t scute_agent_get_cert (const char *certref, struct cert *cert);
139
140 /* Get random bytes from the card. */
141 gpg_error_t scute_agent_get_random (unsigned char *data, size_t len);
142
143 #endif  /* AGENT_H */