Rework LuCI build system
[project/luci.git] / libs / luci-lib-nixio / axTLS / bindings / csharp / axTLS.cs
1 /*
2  * Copyright (c) 2007, Cameron Rich
3  * 
4  * All rights reserved.
5  * 
6  * Redistribution and use in source and binary forms, with or without 
7  * modification, are permitted provided that the following conditions are met:
8  *
9  * * Redistributions of source code must retain the above copyright notice, 
10  *   this list of conditions and the following disclaimer.
11  * * Redistributions in binary form must reproduce the above copyright notice, 
12  *   this list of conditions and the following disclaimer in the documentation 
13  *   and/or other materials provided with the distribution.
14  * * Neither the name of the axTLS project nor the names of its contributors 
15  *   may be used to endorse or promote products derived from this software 
16  *   without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
22  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
25  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
26  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30
31 /**
32  * A wrapper around the unmanaged interface to give a semi-decent C# API
33  */
34
35 using System;
36 using System.Runtime.InteropServices;
37 using System.Net.Sockets;
38
39 /**
40  * @defgroup csharp_api C# API.
41  *
42  * Ensure that the appropriate Dispose() methods are called when finished with
43  * various objects - otherwise memory leaks will result.
44  * @{
45  */
46 namespace axTLS
47 {
48     /**
49      * @class SSL
50      * @ingroup csharp_api 
51      * @brief A representation of an SSL connection.
52      */
53     public class SSL
54     {
55         public IntPtr m_ssl;    /**< A pointer to the real SSL type */
56
57         /**
58          * @brief Store the reference to an SSL context.
59          * @param ip [in] A reference to an SSL object.
60          */
61         public SSL(IntPtr ip)
62         {
63             m_ssl = ip;
64         }
65
66         /**
67          * @brief Free any used resources on this connection. 
68          * 
69          * A "Close Notify" message is sent on this connection (if possible). 
70          * It is up to the application to close the socket.
71          */
72         public void Dispose()
73         {
74             axtls.ssl_free(m_ssl);
75         }
76
77         /**
78          * @brief Return the result of a handshake.
79          * @return SSL_OK if the handshake is complete and ok.
80          * @see ssl.h for the error code list.
81          */
82         public int HandshakeStatus()
83         {
84             return axtls.ssl_handshake_status(m_ssl);
85         }
86
87         /**
88          * @brief Return the SSL cipher id.
89          * @return The cipher id which is one of:
90          * - SSL_AES128_SHA (0x2f)
91          * - SSL_AES256_SHA (0x35)
92          * - SSL_RC4_128_SHA (0x05)
93          * - SSL_RC4_128_MD5 (0x04)
94          */
95         public byte GetCipherId()
96         {
97             return axtls.ssl_get_cipher_id(m_ssl);
98         }
99
100         /**
101          * @brief Get the session id for a handshake. 
102          * 
103          * This will be a 32 byte sequence and is available after the first
104          * handshaking messages are sent.
105          * @return The session id as a 32 byte sequence.
106          * @note A SSLv23 handshake may have only 16 valid bytes.
107          */
108         public byte[] GetSessionId()
109         {
110             IntPtr ptr = axtls.ssl_get_session_id(m_ssl);
111             byte sess_id_size = axtls.ssl_get_session_id_size(m_ssl);
112             byte[] result = new byte[sess_id_size];
113             Marshal.Copy(ptr, result, 0, sess_id_size);
114             return result;
115         }
116
117         /**
118          * @brief Retrieve an X.509 distinguished name component.
119          * 
120          * When a handshake is complete and a certificate has been exchanged, 
121          * then the details of the remote certificate can be retrieved.
122          *
123          * This will usually be used by a client to check that the server's 
124          * common name matches the URL.
125          *
126          * A full handshake needs to occur for this call to work.
127          *
128          * @param component [in] one of:
129          * - SSL_X509_CERT_COMMON_NAME
130          * - SSL_X509_CERT_ORGANIZATION
131          * - SSL_X509_CERT_ORGANIZATIONAL_NAME
132          * - SSL_X509_CA_CERT_COMMON_NAME
133          * - SSL_X509_CA_CERT_ORGANIZATION
134          * - SSL_X509_CA_CERT_ORGANIZATIONAL_NAME
135          * @return The appropriate string (or null if not defined)
136          */
137         public string GetCertificateDN(int component)
138         {
139             return axtls.ssl_get_cert_dn(m_ssl, component);
140         }
141     }
142
143     /**
144      * @class SSLUtil
145      * @ingroup csharp_api 
146      * @brief Some global helper functions.
147      */
148     public class SSLUtil
149     {
150
151         /**
152          * @brief Return the build mode of the axTLS project.
153          * @return The build mode is one of:
154          * - SSL_BUILD_SERVER_ONLY
155          * - SSL_BUILD_ENABLE_VERIFICATION
156          * - SSL_BUILD_ENABLE_CLIENT
157          * - SSL_BUILD_FULL_MODE
158          */
159         public static int BuildMode()
160         {
161             return axtls.ssl_get_config(axtls.SSL_BUILD_MODE);
162         }
163
164         /**
165          * @brief Return the number of chained certificates that the 
166          * client/server supports.
167          * @return The number of supported server certificates.
168          */
169         public static int MaxCerts()
170         {
171             return axtls.ssl_get_config(axtls.SSL_MAX_CERT_CFG_OFFSET);
172         }
173
174         /**
175          * @brief Return the number of CA certificates that the client/server
176          * supports.
177          * @return The number of supported CA certificates.
178          */
179         public static int MaxCACerts()
180         {
181             return axtls.ssl_get_config(axtls.SSL_MAX_CA_CERT_CFG_OFFSET);
182         }
183
184         /**
185          * @brief Indicate if PEM is supported.
186          * @return true if PEM supported.
187          */
188         public static bool HasPEM()
189         {
190             return axtls.ssl_get_config(axtls.SSL_HAS_PEM) > 0 ? true : false;
191         }
192
193         /**
194          * @brief Display the text string of the error.
195          * @param error_code [in] The integer error code.
196          */
197         public static void DisplayError(int error_code)
198         {
199             axtls.ssl_display_error(error_code);
200         }
201
202         /**
203          * @brief Return the version of the axTLS project.
204          */
205         public static string Version()
206         {
207             return axtls.ssl_version();
208         }
209     }
210
211     /**
212      * @class SSLCTX
213      * @ingroup csharp_api 
214      * @brief A base object for SSLServer/SSLClient.
215      */
216     public class SSLCTX
217     {
218         /**
219          * @brief A reference to the real client/server context.
220          */
221         protected IntPtr m_ctx;
222
223         /**
224          * @brief Establish a new client/server context.
225          *
226          * This function is called before any client/server SSL connections are 
227          * made.  If multiple threads are used, then each thread will have its 
228          * own SSLCTX context. Any number of connections may be made with a 
229          * single context. 
230          *
231          * Each new connection will use the this context's private key and 
232          * certificate chain. If a different certificate chain is required, 
233          * then a different context needs to be be used.
234          *
235          * @param options [in]  Any particular options. At present the options
236          * supported are:
237          * - SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if 
238          * the server authentication fails. The certificate can be 
239          * authenticated later with a call to VerifyCert().
240          * - SSL_CLIENT_AUTHENTICATION (server only): Enforce client 
241          * authentication i.e. each handshake will include a "certificate 
242          * request" message from the server.
243          * - SSL_DISPLAY_BYTES (full mode build only): Display the byte 
244          * sequences during the handshake.
245          * - SSL_DISPLAY_STATES (full mode build only): Display the state 
246          * changes during the handshake.
247          * - SSL_DISPLAY_CERTS (full mode build only): Display the 
248          * certificates that are passed during a handshake.
249          * - SSL_DISPLAY_RSA (full mode build only): Display the RSA key 
250          * details that are passed during a handshake.
251          * @param num_sessions [in] The number of sessions to be used for 
252          * session caching. If this value is 0, then there is no session 
253          * caching.
254          * @return A client/server context.
255          */
256         protected SSLCTX(uint options, int num_sessions)
257         {
258             m_ctx = axtls.ssl_ctx_new(options, num_sessions);
259         }
260
261         /**
262          * @brief Remove a client/server context.
263          *
264          * Frees any used resources used by this context. Each connection will 
265          * be sent a "Close Notify" alert (if possible).
266          */
267         public void Dispose()
268         {
269             axtls.ssl_ctx_free(m_ctx);
270         }
271
272         /**
273          * @brief Read the SSL data stream.
274          * @param ssl [in] An SSL object reference.
275          * @param in_data [out] After a successful read, the decrypted data 
276          * will be here. It will be null otherwise.
277          * @return The number of decrypted bytes:
278          * - if > 0, then the handshaking is complete and we are returning the 
279          * number of decrypted bytes. 
280          * - SSL_OK if the handshaking stage is successful (but not yet 
281          * complete).  
282          * - < 0 if an error.
283          * @see ssl.h for the error code list.
284          * @note Use in_data before doing any successive ssl calls.
285          */
286         public int Read(SSL ssl, out byte[] in_data)
287         {
288             IntPtr ptr = IntPtr.Zero;
289             int ret = axtls.ssl_read(ssl.m_ssl, ref ptr);
290
291             if (ret > axtls.SSL_OK)
292             {
293                 in_data = new byte[ret];
294                 Marshal.Copy(ptr, in_data, 0, ret);
295             }
296             else
297             {
298                 in_data = null;
299             }
300
301             return ret;
302         }
303
304         /**
305          * @brief Write to the SSL data stream.
306          * @param ssl [in] An SSL obect reference.
307          * @param out_data [in] The data to be written
308          * @return The number of bytes sent, or if < 0 if an error.
309          * @see ssl.h for the error code list.
310          */
311         public int Write(SSL ssl, byte[] out_data)
312         {
313             return axtls.ssl_write(ssl.m_ssl, out_data, out_data.Length);
314         }
315
316         /**
317          * @brief Write to the SSL data stream.
318          * @param ssl [in] An SSL obect reference.
319          * @param out_data [in] The data to be written
320          * @param out_len [in] The number of bytes to be written
321          * @return The number of bytes sent, or if < 0 if an error.
322          * @see ssl.h for the error code list.
323          */
324         public int Write(SSL ssl, byte[] out_data, int out_len)
325         {
326             return axtls.ssl_write(ssl.m_ssl, out_data, out_len);
327         }
328
329         /**
330          * @brief Find an ssl object based on a Socket reference.
331          *
332          * Goes through the list of SSL objects maintained in a client/server 
333          * context to look for a socket match.
334          * @param s [in] A reference to a <A HREF="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemnetsocketssocketclasstopic.asp">Socket</A> object.
335          * @return A reference to the SSL object. Returns null if the object 
336          * could not be found.
337          */
338         public SSL Find(Socket s)
339         {
340             int client_fd = s.Handle.ToInt32();
341             return new SSL(axtls.  ssl_find(m_ctx, client_fd));
342         }
343
344         /**
345          * @brief Authenticate a received certificate.
346          * 
347          * This call is usually made by a client after a handshake is complete 
348          * and the context is in SSL_SERVER_VERIFY_LATER mode.
349          * @param ssl [in] An SSL object reference.
350          * @return SSL_OK if the certificate is verified.
351          */
352         public int VerifyCert(SSL ssl)
353         {
354             return axtls.ssl_verify_cert(ssl.m_ssl);
355         }
356
357         /**
358          * @brief Force the client to perform its handshake again.
359          *
360          * For a client this involves sending another "client hello" message.
361          * For the server is means sending a "hello request" message.
362          *
363          * This is a blocking call on the client (until the handshake 
364          * completes).
365          * @param ssl [in] An SSL object reference.
366          * @return SSL_OK if renegotiation instantiation was ok
367          */
368         public int Renegotiate(SSL ssl)
369         {
370             return axtls.ssl_renegotiate(ssl.m_ssl);
371         }
372
373         /**
374          * @brief Load a file into memory that is in binary DER or ASCII PEM 
375          * format.
376          *
377          * These are temporary objects that are used to load private keys,
378          * certificates etc into memory.
379          * @param obj_type [in] The format of the file. Can be one of:
380          * - SSL_OBJ_X509_CERT (no password required)
381          * - SSL_OBJ_X509_CACERT (no password required)
382          * - SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
383          * - SSL_OBJ_P8 (RC4-128 encrypted data supported)
384          * - SSL_OBJ_P12 (RC4-128 encrypted data supported)
385          *
386          * PEM files are automatically detected (if supported).
387          * @param filename [in] The location of a file in DER/PEM format.
388          * @param password [in] The password used. Can be null if not required.
389          * @return SSL_OK if all ok
390          */
391         public int ObjLoad(int obj_type, string filename, string password)
392         {
393             return axtls.ssl_obj_load(m_ctx, obj_type, filename, password);
394         }
395
396         /**
397          * @brief Transfer binary data into the object loader.
398          *
399          * These are temporary objects that are used to load private keys,
400          * certificates etc into memory.
401          * @param obj_type [in] The format of the memory data.
402          * @param data [in] The binary data to be loaded.
403          * @param len [in] The amount of data to be loaded.
404          * @param password [in] The password used. Can be null if not required.
405          * @return SSL_OK if all ok
406          */
407         public int ObjLoad(int obj_type, byte[] data, int len, string password)
408         {
409             return axtls.ssl_obj_memory_load(m_ctx, obj_type, 
410                                             data, len, password);
411         }
412     }
413
414     /**
415      * @class SSLServer
416      * @ingroup csharp_api 
417      * @brief The server context.
418      *
419      * All server connections are started within a server context.
420      */
421     public class SSLServer : SSLCTX
422     {
423         /**
424          * @brief Start a new server context.
425          * 
426          * @see SSLCTX for details.
427          */
428         public SSLServer(uint options, int num_sessions) :
429                             base(options, num_sessions) {}
430
431         /**
432          * @brief Establish a new SSL connection to an SSL client.
433          *
434          * It is up to the application to establish the initial socket 
435          * connection.
436          *
437          * Call Dispose() when the connection is to be removed.
438          * @param s [in] A reference to a <A HREF="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemnetsocketssocketclasstopic.asp">Socket</A> object.
439          * @return An SSL object reference.
440          */
441         public SSL Connect(Socket s)
442         {
443             int client_fd = s.Handle.ToInt32();
444             return new SSL(axtls.ssl_server_new(m_ctx, client_fd));
445         }
446     }
447
448     /**
449      * @class SSLClient
450      * @ingroup csharp_api
451      * @brief The client context.
452      *
453      * All client connections are started within a client context.
454      */
455     public class SSLClient : SSLCTX
456     {
457         /**
458          * @brief Start a new client context.
459          * 
460          * @see SSLCTX for details.
461          */
462         public SSLClient(uint options, int num_sessions) :
463                         base(options, num_sessions) {}
464
465         /**
466          * @brief Establish a new SSL connection to an SSL server.
467          *
468          * It is up to the application to establish the initial socket 
469          * connection.
470          *
471          * This is a blocking call - it will finish when the handshake is 
472          * complete (or has failed).
473          *
474          * Call Dispose() when the connection is to be removed.
475          * @param s [in] A reference to a <A HREF="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemnetsocketssocketclasstopic.asp">Socket</A> object.
476          * @param session_id [in] A 32 byte session id for session resumption. 
477          * This can be null if no session resumption is not required.
478          * @return An SSL object reference. Use SSL.handshakeStatus() to check 
479          * if a handshake succeeded.
480          */
481         public SSL Connect(Socket s, byte[] session_id)
482         {
483             int client_fd = s.Handle.ToInt32();
484             byte sess_id_size = (byte)(session_id != null ? 
485                                 session_id.Length : 0);
486             return new SSL(axtls.ssl_client_new(m_ctx, client_fd, session_id,
487                         sess_id_size));
488         }
489     }
490 }
491 /** @} */