Saturday, April 6, 2013

Including Lua 5.x in Visual Studio 2012 for Embedding in C++

Lua is an incredibly powerful dynamically-typed scripting language. Seriously. Anyone that thinks Perl is the king of scripting has clearly not spent some intimate time with Lua. It can process literally millions of large rows in less than a second. It is this speed and power that makes it a very desirable tool to embed in high-stress systems. Many get their first taste of Lua from video games, a great example being Blizzard Entertainment's epic MMORPG World of Warcraft. Recently, even the powerful online information giant Wikipedia made the leap to implement Lua (kudos to them, I might add!).

It's really a quite sad story how Javascript became the scripting language of choice for the web, rather than Lua. A clever play on the name of a completely unrelated technology at it's emergence (Java) left Lua out in the cold. A sad loss for the web really, but that's a whole other story.

The point is, you don't have to let your applications miss out! Embedding Lua in C++ is a great choice for many things. Sadly, finding a straight-forward answer on how to do so can be a rather discouraging task. Especially if you are working with Visual c++ in Visual Studio. The great news is, it's actually quite easy to do and I'm here to show you exactly how to do it!

The first thing you will need is a suitable Lua build. The current version is 5.2.x. The following approach I'm going to show you is interchangeable with both Lua 5.1 and Lua 5.2. While I will be demonstrating how to do this in Visual Studio 2012, this will also work in Visual Studio 2010.

There are 2 routes you can go about this. You can download the source from Lua.Org directly, or you can get a windows-centric distribution from Lua for Windows, which installs via a simple msi installer and includes a whole plethora of helpful extension libraries for almost anything you could think of doing with Lua. The catch with LuaForWindows is, it's Lua 5.1 and will not be carried on to future versions of Lua. If you get the source from Lua.Org you will have run a build on it yourself (I may be including an article on doing this soon, as it's very easy to do).

Once you have your build of Lua, you are ready to embed it in your c++ project. To do this, you need to tell Visual Studio's compiler and linker where to look for it and what libraries to include.

Let's start with telling it where to look.

I'm going to assume you have installed Lua to the default "c:\Program Files (x86)" directory on your machine. If you have not, don't worry, we'll cover that too.

With your project in visual studio, open the project's "Properties" window. Go to the "VC++ Directories" tab. In here, you will need to edit "Include Directories", "Reference Directories" and "Library Directories". To edit these values, you click on the value, then click on the arrow box that will appear in the top-right side of the value box, and select edit. The window that pops up will allow you to edit the values for the particular line.

First set the "Include Directories" value. If you have installed Lua to the ProgramFiles (x86) directory as suggested above, you can use the following simple macro to point to the directory:

$(ProgramFiles)\Lua\5.1\include

If your directory looks a bit different, just adjust the above text accordingly (example: \Lua\lua-5.1\include).

If you have Lua installed to another location, you can simply use the file navigation tool that appears in the editor window to navigate to the location and point to it. The important part is, you want it pointing to the "/include" folder within the Lua directory.

The process for the remaining settings are the same procedure. Below is a list of each setting and the value to set it to. Remember to adjust the file path if needed.


Include Directories: $(ProgramFiles)\Lua\5.1\include as demonstrated above.
Reference Directories: $(ProgramFiles)\Lua\5.1\lib points to the "lib" folder
Library Directories: $(ProgramFiles)\Lua\5.1\lib points to the "lib" folder

Now visual studio knows what directories to look in when searching for file dependencies. The last part to do is to tell it what lib(s) specifically to include.

In the properties window, go to the "Linker" tab, select the "Input" tab within that, and we will be editing the "Additional Dependencies" value.

As before, click the line, then click the arrow box and select edit. This time we simply need to tell it what lib to use. The only important thing to note is that any libs we specify in here need to be on separate lines.

Enter the following value:

lua5.1.lib

If it is a different version you are using, just adjust the value to the appropriate version.

That's it! Lua is now successfully referenced in our application and ready to be implemented. To see for yourself, try including the c++-specific Lua header file in code:

#include <lua.hpp>

You will notice at the bottom of the visual studio window it is loading the dependencies. If it is giving you error messages that things can not be found, you will need to double check that you have referenced the correct directory locations.

