PassID API service serves endpoint on JSON-RPC protocol.
Server has 6 API methods defined. All API mehods are defined in api.py and their logic is defined in class PassIdProto.
To demonstrate the eMRTD PoC, API methods passID.register and passID.login should be called respectively.

• Prerequisites
• Usage
  • Server Parameters
• API Methods
• API Errors
• Testing
• License

• Python 3.7 or higher,
• Installed dependencies from here,
• Configured PostgreSQL database (see here).

Run in the foreground:

 sudo python3 src/APIservice/apiserver/apiserver.py --db-user <USER> --db-pwd <PWD> --db-name <NAME> --url 0.0.0.0

Run in the background:

sudo nohup python3 src/APIservice/apiserver/apiserver.py --db-user <USER> --db-pwd <PWD> --db-name <NAME> --url 0.0.0.0 &  

Note: Listening to port 443 requiers commands to be run as sudo.

Local run using MemoryDB:
Note: Use python tool pkdext to extract CSCA and DSC certificates from master list in LDAP (*.ldif) files

python3 src/APIservice/apiserver/apiserver.py --mdb --mdb-pkd=<path_to_pkd_root>

Local run in dev mode using MemoryDB:

python3 src/APIservice/apiserver/apiserver.py --dev --mdb --mdb-pkd=<path_to_pkd_root>

• --url : server URL address)

default: 127.0.0.1
type: str
options:
        -localhost (127.0.0.1)
        -*         (0.0.0.0)
        -<IP>      (<IP>)

• --port : server port

default: 443 or 80 in case of `-no-tls` flag
type: int
options: 
        -<PORT>      (<PORT>)

• --db-user : database username

default: empty string
type: str

• --db-pwd : database password

default: empty string
type: str

• --db-name : database name

default: empty string
type: str

• --challenge-ttl : number of seconds before requested challenge expires

default: 300
type: int

• --cert : server TLS certificate

default: key in filepath "tls/passid_server.cer"
type: str

• --dev : developer mode. When this flag is set all newly registered accounts will expired after 1 minute.
  See also other --dev-* flags.

default: false
type: bool

• --dev-fc : use fixed constant challenge with value of this bytes instead of random challenge
  To be used for testing server with test client

default: false
type: bool

• --dev-no-tcv : skip verification of eMRTD trustchain (CSCA=>DSC=>SOD)

default: false
type: bool

• --key : server TLS private key

default: key in filepath "tls/server_key.pem"
type: str

• --log-level : set logging level. 0=verbose, 1=debug, 2=info, 3=warn, 4=error

default: 0 - verbose
type: int

• --mdb : use MemoryDB instead of sql database
  Note: All entries are stored in memory (RAM) and are erased when server is restarted

default: false
type: bool

• --mdb-pkd : path to the root folder of trustchain CSCA/DSC certificates to be loaded into MemoryDB

default: None
type: str

• --no-tls : do not use TLS connection

default: false
type: bool

• passID.ping
  Used for testing connection with server.
  params: int32 [ping] number
  returns: int32 random [pong] number

• passID.getChallenge
  Returns new random 32 bytes chanllenge to be at register or login to establish new session with.
  params: none
  returns: 32-byte [challenge]

• passID.cancelChallenge
  Cancel requested challenge.
  params: base64 encoded 32-byte [challenge]
  returns: none

• passID.register
  Register new user using eMRTD credentials. Account will be valid for 10 minutes (1 minute if --dev flag was used) after which it will expire and user will have to register again.
  By default EF.SOD is always validated into eMRTD trustchain unless --dev-no-tcv flag was used.
  params:

  • base64 encoded [dg15] file (eMRTD AA Public Key)
  • base64 encoded [SOD] file (eMRTD Data Security Object)
  • hex encoded 4-byte [cid] (challenge id)
  • ordered list [csigs] of 4 base64 encoded eMRTD signatures (AA) made over 8-byte long challenge chunks (see verification process)
  • (Optional)base64 encoded [dg14] file.
    File is required if elliptic curve cryptography was used to produce signatures. (EF.DG14 contains info about ECC signature algorithm)

  returns:

  • base64 encoded 20-byte [uid] user id
  • base64 encoded 32-byte HMAC [session_key]
  • int32 unix time when session [expires] (not used).

• passID.login
  Logins existing user using eMRTD credentials.
  params:

  • base64 encoded 20-byte [uid] user id
  • hex encoded 4-byte [cid] (challenge id)
  • ordered list [csigs] of 4 base64 encoded eMRTD signatures (AA) made over 8-byte long challenge chunks (see verification process)
  • (Optional) base64 encoded [dg1] file (eMRTD MRZ).
    By default EF.DG1 is required second time user logs-in.

  returns:

  • base64 encoded 32-byte HMAC [session_key]
  • int32 unix time when session [expires] (not used).

• passID.sayHello
  Returns grettings from server. Returned greeting is in format: "Hi, anonymous!" or
  "Hi, <LAST_NAME> <FIRST_NAME>!" if EF.DG1 was provided at login.
  (API method is defined only to present validated and parsed personal user data back to client)
  params:

  • base64 encoded 20-byte [uid] user id
  • base64 encoded 32-byte [mac] digest of HMAC-SHA256 calculated over [api name | uid] using session key (generated at register/login).

  returns:

  • str greeting

Server can return these PassID errors defined here.

See test client in unittest folder.

This project is licensed under the MIT License - see the LICENSE.md file for details