Hướng dẫn tích hợp API chữ ký số vào ứng dụng thông qua webservice viettel

CA

Certification Authority

PKI

Public Key Infrastructure

M

Mandatory

O

Optional

RD

Required Conditional

AP

Application Provider

RP

Relying Party

SCAL1

Sole Control Assurance Level 1

SCAL2

Sole Control Assurance Level 2

RS

Remote Signing

SAD

Signature Activation Data

POST /rssp/v1/info HTTP/1.1

HOST: rssp.mobile-id.vn

Content-Type: application/json

{}

{

    "version": "1.0.0"

    "name": "Remote Signing Services",

    "description": "An efficient remote signature service",

    "logo": "https://rssp.mobile-id.vn/images/logo.png",

    " languages": [

        "VN", "EN"

    ],

    " authTypes": [

        "PASSCODE","OTPSMS","OTPEMAIL"

    ],

    "methods": [

        "auth/login","auth/revoke",

        "credentials/list","credentials/info",

        "credentials/sendOTP","credentials/authorize"

        "credentials/extendTransaction","signature/signHash",

        "owner/list","owner/assign"

]

}

1

version

String

M

The current version of Remote Signing

2

name

String

M

The name of the service

3

description

String

O

The description of the service

4

logo

String

O

The logo image URL of the service

5

languages

String []

M

The languages are supported by the service

6

authTypes

String []

M

Authorization methods are supported by the service. These values RSSP support:

-      Basic: authorization by user and password.

-      SSL2: authorization by pkcs7 signature.

-      OAUTH2: RSSP support oauth2.

7

oauth2

String

RC

The base URI of the OAuth 2.0 authorization server endpoint supported by the remote service for service authorization and/or credential authorization. The parameter SHALL be present in any of the following cases:

• The authType parameter contains “oauth2code” or “oauth2client”;

• The remote service supports the value “oauth2code” for the authMode parameter returned by credentials/info.

8

methods

String []

M

Functions are supported by the service

POST /rssp/v1/auth/login HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: SSL2 dXNlcm5hbWU6cGFzc3dvcmQ6c2lnbmF0dXJlOnBrY3MxU2lnbmF0dXJlOnRpbWVzdGFtcA==, Basic VVNFUk5BTUU6dXNlcjoxMjM0NTY=

Content-Type: application/json

{

    "relyingParty": "MOBILE-ID",

    "relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

    "rememberMe": true,

    "language": "EN"

}

{

    "responseCode": 0,

    "responseMessage": "Successfully",

    "billCode": "MOBILE-ID-190611194921-3-559951",

    "accessToken": "VGhpcyBpcyBhY2Nlc3NUb2tlbg==",

    "refreshToken": "cmVmcmVzaFRva2VuIGlzIG1lLg==",

    "expiresIn": 60,

    "username": "user"

}

1

relyingParty

String

M

In case of many services are running on Remote Signing. Relying Party is used to determine which client is calling to.

2

relyingPartyBillCode

String

O

Relying Party’s billcode.

3

billCode

String

O

Request’s bill code.

4

rememberMe

Boolean

O

A Boolean value typically corresponding to an option that the user may activate during the authentication phase to "stay signed in" and maintain a valid authentication across multiple sessions:

§  "true": if the remote service supports user re-authentication, a refreshToken will be returned and the signature application may use it on a subsequent call to this method instead of passing an Authorization header.

§  "false": a refreshToken will not be returned.

If the parameter is omitted, it will default to "false".

5

clientInfo/iccid

String

O

Client machine information. RS will use this one to manage working session binding with a replyingParty or owner.

6

clientInfo/imei

String

O

Client machine information. RS will use this one to manage working session binding with a replyingParty or owner.

7

clientInfo/macAddr

String

O

Client machine information. RS will use this one to manage working session binding with a replyingParty or owner.

8

language

String

O

Possible value: VN, EN

1

responseCode

int

M

Code describes the result.

Expected: 0

2

responseMessage

String

M

Message describes the result in detail.

3

billCode

String

M

Receipt for each transaction

4

accessToken

String

M

The short-lived service access token used to authenticate the subsequent API requests within the same session. When receiving an API call with an expired token, the remote service will return an error and require a new auth/login request.

5

refreshToken

String

RC

