Annotation of embedaddon/axTLS/bindings/csharp/axTLS.cs, revision 1.1.1.1
1.1 misho 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: /** @} */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to axTLS.cs CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / axTLS / bindings / csharp