API authentication operations

Login

This will perform the certificate based login procedure into the system. This procedure will be done in two steps.

The first step will obtain a session-id and handling of the client certificate.

The second step will handle the information of the common derivation key between be client and the server.

Login, Step#1

This step will initialize the login procedure.

Input parameters

Input-Certificate: A X509 client certificate as a base64-encoded string. This type is mandatory.
Input-DateTime: Current date and time as ISO 8601 encoded string. This type is mandatory.
Input-Role: Type of login role procedure. Available types: Officer and Self. Officer means administration role behalf of other users. Self means decreased functionality dedicated to current user itself. If not specified, Self will be used.
Input-Client: Optional information of the current client doing the login procedure. The information will be stored into the system for different kind of purposes. This type is optional
Input-Client-Device-Name: The name of the device.
Input-Client-Application-Name: The name of the application.
Input-Client-Language-Name: Current language of the client.

After calling the Login method, the following procedure will be operated on the server:

The server will check the state of the client certificate.
The server will create a session-id with a length of 20 bytes.
The server will create a server-nonce with a length of 32 bytes.
The server will encrypt the server-nonce with the client certificate.
The server will obtain a server certificate.

Output parameters

Output-SessionId: The session-id as a base64-encoded string.
Output-Certificate: The X509 server certificate as a base64-encoded string.
Output-Value: The encrypted server-nonce as a base64-encoded string.
Output-Status: The generic status object of the call.

SOAP implementation

Content type

text/xml; charset="utf-8";

Header

Action: "http://www.pointsharp.com/netid/server/portal/IServiceSoap/Login"

Request

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <Login xmlns="http://www.pointsharp.com/netid/server/portal">
      <Info>
        <Client>
          <Device>
            <Name>Windows NT</Name>
          </Device>
          <Application>
            <Name>Net iD Portal GUI</Name>
          </Application>
          <Language>
            <Name>en-US</Name>
          </Language>
        </Client>
        <Certificate>MII...</Certificate>
        <DateTime>2023-01-01 12:00:00</DateTime>
        <Role>Officer</Role>
      </Info>
    </Login>
  </s:Body>
</s:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <LoginResponse xmlns="http://www.pointsharp.com/netid/server/portal">
      <LoginResult>
        <SessionId>bXzEItFarA3qb4JfXbDeBMT1hng=</SessionId>
        <Certificate>MII...</Certificate>
        <Value>MII...</Value>
        <Status>
          <Code>Success</Code>
          <Description>Success</Description>
        </Status>
      </LoginResult>
    </LoginResponse>
  </s:Body>
</s:Envelope>

REST implementation

Content type

application/json; charset="utf-8";

Method

POST

URI

/api/login

Request

{
  "Client": {
    "Device": {
      "Name": "Windows NT"
    },
    "Application": {
      "Name": "Net iD Portal GUI"
    },
    "Language": {
      "Name": "en-US"
    }
  },
  "Certificate": "MII...",
  "DateTime": "2023-01-01 12:00:00",
  "Role": "Officer"
}

Response

{
  "SessionId": "bXzEItFarA3qb4JfXbDeBMT1hng=",
  "Certificate": "MII...",
  "Value": "MII...",
  "Status": {
    "Code": "Success",
    "Description": "Success"
  }
}

Login, Step#2

This step will handle the information of the common derivation key between be client and the server.

The information needed from the client:

The client must create a client-nonce with a length of 32 bytes.
The client must encrypt the client-nonce with the server certificate as a PKCS#7-blob.
The client must concat the client-nonce and sessionid which always will be total amount of 52 bytes (clientnonce+sessionid) (32+20).
Run the 52 bytes of data through HMAC with the date and time (19 bytes) as key. The current HMAC-algorithm can be loaded from the GetObject:ApplicationInfo call (ApplicationInfo.SecurityMode.HashAlgorithm). The result will be a 20 bytes HMAC-value.
The client must sign the 20 bytes HMAC-value with the client certificate as a PKCS#7-blob.

Input parameters

