Chris' Blog.

My occasional thoughts on iOS development, developers careers, trying to make an income from the App Store, and updates on life in general.

Rust

Hi! Here is a PNG writer I wrote as a utility as part of a hobby project I’ve been working on, where I preferred to minimise dependencies and keep things simple. It hope it serves as a good way of understanding the PNG format! Note that this doesn’t compress, and it only supports RGBA; but it can be useful for tiny pixel art images.

Let’s start with the prerequisites:

RFC 1951 Deflate stream

The first thing needed is a function to convert an arbitrary buffer into a ‘deflate stream’. A deflate stream is made up of blocks of up to 64kb. The simplest possible compliant deflate block looks like this:

1 byte: 1 = this is the final block; 0 = this is not the final block.
2 bytes: data length, lowest-significant-byte first.
2 bytes: length 1’s complement (all bits flipped).
N bytes: data

In Rust, this looks like:

fn to_deflate_stream(input: &[u8]) -> Vec<u8> {
    if input.is_empty() {
        return vec![1, 0, 0, 0xff, 0xff]; // 1 block with no content.
    }
    let mut output = Vec::<u8>::new();
    let chunks = input.chunks(0xffff);
    let final_index = chunks.len() - 1;
    for (index, chunk) in chunks.enumerate() {
        let is_final = index == final_index;
        output.push(if is_final { 1 } else { 0 });
        let len = chunk.len();
        let len_lsb = (len & 0xff) as u8;
        let len_msb = (len >> 8) as u8;
        output.push(len_lsb); // Max len.
        output.push(len_msb);
        output.push(!len_lsb); // 1's complement of len.
        output.push(!len_msb);
        output.extend_from_slice(chunk);
    }
    output
}

RFC 1950 Zlib stream

The next building block necessary is to convert a data buffer into a Zlib stream. This consists of adding a header and footer to a Deflate stream. The simplest possible header for the uncompressed case is 0x7801, meaning:

A standard window size of 7 (meaningless when not compressed).
A method of 8 (meaning deflate).
A 1 in the second byte for a checksum, no dictionary bit set, and 0 for the compression level bits.

The footer is an ADLER32 checksum.

In Rust, this looks like:

fn to_zlib_stream(input: &[u8]) -> Vec<u8> {
    // Header.
    let mut output = Vec::<u8>::new();
    output.push(0x78); // CMF byte. Bits 0-3=method, 4-7=info/window size. Method=8, Window size=7.
    output.push(1); // FLG byte. Bits 0-4=fcheck, 5=fdict which we dont want so 0, 6-7=flevel where 0 means fastest.

    // Body.
    let deflated = to_deflate_stream(input);
    output.extend(deflated);

    // Checksum.
    // See: https://en.wikipedia.org/wiki/Adler-32#Example_implementation
    let mut a: u32 = 1;
    let mut b: u32 = 0;
    for data in input {
        a = (a + (*data as u32)) % 65521;
        b = (b + a) % 65521;
    }
    output.push((b >> 8) as u8);
    output.push((b & 0xff) as u8);
    output.push((a >> 8) as u8);
    output.push((a & 0xff) as u8);

    output
}

CRC32

Another important piece of the puzzle is the ability to calculate CRCs for a buffer.

I can’t claim to understand how these work. If interested, you could read more here: http://libpng.org/pub/png/spec/1.0/PNG-CRCAppendix.html

In Rust, it looks like:

fn crc(data: &[u8]) -> u32 {
    // Make the CRC table first.
    // An optimised implementation would only do this once.
    let mut crc_table: [u32; 256] = [0; 256];
    for n in 0..256 {
        let mut c: u32 = n as u32;
        for _k in 0..8 {
            if c & 1 == 1 {
                c = 0xedb88320u32 ^ (c >> 1);
            } else {
                c = c >> 1;
            }
        }
        crc_table[n] = c;
    }

    // Calculate the CRC.
    let mut crc: u32 = 0xffffffff;
    for b in data {
        let index = ((crc ^ (*b as u32)) & 0xff) as usize;
        crc = crc_table[index] ^ (crc >> 8);
    }
    !crc
}

PNG

And now we have the prerequisites for generating the PNG. PNG files consist of a header then at least 3 blocks. The following describes the RGBA case, which has no palette:

The header looks like: 0x89 “PNG” CR LF EOF LF.

Each block looks like:

