usr - Universal Systems Runtime v0.1.4

⚠️ Pre-release / Experimental

Built to explore low-level systems programming, cryptography, and Telegram text formatting internals. Not recommended for production use.

✨ What's New in v0.1.4

• All cryptographic bugs fixed - SHA-256 two-block padding, AES-256 decrypt fully implemented
• Complete AES suite - IGE, CBC (PKCS#7), CTR modes
• SHA-512, HMAC-SHA256, PBKDF2 - full streaming + one-shot APIs
• Base64, hex, URL, HTML encoding/decoding
• Secure random via getrandom() / /dev/urandom
• UTF-8/UTF-16 utilities - decode, encode, validate, codepoint count, offset conversion
• Complete Markdown parser + renderer - V1 and V2, correct UTF-16 offsets
• Complete HTML parser + renderer - all Telegram HTML tags
• Entity normalization - proper nesting via interval-stack algorithm
• Python bindings - all APIs exposed via ctypes, zero external dependencies

📦 Installation

Build from Source (Recommended)

git clone https://github.com/ankit-chaubey/usr
cd usr

# Build static library
mkdir -p build /tmp/objs
for f in $(find src -name '*.c'); do
  gcc -O2 -Iinclude -Isrc/crypto -c "$f" -o /tmp/objs/$(basename ${f%.c}).o
done
ar rcs build/libusr.a /tmp/objs/*.o

# Run tests
gcc -O2 -Iinclude tests/test_crypto.c    build/libusr.a -o build/test_crypto
gcc -O2 -Iinclude tests/test_encoding.c  build/libusr.a -o build/test_encoding
gcc -O2 -Iinclude tests/test_utf8.c      build/libusr.a -o build/test_utf8
gcc -O2 -Iinclude tests/test_roundtrip.c build/libusr.a -o build/test_roundtrip
gcc -O2 -Iinclude tests/fuzz_roundtrip.c build/libusr.a -o build/fuzz_roundtrip
build/test_crypto && build/test_encoding && build/test_utf8
build/test_roundtrip && build/fuzz_roundtrip

Python Bindings

# Build shared library for Python
SRCS=$(find src -name '*.c' | tr '\n' ' ')
gcc -O2 -shared -fPIC -Iinclude -Isrc/crypto $SRCS -o python/usr/libusr.so

cd python
pip install -e .

🧪 Example Usage

C

#include "usr/usr.h"

// SHA-256
uint8_t digest[32];
usr_sha256((uint8_t*)"hello", 5, digest);

// AES-256-IGE (Telegram MTProto)
uint8_t key[32] = {0x11};  // fill properly
uint8_t iv[32]  = {0x22};
usr_aes256_ige_encrypt(data, 32, key, iv);

// Markdown parse
usr_entity ents[64]; char *plain;
size_t n = usr_markdown_parse("*bold* _italic_", USR_MD_V2, &plain, ents, 64);
char *html = usr_entities_to_html(plain, ents, n);

Python

import usr

# Hashing
print(usr.sha256(b"test").hex())
print(usr.hmac_sha256(b"key", b"message").hex())

# AES-256-IGE (Telegram)
key = bytes(32); iv = bytes(32)
enc = usr.aes256_ige_encrypt(b"\x00" * 16, key, iv)
dec = usr.aes256_ige_decrypt(enc, key, iv)

# AES-256-CBC
enc = usr.aes256_cbc_encrypt(b"secret", b"\x11" * 32, b"\x22" * 16)
dec = usr.aes256_cbc_decrypt(enc, b"\x11" * 32, b"\x22" * 16)

# Markdown
plain, ents = usr.markdown_parse("*bold* _italic_")
html = usr.entities_to_html(plain, ents)     # <b>bold</b> <i>italic</i>
md   = usr.entities_to_markdown(plain, ents)  # *bold* _italic_

# Encoding
usr.base64_encode(b"hello")    # 'aGVsbG8='
usr.hex_encode(b"\xde\xad")    # 'dead'
usr.url_encode("hello world")  # 'hello%20world'

📐 API Reference

Cryptography (usr/crypto.h)

Encoding (usr/encoding.h)

Text / Entities

🗂️ Project Structure

usr/
├── include/usr/        # Public headers
│   ├── usr.h           # Umbrella include
│   ├── crypto.h        # SHA-256/512, AES, HMAC, PBKDF2, CRC-32
│   ├── encoding.h      # Base64, hex, URL, HTML
│   ├── entities.h      # MessageEntity types
│   ├── html.h          # HTML ↔ entities
│   ├── markdown.h      # Markdown ↔ entities
│   ├── utf8.h          # UTF-8/16 utilities
│   ├── bytes.h         # Owned byte buffer
│   ├── strbuilder.h    # String builder
│   └── rand.h          # Secure random
├── src/
│   ├── crypto/         # AES, SHA, HMAC, CRC, rand
│   ├── encoding/       # Base64, hex, URL, HTML escaping
│   ├── entities/       # Entity normalization
│   ├── html/           # HTML parser & renderer
│   ├── markdown/       # Markdown parser & renderer
│   └── utf8/           # UTF-8 codec
├── python/usr/         # Python ctypes bindings
│   ├── _lib.py         # Library loader
│   ├── _structs.py     # ctypes structure definitions
│   ├── crypto.py       # Crypto bindings
│   ├── encoding.py     # Encoding bindings
│   ├── entities.py     # Entity class + normalize
│   ├── html.py         # HTML parse/render
│   └── markdown.py     # Markdown parse/render
├── tests/              # C test suite + fuzz
├── examples/full_demo.c
└── benchmarks/bench_crypto.c

👤 Author

Ankit Chaubey · github.com/ankit-chaubey

Inspired by cryptg, tgcrypto, and Telegram MTProto internals.

📄 License

MIT