Mobile Signature AuthState

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

Introduction and overview

Mobile Signature Service allows messages to be digitally signed by a key installed on a mobile deviceETSI standard document: ETSI TS 102 204 V1.1.4. The transmission to the mobile device is provided by a Mobile Signature Service Provider (MSSP). The Mobile Signature plug-in connects to the MSSP via SOAP interface.

The connection settings to MSSP (SOAP, proxy, profiles, etc. ) are configured in the property msspConnection of the Mobile Signature AuthState (MobileSignatureState) - see the list for a description of the property.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.mss.MobileSignatureState
Logging	MSS
Auditing	none
Marker	MSS:extern
Methods	process (all events)

Properties

• displayStringTemplate (string, "${sess:mss.signaturerequest.aptransid}: Mobile Signature Request: Sign")

  The message that is displayed and prompted to be signed on the mobile device.

• sendUserLangInSignatureRequest (boolean, "true")

  If set to "true", the Element UserLang will be added to the SignatureRequest. Depending on the MSSP server's validation rules this field might be mandatory.

• displayLanguageSource (string, "${sess:ch.adnovum.nevisidm.User.attribute.language}")

  The language of the pop-up messages are shown on the mobile phone. (Allowed format: "FR", "DE", "EN", etc.) If the source is empty, the value is set to "EN".

• requestLifetime (integer, 180000)

  Time-out value of the request, in milliseconds. If no valid signature is available after ths time-out, the "failed" transition is resulting.

• pollInterval (integer, 3000)

  Idle time between two status requests to MSSP, in milliseconds.

• firstPollAfter (integer, 0)

  Idle time before sending the first status request to MSSP, in milliseconds.

• maxPollPhaseDuration (integer, 120000)

  Time-out value for the polling duration, in milliseconds. If no valid signature is available after this time-out, the "failed" transition is resulting.

• signatureValidationByMssp (boolean, true)

  Indicates whether the signature shall be validated by the MSSP.

• propagatePollResult (boolean, false)

  If set to "true", no transition is resulting when the request is still pending. The result from the last poll can be propagated to the client.

  If set to "true", the time-out values need to be configured accordingly.

• signatureValidation (string, "certificateValidation", "msspid", "msisdn", "subject", "serialnumber")

  Comma-separated list of validation methods. Defines the way the signature is validated upon reception. The property may contain the following methods:

  • data, certificateValidation Cryptographic signature validation using the certificate defined in the property validationCertificateSource.
  • msspid Compares the received MSSP-ID with the registered one (defined in the property msspIdSource).
  • msisdn Compares the received MSISDN with the registered one (defined in the property msisdnSource).
  • subject Compares the subject-DN from the received certificate with the registered subject-DN.
  • serialnumber Compares the SERIALNUMBER field of the subject-DN of the received certificate with the registered serial number. If either validation fails, the transition result is "failed" (providing detailed information in ${notes:mss.signature.info}).

• validationCertificateSource (string, "${sess:ch.nevis.idm.User.cred.mobile_signature.signerCert}")

  Source of the certificate that is used to verify the signature. To use the certificate provided in the MSSP Response set this value to "MSSP".

• cancelCondition (string, "false")

  Defines a condition that cancels a signature request (e.g., queryString: "${inargs:cancelButton}"). In case this variable is set, the newest request will be ignored and the transition "cancel" – or "failed" in case "cancel" is not defined – will be resulting.

  info

  This condition is not cancelling signature requests already sent, i.e., signature requests already sent may still be displayed on the mobile device.

• sendReceipt (boolean, false)

  Defines whether a receipt message is sent to the user's mobile device upon successful authentication.

• receiptMessage (string, "Successful Authentication!")

  Text shown in the receipt message on the user's mobile device.

• generateChallenge (boolean, false)

  Enables a TAN challenge generation when process() is called first. TAN challenge is generated according to the template defined in the property tanTemplate, and saved in the variable ${sess:mtan.challenge}.

• tanTemplate (string, "6{ABCDEFGHIJKLMNOPQRSTUVWXYZ}")

  See the description of the property tanTemplate in chapter TAN authentication plug-ins.

• crl.keystoreref (string, "")

  Keystore used in the signature validation and CRL check. For a description of how to define keystores, see chapter Certificates keys and public key infrastructure. All key objects contained in the keystore will be used for validation. If multiple key objects are defined, the signature validation is successful if any of the key object certificates validates the signature and is not revoked.

• updateCredential (boolean, false)

  Enables a certificate/credential update after successful authentication with the certificate provided by the MSSP response. Note: To allow an update, the signature validation must be successful with the new certificate.

  The new certificate will be stored in ${notes:mss.validation.certificate.update}. Further values are available in ${notes:mss.msspId} and ${notes:mss.msisdn}. See also the "Notes" topic further on in this table.

