Interfaces – Details

Abbreviations and naming conventions in this documentation:
NiA = Net iD Access (The App used for login and signing)
NiAS = Net iD Access Server (The Web Service communicating with the service and with Net iD Access)
The Service = The heart of the solution with webserver, applications server, databases etc.

Net iD Access Interface Description


Introduction


This document describes the Web Service interface for the Net iD Access Server. The interface is used by a Service Provider, SP, to request authentication and signature from a mobile device client. The resulting PKCS#7 signature can be validated before it is returned to the service. The web service contains the methods described below and is defined by the WSDL and XSD. In production environments SSL/TLS will used to secure the transport towards the web service. Client authentication is required with SSL/TLS client certificates.

Version


As the Web Service interface evolve over time new parameters and methods can be added. The changes will be in a new version of the interface leaving the existing version unchanged for a while but the old version will eventually be deprecated and removed. As new functionality is introduced to the system then the behaviour of an existing version of the interface may change, e.g. existing faults may also be used in new situations.

URL


Latest version always here: https://access.www.secmaker.com/nias/

References


Reference Version
https://access.www.secmaker.com/nias/ServiceServer.asmx?WSDL 1.0.0
Signature Profile for Net iD products, see Developers Guide (PKCS#7) 5.6.3
OCSP, RFC 2560
http://www.ietf.org/rfc/rfc2560.txt

Authenticate
Request an authentication order. This is an asynchronous operation and the output is used later in the Collect method to query the status of the order and to get the final PKCS#7 signature.

Input
The input parameters to Authenticate are the following:

Parameter Description Required
personalNumber The Personal Number Yes
endUserInfo Additional information about the end user that is known by the SP. This is a list of elements of type EndUserInfoType,. The number of items in the list is in the range 0 to 20. There can be no duplicates for the type element in .EndUserInfoType. No

Output

Output parameter from Authenticate is the following:

Parameter Description
orderRef An identifier that uniquely identifies the order. Used later in the Collect method to collect the Authenticate response and to query status.

orderref_001

Fault Fault

If the operation fails a fault will be returned. This fault will contain a code (an XML enumeration) and a detailed description, see Fault chapter.

Sign

Request a signature order. This is an asynchronous operation and the output is used later in the Collect method to query the status of the order and to get the final XML signature.

Input

The input to Sign is wrapped in the element SignRequest, which contains the following sub-elements:

Parameter Description Required
personalNumber The Personal Number Yes
userVisibleData The text to be displayed and signed. Must be UTF-8 encoded. The value should be base 64-encoded. Max 100KB (after base 64-encoding). Yes
userNonVisibleData Data that is not displayed to the user at time of signature computation. The value should be base 64-encoded. Max 5MB (after base 64-encoding). No
endUserInfo Additional information about the end user that is known by the SP. This is a list of elements of type EndUserInfoType. The number of items in the list is in the range 0 to 20. There can be no duplicates for the type element in .EndUserInfoType. No

Output

Output parameter from Sign is the following:

Parameter Description
orderRef An identifier that uniquely identifies the order. Used later in the Collect method to collect the Sign response and to query status.

Fault

If the operation fails a fault will be returned. This fault will contain a code (an XML enumeration) and a detailed description, see Fault chapter.

Collect

This method is used to query the status of an Authenticate or a Sign order. The return value is only progress status until the end user is finished and the order is complete. Once the order is complete the return values are also the resulting PKCS#7 signature, the OCSP response when validating the end users certificate and some information about the end user.

Input

The input parameter to Collect is the following:

Parameter Description Required
orderRef An identifier that uniquely identifies an order. Returned by Authenticate or Sign method. Yes

Output

Output parameters from Collect are the following:

Parameter Description Required
progressStatus An enumeration describing at what stage the processing of the Authenticate or Sign order, see below Yes
signature A validated or not validated Signature encoded as base 64. The format is according to PKCS#7 Attached. This is only present if progressStatus is COMPLETE. No
userInfo An element of type UserInfoType with information about the end user, see below. This is only present if progressStatus is COMPLETE. No
ocspResponse Status of the certificate when the signature was validated, OCSP response encoded as base 64, see below. This is only present if progressStatus is COMPLETE. No

OCSP Response

The OCSP response is signed. The OSCP response can depend on responder

UserInfo Type

UserInfoType holds information about the end user that is returned to the SP.

Parameter Description Required
name Name of the end user. Yes
personalNumber The Personal Number of the end user. Yes
notBefore Validity time Yes
notAfter Validity time Yes
givenName Given name of the end user. Yes
surname Surname of the end user. Yes

DeviceInfo Type

DeviceInfo Type holds information about the end users device that is returned to the SP.

Parameter Description Required
name ? Yes
version OS and version Yes
address IP-adress Yes

userinfo_001

Status

The progressStatus element in the Collect response message is of the type ProgressStatusType that is an enumeration with the following elements:

Parameter Description
COMPLETE The signature is complete and is included in the response.
USER_SIGN The request has been delivered to the End User (mobile client).
OUSTANDING_TRANSACTION The request has not yet been sent to the End User.

EndUserInfo Type

The type EndUserInfoType holds information about the end user that is known by the SP. It is a parameter in the Authenticate and Sign method.

Parameter Description Required
type The type of information about the end user. There are two allowed types (string, 1 – 20 characters):IP_ADDR_WEB – End user web IP address.
This should be the remote address and not a HTTP header value.

IP_ADDR_APP – End user App IP address.
This should be the remote address and not a HTTP header value.

More types may be added in the future. This will not affect the RP Web Service interface version.

Yes
value The Personal Number of the end user. Yes

Fault

All Services methods return RpFault if an error occurs. It has the following sub-elements:

Parameter Description
faultStatus A fault status enumeration of type FaultStatusType described below
detailedDescription Additional information describing the error.

Fault status

All faults are of the FaultStatusType enumeration type. One new fault was introduced in version 2. One existing fault in version 1 is also used in a new situation. It has the following elements:

Status Description
INVALID_PARAMETERS Input parameters are missing or invalid.
ACCESS_DENIED_RP The security configuration of the RP does not allow the requested operation. This can be if the RP is not configured at all, that the SP is not enabled or that the SP does not have access to the order (i.e. the order belongs to another SP)
SIGN_VALIDATION_FAILED The PKI validation of the signature for Authentication or Sign failed. Could be caused by the mobile client not encrypting correctly.
RETRY Some kind of temporary problems. This is if the OCSP server has temporary problems that prevent the verification of the End User for signatures. Retry at a later time.
INTERNAL_ERROR Internal error in SP Service. This is some kind of unexpected error in the system, e.g. problems with network or database. Also of the OCSP server can’t be contacted.
UNKNOWN_USER The End User is unknown or not valid. The reason for this can be that the End user is never enrolled or that the certificate is expired, revoked or blocked. This fault is also returned if the End User is not valid when verifying a signature.
ALREADY_COLLECTED The signature has already been collected; it can only be collected once.
EXPIRED_TRANSACTION The queried transaction has expired. The check for expired transaction is done first, before starting to handle the collect request. This fault will only be returned when the order becomes expired, repeated calls will return INVALID_PARAMETERS
TIMEOUT Not used
INVALID_DEVICESW The mobile client is invalid. This is due to not following the protocol correctly in the Genuine Software Verification.
ALREADY_IN_PROGRESS
USER_CANCEL The mobile client reported that the End User cancelled the Authenticate or Sign request.
TIME_BLOCKED? The End User already has a request to process. There can only be one request for an End User at a time. Cancel the order in the mobile client or retry later when the order has expired.
CANCELLED The order has been cancelled. If an Authenticate or Sign order is already present for a personalNumber when a new one is ordered then the RP that first created the order receives this fault and the order is cancelled. The RP that sends the second order receives ALREADY_IN_PROGRESS fault. There is no order active for personalNumber after that.