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#
| Attribute | Type | Description |
|---|---|---|
AUTH_PAYLOAD_CONTEXT | Literal['eventlog-auth-v1'] = 'eventlog-auth-v1' | |
ED25519_PUBLIC_KEY_LENGTH | Literal[32] = 32 | |
ED25519_SIGNATURE_LENGTH | Literal[64] = 64 | |
SESSION_AUTH_CHALLENGE_LENGTH | Literal[32] = 32 | |
SESSION_AUTH_CHALLENGE_TIME_TO_LIVE_MILLIS | Literal[30000] = 30000 | |
make_session_auth_challenge | Effect[bytes, EventLogSessionAuthError] | A fresh random challenge from |
Types#
| Type | Definition | Description |
|---|---|---|
SessionAuthErrorReason | type 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.
| Parameter | Type | Description |
|---|---|---|
payload | SessionAuthPayload |
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.
| Parameter | Type | Description |
|---|---|---|
payload | bytes |
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.
| Parameter | Type | Description |
|---|---|---|
payload | bytes | |
signing_private_key | bytes |
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 runverify_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.
| Parameter | Type | Description |
|---|---|---|
payload | bytes | |
signing_public_key | bytes | |
signature | bytes |
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 runsign_session_auth_payload#
sign_session_auth_payload(payload, signing_private_key) -> Effect[bytes, EventLogSessionAuthError]| Parameter | Type | Description |
|---|---|---|
payload | SessionAuthPayload | |
signing_private_key | bytes |
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]| Parameter | Type | Description |
|---|---|---|
payload | SessionAuthPayload | |
signature | bytes |
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.
| Parameter | Type | Description |
|---|---|---|
identity | IdentityService |
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.
| Parameter | Type | Description |
|---|---|---|
payload | SessionAuthPayload | |
signature | bytes | |
algorithm | str |
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)