STT

Ten ham

Mo ta

1

Login

Dang nhap lay phien (dang access_token)

2

Certificates/Info

Lay danh sach CTS va chi tiet thong tin CTS

3

SignHash

Ky ma bam

Link

BASE_URL/vtss/service/ras/v1/login

HTTP Verb

Content
Type

application/json

Accept

application/json

Request
Body

{
"client_id": “adss…client”,
"client_secret": “fj49kl…….oOpQS”,
"profile_id": “ADSS RAS Profile 001”,
"user_id": “MST_0100109106-998”
}

client_id

MANDATORY

String

Client ID cua ung dung ky

(Toi da 50 ky tu).

user_id

MANDATORY

String

User ID cua nguoi ky

(Toi da 50 ky tu).

client_secret

MANDATORY

String

Khoa bao mat cua ung dung ky

profile_id

OPTIONAL

String

Profile ID cua nguoi ky

(Toi da 50 ky tu).

Status Code

Message

Response Body

200

OK

{
"access_token": "eyJhbGciOiJIUzI1NsInN…Pcxcz2hM",
"refresh_token": "",

"token_type": "Bearer",

"expires_in": "3600"
}

400

Bad Request

{
"error": "58071",
"error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."
}

401

Unauthorised

{
"error": "59033",
"error_description": "Failed to process request - user ID or password is invalid"
}

access_token

MANDATORY

String

Phien giao dich (access token)

refresh_token

CONDITIONAL

String

Token cap nhat phien giao dich

token_type

MANDATORY

String

Loai access token

expires_in

MANDATORY

String

Han cua phien (seconds)

error_code

CONDITIONAL

String

Ma loi

error_description

CONDITIONAL

String

Mo ta loi

Link

BASE_URL/adss/service/ras/csc/v1/credentials/list

HTTP Verb

Content
Type

application/json

Accept

application/json

Authorization

Bearer

eyJhbGciOiJIUzI1NsInN…Pcxcz2hM

Request
Body

{

"client_id": “adss…client”,
"client_secret": “fj49kl…….oOpQS”,
"profile_id": “ADSS RAS Profile 001”,
"user_id": "MST_0100109106-998",

"certificates": "chain",
"certInfo": true,
"authInfo": true
}

client_id

MANDATORY

String

Client ID cua ung dung ky

(Toi da 50 ky tu).

user_id

MANDATORY

String

User ID cua nguoi ky

(Toi da 50 ky tu).

client_secret

MANDATORY

String

Khoa bao mat cua ung dung ky

profile_id

OPTIONAL

String

Profile ID cua nguoi ky

(Toi da 50 ky tu).

certificates

OPTIONAL

String

Chi dinh thong tin CTS tra ve:
· None: Khong tra ve
· Single: Chi tra ve CTS cua nguoi ky

· Chain: Tra ve chuoi CTS gom CTS cua nguoi ky, cua Viettel-CA va cua Bo TTTT.
Default: ‘single’

certInfo

OPTIONAL

Boolean

· True: Tra ve thong tin kem theo CTS

· False: Khong tra ve thong tin kem theo CTS.

Default: ‘false’

authInfo

OPTIONAL

Boolean

· True: Tra ve cac thong tin ve co che uy quyen duoc ho tro

· False: Khong tra ve cac thong tin ve co che uy quyen duoc ho tro

Default: ‘false’

Status Code

Message

Response Body

200

OK

{
"description": "Go>Sign mobile based implicit credential authorization",
"key”: {
“status": "ENABLED",
"algo": [
"1.2.840.113549.1.1.1"
],
"len": 2048,

"curve": null
},
"cert”: {
“status": "valid",
"certificates": [
"Base64-encoded X.509 end entity certificate",
"Base64-encoded X.509 intermediate CA certificate",
"Base64-encoded X.509 issuer CA certificate"
],
“issuerDN": "Issuer DN printable string",
"SerialNumber": "5AAC41CD8FA22B953640",
"subjectDN": "Subject DN printable string",
"validFrom": "20180709132216+0000",
"validTo": "20190709132216+0000"
},
"authMode": "implicit",

"multisign": “2147483647”,
"lang": null,

"credential_id": "0100109106-998_2475106_20221011075826",

 "SCAL": "2",}

400

Bad Request

{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes
an invalid parameter value, includes a parameter more than once, or is
otherwise malformed."
}

description

OPTIONAL

String

Mo ta

(Toi da 255 ky tu).

key/status

MANDATORY

String

Trang thai cap khoa CTS
· Enabled: Khoa co the dung de ky

· Disabled: Khoa khong the dung de ky

key/algo

MANDATORY

String

Danh sach OID cac thuat toan ho tro ky so

· 1.2.840.113549.1.1.1=RSA
encryption
· 1.2.840.10045.4.3.2=ECDSA with
SHA256

key/len

MANDATORY

Number

Do dai khoa (bits).

key/curve

CONDITIONAL

String

OID ECDSA curve.

Chi tra ve khi keyAlgo thuoc nhom ECDSA.

cert/status

OPTIONAL

String

Trang thai CTS

cert/certificates

CONDITIONAL

String

Danh sach CTS dang Base64.

cert/issuerDN

CONDITIONAL

String

DN cua CA cap CTS

Tra ve khi certInfo: “true”.

cert/serialNumber

CONDITIONAL

String

Serial number CTS

Tra ve khi certInfo: “true”.

cert/subjectDN

CONDITIONAL

String

DN CTS