Data length: 4 bytes, most significant byte first.
Type: 4 ascii chars.
Data
4 bytes CRC of the type and data.

The compulsory 3 blocks are: IHDR, IDAT, and IEND.

IHDR

The header block’s data consists of:

Width and height: 4 bytes each, MSB first.
Bits per pixel: 1 byte.
Type: 6 means RGBA.
Compression: always 0 which means Zlib.
Filter method: always 0.
Interlacing flag.

IDAT

The data block consists of RGBA samples, left to right, top to bottom, in a Zlib stream. At the start of each row, a 0 is prefixed which means ‘no filter applies to this row’.

IEND

The end block has empty data. I’d be willing to bet you could omit this block and no parser would care.

The PNG generator code looks like the following in Rust:

fn png(width: u32, height: u32, rgba: &[u32]) -> Vec<u8> {
    let mut output = Vec::<u8>::new();

    // Header.
    output.push(0x89);
    output.push(b'P');
    output.push(b'N');
    output.push(b'G');
    output.push(0x0d); // Cr
    output.push(0x0a); // Lf
    output.push(0x1a); // Eof
    output.push(0x0a); // Lf

    // Build IHDR.
    let mut ihdr_type_and_data = Vec::<u8>::new();
    ihdr_type_and_data.push(b'I');
    ihdr_type_and_data.push(b'H');
    ihdr_type_and_data.push(b'D');
    ihdr_type_and_data.push(b'R');
    append_msb(&mut ihdr_type_and_data, width);
    append_msb(&mut ihdr_type_and_data, height);
    ihdr_type_and_data.push(8); // 8bpp.
    ihdr_type_and_data.push(6); // RGBA.
    ihdr_type_and_data.push(0); // Compression method: zlib.
    ihdr_type_and_data.push(0); // Filter method.
    ihdr_type_and_data.push(0); // No interlace.
    let ihdr_len = ihdr_type_and_data.len() - 4; // Minus the type.
    let ihdr_crc = crc(&ihdr_type_and_data);
    // Append IHDR to output.
    append_msb(&mut output, ihdr_len as u32);
    output.extend_from_slice(&ihdr_type_and_data);
    append_msb(&mut output, ihdr_crc);

    // Build image data.
    let mut idat_data = Vec::<u8>::new();
    let mut rgba_iter = rgba.iter();
    for _y in 0..height {
        idat_data.push(0); // Each line is prepended a filter type byte (0).
        for _x in 0..width {
            let rgba = rgba_iter.next().unwrap_or(&0);
            idat_data.push((rgba >> 24) as u8);
            idat_data.push((rgba >> 16) as u8); // 'as u8' truncates upper bits for us.
            idat_data.push((rgba >> 8) as u8);
            idat_data.push((*rgba) as u8);
        }
    }
    let compressed_idat_data = to_zlib_stream(&idat_data);

    // Build IDAT.
    let mut idat_type_and_data = Vec::<u8>::new();
    idat_type_and_data.push(b'I');
    idat_type_and_data.push(b'D');
    idat_type_and_data.push(b'A');
    idat_type_and_data.push(b'T');
    idat_type_and_data.extend_from_slice(&compressed_idat_data);
    let idat_len = idat_type_and_data.len() - 4; // Minus the type.
    let idat_crc = crc(&idat_type_and_data);
    // Append IDAT to output.
    append_msb(&mut output, idat_len as u32);
    output.extend_from_slice(&idat_type_and_data);
    append_msb(&mut output, idat_crc);

    // IEND (no data).
    append_msb(&mut output, 0); // Length.
    output.push(b'I'); // Type.
    output.push(b'E');
    output.push(b'N');
    output.push(b'D');
    let iend_crc = crc(b"IEND");
    append_msb(&mut output, iend_crc);

    output
}

fn append_msb(vec: &mut Vec<u8>, value: u32) {
    vec.push((value >> 24) as u8);
    vec.push((value >> 16) as u8);
    vec.push((value >> 8) as u8);
    vec.push((*value) as u8);
}

And that’s it! That’s the basics of writing PNGs in around 150LOC.

The full code can be seen here: github.com/chrishulbert/rust_png_write_sans_dependencies.

Feel free to use it in your projects by copying the file in; I haven’t published this as crate, I think it’s too simple to justify that.

Thanks for reading, I hope this is helpful, God bless :)

Photo by Tengyart on Unsplash

Stack