Input-SessionId: The session-id received from the server in the first step as a base64-encoded string. This type is mandatory.
Input-Value: The encrypted client-nonce as a base64-encoded string. This type is mandatory.
Input-Signature: The signed HMAC-value as a base64-encoded string. This type is mandatory.

After calling the Login method, the following procedure will be operated on the server:

The server will decrypt the client-nonce with the server certificate.
The server will verify the client signature.
The server will concat the decrypted client-nonce and session-id.
The server will run the concat values through HMAC.
The server will compare the HMAC-value with the value in the client signature.
The server will concat the server-none and session-id.
The server will run the concat values through HMAC.
The server will sign the HMAC-value with the server certificate.

Output parameters

Output-SessionId: The session-id as a base64-encoded string.
Output-Id: The unique id of the user.
Output-Signature: The signed HMAC-value as base64-encoded string.
Output-Server: Defines the format of the blob used for encryption.
Output-Status: The generic status object of the call.

SOAP implementation

Content type

text/xml; charset="utf-8";

Header

Action: "http://www.pointsharp.com/netid/server/portal/IServiceSoap/Login"

Request

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <Login xmlns="http://www.pointsharp.com/netid/server/portal">
      <Info>
        <SessionId></SessionId>
        <Value>MII...</Value>
        <Signature>MII...</Signature>
      </Info>
    </Login>
  </s:Body>
</s:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <LoginResponse xmlns="http://www.pointsharp.com/netid/server/portal">
      <LoginResult>
        <SessionId>yxAtxzbc0FH2ERbK3mAGaAkqJOU=</SessionId>
        <Id>21</Id>
        <Signature>MII...</Signature>
        <Server>
          <BlobFormat>json</BlobFormat>
        </Server>
        <Status>
          <Code>Success</Code>
          <Description>Success</Description>
        </Status>
      </LoginResult>
    </LoginResponse>
  </s:Body>
</s:Envelope>

REST implementation

Content type

application/json; charset="utf-8";

Method

POST

URI

/api/login

Request

{
  "SessionId": "",
  "Value": "MII...",
  "Signature": "MII..."
}

Response

{
  "SessionId": "yxAtxzbc0FH2ERbK3mAGaAkqJOU=",
  "Id": "21",
  "Signature": "MII...",
  "Server": {
    "BlobFormat": "json"
  },
  "Status": {
    "Code": "Success",
    "Description": "Success"
  }
}

The following operations needs to be done by the client:

The client must decrypt the server-nonce with the client certificate.
The client must verify the server signature.
The client must concat the server-nonce and session-id.
The client must run the concat values through HMAC.
The client must compare the HMAC-value with the value in the server signature. These should be equal
The client can now use the server-nonce and client-nonce for derivation of key and initial vector for encrypted calls against the API.

Logout

This will logout the user from the system. This call must be encrypted.

Parameters

Input-SessionId: The current session id as base64-string. This type is mandatory.
Input-Count: The current call-count of the session. This must be a numeric value. This type is mandatory.

SOAP implementation

Content type

text/xml; charset="utf-8";

Header

Action: "http://www.pointsharp.com/netid/server/portal/IServiceSoap/Logout"

Request

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <Logout xmlns="http://www.pointsharp.com/netid/server/portal">
      <Info>
        <SessionId></SessionId>
        <Count>1</Count>
      </Info>
    </Logout>
  </s:Body>
</s:Envelope>

Response

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <LogoutResponse xmlns="http://www.pointsharp.com/netid/server/portal">
      <LogoutResult>
        <Status>
          <Code>Success</Code>
          <Description>Success</Description>
        </Status>
      </LogoutResult>
    </LogoutResponse>
  </s:Body>
</s:Envelope>

REST implementation

Content type

application/json; charset="utf-8";

Method

POST

URI

/api/logout

Request

{
  "SessionId": "",
  "Count": "1"
}

Response

{
  "Status": {
    "Code": "Success",
    "Description": "Success"
  }
}

Output parameters

Output-Status: The generic status object of the call.