Tra ve khi certInfo: “true”.

cert/validFrom

CONDITIONAL

String

Thoi gian bat dau hop le cua CTS

Tra ve khi certInfo: “true”.

Format GeneralizedTime (RFC 5280 e.g. “YYYYMMDDHHMMSSZ”).

cert/validTo

CONDITIONAL

String

Thoi gian ket thuc hop le cua CTS

Tra ve khi certInfo: “true”.

Format GeneralizedTime (RFC 5280 e.g. “YYYYMMDDHHMMSSZ”).

authMode

MANDATORY

String

Phuong thuc xac thuc:
· Implicit: Nguoi ky thuc hien xac thuc

SCAL

OPTIONAL

String

· “2”: Su dung SCAL2 

multisign

MANDATORY

Number

So luong chu ky toi da co the ky cung luc

credential_id

MANDATORY

String

credential_id (dinh danh) cua CTS

lang

OPTIONAL

String

Ma ngon ngu cua ket qua (theo RFC 5646).

error_code

CONDITIONAL

String

Ma loi

error_description

CONDITIONAL

String

Mo ta loi

Link

BASE_URL/vtss/service/signHash

HTTP Verb

Content
Type

application/json

Accept

application/json

Authorization

Bearer _TiHRG-bA H3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5_pw

Request
Body

{
"credentialID": "JohnDoe",
"numSignatures": 2,
"description": “Document Name”,
"documents": [{
"document_id": 123,
"document_name": “Document Name 123”,
},{
"document_id": 456,
"document_name": “Document Name 456”,
}],
"hash":
[
"sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
"c1RPZ3dPbSs0NzRnRmowcTB4MWlTTnNwS3FiY3NlNEllaXFsRGcvSFd1ST0="
],

"hashAlgo": "2.16.840.1.101.3.4.2.1",
"signAlgo": "1.2.840.113549.1.1.1",

“async”: 1 }

credentialID

MANDATORY

String

ID CTS (credential_id)

numSignatures

MANDATORY

Number

So luong ham bam can mky

documents/document
_id

OPTIONAL

String

ID dai dien tai lieu ky

documents/document
_name

OPTIONAL

String

* Ten cua tai lieu ky, hien thi tren app Mysign (neu khong co description)

* Can truyen thong tin nhu sau:

- Ma hoa noi dung dang Base64, encode UTF-8 

- Do dai ma Base64 < 100 ky tu

- Noi dung goc bao gom:

+ Chu cai thuong, in hoa: a-z, A-Z

+ Chu so: 0-9

+ Ky tu dac biet: dau gach duoi (_), dau gach ngang (-), d?u cách ( )

hash

CONDITIONAL

String

Ma bam cua tai lieu can ky - Base64

description

OPTIONAL

String

* Mo ta yeu cau ky

* Can truyen thong tin nhu sau:

- Ma hoa noi dung dang Base64, encode UTF-8 

- Do dai ma Base64 < 100 ky tu

- Noi dung goc bao gom:

+ Chu cai thuong, in hoa: a-z, A-Z

+ Chu so: 0-9

+ Ky tu dac biet: dau gach duoi (_), dau gach ngang (-), d?u cách ( )

hashAlgo

CONDITIONAL

String

Ma OID cua thuat toan bam.

Tham so nay bi bo qua neu duoc chi dinh ngam theo thuat toan signAlgo.

signAlgo

MANDATORY

String

OID cua thuat toan ky.

Xac thuc theo thong tin keyAlgo

async

MANDATORY

Integer

Che do ky dong bo/bat dong bo (synchronize/asynchronize)

0: Synchronize mode

1: Asynchronize mode

Trong che do nay, async=1

Status
Code

Message

Response Body

200

OK

{
"transactionId": "de67f948-0498-4919-af28-dff54a6a4e77"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than once, or is otherwise
malformed."
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Missing (or invalid type) string parameter credentialID"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Invalid parameter credentialID"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Missing (or invalid type) integer parameter
numSignatures"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Invalid parameter numSignatures"
}

transactionId

MANDATORY

String

Ma transaction vua thuc hien

error_code

CONDITIONAL

String

Ma loi

error_descripti
on

CONDITIONAL

String

Mo ta loi

Link

BASE_URL/vtss/service/requests/status

HTTP Verb

Content-Type

application/json

Accept

application/json

Authorization

Bearer _TiHRG-bA H3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5_pw

Request Body

{
“transactionId”: “de67f948-0498-4919-af28-dff54a6a4e77”

}

Status
Code

Message

Response Body

200

OK

{
"signatures":
[
"KeTob5gl26S2tmXjqN…MRGtoew=="
],

"status": "1"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than once, or is otherwise
malformed."
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Missing (or invalid type) string parameter credentialID"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Invalid parameter credentialID"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Missing (or invalid type) integer parameter
numSignatures"
}

400

Bad Request

{
"error": "invalid_request",
"error_description": "Invalid parameter numSignatures"
}

signatures

MANDATORY

String

Danh sach chu ky base64

status

MANDATORY

String

Ma trang thai yeu cau:

1 – Success

4000 – Cho nguoi dung xac nhan

4001 – Yeu cau het thoi gian cho (Timeout)

4002 – Nguoi dung tu choi ky

4004 – Ky that bai (co loi xay ra)

50000 – Co loi xay ra khi lay thong tin

error_code

CONDITIONAL

String

Ma loi

error_descripti
on

CONDITIONAL

String

Mo ta loi