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 thing 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 will 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.

The ASP.NET 4.5 MachineKey class brings serious security to the table!

The MachineKey class of .NET 4.0 was a real breath of fresh air. It simplified the task of cryptographically protecting sensitive data into just a few short lines of code. It could be effortlessly configured to function in web farms and cloud-based solutions by simply synchronizing the machine keys across all servers. You could feed it practically anything and it never complained. It's level of security was excellent and was easily customized to suit pretty much whatever needs you had.

Encrypting was as simple as

string encryptedString = MachineKey.Encode(Encoding.UTF8.GetBytes(mySecretString), MachineKeyProtection.All);

and decrypting was as simple as

byte[] decryptedData = MachineKey.Decode(encryptedString, MachineKeyProtection.All);

This could be easily fitted into custom methods to provide numerous helpful tasks, such as generating salted password encryptions to be stored in databases, encrypting serialized objects to be stored in cookies (such as custom forms authentication-type implementations or sessions), protecting shopping cart data. The list goes on.

The MachineKeyProtection enumeration parameter allows you to specify exactly what level of protection you wish to implement, which can be helpful for specific needs. Say you need to ensure something is heavily protected and would like to include an HMAC for validation. The "All" option does this for you. Maybe you have a piece of data that you would like to protect, but it's security isn't mission critical and performance speed is more the priority (as in, say, a large collection of small objects). The "Encrypt" parameter would most likely be the enumeration of choice. Point is, it allows for tailoring to specific scenarios.

Enter the .NET 4.5 revamp!

At first glance, I was a little unsure. While the revamped 4.5 version of the MachineKey class contains the now depreciated Encode and Decode methods, it now has two new methods:

MachineKey.Protect(byte[] data, params string[] purposes)

and

MachineKey.Unprotect(byte[] protectedData, params string[] purposes)

My first thought was "ughh... what did you do to my MachineKey?!?!". After checking up on documentation that "ughh" feeling turned into a "WOW!".

The idea behind the "purposes" parameter(s) is it provides a way to supply, as the parameter name suggests, purposes for the data being protected. Think of it as being able to supply contextual boundaries for the use of the data. You'll notice that this parameter is also decorated with the params modifier, allowing for a variable amount of string parameters to be supplied, such as:

byte[] myUnprotectedBytes = Encoding.UTF8.GetBytes("Hello World!");
byte[] myProtectedBytes = MachineKey.Protect(myUnprotectedBytes, "some special pupose");


Let's imagine that the purpose "some special purpose" really is some special reason that the string "Hello World!" needs to be protected from prying eyes.
Here's the cool part: Since I supplied "some special purpose" as a purpose parameter during the Protect() call, for the data to be unprotected again and restored to it's previous state, the exact same case-sensitive purpose(s) MUST be supplied during the Unprotect() call:

byte[] myUnprotectedBytes = MachineKey.Unprotect(myProtectedBytes, "some special pupose");
string originalString = Encoding.UTF8.GetString(myUnprotectedBytes);

Like I said earlier, the params string[] purposes parameters provide a sort of contextual boundary for the data. If I had instead supplied a different string such as "GIVE ME THE SECRET!" as a purpose during the Unprotect() call, I would have received a rather abstract exception thrown stating "a cryptographic error occurred", which is also nice, as it doesn't give too much details about what exactly went wrong, but we know what happened and that's a nice feature in my opinion as well. This would have also occurred if I had provided the proper purpose and included additional string parameters that were not used during the Protect() call.
Now, I don't know for sure, so don't quote me, but I think the methods may be internally using the purposes params as a form of "salting" the encryption as its being processed. Again, this is only speculation so don't quote me. It just seems this way to me.

You may have noticed that with the new 4.5 methods, we no longer are required to pass a MachineKeyProtection enumeration as a parameter. This is because the new approach is to now apply all protection by default, which should be viewed as a big plus. I will say however, that although the old methods are now depreciated, there may still be occasions where you may choose to use the old methods for the sake of specifying to only "Encrypt" without an HMAC and without validation of purposes for the data in less security-sensitive, more performance-sensitive scenarios.

You may have also noticed that the new methods do not directly take strings as input data or return strings as return values. They deal entirely with bytes. Don't view this as having more work to do. View this as the framework relinquishing FULL control of our data to us, the programmers! Essentially it modularized the specific processes of protecting/unprotecting data, and allows us to decide how we want to handle our data before and after the calls to the API.

If the full weight of this incredible revamp to include purposes is not yet apparent to you, fret not for I will shed some light and get those creative wheels turning for you!

Obviously, purposes provided an enormous security boost. It's like requiring 1, or even many passwords to access the data. But there's much more to this than meets the eye...

These purpose parameters can have as little, or as much meaning as you choose. They can be dynamic, user-specific values, application-specific values, session-specific values. You name it. A programmer I respect very much, Brock Allen covered a great scenario used in a cookie-based temp data API using a very clever implementation of dynamically using the Identity property of the current thread principal as a purpose when protecting and unprotecting, ensuring that only the intended user may access the data. You can view his post here.

You could even take this a step further and create a custom class that is designed to act as a "Purpose Factory" to dynamically handle purposes for specific scenarios or you could even create an entire hierarchy of classes or enums designed to provided more specific purposes for different scenarios.

Anyways, simply put, the new MachineKey of .NET 4.5 is a game changer and I suspect we'll be seeing some pretty clever ideas coming out of the woodworks with it.

My new Blog is here!

I've been meaning to get around to setting up a blog for awhile now where I could share code ideas and samples. Finally, I've decided to get it started. It feels a little strange because I'm more of a framework, server-side kind of guy so a blog, as funny as it sounds, feels very foreign to me. I'm sure I'll get the hang of it soon enough though and, of course, feel free to make suggestions or requests as you see fit.

Much like my diverse span of personal interests, I hope this blog will grow to cover a multitude of topics relating to all that is code! I hope that the topics discussed will be of use to people and inspire you to be creative and think outside of the box. Creativity is the mother of innovation!

I'd also like to take a quick second to say that while I welcome comments, questions and suggestions (including corrections where required, we all make mistakes sometimes) and will always do my best to respond to relevant posts, spam will not be tolerated. Please be kind and considerate to others who may be reading posts here.

With that said, thank you for dropping by and I look forward to hearing from you!