- .NET API: Added support for TLS event handler (LIB61850-373)

dotnet/IEC61850forCSharp/TLS.cs

@@ -1,7 +1,7 @@
 /*
  *  TLS.cs
  *
- *  Copyright 2017 Michael Zillgith
+ *  Copyright 2017-2022 Michael Zillgith
  *
  *  This file is part of libIEC61850.
  *
@@ -37,6 +37,173 @@ namespace IEC61850
 {
     namespace TLS
     {
+        public enum TLSConfigVersion
+        {
+            NOT_SELECTED = 0,
+            SSL_3_0 = 3,
+            TLS_1_0 = 4,
+            TLS_1_1 = 5,
+            TLS_1_2 = 6,
+            TLS_1_3 = 7
+        }
+
+        public enum TLSEventLevel
+        {
+            INFO = 0,
+            WARNING = 1,
+            INCIDENT = 2
+        }
+
+        public enum TLSEventCode
+        {
+            ALM_ALGO_NOT_SUPPORTED = 1,
+            ALM_UNSECURE_COMMUNICATION = 2,
+            ALM_CERT_UNAVAILABLE = 3,
+            ALM_BAD_CERT = 4,
+            ALM_CERT_SIZE_EXCEEDED = 5,
+            ALM_CERT_VALIDATION_FAILED = 6,
+            ALM_CERT_REQUIRED = 7,
+            ALM_HANDSHAKE_FAILED_UNKNOWN_REASON = 8,
+            WRN_INSECURE_TLS_VERSION = 9,
+            INF_SESSION_RENEGOTIATION = 10,
+            ALM_CERT_EXPIRED = 11,
+            ALM_CERT_REVOKED = 12,
+            ALM_CERT_NOT_CONFIGURED = 13,
+            ALM_CERT_NOT_TRUSTED = 14
+        }
+
+        public class TLSConnection
+        {
+            [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
+            static extern int TLSConnection_getTLSVersion(IntPtr self);
+
+            [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
+            static extern IntPtr TLSConnection_getPeerAddress(IntPtr self, IntPtr peerAddrBuf);
+
+            [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
+            static extern IntPtr TLSConnection_getPeerCertificate(IntPtr self, out int certSize);
+
+            private IntPtr self;
+            private bool isValid;
+
+            internal TLSConnection(IntPtr self)
+            {
+                this.self = self;
+                isValid = true;
+            }
+
+            // To be called by event callback caller after callback execution
+            internal void InValidate()
+            {
+                lock (this)
+                {
+                    isValid = false;
+                }
+            }
+
+            /// <summary>
+            /// TLS version used by the connection
+            /// </summary>
+            public TLSConfigVersion TLSVersion
+            {
+                get
+                {
+                    lock (this)
+                    {
+                        if (isValid)
+                        {
+                            return (TLSConfigVersion)TLSConnection_getTLSVersion((IntPtr)self);
+                        }
+                        else
+                        {
+                            throw new InvalidOperationException("Object cannot be used outside of TLS event callback");
+                        }
+                    }
+                }
+            }
+
+            /// <summary>
+            /// Peer IP address and TCP port of the TLS connection
+            /// </summary>
+            public string PeerAddress
+            {
+                get
+                {
+                    lock (this)
+                    {
+                        if (isValid)
+                        {
+                            IntPtr peerAddrBuf = Marshal.AllocHGlobal(130);
+                            IntPtr peerAddrStr = TLSConnection_getPeerAddress(this.self, peerAddrBuf);
+
+                            string peerAddr = null;
+
+                            if (peerAddrStr != IntPtr.Zero)
+                            {
+                                peerAddr = Marshal.PtrToStringAnsi(peerAddrStr);
+                            }
+
+                            Marshal.FreeHGlobal(peerAddrBuf);
+
+                            return peerAddr;
+                        }
+                        else
+                        {
+                            throw new InvalidOperationException("Object cannot be used outside of TLS event callback");
+                        }
+                    }
+                }
+            }
+
+            /// <summary>
+            /// TLS certificate used by the peer
+            /// </summary>
+            public byte[] PeerCertificate
+            {
+                get
+                {
+                    lock (this)
+                    {
+                        if (isValid)
+                        {
+                            int certSize;
+
+                            IntPtr certBuffer = TLSConnection_getPeerCertificate(self, out certSize);
+
+                            if (certBuffer != IntPtr.Zero)
+                            {
+                                if (certSize > 0)
+                                {
+                                    byte[] cert = new byte[certSize];
+
+                                    Marshal.Copy(certBuffer, cert, 0, certSize);
+
+                                    return cert;
+                                }
+                            }
+
+                            return null;
+                        }
+                        else
+                        {
+                            throw new InvalidOperationException("Object cannot be used outside of TLS event callback");
+                        }
+                    }
+                }
+            }
+
+        }
+
+        /// <summary>
+        /// TLS security event handler
+        /// </summary>
+        /// <param name="parameter">user provided context paramter to be passed to the handler</param>
+        /// <param name="eventLevel">severity level of the event</param>
+        /// <param name="eventCode">code to identify the event type</param>
+        /// <param name="message">text message describing the event</param>
+        /// <param name="connection">TLS connection that caused the event</param>
+        public delegate void TLSEventHandler(object parameter, TLSEventLevel eventLevel, TLSEventCode eventCode, string message, TLSConnection connection);
+
         /// <summary>
         /// A container for TLS configuration and certificates.
         /// </summary>
@@ -57,7 +224,7 @@ namespace IEC61850
             static extern void TLSConfiguration_setAllowOnlyKnownCertificates(IntPtr self, [MarshalAs(UnmanagedType.I1)] bool value);
 
             [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
-			static extern void TLSConfiguration_setChainValidation (IntPtr self, [MarshalAs(UnmanagedType.I1)] bool value);
+            static extern void TLSConfiguration_setChainValidation(IntPtr self, [MarshalAs(UnmanagedType.I1)] bool value);
 
             [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
             static extern void TLSConfiguration_setClientMode(IntPtr self);
@@ -76,7 +243,7 @@ namespace IEC61850
 
             [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
             [return: MarshalAs(UnmanagedType.I1)]
-			static extern bool TLSConfiguration_setOwnKeyFromFile (IntPtr self, string filename, string keyPassword);
+            static extern bool TLSConfiguration_setOwnKeyFromFile(IntPtr self, string filename, string keyPassword);
 
             [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
             [return: MarshalAs(UnmanagedType.I1)]
@@ -94,13 +261,52 @@ namespace IEC61850
             [return: MarshalAs(UnmanagedType.I1)]
             static extern bool TLSConfiguration_addCACertificateFromFile(IntPtr self, string filename);
 
-			public TLSConfiguration() {
+            private TLSEventHandler eventHandler = null;
-				self = TLSConfiguration_create ();
+            private object eventHandlerParameter = null;
+
+            [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
+            private delegate void InternalTLSEventHandler(IntPtr parameter, int eventLevel, int eventCode, IntPtr message, IntPtr tlsCon);
+
+            private InternalTLSEventHandler internalTLSEventHandlerRef = null;
+
+            [DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
+            static extern void TLSConfiguration_setEventHandler(IntPtr self, InternalTLSEventHandler handler, IntPtr parameter);
+
+            void InternalTLSEventHandlerImpl(IntPtr parameter, int eventLevel, int eventCode, IntPtr message, IntPtr tlsCon)
+            {
+                if (eventHandler != null)
+                {
+                    TLSConnection connection = new TLSConnection(tlsCon);
+
+                    string msg = Marshal.PtrToStringAnsi(message);
+
+                    eventHandler(eventHandlerParameter, (TLSEventLevel)eventLevel, (TLSEventCode)eventCode, msg, connection);
+
+                    connection.InValidate();
+                }
+            }
+
+            public void SetEventHandler(TLSEventHandler handler, object parameter)
+            {
+                this.eventHandler = handler;
+                this.eventHandlerParameter = parameter;
+
+                if (internalTLSEventHandlerRef == null)
+                {
+                    internalTLSEventHandlerRef = new InternalTLSEventHandler(InternalTLSEventHandlerImpl);
+
+                    TLSConfiguration_setEventHandler(self, internalTLSEventHandlerRef, IntPtr.Zero);
+                }
+            }
+
+            public TLSConfiguration()
+            {
+                self = TLSConfiguration_create();
             }
 
             ~TLSConfiguration()
             {
-				Dispose ();
+                Dispose();
             }
 
             internal IntPtr GetNativeInstance()
@@ -110,100 +316,114 @@ namespace IEC61850
 
             public bool AllowOnlyKnownCertificates
             {
-				set {
+                set
-					TLSConfiguration_setAllowOnlyKnownCertificates (self, value);
+                {
+                    TLSConfiguration_setAllowOnlyKnownCertificates(self, value);
                     allowOnlyKnownCerts = value;
                 }
-				get {
+                get
+                {
                     return allowOnlyKnownCerts;
                 }
             }
 
             public bool ChainValidation
             {
-				set {
+                set
-					TLSConfiguration_setChainValidation (self, value);
+                {
+                    TLSConfiguration_setChainValidation(self, value);
                     chainValidation = value;
                 }
-				get {
+                get
+                {
                     return chainValidation;
                 }
             }
 
             public void SetClientMode()
             {
-				TLSConfiguration_setClientMode (self);
+                TLSConfiguration_setClientMode(self);
             }
 
             public void SetOwnCertificate(string filename)
             {
-				if (TLSConfiguration_setOwnCertificateFromFile (self, filename) == false) {
+                if (TLSConfiguration_setOwnCertificateFromFile(self, filename) == false)
-					throw new CryptographicException ("Failed to read certificate from file");
+                {
+                    throw new CryptographicException("Failed to read certificate from file");
                 }
             }
 
             public void SetOwnCertificate(X509Certificate2 cert)
             {
-				byte[] certBytes = cert.GetRawCertData ();
+                byte[] certBytes = cert.GetRawCertData();
 
-				if (TLSConfiguration_setOwnCertificate (self, certBytes, certBytes.Length) == false) {
+                if (TLSConfiguration_setOwnCertificate(self, certBytes, certBytes.Length) == false)
-					throw new CryptographicException ("Failed to set certificate");
+                {
+                    throw new CryptographicException("Failed to set certificate");
                 }
             }
 
             public void AddAllowedCertificate(string filename)
             {
-				if (TLSConfiguration_addAllowedCertificateFromFile (self, filename) == false) {
+                if (TLSConfiguration_addAllowedCertificateFromFile(self, filename) == false)
-					throw new CryptographicException ("Failed to read allowed certificate from file");
+                {
+                    throw new CryptographicException("Failed to read allowed certificate from file");
                 }
             }
 
             public void AddAllowedCertificate(X509Certificate2 cert)
             {
-				byte[] certBytes = cert.GetRawCertData ();
+                byte[] certBytes = cert.GetRawCertData();
 
-				if (TLSConfiguration_addAllowedCertificate (self, certBytes, certBytes.Length) == false) {
+                if (TLSConfiguration_addAllowedCertificate(self, certBytes, certBytes.Length) == false)
-					throw new CryptographicException ("Failed to add allowed certificate");
+                {
+                    throw new CryptographicException("Failed to add allowed certificate");
                 }
             }
 
             public void AddCACertificate(string filename)
             {
-				if (TLSConfiguration_addCACertificateFromFile (self, filename) == false) {
+                if (TLSConfiguration_addCACertificateFromFile(self, filename) == false)
-					throw new CryptographicException ("Failed to read CA certificate from file");
+                {
+                    throw new CryptographicException("Failed to read CA certificate from file");
                 }
             }
 
             public void AddCACertificate(X509Certificate2 cert)
             {
-				byte[] certBytes = cert.GetRawCertData ();
+                byte[] certBytes = cert.GetRawCertData();
 
-				if (TLSConfiguration_addCACertificate (self, certBytes, certBytes.Length) == false) {
+                if (TLSConfiguration_addCACertificate(self, certBytes, certBytes.Length) == false)
-					throw new CryptographicException ("Failed to add CA certificate");
+                {
+                    throw new CryptographicException("Failed to add CA certificate");
                 }
             }
 
-			public void SetOwnKey (string filename, string password)
+            public void SetOwnKey(string filename, string password)
+            {
+                if (TLSConfiguration_setOwnKeyFromFile(self, filename, password) == false)
                 {
-				if (TLSConfiguration_setOwnKeyFromFile (self, filename, password) == false) {
+                    throw new CryptographicException("Failed to read own key from file");
-					throw new CryptographicException ("Failed to read own key from file");
                 }
             }
 
-			public void SetOwnKey (X509Certificate2 key, string password)
+            public void SetOwnKey(X509Certificate2 key, string password)
             {
-				byte[] certBytes = key.Export (X509ContentType.Pkcs12);
+                byte[] certBytes = key.Export(X509ContentType.Pkcs12);
 
-				if (TLSConfiguration_setOwnKey (self, certBytes, certBytes.Length, password) == false) {
+                if (TLSConfiguration_setOwnKey(self, certBytes, certBytes.Length, password) == false)
-					throw new CryptographicException ("Failed to set own key");
+                {
+                    throw new CryptographicException("Failed to set own key");
                 }
             }
 
             public void Dispose()
             {
-				lock (this) {
+                lock (this)
-					if (self != IntPtr.Zero) {
+                {
-						TLSConfiguration_destroy (self);
+                    if (self != IntPtr.Zero)
+                    {
+                        TLSConfiguration_destroy(self);
                         self = IntPtr.Zero;
                     }
                 }