In practice, I usually find that using a UITableView makes most sense for displaying scrollable content in an app, however every now and again it is handy to use a UIScrollView + UIStackView. The problem is: it occurs infrequently enough that I cannot recall how to set up the constraints! So here’s my notes for my future reference, and hopefully yours too :)

Here’s a screenshot of how to set it up in Xcode: (click to zoom)

Theory

The frame layout guide and content layout guides are only to be used for child views of the scroll, and the child views are to be (usually) only constrained to these guides.
The frame layout guide is for setting child view’s sizes to match the scroll’s visual size.
The content layout guide is what defines the scroll view’s content size.

Vertical scroll setup

Make a UIScrollView and constrain it normally to define its size (eg not using its layout guides).
Put a vertical UIStackView inside the UIScrollView.
Constrain the stack’s leading/trailing/top/bottom to the scroll’s content layout guide.
Make the stack’s width equal to the scroll’s frame layout guide.
Put views in the stack. These views don’t need any constraints put on them at all.

Horizontal scroll setup

Make a UIScrollView and constrain it normally to define its size (eg not using its layout guides).
Put a horizontal UIStackView inside the UIScrollView.
Constrain the stack’s leading/trailing/top/bottom to the scroll’s content layout guide.
Make the stack’s height equal to the scroll’s frame layout guide.
Put views in the stack. These views don’t need any constraints put on them at all.

Paged scroll setup

If you want each child of the stack to be a whole ‘page’:

Horizontal scrolling: Constrain the stack’s childrens’ width to equal the scroll’s frame layout guide.
Vertical scrolling: Constrain the stack’s children’ height to equal the scroll’s frame layout guide.
Set ‘isPagingEnabled’ to true on the scroll.

Thanks for reading, I hope this is helpful, God bless :)

Photo by Fernando Andrade on Unsplash

RSA and EC

I recently had to perform RSA encryption/decryption in Swift for an iOS app. Unfortunately I couldn’t find any examples for how to do this without bringing in a library dependency, which I really wanted to avoid to keep the app efficient and because I can’t reasonably vet their code. And besides: Apple already provides the Security.framework which handles RSA, so it’d be a shame not to use it. It doesn’t bridge nicely to Swift however, so here’s a wrapper I wrote to help use it. I couldn’t find any good examples on the internet so I hope this helps someone:

import Security

// See: https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys
extension SecKey {
    
    enum KeyType {
        case rsa
        case ellipticCurve
        var secAttrKeyTypeValue: CFString {
            switch self {
            case .rsa:
                return kSecAttrKeyTypeRSA
            case .ellipticCurve:
                return kSecAttrKeyTypeECSECPrimeRandom
            }
        }
    }
    
    /// Creates a random key.
    /// Elliptic curve bits options are: 192, 256, 384, or 521.
    static func createRandomKey(type: KeyType, bits: Int) throws -> SecKey {
        var error: Unmanaged<CFError>?
        let keyO = SecKeyCreateRandomKey([
            kSecAttrKeyType: type.secAttrKeyTypeValue,
            kSecAttrKeySizeInBits: NSNumber(integerLiteral: bits),
        ] as CFDictionary, &error)
        // See here for apple's sample code for memory-managing returned errors
        // from the Security framework:
        // https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/storing_keys_as_data
        if let error = error?.takeRetainedValue() { throw error }
        guard let key = keyO else { throw MyErrors.nilKey }
        return key
    }
    
    /// Gets the public key from a key pair.
    func publicKey() throws -> SecKey {
        let publicKeyO = SecKeyCopyPublicKey(self)
        guard let publicKey = publicKeyO else { throw MyErrors.nilPublicKey }
        return publicKey
    }
    
    /// Exports a key.
    /// RSA keys are returned in PKCS #1 / DER / ASN.1 format.
    /// EC keys are returned in ANSI X9.63 format.
    func externalRepresentation() throws -> Data {
        var error: Unmanaged<CFError>?
        let dataO = SecKeyCopyExternalRepresentation(self, &error)
        if let error = error?.takeRetainedValue() { throw error }
        guard let data = dataO else { throw MyErrors.nilExternalRepresentation }
        return data as Data
    }
    