• updateRule.N (string, "")

  Defines the rules under what condition the certificate/credential will be updated. Possible values are

  • updateIfSubjectMatch Only update if the subject of the new certificate matches the old one.
  • updateIfIssuerMatch Only update if the issuer of the new certificate matches the old one.
  • updateIfStoredCertEmpty Only update if no certificate is stored in the given source. - always: Unconditional update.

  Multiple update rules can be configured by appending integer numbers, e.g., updateRule.1, updateRule.2.

• msspConnection, msspConnection1, msspConnection2, ... (property-string, -)

  Comma-separated list of properties used for the connection to the MSSP, values are assigned by "=":

  • msspId The MSSP-ID identifying this connection.
  • msspSignatureUrl SignatureRequest port endpoint.
  • msspStatusQueryUrl StatusQuery port endpoint.
  • msspReceiptUrl ReceiptRequest port endpoint. (optional)
  • msspApId The AP ID.
  • msspApPassword The AP password.
  • msspSignatureProfile The signature profile for this AP.
  • service.httpclient.tls.trustStoreRef
  • service.httpclient.tls.keyObjectRef
  • service.httpclient.tls.hostnameVerification
  • service.httpclient.proxy.host
  • service.httpclient.proxy.port
  info

  HttpClient properties work the same as described here, however this AuthState uses a JAX-WS soap client. So only the configuration options specified above are applicable.

• msisdnSource (string, "${sess:ch.nevis.idm.User.cred.mobile_signature.value}")

  Source of the MSISDN (mobile number) value. By default the standard nevisIDM credential session variable is defined.

• msspIdSource (string, "${sess:ch.nevis.idm.User.cred.mobile_signature.msspIdentifier}")

  Source of the MSSP-ID value. By default the standard nevisIDM credential session variable is defined.

Input

• msisdn

  The user's registered MSISDN. Source as defined in the property msisdnSource, by default the nevisIDM credential value in the session.

• msspId

  The user's registered mobile signature service provider identifier (MSSP-ID). Source as defined in the property msspIdSource, by default the nevisIDM credential value in the session.

• signerCert

  The user's registered signer certificate (if configured). Source as defined in the property validationCertificateSource, by default the nevisIDM credential value in the session.

Transitions

• ok

  Mobile signature validation successful

• failed

  No valid signature

• cancel

  Request is canceled by user (optional)

• requestok

  Signature request has been sent to MSSP (optional)

• pending

  Outstanding signature request (optional)

• update

  Update credential values (optional)

Output

For resulting status codes, see Notes.

Errors

• lasterror=1

  lasterrorinfo=Login failed

Notes

• mss.signature.statuscode

  Current and resulting MSS status code.

• mss.signature.statusmessage

  Current and resulting MSS status message.

• mss.signature.info

  Additional information on the current MSS status (if set).

• mss.signature.error

  Error cause in case of an error during the MSS status message validation. Possible values: CRL_EXPIRED, CRL_NOT_AVAILABLE, UNKNOWN_ERROR.

Only set if signer certificate is updated:

• mss.signerCert.update

  Updated certificate

• mss.msspId

  The user's service provider identifier.

• mss.msisdn

  The user's MSISDN.

• mss.identificator.update

  The subject DN of the updated certificate.

• mss.issuer.update

  The issuer DN of the updated certificate.

• mss.receiptmessage.statuscode

  The status code of the receipt message received from the Mobile Signature server.

• mss.receiptmessage.statusmessage

  The status message of the receipt message received from the Mobile Signature server.

Example

<AuthState name="MobileSignature" class="ch.nevis.esauth.auth.states.mss.MobileSignatureState" final="false">
   <ResultCond name="ok" next="UpdateMSCredential"/>
   <ResultCond name="failed" next="Logout"/>
   <Response value="AUTH_CONTINUE">
      <Gui name="AuthMssDialog" label="mss.label">
         <GuiElem name="lasterror" type="error"
            label="${notes:lasterrorinfo}" value="${notes:lasterror}"/>
         <GuiElem name="loginmessage" type="info"
            label="The Signature Request has been sent.  Sign the Request on your mobile phone. " value="Message"/>
         <GuiElem name="submit" type="button" label="Continue" value="Login"/>
      </Gui>
   </Response>
   <property name="msspConnection" value="msspId=THE_MSSP_ID,msspApId=YOUR_AP_ID,msspApPassword=THE_AP_PASSWORD,msspSignatureProfile=http://mssp.profile.ch/MyProfile,msspSignatureUrl=https://mssp.endpoint.ch/SignatureRequestPort,msspStatusQueryUrl=https://mssp.endpoint.ch/StatusQueryPort,msspReceiptUrl=https://mssp.endpoint.ch/ReceiptRequestPort,service.keystore=/path/to/keystore.jks,service.keystorePasswd=KEYSTORE_PASSWORD,service.truststore=/path/to/truststore.jks,service.truststorePasswd=TRUSTSTORE_PASSWORD "/>
   <property name="requestLifetime" value="300000" />
   <property name="pollInterval" value="5000" />
   <property name="signatureValidation" value="certificateValidation,msspid,msisdn" />
</AuthState>