Congratulations! You are ready to use Lua in your application! I will be doing an article about setting up the Lua instance within your app but if you MUST get some info on how to do it, Check out the online version of the book Programming in Lua here. It is written by one of the founders of Lua and includes everything you need to get started.

Cryptographically Secure Pseudo-Random Number Generation in .NET

Many times we need to generate random variables for numerous reasons. When a trivial value is required, the Random class can be just fine but when you need a value that will be used to keep something unique and secure, the Random class simply will not do. This is where the RNGCryptoServiceProvider class comes in to play.

Most would be quick to simply pump out whatever value they need from this class and assume all is well, but beware, as this may not be the case.

If the value will be used to keep something secure, it needs to be cryptographically secure and while that is the purpose of the RNGCryptoServiceProvider, it is still up to you to make sure that the value is even capable of being secure.

Entropy is a term used to describe the randomness of a value. According to current guidelines, a value must contain at least 64 bits of entropy to be considered cryptographically secure. That means, it must contain 64 truly random bits, at a minimum. The reasoning of this is that with current computing power, anything less that 64 random bits would be a relatively trivial task for a machine to guess by sequential generation of values. I'm not saying this can't be done easily with a very powerful system or, as many "hackers" are doing these days, pushing the work on to a very powerful GPU, but we should be safe to assume that the entry point for secure random values will start at 64 bit of entropy.

Lets take a look at how this can be done in a re-usable class, by creating an example. We'll call it CSPRNG (Cryptographically Secure Pseudo Random Number Generator).

    public static class CSPRNG
    {
        public static byte[] GetBytes(int entropy)
        {
            if (entropy < 8)
            {
                throw new ArgumentOutOfRangeException("entropy",
                    "Entropy must be 64 bits or greater to be cryptographically secure.");
            }
            using (RNGCryptoServiceProvider _rng = new RNGCryptoServiceProvider())
            {
                byte[] _obj = new byte[entropy];
                _rng.GetBytes(_obj);
                return _obj;
            }
        }

        public static Guid GetGuid()
        {
            using (RNGCryptoServiceProvider _rng = new RNGCryptoServiceProvider())
            {
                byte[] _obj = new byte[16];
                _rng.GetBytes(_obj);
                return new Guid(_obj);
            }
        }

        public static long GetInt64(bool allowNegativeValue = false)
        {
            using (RNGCryptoServiceProvider _rng = new RNGCryptoServiceProvider())
            {
                byte[] _obj = new byte[8];
                _rng.GetBytes(_obj);
                long _num = BitConverter.ToInt64(_obj, 0);
                if (!allowNegativeValue)
                {
                    _num = (_num & ~(1L << 63));
                }
                return _num;
            }
        }
    }

This static class is capable of creating 3 different types of variables for use: a byte array with a minimum length of 8 bytes(64 bits), a Guid(128 bits) and an Int64 value(64 bits).

You will notice that the above class does NOT allow any value less than 64 bits (or 8 bytes) to be generated. If it is requested to do so, it will throw an error. This is so we can be assured that this class will ONLY create cryptographically secure values.

The Int64 generator features an optional parameter that controls if negative values are allowed or not. It does so by guaranteeing the most significant bit is ALWAYS turned-off when non-negative values are not allowed. Technically, this could be an issue. A signed Int64 value uses the most significant bit to indicate the signage of the value (positive or negative). By forcing positive values, we are making this value only 63 bits of entropy, but I allow this 1 exception to break the rule for the simple reason that sometimes a negative value will break the requirements of the caller. Another option would be to create an UInt64 (unsigned 64 bit integer) to ensure that all 64 bits are used for entropy.

Some may ask why a Guid would be included, as we could just simply create a seemingly random Guid from the classes static NewGuid() constructor. The reason is this: the static Guid constructor guarantees uniqueness but it does not guarantee a cryptographically secure value because it is not truly random. I've seen many posts on the web about how it would take trillions of years to create a collision and I assure you, they need to check their math, as that is not the case. On a sub-standard system, a duplicate value could be created in ~200 years. Yes that's a lot, but put that same algorithm on to a machine designed for brute force attacks and that number drops drastically.

Hope this sheds some light on keeping random values secure and feel free to use or modify the code above as you see fit.