    // Self must be the public key returned by publicKey().
    // Algorithm should be SecKeyAlgorithm.rsaEncryption* or .eciesEncryption*
    func encrypt(algorithm: SecKeyAlgorithm, plaintext: Data) throws -> Data {
        var error: Unmanaged<CFError>?
        let ciphertextO = SecKeyCreateEncryptedData(self, algorithm,
            plaintext as CFData, &error)
        if let error = error?.takeRetainedValue() { throw error }
        guard let ciphertext = ciphertextO else { throw MyErrors.nilCiphertext }
        return ciphertext as Data
    }
    
    // Self must be the private/public key pair returned by createRandomKey().
    // Algorithm should be SecKeyAlgorithm.rsaEncryption* or .eciesEncryption*
    func decrypt(algorithm: SecKeyAlgorithm, ciphertext: Data) throws -> Data {
        var error: Unmanaged<CFError>?
        let plaintextO = SecKeyCreateDecryptedData(self, algorithm,
            ciphertext as CFData, &error)
        if let error = error?.takeRetainedValue() { throw error }
        guard let plaintext = plaintextO else { throw MyErrors.nilPlaintext }
        return plaintext as Data
    }

    enum MyErrors: Error {
        case nilKey
        case nilPublicKey
        case nilExternalRepresentation
        case nilCiphertext
        case nilPlaintext
    }

}

How to use it

It boils down to calling:

createRandomKey(…) to get a key pair.
publicKey() to get just the public key.
externalRepresentation() to get the public key as data that you can send to eg your backend.
encrypt(…) to encrypt something with the public key.
decrypt(…) to decrypt something with the key pair.

Here’s some demo code for using the above:

// Elliptic curve test.
do {
    let keyPair = try SecKey.createRandomKey(
        type: .ellipticCurve,
        bits: 384)
    let publicKey = try keyPair.publicKey()
    let plain = "Chuck Norris has counted to infinity. Twice.".data(using: .utf8)!
    let ciphertext = try publicKey.encrypt(
        algorithm: .eciesEncryptionStandardVariableIVX963SHA256AESGCM,
        plaintext: plain)
    let plainAgain = try keyPair.decrypt(
        algorithm: .eciesEncryptionStandardVariableIVX963SHA256AESGCM,
        ciphertext: ciphertext)
    let string = String(data: plainAgain, encoding: .utf8)! // Don't force-unwrap in real code.
    print("EC decrypted: " + string)
} catch {
    print("Error: \(error)")
}

// RSA test.
do {
    let keyPair = try SecKey.createRandomKey(
        type: .rsa,
        bits: 2048)
    let publicKey = try keyPair.publicKey()
    let plain = "Chuck Norris can set ants on fire with a magnifying glass. At night.".data(using: .utf8)!
    let ciphertext = try publicKey.encrypt(
        algorithm: .rsaEncryptionOAEPSHA1AESGCM,
        plaintext: plain)
    let plainAgain = try keyPair.decrypt(
        algorithm: .rsaEncryptionOAEPSHA1AESGCM,
        ciphertext: ciphertext)
    let string = String(data: plainAgain, encoding: .utf8)! // Don't force-unwrap in real code.
    print("RSA decrypted: " + string)
} catch {
    print("Error: \(error)")
}

Algorithm selection

If you’re integrating with an existing system, you’ll simply have to match their key type and algorithm. But if it’s up to you, here’s some tips for how to choose:

Read Apple’s headers! In Xcode, command-click on SecKeyAlgorithm and read the comments above it. Many algorithms will be noted as legacy, so avoid if possible. And some do not support arbitrary-length data which might be a problem for you. So choose wisely.

And a reasonable option in my opinion is:

Key type: .ellipticCurve
Key size: 384 bits
Algorithm: .eciesEncryptionCofactorVariableIVX963SHA384AESGCM

Note

I’m not a qualified cryptographer, this information carries no warranty, you should talk to a qualified security professional about the implications of when to use this appropriately!

Thanks for reading, I hope this is helpful, God bless :)

Photo by David Clode on Unsplash

You can see older posts in the right panel, under 'archive'.

Chris' Blog.

Rust PNG writer from scratch 12 Jul, 2022

RFC 1951 Deflate stream

RFC 1950 Zlib stream

CRC32

PNG

IHDR

IDAT

IEND

UIScrollView content and frame layout guides: scroll your UIStackView content purely in storyboards (iOS) 1 May, 2022

Theory

Vertical scroll setup

Horizontal scroll setup

Paged scroll setup

Swift Security framework wrapper for RSA and Elliptic Curve encryption / decryption 21 Sep, 2021

How to use it

Algorithm selection

Note

Archive