PointerAuthentication

PointerAuthentication

A namespace for the pointer authentication builtins.

public struct PointerAuthentication 

This should be considered an extension of the ptrauth module.

Methods

strip(_:_:)

Strip the signature from a value without authenticating it.

@inline(__always)
    public static func strip(
        _ pointer: UnsafeRawPointer,
        _ key: ptrauth_key
    ) -> UnsafeRawPointer 

If the value is a function pointer, the result will not be a legal function pointer because of the missing signature, and attempting to call it will result in an authentication failure.

Parameters

• pointer: The value to strip the signature from.
• key: The ptrauth_key used to stip the signature.

Returns

The stripped pointer.

blendDiscriminator(_:_:)

Blend a pointer and a small integer to form a new extra-data discriminator. Not all bits of the inputs are guaranteed to contribute to the result.

@inline(__always)
    public static func blendDiscriminator(
        _ pointer: UnsafeRawPointer,
        _ integer: UInt64
    ) -> UInt 

On ARM64, only the low 16 bits of the integer will be considered.

Parameters

• pointer: The pointer to perform the operation on.
• integer: The integer to blend into the pointer.

Returns

The new extra-data-discriminator.

signConstant(_:_:_:)

Add a signature to the given pointer value using a specific key, using the given extra data as a salt to the signing process.

@inline(__always)
    public static func signConstant(
        _ value: UnsafeRawPointer,
        _ key: ptrauth_key,
        _ data: UInt64
    ) -> UnsafeRawPointer 

Parameters

• value: The value pointer to sign.
• key: The key to sign the pointer with.
• data: Extra data to be used as a salt.

Returns

The constant passed in through value.

signUnauthenticated(_:_:_:)

Add a signature to the given pointer value using a specific key, using the given extra data as a salt to the signing process.

@inline(__always)
    public static func signUnauthenticated(
        _ value: UnsafeRawPointer,
        _ key: ptrauth_key,
        _ data: UInt64
    ) -> UnsafeRawPointer 

This operation does not authenticate the original value and is therefore potentially insecure if an attacker could possibly control that value.

Parameters

• value: The value pointer to sign.
• key: The key to sign the pointer with.
• data: Extra data to be used as a salt.

Returns

The constant passed in through value.

authAndResign(_:_:_:_:_:)

Authenticate a pointer using one scheme and resign it using another.

@inline(__always)
    public static func authAndResign(
        _ value: UnsafeRawPointer,
        _ oldKey: ptrauth_key,
        _ oldData: UInt64,
        _ newKey: ptrauth_key,
        _ newData: UInt64
    ) -> UnsafeRawPointer 

If the result is subsequently authenticated using the new scheme, that authentication is gauranteed to fail if and only if the initial authentication failed.

This operation is guarunteed to not leave the intermediate value available for attack before it is re-signed.

Parameters

• value: The value pointer to sign.
• oldKey: The old ptrauth_key the value was signed with.
• oldData: The old salt used in signing the value pointer.
• newKey: The new key to resign the value with.
• newData: New salt to be used in signing the value pointer.

Returns

The newly signed value.

authFunction(_:_:_:)

Authenticate a pointer using one scheme and resign it as a C function pointer.

@inline(__always)
    public static func authFunction(
        _ value: UnsafeRawPointer,
        _ oldKey: ptrauth_key,
        _ oldData: UInt64
    ) -> UnsafeRawPointer 

If the result is subsequently authenticated using the new scheme, that authentication is gauranteed to fail if and only if the initial authentication failed.

This operation is guarunteed to not leave the intermediate value available for attack before it is re-signed.

Parameters

• value: The value to resign as a C function pointer.
• oldKey: The old ptrauth_key the value was signed with.
• oldData: The old salt used in signing the value pointer.

Returns

The authenticated resigned value pointer signed as a C function pointer.

authData(_:_:_:)

Authenticate a data pointer

@inline(__always)
    public static func authData(
        _ value: UnsafeRawPointer,
        _ oldkey: ptrauth_key,
        _ oldData: UInt64
    ) -> UnsafeRawPointer 

If the authentication fails, dereferencing the resulting pointer will likewise fail.

Parameters

• value: The data pointer to authenticate.
• oldKey: The ptrauth_key used to sign the pointer.
• oldData: The old salt used in signing the pointer.

stringDiscriminator(_:)

Return an extra-discriminator value which can validly be used as the second argument to blendDiscriminator.

@inline(__always)
    public static func stringDiscriminator(
        _ string: String
    ) -> UInt64 

Parameters

• string: The string to generate the discriminator from.

Returns

The custom discriminator generated from the string.

signGenericData(_:_:)

Compute a full pointer-width generic signature for the given value, using the given data as a salt.

@inline(__always)
    public static func signGenericData(
        _ value: UnsafeRawPointer,
        _ data: UInt64
    ) -> ptrauth_generic_signature_t 

This generic signature is process independant, but may not be consistent accross reboots.

This can be used to validate the integrity of arbitrary data by storing the a signature for that data together with it. Because the signature is pointer-sized, if the signature matches the result of re-signing the current data, a match provides very strong evidence that the data has not been corrupted.

Parameters

• value: The generic data pointer to generate the signature for.
• data: Extra data to use as a salt in the signing of the generic data.

Returns

A ptrauth_generic_signature_t