cpu

Modern processors can run one round of AES, or multiply two 64-bit values without carries, in a single instruction. This package makes those instructions available on u128 values, and tells you at run time whether the machine in front of you has them. tls uses it for AES-GCM, so the VPN and proxy protocols and the TLS record layer run on the fast path by themselves; most programs never need to call this package.

The instructions are real only when the program is built with the LLVM backend, which every release build uses. On the C backend, the native backend, the interpreter and in the browser every function still works, but as a slow software model of the instruction, and HasHardwareCrypto is false so that callers choose their own faster code. The software model gives the same bytes, which is what lets a test run the same data both ways.

Things to know:

• Test first, then call. The Hw functions work everywhere, but only where HasHardwareCrypto is true are they one instruction each.
• The switch is read when a cipher is made. SetHardware(false) affects the next AeadNew or one shot call, not a context that already exists. The environment variable SALAM_NO_HWCRYPTO does the same for a whole run.
• HwClmul wants a literal. Its third argument becomes part of the instruction, so write 0, 1, 16 or 17 there, not a variable.
• Constant time. The instructions take the same time for any data, which the table based software AES cannot promise.

Check the fast path against the slow one

SetHardware turns the fast path off, so one program can seal the same message both ways and compare. This is how the tests of the package check that the two paths give the same bytes. On a machine without the instructions both runs take the software path and the answer is still the same.

import cpu
import mem
import tls

func hex(p: void*, n: int): str:
    b := p as u8*
    digits := "0123456789abcdef"
    mut s := ""
    repeat n in i:
        v := b[i] as int
        s += digits.substr(v >> 4, 1)
        s += digits.substr(v & 15, 1)
    end
    ret s
end

func seal(): str:
    key := mem.AllocateZeroed(16 as u64)
    nonce := mem.AllocateZeroed(12 as u64)
    msg := mem.AllocateZeroed(32 as u64)
    out := mem.AllocateZeroed(48 as u64)
    tls.AesGcmSealRaw(key, 16, nonce, null, 0, msg, 32, out)
    r := hex(out, 48)
    mem.Free(key)
    mem.Free(nonce)
    mem.Free(msg)
    mem.Free(out)
    ret r
end

func main:
    cpu.SetHardware(true)
    fast := seal()
    cpu.SetHardware(false)
    slow := seal()
    println "same bytes:", fast == slow
    println "tag:", fast.substr(64, 32)
end

The tag line is the tag of 32 zero bytes under an all zero key and nonce; the algorithm fixes it, so it is the same on every machine.

Which function for which job

Constants and variables

const FEATURE_HW_CRYPTO: i32 = 1

import cpu
import mem

func show(label: str, x: u128):
    b := mem.AllocateZeroed(16 as u64)
    cpu.HwStore(b, x)
    p := b as u8*
    digits := "0123456789abcdef"
    mut s := ""
    repeat 16 in i:
        v := p[i] as int
        s += digits.substr(v >> 4, 1)
        s += digits.substr(v & 15, 1)
    end
    println label, s
    mem.Free(b)
end

func main:
    b := mem.AllocateZeroed(16 as u64)
    p := b as u8*
    repeat 16 in i:
        p[i] = (i * 17) as u8
    end
    x := cpu.HwLoad(b)
    show("load ", x)
    show("round", cpu.HwAesEnc(x, x))
    show("last ", cpu.HwAesEncLast(x, x))
    show("mul  ", cpu.HwClmul(x, x, 0))
    show("mulhi", cpu.HwClmul(x, x, 17))
    show("swap ", cpu.HwSwap64(x))
    show("bswap", cpu.HwBswap(x))
    cpu.SetHardware(false)
    println "off:", cpu.HasHardwareCrypto()
    cpu.SetHardware(true)
    f := cpu.Features()
    ok := (f & cpu.FEATURE_HW_CRYPTO) != 0
    println "on matches the processor:", cpu.HasHardwareCrypto() == ok
    println "families agree:", cpu.HasAesNi() == (ok and (f & cpu.FEATURE_X86) != 0), cpu.HasArmCrypto() == (ok and (f & cpu.FEATURE_ARM64) != 0), cpu.HasPclmul() == cpu.HasAesNi()
    mem.Free(b)
end

const FEATURE_X86: i32 = 2

const FEATURE_ARM64: i32 = 4

Functions

func Features(): int

func HwAesEnc(state: u128, key: u128): u128

func HwAesEncLast(state: u128, key: u128): u128

func HwClmul(a: u128, b: u128, imm: int): u128

func HwSwap64(x: u128): u128

func HwBswap(x: u128): u128

func HwLoad(p: void*): u128

func HwStore(p: void*, x: u128)

func SetHardware(enable: bool)

func HasHardwareCrypto(): bool

func HasAesNi(): bool

func HasPclmul(): bool

func HasArmCrypto(): bool