The long-lived refresh token used to re-authenticate the user on the subsequent session. The value is returned if the rememberMe parameter in the request is "true" and the remote service supports user re-authentication.

6

expiresIn

int

O

The lifetime in seconds of the service access token. If omitted, the default expiration time is 3600 seconds.

7

remainingCounter

int

RC

Number of remaining attempts of login, only return if basic available in header Authorization and password of owner is wrong.

8

temporaryLockTime

Int

RC

Owner lockout time, only try again when the time is up.  In seconds.

9

ownerInfo/fullName

String

RC

Full name of account.

10

ownerInfo/phone

String

O

Phone of account.

11

ownerInfo/email

String

O

Email of account.

12

ownerInfo/oauth2

String

O

OAUTH2 account information.

Credential information

No

Name

Type

Require

Description

1

username

String

M

Username of relyingParty provided by Remote Signing

2

password

String

M

Password of relyingParty provided by Remote Signing

3

signature

String

M

Signature of relyingParty provided by Remote Signing

4

pkcs1Signature

String

M

Value is signed from client private key. Key is generated and provided by Remote Signing

Value=username + password + signature + timestamp

5

timestamp

String

M

Current timestamp, format in yyyyddmmHHMMss format or Unix epoch time likes 1570182293561.

POST /rssp/v1/auth/revoke HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

    "relyingParty": "MOBILE-ID",

    "relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

    "tokenType": 0,

    "token": "VGhpcyBpcyBhY2Nlc3NUb2tlbg==",

    "language": "EN"

}

{

    "responseCode": 0,

    "responseMessage": "Successfully",

    "billCode": "MOBILE-ID-190611194921-3-559951"

}

1

relyingPartyBillCode

String

O

Relying Party’s billcode

2

billCode

String

O

Request’s bill code.

3

tokenType

int

O

The type of token submitted for revocation. The possible values are:

0: access token

1: refresh token

2: SAD token

If token type is omitted. RS understands the token received is access token.

4

token

String

M

The token will be revoked

5

language

String

O

Possible value: VN, EN

6

agreementUUID

String

RS

Contract identifier, this value is required when tokenType is 2 (to revoke SAD token) and access_token in Authorization header is retrieved from login with SSL2 Only.

7

thumbprint

String

RC

Thumbprint of certificate, this value is required when tokenType is 2 (to revoke SAD token).

1

responseCode

int

M

Code describes the result.

Expected: 0

2

responseMessage

String

M

Message describes the result in detail.

3

billCode

String

M

Receipt for each transaction

POST /rssp/v1/credentials/list HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

    "relyingParty": "MOBILE-ID",

    "relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

    "agreementUUID": FEC#201910281308,

    "language": "EN"

}

{

    "responseCode": 0,

    "responseMessage": "Successfully",

    "billCode": "MOBILE-ID-190611194921-3-559951"

    "certificates": [

        {

            "certificateID": 84902,

            "issuerDN": "<X.500_issuer_DN_printable_string>",

            "serialNumber": "5AAC41CD8FA22B953640",

            "thumbprint": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8",

            "subjectDN": "<X.500_subject_DN_printable_string>",

            "validFrom": "20180101100000Z",

            "validTo": "20190101095959Z",

        },

        {

            "certificateID": 84899,

            "issuerDN": "<X.500_issuer_DN_printable_string>",

            "serialNumber": "5AAC41CD8FA22B953640",

            "thumbprint": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8",

            "subjectDN": "<X.500_subject_DN_printable_string>",

            "validFrom": "20180101100000Z",

            "validTo": "20190101095959Z",

        }

    ]

}

1

relyingPartyBillCode

String

O

Relying Party’s billcode

2

billCode

String

O

Request’s bill code.

3

agreementUUID

String

RC

The uuid of agreement, this value was returned from the agreement registration (SOAP API).

This param require when access_token is retrieved from login with SSL2 Only.

4

searchConditions/certificateStatus

String

O

State of certificate. The possible values are:

·         “ALL”,

·         “GOOD”,

·         “REVOKED”.

Default value is “ALL”.

5

searchConditions/cetificatePurpose

String

O

Purpose usage of certificate. The possible values are:

·         “ALL”,

·         “SIGNATURE”,

·         “ENCRYPTION”.

Default value is “ALL”

6

certificateInfo

Boolean

O

