Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tuokri/UnrealScript-FCrypto

Pure UnrealScript SSL/TLS implementation and cryptography utilities based on BearSSL. Work in progress.
https://github.com/tuokri/UnrealScript-FCrypto

bearssl block-cipher cryptography decryption ecdh ecdhe encryption hkdf hmac https-client sha-1 udk ue3 unreal-engine-3 unrealscript xxtea

Last synced: 3 months ago
JSON representation

Pure UnrealScript SSL/TLS implementation and cryptography utilities based on BearSSL. Work in progress.

Awesome Lists containing this project

README 

        
# FCrypto



UnrealScript cryptography utilities. The majority of this library

is based heavily on [BearSSL](https://www.bearssl.org/).



# DISCLAIMER: This library is under development and should be considered pre-alpha software!



#### Why BearSSL?



FCrypto is based on BearSSL simply because it is one of the most well documented

cryptography libraries I have studied. The code is extremely readable and has

helpful comments for both the API and the internals. The design choices and

implementation details with their rationale are extensively documented --

in and out of code. As UnrealScript is a C-like language (although not nearly

as low level as C), it is quite natural to port C code to UScript.

However, the number one reason for using BearSSL as a basis for my own UnrealScript

implementation was its i15 big integer implementation. It was the only big integer

reference implementation I could find that doesn't use any integer data types

wider than 32 bits. Since Unrealscript only has bytes and 32 bit (signed)

integer types, BearSSL's i15 implementation was perfect for

this use case. It is also possible there are other big integer implementations

that could have been easier to port into UnrealScript, and I just hadn't looked

hard enough. But in any case, BearSSL is the perfect learning tool from a

cryptography novice's perspective.



#### How secure is it?



Using FCrypto for any real production applications that transfer actual

critical/confidential data is not recommended. Any constant-time cryptography

guarantees of BearSSL could be lost in the porting process from C to

UnrealScript (not to mention bugs). FCrypto does not implement the entire

TLS suite. UnrealScript scripting engine is also a proprietary black box, so

it is hard to make any low level guarantees on what the script code actually does.

With that said, FCrypto is still probably more than secure (actually, probably

overkill) for all the video game server data transfer purposes of my personal

projects.



TODO: List other references/influences.



The "F" in FCrypto stands for my online username "fluudah" (yeah, lazy naming).



## Example Use Case



TODO: move/rename this section



1. ECDHE to exchange per-session keys (used for XXTEA).

2. ECDH to exchange static keys (used for HMAC).

3. Communicate application data.



## Features



### Big (Modular) Integers



UnrealScript big integer implementation based on

[BearSSL "i15" implementation](https://bearssl.org/bigint.html).



There are quite a many restrictions and details related to the

implementation, so reading BearSSL documentation on big integer

design is necessary if you plan on using this feature.



#### Implementation Notes



UnrealScript only has 32-bit integers, whereas BearSSL i15 big integers use

`uint16_t*` as the underlying type. This UScript implementation is therefore

essentially wasting half of the memory space. This should however be negligible

for any modern system running UE3 games or servers. For export, the integers

can be encoded into a byte array format that does not waste memory. Various

places in the code have additional checks to ensure the results are not altered,

notably when writing UScript 32-bit integers into (originally) 16-bit variables

in the BearSSL version e.g.:



```UnrealScript

X[V++] = Acc & 0xFFFF; // @ALIGN-32-16.

```



### Key Exchange



#### ECDH



Elliptic Curve Diffie-Hellman.



#### ECDHE



Elliptic Curve Diffie-Hellman Ephemeral.



#### Supported Elliptic Curves



##### Curve25519



### Symmetric Encryption



#### XXTEA



XXTEA with PKCS #7. Included in the library due to simplicity of the implementation.

XXTEA is theoretically vulnerable, but used for being lightweight and secure enough

for non-critical data.



### Hash Functions



#### SHA-1



### Other (TODO)



#### HMAC



#### HKDF



#### Development TODOs



##### Release tooling



For actual releases we'll want a versioned script package.

Write a release generation script that copies only the needed

script files into a versioned directory and compiles the release.



1. Grab version tag from Git.

2. Copy and rename files with the version appended.

3. Final result should be something like FCrypto_0_1_0.u.



This allows us to release new versions without causing compatibility

issues with older versions while also discarding development and testing

only files from the final release.



##### Benchmarking suite



Benchmark our current `const out` optimizations (assumed to be a reference)

for passing in arrays (dynamic & static) and structs into functions vs. just

copying them.



Initial testing suggests `const out` does provide a minor speedup when testing

with large number of benchmark iterations. The plain copy version is faster when

doing very few iterations.



When the amount of data is large e.g., a struct containing arrays, the `const out`

version clearly beats the copy version.