1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
#ifndef SEQUOIA_H
#define SEQUOIA_H
#include <stddef.h>
#include <stdint.h>
/* sequoia::Context. */
/*/
/// A `struct sq_context *` is required for many operations.
///
/// # Example
///
/// ```c
/// struct sq_context *ctx sq_context_new("org.sequoia-pgp.example");
/// if (ctx == NULL) { ... }
/// ```
/*/
struct sq_context;
/*/
/// Represents a `Context` configuration.
/*/
struct sq_config;
/*/
/// Network policy for Sequoia.
///
/// With this policy you can control how Sequoia accesses remote
/// systems.
/*/
/* Do not contact remote systems. */
#define SQ_NETWORK_POLICY_OFFLINE 0
/* Only contact remote systems using anonymization techniques
* like TOR. */
#define SQ_NETWORK_POLICY_ANONYMIZED 1
/* Only contact remote systems using transports offering
* encryption and authentication like TLS. */
#define SQ_NETWORK_POLICY_ENCRYPTED 2
/* Contact remote systems even with insecure transports. */
#define SQ_NETWORK_POLICY_INSECURE 3
/*/
/// Creates a Context with reasonable defaults.
///
/// `domain` should uniquely identify your application, it is strongly
/// suggested to use a reversed fully qualified domain name that is
/// associated with your application. `domain` must not be `NULL`.
///
/// Returns `NULL` on errors.
/*/
struct sq_context *sq_context_new(const char *domain);
/*/
/// Frees a context.
/*/
void sq_context_free(struct sq_context *context);
/*/
/// Creates a Context that can be configured.
///
/// `domain` should uniquely identify your application, it is strongly
/// suggested to use a reversed fully qualified domain name that is
/// associated with your application. `domain` must not be `NULL`.
///
/// The configuration is seeded like in `sq_context_new`, but can be
/// modified. A configuration has to be finalized using
/// `sq_config_build()` in order to turn it into a Context.
/*/
struct sq_config *sq_context_configure(const char *domain);
/*/
/// Returns the domain of the context.
/*/
const char *sq_context_domain(const struct sq_context *ctx);
/*/
/// Returns the directory containing shared state.
/*/
const char *sq_context_home(const struct sq_context *ctx);
/*/
/// Returns the directory containing backend servers.
/*/
const char *sq_context_lib(const struct sq_context *ctx);
/*/
/// Returns the network policy.
/*/
uint8_t sq_context_network_policy(const struct sq_context *ctx);
/* sequoia::Config. */
/*/
/// Finalizes the configuration and return a `Context`.
///
/// Consumes `cfg`. Returns `NULL` on errors.
/*/
struct sq_context *sq_config_build(struct sq_config *cfg);
/*/
/// Sets the directory containing shared state.
/*/
void sq_config_home(struct sq_config *cfg, const char *home);
/*/
/// Sets the directory containing backend servers.
/*/
void sq_config_lib(struct sq_config *cfg, const char *lib);
/*/
/// Sets the network policy.
/*/
void sq_config_network_policy(struct sq_config *cfg, uint8_t policy);
/* sequoia::openpgp::types. */
/*/
/// Uniquely identifies OpenPGP keys.
/*/
struct sq_keyid;
/*/
/// Returns a KeyID with the given `id`.
/*/
struct sq_keyid *sq_keyid_new (uint64_t id);
/*/
/// Returns a KeyID with the given `id` encoded as hexadecimal string.
/*/
struct sq_keyid *sq_keyid_from_hex (const char *id);
/*/
/// Frees a keyid object.
/*/
void sq_keyid_free (struct sq_keyid *keyid);
/* sequoia::keys. */
/*/
/// A transferable public key (TPK).
///
/// A TPK (see [RFC 4880, section 11.1]) can be used to verify
/// signatures and encrypt data. It can be stored in a keystore and
/// uploaded to keyservers.
///
/// [RFC 4880, section 11.1]: https://tools.ietf.org/html/rfc4880#section-11.1
/*/
struct sq_tpk;
/*/
/// Returns the first TPK found in `buf`.
///
/// `buf` must be an OpenPGP encoded message.
/*/
struct sq_tpk *sq_tpk_from_bytes (const char *b, size_t len);
/*/
/// Frees the TPK.
/*/
void sq_tpk_free (struct sq_tpk *tpk);
/*/
/// Dumps the TPK.
/*/
void sq_tpk_dump (const struct sq_tpk *tpk);
/* sequoia::net. */
/*/
/// For accessing keyservers using HKP.
/*/
struct sq_keyserver;
/*/
/// Returns a handle for the given URI.
///
/// `uri` is a UTF-8 encoded value of a keyserver URI,
/// e.g. `hkps://examle.org`.
///
/// Returns `NULL` on errors.
/*/
struct sq_keyserver *sq_keyserver_new (const struct sq_context *ctx,
const char *uri);
/*/
/// Returns a handle for the given URI.
///
/// `uri` is a UTF-8 encoded value of a keyserver URI,
/// e.g. `hkps://examle.org`. `cert` is a DER encoded certificate of
/// size `len` used to authenticate the server.
///
/// Returns `NULL` on errors.
/*/
struct sq_keyserver *sq_keyserver_with_cert (const struct sq_context *ctx,
const char *uri,
const uint8_t *cert,
size_t len);
/*/
/// Returns a handle for the SKS keyserver pool.
///
/// The pool `hkps://hkps.pool.sks-keyservers.net` provides HKP
/// services over https. It is authenticated using a certificate
/// included in this library. It is a good default choice.
///
/// Returns `NULL` on errors.
/*/
struct sq_keyserver *sq_keyserver_sks_pool (const struct sq_context *ctx);
/*/
/// Frees a keyserver object.
/*/
void sq_keyserver_free (struct sq_keyserver *ks);
/*/
/// Retrieves the key with the given `keyid`.
///
/// Returns `NULL` on errors.
/*/
struct sq_tpk *sq_keyserver_get (struct sq_keyserver *ks,
const struct sq_keyid *id);
#endif
|
