Compare commits

..

No commits in common. "main" and "v0.2" have entirely different histories.
main ... v0.2

10 changed files with 200 additions and 188 deletions

5
.gitignore vendored
View File

@ -1,7 +1,2 @@
tags
*.cs
# MADR
/node_modules/
/package-lock.json
/package.json

View File

@ -7,10 +7,3 @@ When returning an Interface it may be required to append a dummy valueto work ar
- whoami @4 () -> ( you :Api.User );
+ whoami @4 () -> ( you :Api.User, dummy :UInt8 = 0 );
```
## Docs
A lot of information (concepts, usage, decisions) about this API can be found at [docs.fab-access.org](https://docs.fab-access.org/books/schnittstellen-und-apis/page/fabaccess-api#bkmrk-fabaccess-api).
See also:
- [pyfabapi (Python Wrapper)](https://gitlab.com/fabinfra/fabaccess/pyfabapi)
- [FabAccess-API-cs (C# implementation)](https://gitlab.com/fabinfra/fabaccess/fabaccess-api-cs)

View File

@ -1,76 +1,135 @@
@0xb9cffd29ac983e9f;
using Rust = import "programming_language/rust.capnp";
$Rust.parentModule("schema");
using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");
using Session = import "connection.capnp".Session;
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.
}
}
struct Response {
enum Error {
aborted @0;
# This authentication exchange was aborted by either side.
enum Result {
# Result code of the outcome
successful @0;
badMechanism @1;
# The server does not support this mechanism in this context.
invalidCredentials @2;
# 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.
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.
# This code SHOULD only be sent if no other value is more fitting.
failed @3;
# 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.
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.
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.
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.
}
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
retry @1;
# A client should just try again, potentially after prompting the user
# to enter their credentials again.
wait @2;
# The client should wait and try again later. 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.
}
union {
failed :group {
code @0 :Error;
# Error code indicating the cause of the error
challence @0 :Data;
outcome :group {
result @1 :Result; # Result code
additionalData @1 :Data;
# Some mechanisms will send additional data after an 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.
}
# 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.
challenge @2 :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 @3 :Session;
# The session that was created. It grants access to all capabilities the connecting
# party has permissions for.
additionalData @4 :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;
# 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.
}

View File

@ -6,44 +6,18 @@ $Rust.parentModule("schema");
using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");
using Authentication = import "authenticationsystem.capnp".Authentication;
using AuthenticationSystem = import "authenticationsystem.capnp".AuthenticationSystem;
using MachineSystem = import "machinesystem.capnp".MachineSystem;
using UserSystem = import "usersystem.capnp".UserSystem;
using PermissionSystem = import "permissionsystem.capnp".PermissionSystem;
const apiVersionMajor :Int32 = 0;
const apiVersionMinor :Int32 = 3;
const apiVersionPatch :Int32 = 0;
struct Version
{
major @0 :Int32;
minor @1 :Int32;
patch @2 :Int32;
}
interface Bootstrap
{
getAPIVersion @0 () -> Version;
authenticationSystem @0 () -> ( authenticationSystem : AuthenticationSystem );
getServerRelease @1 () -> ( name :Text, release :Text );
# Returns the server implementation name and version/build number
# 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)]")
machineSystem @1 () -> ( machineSystem : MachineSystem );
mechanisms @2 () -> ( mechs: List(Text) );
# Get a list of Mechanisms this server allows in this context.
userSystem @2 () -> ( userSystem : UserSystem );
createSession @3 ( mechanism :Text ) -> ( authentication :Authentication );
# Create a new session with the server that you wish to authenticate using `mechanism`.
# Using pipelining makes this one-roundtrip capable without explicit initial data support.
}
struct Session {
machineSystem @0 : MachineSystem;
userSystem @1 : UserSystem;
permissionSystem @2 : PermissionSystem;
vendor @3 :AnyPointer;
# Vendor-specific APIs outside the normal API stability
permissionSystem @3 () -> ( permissionSystem : PermissionSystem );
}

View File

@ -26,20 +26,3 @@ struct KeyValuePair {
key @0 :Text;
value @1 :Text;
}
struct Optional(T) {
union {
nothing @0 :Void;
just @1 :T;
}
}
struct Fallible(T, E) {
# Some operations can fail in several expected ways.
# In those cases returning an `Optional` doesn't transfer information about the way that the
# operation failed. `Fallible` contains this information in the generic `E` type.
union {
failed @0 :E;
successful @1 :T;
}
}

View File

@ -7,7 +7,6 @@ using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");
using General = import "general.capnp";
using Optional = General.Optional;
using User = import "user.capnp".User;
using Space = import "space.capnp".Space;
@ -19,12 +18,10 @@ struct Machine {
blocked @3;
disabled @4;
reserved @5;
totakeover @6;
}
struct MachineInfoExtended {
currentUser @0 :Optional(User);
lastUser @1 :Optional(User);
instructorUser @2 :Optional(User);
currentUser @0 :User;
transferUser @1 :User;
}
struct Reservation {
@ -38,16 +35,17 @@ struct Machine {
name @2 :Text;
description @3 :Text;
state @4 :MachineState;
manager @5:Optional(User);
manager @5:User;
wiki @13 :Text;
urn @14 :Text;
category @15 :Text;
info @6 :Info;
interface Info $CSharp.name("InfoInterface") {
getPropertyList @0 () -> ( propertyList :List(General.KeyValuePair) );
getMachineInfoExtended @0 () -> ( machineInfoExtended :MachineInfoExtended, dummy :UInt8 = 0);
getReservationList @1 () -> ( reservationList :List(Reservation) );
getPropertyList @1 () -> ( propertyList :List(General.KeyValuePair) );
getReservationList @2 () -> ( reservationList :List(Reservation) );
}
use @7 :Use;
@ -62,16 +60,10 @@ struct Machine {
interface InUse $CSharp.name("InUseInterface") {
giveBack @0 ();
sendRawData @1 (data :Data);
releasefortakeover @2 ();
}
prodable @16 :Prodable;
interface Prodable $CSharp.name("ProdInterface") {
prodWithData @0 (data :Data);
}
takeover @9 :Takeover;
interface Takeover $CSharp.name("TakeoverInterface") {
transfer @9 :Transfer;
interface Transfer $CSharp.name("TransferInterface") {
accept @0 ();
reject @1 ();
}
@ -84,18 +76,16 @@ struct Machine {
manage @11 :Manage;
interface Manage $CSharp.name("ManageInterface") {
getMachineInfoExtended @0 () -> MachineInfoExtended;
setProperty @0 (property :General.KeyValuePair);
removeProperty @1 (property :General.KeyValuePair);
setProperty @1 (property :General.KeyValuePair);
removeProperty @2 (property :General.KeyValuePair);
forceUse @2 ();
forceFree @3 ();
forceUse @3 ();
forceFree @4 ();
forceTransfer @4 (user :User);
forceTransfer @5 (user :User);
block @6 ();
disabled @7 ();
block @5 ();
disabled @6 ();
}
admin @12 :Admin;

View File

@ -7,16 +7,15 @@ using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");
using General = import "general.capnp";
using Optional = General.Optional;
using Machine = import "machine.capnp".Machine;
struct MachineSystem
interface MachineSystem
{
info @0 :Info;
info @0 () -> ( info : Info );
interface Info $CSharp.name("InfoInterface") {
getMachineList @0 () -> ( machine_list :List(Machine) );
getMachine @1 ( id :Text ) -> Optional(Machine);
getMachineURN @2 ( urn :Text ) -> Optional(Machine);
getMachine @1 ( id :Text ) -> ( machine :Machine, dummy :UInt8 = 0 );
getMachineURN @2 ( urn :Text ) -> ( machine :Machine, dummy :UInt8 = 0 );
}
}

View File

@ -8,14 +8,14 @@ $CSharp.namespace("FabAccessAPI.Schema");
using Role = import "role.capnp".Role;
struct PermissionSystem
interface PermissionSystem
{
info @0 :Info;
info @0 () -> ( info : Info );
interface Info $CSharp.name("InfoInterface") {
getRoleList @0 () -> ( role_list :List(Role) );
}
manage @1 :Manage;
manage @1 () -> ( manage : Manage );
interface Manage $CSharp.name("ManageInterface") {
}

View File

@ -24,7 +24,8 @@ struct User
info @3 :Info;
interface Info $CSharp.name("InfoInterface") {
listRoles @0 () -> ( roles :List(Role) );
getUserInfoExtended @0 () -> ( userInfoExtended :UserInfoExtended );
listRoles @1 () -> ( roles :List(Role) );
}
manage @4 :Manage;
@ -34,18 +35,61 @@ struct User
admin @5 :Admin;
interface Admin $CSharp.name("AdminInterface") {
getUserInfoExtended @0 () -> ( userInfoExtended :UserInfoExtended );
addRole @0 ( role :Role ) -> ();
removeRole @1 ( role :Role ) -> ();
addRole @1 ( role :Role ) -> ();
removeRole @2 ( role :Role ) -> ();
pwd @3 ( new_pwd :Text ) -> ();
pwd @2 ( new_pwd :Text ) -> ();
}
cardDESFireEV2 @6 :CardDESFireEV2;
interface CardDESFireEV2 $CSharp.name("CardDESFireInterface") {
# For more details about FabFire specification please see:
# https://docs.fab-access.org/books/fabfire-und-nfc-tags/page/fabfire-funktionsprinzip-grundlagen
# Card authentication using NXP/MiFare DESFire cards.
# These cards have the ability to restrict access for data on the cards using symmetric
# encryption and using a keyed Diffie-Hellman to prevent eavesdropping by any relaying
# party.
# A card has several "applications", containing up to 32 files. A file can be read or
# written. Both kinds of access can be restricted to parties knowing a PSK, on a
# file-to-file basis.
# The current system uses File 0001 through File 0004:
#
# File 0001 allows public (i.e. unauthenticated) read access and contains the Strings
# "FABACCESS", "DESFIRE", and "1.0" as packed list of UTF-8 encoded zero-terminated strings:
# (i.e. "FABACCESS\0DESFIRE\01.0\0")
# This file serves as sort of magic identifier allowing a server to verify quickly if it is
# able to use this card at all.
#
# File 0002 too allows public read access and contains:
# - An URL-encoded name of the issuing lab as URN in the format "urn:fabaccess:lab:<labname>"
# Examples:
# - "urn:fabaccess:lab:innovisionlab"
# - "urn:fabaccess:lab:Bibliothek%20Neustadt%20Makerspace"
# - "urn:fabaccess:lab:Offene%20Werkstatt%20M%C3%A4rz"
# - A valid IRI pointing towards the bffd instance running for this lab. This uffd SHOULD be
# reachable from the internet. Using private use IP addresses or IRIs that resolve to such
# may be necessary for labs behind restrictive firewalls or due to local policy.
# The IRI MUST use the "fabaccess" scheme, and SHOULD NOT contain an userinfo, path, query,
# or fragment part.
# Examples:
# - "fabaccess://innovisionlab.de/"
# - "fabaccess://192.168.178.65"
# - "fabaccess://fabaccess-server.localnet"
# - A zero-terminated list of UTF-8 encoded IRIs giving contact options to notify the issuer
# or owner in case the card has been lost. Issuers SHOULD set one value on card creation and
# MAY allow card owners to change or add values of their choosing.
# Examples:
# - "mailto:lostcard@innovisionlab.de"
# - "https://innovisionlab.de/lostcard"
# - "https://werkstatt-märz.de/cardlost.php?action=submitcardlost"
#
# File 0003 allows public access or access using a key, at the issuers option.
# It contains a token that can be used by the home server of the card owner to identify the
# card owner. The format of the token MUST NOT be relied on by any party except the home
# server.
#
# File 0004 restricts read access to a single key known to the home server of the card
# owner.
# It is empty but by being access restricted allows the home server to validate the card as
# being genuine and thus finalizing the authentication of the user.
getTokenList @0 () -> ( token_list :List(Data) );
# Get a list of all user Token currently bound to an user. This will generally be the number

View File

@ -8,44 +8,19 @@ $CSharp.namespace("FabAccessAPI.Schema");
using General = import "general.capnp";
using User = import "user.capnp".User;
using Optional = General.Optional;
using Fallible = General.Fallible;
struct UserSystem
interface UserSystem
{
info @0 :Info;
info @0 () -> ( info : Info );
interface Info $CSharp.name("InfoInterface") {
getUserSelf @0 ( ) -> User;
getUserSelf @0 ( ) -> ( user :User, dummy :UInt8 = 0 );
}
search @2 :Search;
interface Search $CSharp.name("SearchInterface") {
getUserByName @0 (username: Text) -> Optional(User);
}
manage @1 :Manage;
manage @1 () -> ( manage : Manage );
interface Manage $CSharp.name("ManageInterface") {
getUserList @0 () -> ( user_list :List(User) );
addUser @1 (username :Text, password: Text) -> User;
# DEPRECATED: use `addUserFallible` instead
removeUser @2 (user: User);
struct AddUserError {
enum AddUserError $CSharp.name("AddUserErrorEnum") {
alreadyExists @0;
# An user with that username already exists
usernameInvalid @1;
# The provided username is unusable, e.g. contains invalid characters,
# is too long or too short.
passwordInvalid @2;
# The provided password is unusable, e.g. it's of zero length
}
error @0 :AddUserError;
}
addUserFallible @3 (username :Text, password: Text) -> Fallible(User, AddUserError);
addUser @1 (username :Text, password: Text) -> ( user :User );
removeUser @2 (user :User, dummy :UInt8 = 0);
}
}