FabInfra-Mirror/api.fabaccess-api
1
0
Fork 0
mirror of https://gitlab.com/fabinfra/fabaccess/fabaccess-api.git synced 2025-03-12 06:41:51 +01:00
Code Issues Packages Projects Releases Wiki Activity

Make Authentication return an authenticated Bootstrap instead

Browse Source 
Fixes: #12
Fixes: #14
This commit is contained in:
Nadja Reitzenstein 2021-09-23 22:33:56 +02:00
parent 6b0aba90a9
commit 277133dd35
3 changed files with 112 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
authenticationsystem.capnp
View File

@ -1,135 +1,112 @@
@0xb9cffd29ac983e9f;
using Rust = import "programming_language/rust.capnp";
$Rust.parentModule("schema");
using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");
using User = import "user.capnp".User;
interface AuthenticationSystem {
mechanisms @0 () -> ( mechs :List(Text) );
# Get the list of mechanisms supported by the server
start @1 ( request :Request ) -> ( response :Response );
# Initiate an authentication exchange
# NOTE: Calling start() after an authentication exchange has already
# finished is undefined behaviour. If you want to double-authenticate call
# auth() from connection.capnp again to get a fresh capability you can use.
# This may however return NULL if you are not allowed to authenticate twice.
step @2 ( response :Data ) -> ( response :Response );
# Respond to a challenge with more data
# NOTE: As with start() calling this after having received an outcome is
# undefined behaviour.
abort @3 () -> ();
# Abort the current exchange. This may be sent by both client and server
# at any point during the exchange. It MUST not be sent by a server
# after sending an outcome or by a client after receiving an outcome.
# A server receiving an abort after sending an outcome but before
# receiving any other message MUST respect the abort.
whoami @4 () -> ( you :User, dummy :UInt8 = 0 );
# Returns NULL if not authenticated and an User object if authenticated.
}
struct Request {
mechanism @0 :Text; # The SASL mechanism name.
initialResponse :union {
# A client may send some intial data when requesting an auth exchange.
# According to RFC4422 section 4.3a an implementation MUST be able to
# distinguish between an empty initial reponse and no initial response.
none @1 :Void;
# No initial reponse is being sent.
# The lowest numbered field in an union is the default value in Cap'n
# Proto.
initial @2 :Data;
# A response may be any sequence of octets, including zero-length
# sequences and zero-valued octets.
}
}
using L10NString = import "utils.capnp".L10NString;
using Session = import "connection.capnp".Session;
struct Response {
enum Result {
# Result code of the outcome
successful @0;
enum Error {
aborted @0;
# This authentication exchange was aborted by either side.
badMechanism @1;
# The server does not support this mechanism in this context.
unwilling @2;
# Generic "I'm sorry dave, I can't do that" response. MAY be set for any
# reason, all reasons or no reason at all.
# A server SHOULD set the `action` and `helpText` fields as appropiate.
# Generic "I'm sorry dave, I can't do that" response. MAY be set for any reason, all reasons
# or no reason at all. This code will for example be used if a client is being rate limited.
# A server SHOULD set the `action` and `description` fields as appropiate.
# This code SHOULD only be sent if no other value is more fitting.
invalidCredentials @3;
# The exchange was valid, but the provided credentials are invalid. This
# may mean that the authcid is not known to the server or that the
# password/certificate/key/etc. is not correct.
# The exchange was valid, but the provided credentials are invalid. This may mean that the
# authcid is not known to the server or that the password/certificate/key/ticket/etc is not
# correct.
unauthorized @4;
# The given authcid is not authorized to act as the requested authzid.
# This MAY also be returned for the cases `authzid == NULL` or
# `authzid == authcid`, for example because login is disabled for that
# authcid.
# The given authcid is not authorized to act as the requested authzid. This MAY also be
# returned for the cases `authzid == NULL` or `authzid == authcid`, for example because
# login is disabled for that authcid.
malformedAuthZid @5;
# The provided authzid is malformed in some way.
failed @6;
# A generic failed result. A server sending this result MUST set the
# `action` field to indicate whether this is a temporary or permanent
# failure and SHOULD set `helpText` to a human-readable error message.
# A generic failed result. A server sending this result MUST set the `action` field to
# indicate whether this is a temporary or permanent failure and SHOULD set `description` to
# a human-readable error message.
}
enum Action {
# In case of a unsuccessful outcome, how should a client proceed?
unset @0;
# Not a unsuccessful outcome, or the server doesn't know either.
# Also, the default value
# The server doesn't know either. A client SHOULD treat this either as as `retry` or as
# `wait`.
retry @1;
# A client should just try again, potentially after prompting the user
# to enter their credentials again.
# A client SHOULD try again, depending on the `Error` after prompting the user for their
# credentials once more.
wait @2;
# The client should wait and try again later. This MAY mean that
# whatever failure happened was temporary or the server is applying
# The client SHOULD wait and retry after a grace period. A client MUST wait at least 500ms
# and SHOULD implement exponential backoff up to no less than 64s.
# This MAY mean that whatever failure happened was temporary or the server is applying
# rate-limiting to the connection.
permanent @3;
# The issue appears to the server as being permanent. Another try is
# very likely to return the exact same result. In most cases the user
# should notify the responsible system administrator.
# The issue appears to the server as being permanent. Another try is very likely to return
# the exact same result. In most cases the user should notify the responsible system
# administrator. A client SHOULD NOT try to authenticate to the server again until the user
# manually indicates a retry.
}
union {
challence @0 :Data;
outcome :group {
result @1 :Result; # Result code
error :group {
# Some kind of error happened. This in the first entry in the union because it is the
# default set value meaning if a server fails to set any of the values, indicating some
# pretty severe server bugs, it is parsed as an "aborted" error.
action @2 :Action; # Hints for the client how to proceed in case of an error
helpText @3 :Text; # Human-readable further information in case of an error
additionalData :union {
# Additional data that may be sent by the server to the client after a
# successful authentication exchange.
none @4 :Void;
# No additional data is being sent. This MUST be set on unsuccessful
# outcomes.
additional @5 :Data;
# Additional data may be any sequence of octets, including zero-length
# sequences and zero-value octets.
result @0 :Error;
action @1 :Action;
description @2 :L10NString;
# A human-readable error description that is designed to be shown to the user in case of
# failure. Clients MAY NOT display this message if they understand the error e.g. for
# the error/action "invalidCredentials/retry".
}
challenge @3 :Data;
# The data provided so far is not enough to authenticate the user. The data MAY be a
# NULL-ptr or a non-NULL list ptr of zero bytes which clients MUST pass to their SASL
# implementation as "no data" and "some data of zero length" respectively.
successful :group {
# The exchange was successful and a new session has been created for the authzid that
# was established by the SASL exchange.
session @4 :Session;
additionalData @5 :Data;
# SASL may send additional data with the successful result. This MAY be a NULL-ptr or a
# non-NULL list ptr of zero bytes which clients MUST pass to their SASL implementation
# as "no additional data" and "some additional data of zero length" respectively.
}
}
}
interface Authentication {
step @0 ( data: Data ) -> ( response: Response );
# Respond to a challenge with more data. A client MUST NOT call this after having received an
# "successful" response.
abort @1 () -> ();
# Abort the current exchange. This will invalidate the Authentication making all further calls
# to `step` return an error response. A client MUST NOT call this function after
# having received an "successful" response.
# A server will indicate that they have aborted an authentication exchange by replying with an
# "aborted" Error to the next `step` call. A server SHOULD directly terminate the underlying stream
# after sending this response. The server MAY after a short grace period terminate the stream
# without sending a response if no call to `step` was received by the client.
}

23
connection.capnp
View File

@ -6,7 +6,7 @@ $Rust.parentModule("schema");
using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");
using AuthenticationSystem = import "authenticationsystem.capnp".AuthenticationSystem;
using Authentication = import "authenticationsystem.capnp".Authentication;
using MachineSystem = import "machinesystem.capnp".MachineSystem;
using UserSystem = import "usersystem.capnp".UserSystem;
using PermissionSystem = import "permissionsystem.capnp".PermissionSystem;
@ -31,11 +31,20 @@ interface Bootstrap
# Designed only for human-facing debugging output so should be informative over machine-readable
# Example: ( name = "bffhd", release = "0.3.1-f397e1e [rustc 1.57.0 (f1edd0429 2021-11-29)]")
authenticationSystem @2 () -> ( authenticationSystem : AuthenticationSystem );
mechanisms @2 () -> ( mechs: List(Text) );
# Get a list of Mechanisms this server allows in this context.
machineSystem @3 () -> ( machineSystem : MachineSystem );
userSystem @4 () -> ( userSystem : UserSystem );
permissionSystem @5 () -> ( permissionSystem : PermissionSystem );
createSession @3 ( mechanism :Text, initialData :Data ) -> ( authentication :Authentication);
# Create a new session with the server that you wish to authenticate using `mechanism`.
# If the mechanism is a client-first mechanism you MAY set `initialData` to contain the data you
# want to send. If the mechanism is server-first or you do not wish to send initial data, make
# initialData a NULL-pointer.
}
struct Session {
me @0 :Text;
machineSystem @1 : MachineSystem;
userSystem @2 : UserSystem;
permissionSystem @3 : PermissionSystem;
}

29
utils.capnp Normal file
View File

@ -0,0 +1,29 @@
@0xed0c02f41fea6b5a;
interface L10NString {
# Any string type that is intended to be displayed to an user that is more than an identifier to
# be used as-is must be able to be localized into the users preferred language. This includes
# description, help messages, etc. but of course does not extend to usernames.
# TODO: Potentially make generic over the localized content (e.g. dates)? Can be done after the
# fact without braking protocol, so no big issue.
get @0 ( lang :Text ) -> ( lang :Text, content :Text );
# Retrieve the string in the given locale. The input parameter MUST be a RFC5646-formatted
# locale identifier (e.g: "en-US", "de-DE", "az-Arab-IR").
# A server MUST set the outputs `lang` to the exact tag that the content it sends was written in
# and `content` to the localized string.
# If a server can't find a localized version it SHOULD try to substitute it. Substitution SHOULD
# only search for close matches, e.g. returning "en-UK" for a string requested in "en-US" or
# returning "es-ES" for a requested "es-VE". Substitution MUST NOT return a localization that an
# user can not be expected to understand unless the server has a priori knowledge that the user
# can read and understand said language.
# If a server sends a substituted string it MUST set the output `lang` to the tag of the
# substitute it is sending.
# If a server can't find a suitable substitute or is not doing substitution it MUST set the
# output `content` to a NULL pointer and set the output `lang` to the input `lang` it was
# passed.
# If a server can't parse a given `lang` tag it MUST set the output `lang` to a NULL pointer.
available @1 () -> ( langs :List(Text) );
# Returns the list of locales this content is available in.
}