Returns the details of certificate information. This is useful in case the signature application wants to retrieve some details of the certificate without having to decode it first. The default value is “false”, so if the parameter is omitted then the information will not be returned.

7

language

String

O

Possible value: VN, EN

1

responseCode

int

M

Code describes the result.

Expected: 1007

2

responseMessage

String

M

Message describes the result in detail.

3

billCode

String

M

Receipt for each transaction

4

certificates/issuerDN

String

RC

The Issuer Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.

5

certificates/serialNumber

String

RC

The Serial Number from the X.509v3 end entity certificate represented as hex-encoded string format. This value will be returned when certificateInfo is “true”.

6

certificates/thumbprint

String

M

The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.

7

certificates/subjectDN

String

RC

The Subject Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.

8

certificates/validFrom

String

RC

The validity start date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.

9

certificates/validTo

String

RC

The validity end date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.

10

certificate/certificateProfile/name

String

RC

Name of certificate’s profile. This value will be returned when certificateInfo is “true”.

11

certificate/certificateProfile/description

String

RC

Description of certificate’s profile.  This value will be returned when certificateInfo is “true”.

12

certificates/purpose

String

RC

Purpose usage of certificate. This value will be returned when certificateInfo is “true”.

13

certificates/numSignatures

int

RC

A number equal or higher to 1 representing the maximum number of signatures that can be created with this credential with a single authorization request. This value will be returned when certificateInfo is “true”.

14

certificates/remainingSigningCounter

int

M

Remaining signing counter of this certificate.

§  -1: unlimited.

§  0: out of signing.

15

certificates/version

int

M

The certificate version, the third application must rely on this value to decide perform credentials/info for update the certificate info.

POST /rssp/v1/credentials/info HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

    "relyingParty": "MOBILE-ID",

    "relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

    "certificateID": 5,

    "certificates": "chain",

    "certificateInfo": true,

    "authenticationInfo": true,

    "language": "EN"

}

{

    "responseCode": 0,

    "responseMessage": "Successfully",

    "billCode": "MOBILE-ID-190611194921-3-559951",

    "certificate": {

        "status": "valid",

        "certificates": [

            "<Base64-encoded_X.509_end_entity_certificate>",

            "<Base64-encoded_X.509_intermediate_CA_certificate>",

            "<Base64-encoded_X.509_root_CA_certificate>"

        ],

        "issuerDN": "<X.500_issuer_DN_printable_string>",

        "serialNumber": "5AAC41CD8FA22B953640",

        "thumbprint": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8",

        "subjectDN": "<X.500_subject_DN_printable_string>",

        "validFrom": "20180101100000Z",

        "validTo": "20190101095959Z",

        "sharedMode": 1,

        "createdRP": "MOBILE-ID"

    },

    "authorizeMethod": [

        1,

        2,

        4

    ],

    "numSignatures": 5,

    "authMode": "explicit",

    "SCAL": 2,

    "language": "EN"

}

1

relyingPartyBillCode

String

O

Relying Party’s billcode

2

billCode

String

O

Request’s bill code.

3

agreementUUID

String

RC

The uuid of agreement, this value was returned from the agreement registration (SOAP API).

This param require when access_token is retrieved from login with SSL2 Only.

4

thumbprint

String

M

The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.

5

certificates

String

O

Specifies which certificates from the certificate chain will be return in the response.

§  “none”: No certificate will be returned.

§  “single”: Only signer certificate will be returned.

§  “chain”: The full certificate chain will be returned.

If this attribute is omitted, the the default is “single” will be treated.

6

certificateInfo

Boolean

O

Returns the details of certificate information. This is useful in case the signature application wants to retrieve some details of the certificate without having to decode it first. The default value is “false”, so if the parameter is omitted then the information will not be returned.

7

authenticationInfo

Boolean

O

Returns the authentication method which is supported for a client. The default value is “false”, so if the parameter is omitted then the information will not be returned.

8

language

String

O

Possible value: VN, EN

1

responseCode

int

M

Code describes the result.

Expected: 1007

2

responseMessage

String

M

Message describes the result in detail.

3

billCode

String

M

Receipt for each transaction

4

certificate/status

String

O

The status of signer certificate which is binding with the client. Some examples responses:

§  “not enrolled”

§  “valid”

§  “unknown”

§  “revoked”

§  “expired”

5

certificate/certificates

String[]

