# IdP API
We here go through the REST end-points available at the servers realizing a (virtual) IdP.

## Global IdP API
All IdPs have the following API handles available. Each are accessible through REST. Otherwise they can be accessed through calls to the specific IdP classes in package _eu.olympus.server_.


### GetCertificate
Returns a certificate containing the server's public Signature verification key, used to verify client tokens. If a distributed IdP is in place, this will be the same key for all servers.

## Administration

### Start Refresh
The server will initiate a key-share refresh with the other servers.

## Pesto and pABC IdPs
The following methods are specific for the Pesto and pABC IdP setting and are intended to be call by the relevant client.

### Perform OPRF (Username, Nonce, Cryptographic value, Token, TokenType)
Performs an OPRF operation on a cryptographic value based on a nonce (constructed using the user's password). If an account for a user with the given Username already exists then the optional Token of TokenType is also validated before carrying out the OPRF operation. The user will use the output to (re)generate a public/private signing key pair.

### Finish Registration (Username, Cookie, Public Key, Signature, Nonce, idProof)
Finishes a user account registration by storing a Public Key associated with Username and adding attributes in the optional idProof (assuming they can be verified). However the Signature on the nonce, idProof and Username must first be verified with the Public Key. Furthermore, it must also be verified that Cookie is valid (i.e. registration phase for user has been initiated). The Public key will be associated with Username and used to verify future authentication attempts. 

### AddAttributes (Username, Cookie, Nonce, Signature, idProof)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce and idProof. If the authentication succeeds then the attributes in idProof is added to the user's account, assuming that these attributes can be verified.  

### GetAllAttributes (Username, Cookie, Nonce, Signature)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username and Nonce and returns all the verified attributes a user has stored with their account.

### DeleteAttributes (Username, Cookie, Nonce, Signature, Attributes)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce and the Attributes. It then deletes the Attributes specified from the user's account.

### DeleteAccount (Username, Cookie, Nonce, Signature)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce and deletes the user's account completely.

### ChangePassword (Username, NewSignature, OldSignature, New Public Key, Cookie, Nonce)
Authenticates an already existing user based on their Username, a session Cookie and two signatures (NewSignature and OldSignature) on the Username, Nonce and New Public Key. If the check succeeds it associates New Public Key with Username.

### RequestMFA (Username, Cookie, Nonce, Signature, TokenType)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce and TokenType. If successful it returns an MFA challenge for an MFA authenticator of TokenType.

### ConfirmMFA (Username, Cookie, Nonce, Signature, Token, TokenType)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce, Token and TokenType. If successful it verifies the MFA Token based on the a MFA challenge received by a call to Request MFA. If the token is verified then the MFA of the TokenType is added to the user's account such that it is **lways** required to authenticate in the future. 

### RemoveMFA (Username, Cookie, Nonce, Signature, Token, TokenType)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce, Token and TokenType. If the verification is successful then the MFA of TokenType is removed from the user's account such that it is not needed in the future. 

### RefreshCookie (Cookie) 
Validates that the Cookie is still valid and returns a new cookie if so which renewed validity time.


## Extra calls to Pesto IdPs 
On top of the methods above a Pesto IdP also affords the following methods:
### Authenticate (Username, Cookie, Nonce, Signature, Policy)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce and Policy. The Signature is verified against the public key associated with Username. If the authentication succeeds then a token is constructed and returned to the user, based on the user's stored attributes in accordance with the Policy supplied. That is, the Policy specifies which user attributes are included in the token (if any).

## Extra calls to pABC IdPs
On top of the methods above a pABC IdP also affords the following methods:
### Get dp-ABC Public Parameters 
Returns the dp-ABC specific parameters of the servers.

### GetCredential (Username, Cookie, Nonce, Signature)
Authenticates an already existing user based on their Username, a session Cookie and a Signature on the Username, Nonce and Policy. The Signature is verified against the public key associated with Username. If the authentication succeeds then a credential based on all the user's attributes is constructed and returned to the user.


## IdP 2 IdP

### Add Partial Server Signature (Username, PartialSignature)
Receive a Partial server Signature on a Username from another server. This is used during user account creation or user password change to ensure that each server knows that all servers agree that they have received a request from a given user. 

### Add Partial MFA Secret (Username, Secret, TokenType)
Receive a partial secret for an MFA of TokenType for the user with a specific Username. This is used during MFA request by a user to construct a shared MFA secret among the servers. 

### Add Session (Cookie, Authorization)
Receive a Cookie and an Authorization. The Authorization specifies an ID, a set of roles (user, administrator or IdP) and an expiration time. A caller can the supply this Cookie to REST calls to prove that they are authorized to make these calls. This is used to setup the IdPs and to do key-share refresh.

### Add Mastershare (Nonce share, Key share)
Receive a share of a nonce and the server's master key. This is used during key refreshing to receive nonce and master key shares from the other partial IdP servers allowing the given server to update its signing and OPRF keys by restoring its master key share.

### Add Key Share (ID, Key share)
Receive a sharing of an other partial IdP's master key share. This is used during key share refresh to allow each server to keep a secret shared backup of their master key share on the other servers.

## Password JWT and Distributed RSA IdPs
The following methods are specific for the Password JWT and Distributed RSA IdP setting. 

### CreateUser (Username, Password)
Creates a new user account based on a Username and Password. Fails if an account already exists with the given Username.

### CreateUserAndAddAttributes (Username, Password, idProof)
Creates a new user account based on a Username and Password and associates certain attributes with this user's identity based on the data contained in idProof. Fails if an account already exists with the given Username or if the proof of the user's attributes is not accepted.

### StartSession (Username, Password, Token, TokenType)
Start a new session of an already existing user based on their Username, Password and optionally a MFA token of a certain type (required if an MFA of TokenType has been added for that user). If the authentication succeeds then a time-constrained session Cookie is returned to the user which they use to authenticate themselves towards the server for the rest of the session. 

### ValidateSession (Cookie)
Verifies that a session Cookie is still valid. If it is, then its lifetime is renewed.

### Authenticate (Username, Cookie, Policy)
Authenticates an already existing user based on their Username and a session Cookie. If the authentication succeeds then a token is constructed and returned to the user, based on the user's stored attributed in accordance with the Policy supplied. That is, the token may or may not contain information based on the user's attributes as specified by the Policy.

### Add Attributes (Username, Cookie, idProof)
Authenticates an already existing user based on their Username and a session Cookie. If the authentication succeeds then the attributes in idProof is added to the user's account, assuming that these attributes can be verified.  

### GetAllAttributes (Username, Cookie)
Authenticates an already existing user based on their Username and a session Cookie and returns all the verified attributes a user has stored with their account.

### DeleteAttributes (Username, Cookie, Attributes)
Authenticates an already existing user based on their Username and a session Cookie  and deletes the Attributes specified from the user's account.

### DeleteAccount (Username, Password, Cookie)
Authenticates an already existing user based on their Username, Password and a session Cookie and deletes the user's account completely.

### ChangePassword (Username, OldPassword, NewPassword, Cookie)
Authenticates an already existing user based on their Username, OldPassword and a session Cookie and replaces the user's OldPassword with a NewPassword.

### RequestMFA (Username, Password, Cookie, TokenType)
Authenticates an already existing user based on their Username, Password and a session Cookie and returns an MFA challenge for an MFA authenticator of a certain type.

### ConfirmMFA (Username, Password, Cookie, Token, TokenType)
Authenticates an already existing user based on their Username, Password, a session Cookie and an MFA token constructed based on the a MFA challenge received by a call to RequestMFA. If the token is verified then the MFA of the TokenType is added to the user's account such that it will be **required** to use to authenticate in the future. 

### RemoveMFA (Username, Password, Cookie, Token, TokenType)
Authenticates an already existing user based on their Username and Password, a session Cookie and an MFA token of TokenType. If the verification is successful then the MFA of TokenType is removed from the user's account such that it is not needed in the future.