Debian Codegraph @

deps/libneon/src/ne_ssl.h

raw
1 /*
2 SSL/TLS abstraction layer for neon
3 Copyright (C) 2003-2006, 2009, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 /* ne_ssl.h defines an interface for loading and accessing the
23 * properties of SSL certificates. */
24
25 #ifndef NE_SSL_H
26 #define NE_SSL_H 1
27
28 #include <sys/types.h>
29
30 #include "ne_defs.h"
31
32 NE_BEGIN_DECLS
33
34
35
36 ///
37
38 /* A "distinguished name"; a unique name for some entity. */
39 typedef struct ne_ssl_dname_s ne_ssl_dname;
40
41 /* Returns a single-line string representation of a distinguished
42 * name, intended to be human-readable (e.g. "Acme Ltd., Norfolk,
43 * GB"). Return value is a UTF-8-encoded malloc-allocated string and
44 * must be free'd by the caller. */
45 char *ne_ssl_readable_dname(const ne_ssl_dname *dn);
46
47 /* Returns zero if 'dn1' and 'dn2' refer to same name, or non-zero if
48 * they are different. */
49 int ne_ssl_dname_cmp(const ne_ssl_dname *dn1, const ne_ssl_dname *dn2);
50
51 /* An SSL certificate. */
52 typedef struct ne_ssl_certificate_s ne_ssl_certificate;
53
54 /* Read a certificate from a file in PEM format; returns NULL if the
55 * certificate could not be parsed. */
56 ne_ssl_certificate *ne_ssl_cert_read(const char *filename);
57
58 /* Write a certificate to a file in PEM format; returns non-zero if
59 * the certificate could not be written. */
60 int ne_ssl_cert_write(const ne_ssl_certificate *cert, const char *filename);
61
62 /* Export a certificate to a base64-encoded, NUL-terminated string.
63 * The returned string is malloc-allocated and must be free()d by the
64 * caller. */
65 char *ne_ssl_cert_export(const ne_ssl_certificate *cert);
66
67 /* Import a certificate from a base64-encoded string as returned by
68 * ne_ssl_cert_export(). Returns a certificate object or NULL if
69 * 'data' was not valid. */
70 ne_ssl_certificate *ne_ssl_cert_import(const char *data);
71
72 /* Returns the identity of the certificate, or NULL if none is given.
73 * For a server certificate this will be the hostname of the server to
74 * which the cert was issued. A NUL-terminated UTF-8-encoded string
75 * is returned, which is valid for the lifetime of the certificate
76 * object. */
77 const char *ne_ssl_cert_identity(const ne_ssl_certificate *cert);
78
79 /* Return the certificate of the entity which signed certificate
80 * 'cert'. Returns NULL if 'cert' is self-signed or the issuer
81 * certificate is not available; if non-NULL, the pointer is valid for
82 * the lifetime of the certificate object. */
83 const ne_ssl_certificate *ne_ssl_cert_signedby(const ne_ssl_certificate *cert);
84
85 /* Returns the distinguished name of the certificate issuer. */
86 const ne_ssl_dname *ne_ssl_cert_issuer(const ne_ssl_certificate *cert);
87
88 /* Returns the distinguished name of the certificate subject. */
89 const ne_ssl_dname *ne_ssl_cert_subject(const ne_ssl_certificate *cert);
90
91 #define NE_SSL_DIGESTLEN (60)
92
93 /* Calculate the certificate digest ("fingerprint") and format it as a
94 * NUL-terminated hex string in 'digest', of the form "aa:bb:...:ff".
95 * Returns zero on success or non-zero if there was an internal error
96 * whilst calculating the digest. 'digest' must be at least
97 * NE_SSL_DIGESTLEN bytes in length. */
98 int ne_ssl_cert_digest(const ne_ssl_certificate *cert, char *digest);
99
100 /* Copy the validity times for the certificate 'cert' into 'from' and
101 * 'until' (either may be NULL). If the time cannot be represented by
102 * a time_t value, then (time_t)-1 will be written. */
103 void ne_ssl_cert_validity_time(const ne_ssl_certificate *cert,
104 time_t *from, time_t *until);
105
106 #define NE_SSL_VDATELEN (30)
107 /* Copy the validity times into buffers 'from' and 'until' as
108 * NUL-terminated human-readable strings, using RFC 1123-style date
109 * formatting (and not localized, so always using English month/week
110 * names). The buffers must be at least NE_SSL_VDATELEN bytes in
111 * length, and either may be NULL. */
112 void ne_ssl_cert_validity(const ne_ssl_certificate *cert,
113 char *from, char *until);
114
115 /* Returns zero if 'c1' and 'c2' refer to the same certificate, or
116 * non-zero otherwise. */
117 int ne_ssl_cert_cmp(const ne_ssl_certificate *c1,
118 const ne_ssl_certificate *c2);
119
120 /* Deallocate memory associated with certificate. */
121 void ne_ssl_cert_free(ne_ssl_certificate *cert);
122
123 /* A client certificate (and private key). A client certificate
124 * object has state; the object is either in the "encrypted" or
125 * "decrypted" state. */
126 typedef struct ne_ssl_client_cert_s ne_ssl_client_cert;
127
128 /* Read a client certificate and private key from a PKCS12 file;
129 * returns NULL if the file could not be parsed, or otherwise
130 * returning a client certificate object. The returned object may be
131 * in either the encrypted or decrypted state. */
132 ne_ssl_client_cert *ne_ssl_clicert_read(const char *filename);
133
134
135
136 /* Returns non-zero if client cert is in the encrypted state. */
137 int ne_ssl_clicert_encrypted(const ne_ssl_client_cert *ccert);
138
139
140 /*
141 * Load client certificate from PEM files
142 **/
143 ne_ssl_client_cert *ne_ssl_clicert_pem_read(const char* pkey, const char* cred, const char* password);
144
145
146 /* Duplicate a client certificate object
147 * Must be in a decrypted state */
148 ne_ssl_client_cert *ne_ssl_dup_client_cert(const ne_ssl_client_cert *cc);
149
150 /* Returns the "friendly name" given for the client cert, or NULL if
151 * none given. Returns a NUL-terminated, UTF-8-encoded string. This
152 * function may be used on a ccert object in either encrypted or
153 * decrypted state. */
154 const char *ne_ssl_clicert_name(const ne_ssl_client_cert *ccert);
155
156 /* Decrypt the encrypted client cert using the given password.
157 * Returns non-zero on failure, in which case, the ccert object
158 * remains in the encrypted state and the function may be called again
159 * with a different password. This function has undefined behaviour
160 * for a ccert object which is in the decrypted state. */
161 int ne_ssl_clicert_decrypt(ne_ssl_client_cert *ccert, const char *password);
162
163 /* Return the actual certificate part of the client certificate (never
164 * returns NULL). This function has undefined behaviour for a ccert
165 * object which is in the encrypted state. */
166 const ne_ssl_certificate *ne_ssl_clicert_owner(const ne_ssl_client_cert *ccert);
167
168 /* Destroy a client certificate object. This function may be used on
169 * a ccert object in either the encrypted or decrypted state. */
170 void ne_ssl_clicert_free(ne_ssl_client_cert *ccert);
171
172
173 /* SSL context object. The interfaces to manipulate an SSL context
174 * are only needed when interfacing directly with ne_socket.h. */
175 typedef struct ne_ssl_context_s ne_ssl_context;
176
177 /* Context creation modes: */
178 #define NE_SSL_CTX_CLIENT (0) /* client context */
179 #define NE_SSL_CTX_SERVER (1) /* default server context */
180 #define NE_SSL_CTX_SERVERv2 (2) /* SSLv2-specific server context */
181
182
183
184
185 ne_ssl_context *ne_ssl_context_create(int mode);
186
187 /* Client mode: trust the given certificate 'cert' in context 'ctx'. */
188 void ne_ssl_context_trustcert(ne_ssl_context *ctx, const ne_ssl_certificate *cert);
189
190 /* trust all the CA certificate contained in the directory dir for this ssl context */
191 int ne_ssl_context_trust_add_ca_path(ne_ssl_context * ctx, const char* path);
192
193 /* Server mode: use given cert and key (filenames to PEM certificates). */
194 int ne_ssl_context_keypair(ne_ssl_context *ctx,
195 const char *cert, const char *key);
196
197 /* Server mode: set client cert verification options: required is non-zero if
198 * a client cert is required, if ca_names is non-NULL it is a filename containing
199 * a set of PEM certs from which CA names are sent in the ccert request. */
200 int ne_ssl_context_set_verify(ne_ssl_context *ctx, int required,
201 const char *ca_names, const char *verify_cas);
202
203 #define NE_SSL_CTX_SSLv2 (0)
204 /* Set a flag for the SSL context. */
205 void ne_ssl_context_set_flag(ne_ssl_context *ctx, int flag, int value);
206
207 /* Destroy an SSL context. */
208 void ne_ssl_context_destroy(ne_ssl_context *ctx);
209
210 NE_END_DECLS
211
212 #endif