RC

One or more Base64-encoded X.509v3 certificates from the certificate chain. If the certificates parameter is “chain”, the entire certificate chain SHALL be returned with the end entity certificate at the beginning of the array. If the certificates parameter is “single”, only the end entity certificate SHALL be returned. If the certificates parameter is “none”, this value SHALL NOT be returned.

6

certificate/issuerDN

String

RC

The Issuer Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.

7

certificate/serialNumber

String

RC

The Serial Number from the X.509v3 end entity certificate represented as hex-encoded string format. This value will be returned when certificateInfo is “true”.

8

certificate/thumbprint

String

M

The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.

9

certificate/subjectDN

String

RC

The Subject Distinguished Name from the X.509v3 end entity certificate as UTF-8-encoded character string. This value will be returned when certificateInfo is “true”.

10

certificate/validFrom

String

RC

The validity start date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.

11

certificate/validTo

String

RC

The validity end date from the X.509v3 end entity certificate as character string. This value will be returned when certificateInfo is “true”.

12

certificate/certificateProfile/name

String

M

Name of certificate’s profile. This value will be returned when certificateInfo is “true”.

13

certificate/certificateProfile/description

String

M

Description of certificate’s profile.  This value will be returned when certificateInfo is “true”.

14

certificate/purpose

String

O

Purpose usage of the certificate.

15

sharedMode

String

O

Which sharing mode will be used in the Remote Signing. The possible values are:

·         “PRIVATE_MODE”

·         “RP_SHARED_MODE”

·         “AGREEMENT_SHARED_MODE”

Default value is PRIVATE_MODE. It’s meant once Relying Party don’t use this parameter, the PRIVATE_MODE is used instead

16

createdRP

String

O

This is Relying Party name. It indicates that the certificate was created by that RP. It is helpful if the certificate is shared to an agreement from different RP.

17

numSignatures

int

M

A number equal or higher to 1 representing the maximum number of signatures that can be created with this credential with a single authorization request.

18

authModeSupported

String[]

M

Specifies one of the authorization modes.

§  “EXPLICIT/PIN”: the authorization process is managed by the signature application, authentication method is passcode.

§  “EXPLICIT/OTP-SMS”: the authorization process is managed by the signature application, authentication method is otp sms.

§  “EXPLICIT/OTP-EMAIL”: the authorization process is managed by the signature application, authentication method is otp email.

§  “IMPLICIT/CYBER-ID”: the authorization process is managed by the remote service autonomously. Authentication factors are managed by the RSSP by interacting directly with the user, and not by the signature application.

§  “IMPLICIT/BIP-CATTP”: the authorization process is managed by Cyber-ID – a mobile application – which could interact to PKI USIM for signing.

§  “EXPLICIT/OTP-MOBILE”: the authorization process is managed by OTP Mobile Application.

§  “OAUTH2”: not implement yet.

19

authMode

String

M

One value in values of No.15, is authorization mode activated at moment. To change must make by RSSP administrator.

20

SCAL

int

O

§  1: The hash to-be-signed is not linked to the signature activation data.

§  2: The hash to-be-signed is linked to the signature activation data.

21

contractExpirationDt

String

O

Contract's expiration date, to reissue certificate for compensation.

22

remainingSigningCounter

int

O

Remaining signing counter of this certificate.

§  -1: unlimited.

§  0: out of signing.

23

authorizationEmail

String

RC

Authorization email. This value will be returned when authenticationInfo is “true”.

24

authorizationPhone

String

RC

Authorization phone. This value will be returned when authenticationInfo is “true”.

25

passphraseDefault

boolean

RC

True if passphrase is default and user must change passphrase before do cryptography.

POST /rssp/v1/credentials/sendOTP HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

    "relyingParty": "MOBILE-ID",

    "relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

    "certificateID": 84902,

    "authorizeMethod": 1,

    "notificationTemplate": "RemoteSigning: Your authorization code {AuthorizeCode}",

    "notificationSubject": "Remote Signing - Your authorization code",

    "language": "EN"

}

{

    "responseCode": 1007,

    "responseMessage": "Request accepted",

    "billCode": "MOBILE-ID-190611194921-3-559951"

}

1

relyingPartyBillCode

String

O

Relying Party’s billcode.

2

billCode

String

O

Request’s bill code.

3

agreementUUID

