Update README.md

Improve build scripts and makefiles (custom RANLIB and STRIP prefix)

Makefile.inc

@@ -1,11 +1,16 @@
 # Common makefile helper file
 
+# Allow overriding prefix for strip separately
+ifndef PREFIX_STRIP_USE
+  PREFIX_STRIP := $(PREFIX)
+endif
+
 # Note - := means expand all and save result, = means expand all each time
 AR := $(PREFIX)ar
 CC := $(PREFIX)gcc
 CXX := $(PREFIX)g++
 LD := $(PREFIX)ld
-STRIP := $(PREFIX)strip
+STRIP := $(PREFIX_STRIP)strip
 
 # Get a good guess as to our compile target
 gcc_machine := $(subst -, ,$(shell $(CC) -dumpmachine))

README.md

@@ -1,5 +1,5 @@
 # PSCrypto
-A PlanetSide specific wrapper around CryptoPP for use with Scala or Java. These functions are used for establishing an authenticated and confidential connection between a PlanetSide server and client.
+A PlanetSide specific wrapper around CryptoPP for use with Scala, Java, C++ or C. These functions are used for [establishing an authenticated and confidential connection](https://github.com/psforever/PSF-LoginServer/blob/master/pslogin/src/main/scala/CryptoSessionActor.scala) between a PlanetSide server and client.
 
 To get the library, run
 
@@ -13,16 +13,23 @@ Or if you already cloned without getting the submodules
 git submodule update --init --recursive
 ```
 
+## Why is this library necessary?
+PlanetSide uses an older version of a cryptographic library called CryptoPP (Crypto++). It uses this for encrypting, decrypting, and authenticating _all_ login and world packets. Some of the algorithms used by PlanetSide are depreciated and no longer used for modern crypto (read: insecure). This means that implementations of some algorithms (e.g., MD5MAC) are hard to find.
+
+What we have done is figured out the last known version of CryptoPP that used some of these algorithms, forked it, made it compile, and wrapped it so it could be easily called from server code, which is in Scala. It's possible that these old algorithms could be recreated for new modern code, but this was the easiest option and it nearly identically matches what PlanetSide was doing for crypto (discovered after over a month of reverse engineering client netcode).
+
 ## Building
-GNU Make and an `g++` (GNU C++) required. Builds tested in Debian, Cygwin with Mingw64, and GNUWin32.
+GNU Make and `g++` (GNU C++) required. Builds tested in Debian Jessie, Cygwin with Mingw64, and GNUWin32.
 In the top-level PSCrypto directory (not the subfolder), run
 
 ```shell
-$ make -j4 # build for current system
+$ make -j4 # will build for current system's GCC
 ```
 
 This will build the CryptoPP dependency and then the `pscrypto` library, which links to CryptoPP. The pscrypto build artifact will be in pscrypto/ as `libpscrypto.so` or `pscrypto.dll` depending on your platform. Note that the library architecture must match that of the JVM or process you are loading it in to, otherwise you will see loader errors.
 
+Keep in mind that if you are building with Cygwin's GCC (not a cross compiler like MinGW), then your binaries _will not work_ on systems without Cygwin installed!
+
 ## Cross Compiling
 Use the environment variable `PREFIX` to define a compiler tuple for building. For example
 
@@ -33,3 +40,24 @@ $ PREFIX=x86_64-w64-mingw32- make -j4
 This will build a `pscrypto.dll` for 64-bit Windows. Platform and architecture quirks are handled by the file `Makefile.inc`.
 
 You can also specify the `ARCH` variable manually (as `i686` or `x86_64`) in order to enable multilib building, if available.
+
+## Releasing Code
+You are able to create a release on a Linux 64-bit system with the MingW64 compiler toolchain installed. The prefixes required to build in order to support Windows 32,64 and Linux 64-bit are (`apt install g++-mingw-w64`):
+
+```
+x86_64-w64-mingw32-
+i686-w64-mingw32-
+x86_64-linux-gnu-
+```
+
+Check out [the script to build a release](scripts/build.sh) for more information.
+
+### Developer Release Checklist
+
+* Everything builds correctly
+* System testing has passed (i.e it works on Windows)
+* Version has been bumped in [pscrypto/pscrypto.h](pscrypto/pscrypto.h) and in the Windows resource file [pscrypto/resource.rc](pscrypto/resource.rc)
+* A release can be made with the build script
+* Release notes have been updated
+* All external references and this repository are tagged with attached release binaries
+* Update links (travis, other readmes) to point to the latest release

ReleaseNotes.txt

@@ -0,0 +1,8 @@
+Version 1.1
+===========
+* Minor fix on Unix systems. /dev/random was being defaulted to, causing the
+  entropy pool to run out, blocking library users. /dev/urandom now default
+
+Version 1.0
+===========
+* Initial release with PlanetSide crypto functionality

external/psf-cryptopp

@@ -1 +1 @@
-Subproject commit 28b6e6e6edaf340e2369707283a990ea24943f6b
+Subproject commit 5db8f1c704d3e61f1ba7e200bc2be57430592978

pscrypto/pscrypto.h

@@ -4,7 +4,7 @@
 #define _PS_STRINGIZE(S) #S
 
 #define PSCRYPTO_VERSION_MAJOR 1
-#define PSCRYPTO_VERSION_MINOR 0
+#define PSCRYPTO_VERSION_MINOR 1
 
 #define PSCRYPTO_VERSION_STRING _PS_STRINGIZE(PSCRYPTO_VERSION_MAJOR) "." _PS_STRINGIZE(PSCRYPTO_VERSION_MINOR)
 

pscrypto/pscrypto.py

@@ -3,7 +3,7 @@ from binascii import hexlify
 from ctypes import *
 import os
 
-lib = cdll.LoadLibrary(os.path.dirname(os.path.realpath(__file__)) + "/pscrypto.dll")
+lib = cdll.LoadLibrary(os.path.dirname(os.path.realpath(__file__)) + "/libpscrypto.so")
 
 lib.MD5_MAC.restype = c_bool
 lib.MD5_MAC.prototype = [c_char_p, c_uint, c_char_p, c_uint, c_char_p, c_uint]
@@ -75,7 +75,6 @@ def ServerEnc(encHandle, pt):
     return ct.raw
 
 def main():
-    raw_input()
     (dhHandle, priv, pub) = ServerDHStart("\x41\x75"*8, "\x01"*15 + "\x03")
     print "Started"
     print ServerDHAgree(dhHandle, priv, "A"*16)

pscrypto/resource.rc

@@ -2,8 +2,8 @@
 
 // DLL version information.
 VS_VERSION_INFO    VERSIONINFO
-FILEVERSION        1,0,0,0
-PRODUCTVERSION     1,0,0,0
+FILEVERSION        1,1,0,0
+PRODUCTVERSION     1,1,0,0
 FILEFLAGSMASK      VS_FFI_FILEFLAGSMASK
 #ifdef _DEBUG
   FILEFLAGS        VS_FF_DEBUG | VS_FF_PRERELEASE
@@ -20,12 +20,12 @@ BEGIN
     BEGIN
       VALUE "CompanyName", "PSForever Project"
       VALUE "FileDescription", "A PlanetSide crypto library for CryptoPP."
-      VALUE "FileVersion", "1.0.0.0"
+      VALUE "FileVersion", "1.1.0.0"
       VALUE "InternalName", "pscrypto"
       VALUE "LegalCopyright", "(C) 2016 PSForever Project"
       VALUE "OriginalFilename", "pscrypto.dll"
       VALUE "ProductName", "PlanetSide Crypto"
-      VALUE "ProductVersion", "1.0.0.0"
+      VALUE "ProductVersion", "1.1.0.0"
     END
   END
   BLOCK "VarFileInfo"

scripts/build.sh

@@ -1,8 +1,27 @@
 #!/bin/bash
 set -ue
 
+# The GCC binaries (gcc, g++, etc) can have their name prefixed
+# by specifying a program-prefix option when configuring.
+# https://gcc.gnu.org/install/configure.html
+#   Search above page for "--program-prefix"
+# The prefix allows multiple GCC to be installed and on system PATH.
+# MINGW (Which we use for crosscompilation) uses this option.
+#   x86_64-w64-mingw32- and i686-w64-mingw32-
+# GCC as built by Linux distros usually uses this option.
+#   however the prefixes vary
+
+# Default prefix to "x86_64-linux-gnu-", but allow overriding.
+#   (For example Fedora 25 is noted needing something like "x86_64-redhat-linux-")
+# NOTE: ${x-y} is a bash-ism. differs from portable ${x:-y} if x undefined
+PARAM_GCC_PROGRAM_PREFIX=${PARAM_GCC_PROGRAM_PREFIX-"x86_64-linux-gnu-"}
+PARAM_GCC_PREFIX_RANLIB=${PARAM_GCC_PREFIX_RANLIB-"x86_64-linux-gnu-"}
+PARAM_GCC_PREFIX_STRIP=${PARAM_GCC_PREFIX_STRIP-"x86_64-linux-gnu-"}
+
 CONFIGS=3
-BUILD_MATRIX_PREFIX=("x86_64-w64-mingw32-" "i686-w64-mingw32-" "x86_64-linux-gnu-")
+BUILD_MATRIX_PREFIX=("x86_64-w64-mingw32-" "i686-w64-mingw32-" "${PARAM_GCC_PROGRAM_PREFIX}")
+BUILD_MATRIX_PREFIX_RANLIB=("x86_64-w64-mingw32-" "i686-w64-mingw32-" "${PARAM_GCC_PREFIX_RANLIB}")
+BUILD_MATRIX_PREFIX_STRIP=("x86_64-w64-mingw32-" "i686-w64-mingw32-" "${PARAM_GCC_PREFIX_STRIP}")
 BUILD_MATRIX_ARTIFACT=("pscrypto.dll" "pscrypto.dll" "libpscrypto.so")
 BUILD_MATRIX_JAVA_FOLDER=("win32-x86-64" "win32-x86" "linux-x86-64")
 
@@ -18,10 +37,15 @@ for i in `seq 1 $CONFIGS`; do
    javaFolder=${BUILD_MATRIX_JAVA_FOLDER[$iter]}
 
    export PREFIX=${BUILD_MATRIX_PREFIX[$iter]}
+   export PREFIX_RANLIB=${BUILD_MATRIX_PREFIX_RANLIB[$iter]}
+   export PREFIX_RANLIB_USE=t
+   export PREFIX_STRIP=${BUILD_MATRIX_PREFIX_STRIP[$iter]}
+   export PREFIX_STRIP_USE=t
 
    echo "Now building $javaFolder..."
-   make clean > /dev/null 2>&1
-   make -j > "build-log-${javaFolder}.txt" 2>&1
+   make clean > "build-log-clean-${javaFolder}.txt" 2>&1
+   # -j with no number was LITERALLY causing a system crash (out of memory)
+   make -j 2 > "build-log-${javaFolder}.txt" 2>&1
 
    mkdir -p "$BUILD_DEST/$javaFolder"
    cp "pscrypto/${BUILD_MATRIX_ARTIFACT[$iter]}" "$BUILD_DEST/$javaFolder/"