[Enterprise] C++ api and example

1 files changed, 224 insertions, 0 deletions

diff --git a/enterprise.h b/enterprise.h
new file mode 100644
index 00000000..4d6b1fdd
--- /dev/null
+++ b/enterprise.h
@@ -0,0 +1,224 @@
+// Copyright (c) 2015-2022 Vector 35 Inc
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+
+#pragma once
+
+#include <string>
+#include <vector>
+#include <stdexcept>
+#include "binaryninjacore.h"
+
+namespace BinaryNinja
+{
+	/*!
+	    API for interacting with an Enterprise Server.
+	    These methods will only do anything on Enterprise editions of Binary Ninja.
+	 */
+	namespace EnterpriseServer
+	{
+		/*!
+		    Custom exception class for all Enterprise functions that can throw exceptions
+		 */
+		struct EnterpriseException: std::runtime_error {
+			EnterpriseException(const std::string& what): std::runtime_error(what) {}
+		};
+
+		/*!
+		    Authenticate to the server with username and password
+		    \param username Username to authenticate with
+		    \param password Password to authenticate with
+		    \param remember Remember token in keychain
+		    \return True if successful
+		 */
+		bool AuthenticateWithCredentials(const std::string& username, const std::string& password, bool remember);
+
+		/*!
+		    Authenticate with an external provider
+		    \param method Provider method
+		    \param remember Remember token in keychain
+		    \return True if successful
+		 */
+		bool AuthenticateWithMethod(const std::string& method, bool remember);
+
+		/*!
+		    Get a list of accepted methods for authentication
+		    \return List of (method, name) pairs
+		 */
+		std::vector<std::pair<std::string, std::string>> GetAuthenticationMethods();
+
+		/*!
+		    Forget saved credentials
+		    \return True if successful
+		 */
+		bool Deauthenticate();
+
+		/*!
+		    Cancel a currently running authentication task
+		 */
+		void CancelAuthentication();
+
+		/*!
+		    Perform initial connect to the server, pulling signing key and time limit
+		    \return True if successful
+		 */
+		bool Connect();
+
+		/*!
+		    Acquire or refresh a floating license
+		    \param timeout Time (in minutes)
+		    \return True if successful
+		 */
+		bool AcquireLicense(uint64_t timeout);
+
+		/*!
+		    Release the current hold on a license
+		    \return True if successful
+		 */
+		bool ReleaseLicense();
+
+		/*!
+		    Check if the server is connected
+		    \return True if connected
+		 */
+		bool IsConnected();
+
+		/*!
+		    Check if the user has authenticated with the server
+		    \return True if authenticated
+		 */
+		bool IsAuthenticated();
+
+		/*!
+		    Get currently connected username
+		    \return Username of currently connected user
+		 */
+		std::string GetUsername();
+
+		/*!
+		    Get token for current login session
+		    \return Token for currently connected user
+		 */
+		std::string GetToken();
+
+		/*!
+		    Get the display name of the currently connected server
+		    \return Display name of the currently connected server
+		 */
+		std::string GetServerName();
+
+		/*!
+		    Get the internal id of the currently connected server
+		    \return Id of the currently connected server
+		 */
+		std::string GetServerId();
+
+		/*!
+		    Get the version number of the currently connected server
+		    \return Version of the currently connected server
+		 */
+		uint64_t GetServerVersion();
+
+		/*!
+		    Get the build id string of the currently connected server
+		    \return Build id of the currently connected server
+		 */
+		std::string GetServerBuildId();
+
+		/*!
+		    Get the expiry time for the current license
+		    \return Expiry time, in seconds from the epoch
+		 */
+		uint64_t GetLicenseExpirationTime();
+
+		/*!
+		    Get the total length of the current license
+		    \return Total time, in seconds
+		 */
+		uint64_t GetLicenseDuration();
+
+		/*!
+		    Get the maximum time limit for reservations
+		    \return Maximum reservation time, in seconds
+		 */
+		uint64_t GetReservationTimeLimit();
+
+		/*!
+		    Check if the user's license is still activated
+		    \return True if still activated
+		 */
+		bool IsLicenseStillActivated();
+
+		/*!
+		    Get the last recorded error
+		    \return Error text
+		 */
+		std::string GetLastError();
+
+		/*!
+			Register an object to receive callbacks when enterprise server events happen
+			\param notify Object to receive callbacks
+		 */
+		void RegisterNotification(BNEnterpriseServerCallbacks* notify);
+
+		/*!
+			Un-register a previously registered notification handler object
+			\param notify Object to un-register
+		 */
+		void UnregisterNotification(BNEnterpriseServerCallbacks* notify);
+
+		/*!
+		    RAII object for holding an Enterprise license in a scope. Automatically
+		    releases the license when destroyed.
+
+		    \b Example:
+		    \code{.cpp}
+
+		    using namespace BinaryNinja;
+		    assert(EnterpriseServer::Connect());
+		    assert(EnterpriseServer::AuthenticateWithCredentials("username", "password", true));
+		    {
+		        EnterpriseServer::LicenseCheckout _{};
+		        Ref<BinaryView> bv = OpenView("/bin/ls", true, {}, options);
+		        printf("%llx\n", bv->GetStart());
+		        // License is released at end of scope
+		    }
+
+		    \endcode
+		 */
+		class LicenseCheckout
+		{
+			bool m_acquiredLicense;
+		public:
+			/*!
+			    RAII constructor that checks out a license. License will be refreshed
+			    automatically in a background thread while checked out, in intervals of `duration`
+			    In the event of program crash, the license will expire `duration` seconds after
+			    the most recent background refresh, so you may want a smaller value like 60 if
+			    you expect your program to crash / be killed often.
+			    See class docs for example usage.
+			    \param duration Duration for refreshes and also length of each license checkout.
+			    \throws EnterpriseException If license checkout fails
+			 */
+			explicit LicenseCheckout(int64_t duration = 900);
+
+			~LicenseCheckout();
+		};
+	}
+}