String

RC

The uuid of agreement, this value was returned from the agreement registration (SOAP API).

This param require when access_token is retrieved from login with SSL2 Only.

4

thumbprint

String

M

The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.

5

notificationTemplate

String

O

Message contains Authorize Code will be sent to customer’s Phone/Email.

Authorize Code is generated on Remote Signing and embedded into template.

E.g: Your authorization code: {AuthorizeCode}. Authorize Code is valid within 300 seconds.

6

notificationSubject

String

O

This parameter is used as Email subject for signing authorization. If OTP Email is used, this parameter is mandatory

It should be used in case of the Remote Signing will use owned SMTP to send OTP Email to customer.

7

language

String

O

Possible value: VN, EN

1

responseCode

int

M

Code describes the result.

Expected: 1007

2

responseMessage

String

M

Message describes the result in detail.

3

billCode

String

M

Receipt for each transaction

4

temporaryLockTime

Int

RC

Certificate lockout time, only try again when the time is up.  In seconds.

POST /rssp/v1/credentials/authorize HTTP/1.1

HOST: rssp.mobile-id.vn

Authorization: Bearer VGhpcyBpcyBhY2Nlc3NUb2tlbg==

Content-Type: application/json

{

    "relyingParty": "MOBILE-ID",

    "relyingPartyBillCode": "MOBILE-ID-190611194921-3-559950",

    "certificateID": 84902,

    "billCode": "MOBILE-ID-190611194921-3-559951",

    "authorizeCode": "654321",

    "authorizeMethod": 1,

    "numSignatures": 2,

    "hash": [

        "532eaabd9574880dbf76b9b8cc00832c20a6ec113d682299550d7a6e0f345e25",

        "bd9c74f0a16ddc8c877651085e161824be897aa129604326fe67bc2a41316b77"

    ],

    "hashAlgorithm": "sha-256",

    "language": "EN",

    "notificationTitle":"Dịch vụ SMART-ID",

    "notificationMessage":"Yêu cầu cần được xác thực",

    "messageCaption":"Đăng nhập dịch vụ VPN",

    "transactionInfo":{

        "Dịch vụ":"VPN của Mobile-ID",

        "Địa điểm":"Hồ Chí Minh"

    },

    "clientInfo":{

        "iccid":"8991101200003204514",

        "imei":"990000862471854",

        "macAddr":"00:0a:95:9d:68:16"

    },

    "message":"Complete the authentication to use the service",

    "logoURI":"https://rssp.mobile-id.vn/images/mobile-id_logo_159x50.png",

    "bgImageURI":"https://rssp.mobile-id.vn/images/background02.jpg",

    "rpIconURI":"https://rssp.mobile-id.vn/images/mobile-id_logo_159x50.png",

    "rpName":"MOBILE_ID",

    "confirmationPolicy":"PIN",

    "expirationDuration":3,

    "vcEnabled":true,

    "acEnabled":false,

    "messagingMode":1,

}

{

    "responseCode": 0,

    "responseMessage": "Successfully",

    "billCode": "MOBILE-ID-190611194921-3-559951",

    "SAD": "_TiHRG-bAH3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5_pw",

    "expiresIn": 60,

    "remainingCounter": 5

}

1

relyingPartyBillCode

String

O

Relying Party’s billcode.

2

billCode

String

O

Request’s bill code.

3

agreementUUID

String

RC

The uuid of agreement, this value was returned from the agreement registration (SOAP API).

This param require when access_token is retrieved from login with SSL2 Only.

4

thumbprint

String

M

The certificate thumbprint. This value is calculated by hashing the encoded certificate binary. The SHA-256 algorithm is usually used to hash this data.

5

authorizeCode

String

RC

Authorize Code provided by customer. It could be PIN (PassCode) or OTP. It is required when authMode returned in credentials/info is EXPLICIT/PIN or EXPLICIT/OTP-SMS or EXPLICIT/OTP-EMAIL or EXPLICIT/OTP-MOBILE.

6

language

String

O

Possible value: VN, EN

7

numSignatures

int

M

The number of signatures to authorize. Multi-signature transactions can be obtained by using a combination of passing an array of hash values and calling the signatures/signHash method

8

hash

String[]

RC

One or more Base64-encoded hash values to be signed. It is required when SCAL is level 2.

9

hashAlgorithm

String