Create SCK

graph TD A((start)) --> A1[Generate new SCK pair] A1 --> B[request POW] B --> C[calculate POW] CheckSCK -->|invalid SCK|A1 CheckSCK -->|invalid POW|A1 CheckSCK -->|ok|End C --> CheckSCK{check SCK & POW} End((done))

Note that generation new SCK is important. Service may keep track os used keys, perform SCK analysis and reject weak or already used keys.

When SCK is registered, the session could be established by obtaining TSK.

Service authentication.

Service authenticate itself if the SCK and POW are both ok. Depending on the protocol level, it signs its answer with some service key, known by this time to the client. The method to obtain service key depends on the protocol version and could be: pre-shared service key, pre-shared service contract origin and UNS2 contract. It should be described in more details somewhere else.

API calls

First, using guest commands and depedning on the supported parsec level, the clietn finds the SK, session public key. It could euthr know it in advance (pre-shared service key, PSSK), extract it from the service contract with pre-shared origin (PSSCO), or get UNS2 contract from the universa network and extract SK from it. This is not essential for the procedurem though. Only the fact that client must known SK before creating SCK. Otherwise it won't be able to ensure the service is authentic which can have grave consequences.

sequenceDiagram participant client participant service loop until SCK is registered client ->>+ service: RequestSCK(SCKAddress:) service -->> client: {context:, POWTask:} Note over client, service: client calculates POW using POWTask client ->> service: RegisterSCK(Context,SR(POWResult,SCK) service -->>- client: registration result end

RequestSCK

Before requesting SCK client should generate new random SCK. It is important to never reuse generated SCK. Use string address of the newly generated SCK to request:

RequestSCK(SCKAddress:string,testMode:boolean=false) 
   -> { context: Uint8Array, POWTask: { type: 1, count: number, salt: Uint8Array  } }

POWtaks now has the only type 1, and described in detais here[[parsec POW task 1]]. Its result allow client to perform next steps. stepMode, if supported by the service, allow to use it for unit-testing, with limited functionality and sipler POW tasks.

RegisterSCK

When the POW task is calculated, client tries to register the key:

RegisterSCK(context: Uint8Array,signedRecord: Uint8Array)
    -> {}

Signed record should be signed with the SCK key wich address has been used in reuqest and contain the following payload:

{
    POWResult: <result>,
}

Successfull registration return:

{
    sessionId: string
}

The session id should be used with newly registered SCK to obtain TSK.

Most common error codes are:

Code Meanind
parsec_bad_sck_key generated SCK is not valid (e.g. weak, ar already used). It is common case.
parsec_pow_error POW solution is wrong. Try to re-request and sovle it again.

In th ecase of the error, the regostration should be re-requested with a new key. Do not reuse generated keys.

The registration method could be called more than once, it will return the same state without checking parameters. Parameters are assessed only the first time.