GitHub

event_log_session_auth

API reference for event_log_session_auth.

How a client proves it holds an identity (Effect's eventlog/EventLogSessionAuth): it signs, with the Ed25519 key derived from the identity's root secret, a canonical payload binding the server's remote id and one-time challenge to its public keys.

The payload is five length-prefixed fields (a 4-byte big-endian length, then the bytes): the context "eventlog-auth-v1", the remote id (its hex text when given as bytes), the challenge, the public key and the 32-byte signing public key.

Values

AttributeTypeDescription
AUTH_PAYLOAD_CONTEXTLiteral['eventlog-auth-v1'] = 'eventlog-auth-v1'
ED25519_PUBLIC_KEY_LENGTHLiteral[32] = 32
ED25519_SIGNATURE_LENGTHLiteral[64] = 64
SESSION_AUTH_CHALLENGE_LENGTHLiteral[32] = 32
SESSION_AUTH_CHALLENGE_TIME_TO_LIVE_MILLISLiteral[30000] = 30000
make_session_auth_challengeEffect[bytes, EventLogSessionAuthError]

A fresh random challenge from SecureRandom on the WebCrypto reference.

Types

TypeDefinitionDescription
SessionAuthErrorReasontype SessionAuthErrorReason = Literal['InvalidPayload', 'InvalidContext', 'InvalidAlgorithm', 'InvalidSigningPublicKeyLength', 'InvalidSignatureLength', 'InvalidSigningPrivateKey', 'CryptoUnavailable', 'CryptoFailure']

Classes

Functions

encode_session_auth_payload

encode_session_auth_payload(payload) -> Effect[bytes, EventLogSessionAuthError]

The canonical bytes of payload.

ParameterTypeDescription
payloadSessionAuthPayload

Returns Effect[bytes, EventLogSessionAuthError]

def encode_session_auth_payload(
    payload: SessionAuthPayload,
) -> Effect[bytes, EventLogSessionAuthError]:
    """The canonical bytes of ``payload``."""
    error = _check_signing_public_key(payload.signing_public_key)
    return fail(error) if error is not None else sync(lambda: _encode(payload))

decode_session_auth_payload

decode_session_auth_payload(payload) -> Effect[SessionAuthPayload, EventLogSessionAuthError]

The payload of canonical bytes; an InvalidPayload / InvalidContext error when they are not one.

ParameterTypeDescription
payloadbytes

Returns Effect[SessionAuthPayload, EventLogSessionAuthError]

def decode_session_auth_payload(
    payload: bytes,
) -> Effect[SessionAuthPayload, EventLogSessionAuthError]:
    """The payload of canonical bytes; an ``InvalidPayload`` /
    ``InvalidContext`` error when they are not one."""
    return _attempt(lambda: _decode(payload))

sign_session_auth_payload_bytes

sign_session_auth_payload_bytes(payload, signing_private_key) -> Effect[bytes, EventLogSessionAuthError]

Sign canonical bytes with a PKCS#8 Ed25519 private key, on sig.layer_web_crypto with the WebCrypto reference.

ParameterTypeDescription
payloadbytes
signing_private_keybytes

Returns Effect[bytes, EventLogSessionAuthError]

def sign_session_auth_payload_bytes(
    payload: bytes, signing_private_key: bytes
) -> Effect[bytes, EventLogSessionAuthError]:
    """Sign canonical bytes with a PKCS#8 Ed25519 private key, on
    ``sig.layer_web_crypto`` with the ``WebCrypto`` reference."""

    @gen
    def run():
        yield from decode_session_auth_payload(payload)
        yield from _require_web_crypto()
        private_key = yield from key_format.decode_private(
            key_format.pkcs8, sig.ed25519, signing_private_key
        ).map_error(
            lambda cause: EventLogSessionAuthError(
                "InvalidSigningPrivateKey",
                "Failed to import Ed25519 signing private key (expected PKCS#8 bytes)",
                cause,
            )
        )
        return (
            yield from sig.Signature()
            .flat_map(lambda service: service.sign(private_key, payload))
            .pipe(provide_layer(_layer_signature))
            .map_error(_crypto_failure("Failed to sign canonical session auth payload"))
        )

    return run

verify_session_auth_payload_bytes

verify_session_auth_payload_bytes(payload, signing_public_key, signature) -> Effect[bool, EventLogSessionAuthError]

Whether signature signs the canonical bytes for the key; the lengths are checked before verifying on sig.layer_web_crypto with the WebCrypto reference.

ParameterTypeDescription
payloadbytes
signing_public_keybytes
signaturebytes

Returns Effect[bool, EventLogSessionAuthError]

def verify_session_auth_payload_bytes(
    payload: bytes, signing_public_key: bytes, signature: bytes
) -> Effect[bool, EventLogSessionAuthError]:
    """Whether ``signature`` signs the canonical bytes for the key; the
    lengths are checked before verifying on ``sig.layer_web_crypto``
    with the ``WebCrypto`` reference."""

    @gen
    def run():
        yield from decode_session_auth_payload(payload)
        error = _check_signing_public_key(signing_public_key)
        if error is not None:
            return (yield from fail(error))
        if len(signature) != ED25519_SIGNATURE_LENGTH:
            return (
                yield from fail(
                    EventLogSessionAuthError(
                        "InvalidSignatureLength",
                        f"Expected signature length to be {ED25519_SIGNATURE_LENGTH} bytes, "
                        f"received {len(signature)}",
                    )
                )
            )
        yield from _require_web_crypto()
        public_key = yield from sig.public_key(sig.ed25519, signing_public_key).map_error(
            lambda cause: EventLogSessionAuthError(
                "InvalidSigningPublicKeyLength",
                "Failed to import Ed25519 signing public key",
                cause,
            )
        )
        return (
            yield from sig.Signature()
            .flat_map(lambda service: service.verify(public_key, signature, payload))
            .pipe(provide_layer(_layer_signature))
            .map_error(_crypto_failure("Failed to verify canonical session auth payload signature"))
        )

    return run

sign_session_auth_payload

sign_session_auth_payload(payload, signing_private_key) -> Effect[bytes, EventLogSessionAuthError]
ParameterTypeDescription
payloadSessionAuthPayload
signing_private_keybytes

Returns Effect[bytes, EventLogSessionAuthError]

def sign_session_auth_payload(
    payload: SessionAuthPayload, signing_private_key: bytes
) -> Effect[bytes, EventLogSessionAuthError]:
    return encode_session_auth_payload(payload).flat_map(
        lambda data: sign_session_auth_payload_bytes(data, signing_private_key)
    )

verify_session_auth_payload

verify_session_auth_payload(payload, signature) -> Effect[bool, EventLogSessionAuthError]
ParameterTypeDescription
payloadSessionAuthPayload
signaturebytes

Returns Effect[bool, EventLogSessionAuthError]

def verify_session_auth_payload(
    payload: SessionAuthPayload, signature: bytes
) -> Effect[bool, EventLogSessionAuthError]:
    return encode_session_auth_payload(payload).flat_map(
        lambda data: verify_session_auth_payload_bytes(data, payload.signing_public_key, signature)
    )

derive_signing_public_key

derive_signing_public_key(identity) -> Effect[bytes]

The Ed25519 signing public key identity presents in session auth (Effect's deriveSigningPublicKey), derived on the WebCrypto reference. Record it when provisioning an identity, so authorize_identity can reject any other key presented for its public key.

ParameterTypeDescription
identityIdentityService

Returns Effect[bytes]

def derive_signing_public_key(identity: IdentityService) -> Effect[bytes]:
    """The Ed25519 signing public key ``identity`` presents in session auth
    (Effect's ``deriveSigningPublicKey``), derived on the ``WebCrypto``
    reference. Record it when provisioning an identity, so
    ``authorize_identity`` can reject any other key presented for its public
    key."""
    return _identity_material(identity).map(lambda material: material.signing_public_key)

verify_session_authenticate_request

verify_session_authenticate_request(payload, signature, algorithm) -> Effect[bool, EventLogSessionAuthError]

Verify an Authenticate request; only "Ed25519" is known.

ParameterTypeDescription
payloadSessionAuthPayload
signaturebytes
algorithmstr

Returns Effect[bool, EventLogSessionAuthError]

def verify_session_authenticate_request(
    payload: SessionAuthPayload, signature: bytes, algorithm: str
) -> Effect[bool, EventLogSessionAuthError]:
    """Verify an ``Authenticate`` request; only ``"Ed25519"`` is known."""
    if algorithm != "Ed25519":
        return fail(
            EventLogSessionAuthError(
                "InvalidAlgorithm", f"Unsupported session auth algorithm: {algorithm}"
            )
        )
    return verify_session_auth_payload(payload, signature)