API Reference¶

Error handling rules¶

For errors resulted for SOAP interface invocations, MSign returns SOAP faults with fault codes and fault reasons describing the fault in plain English. If there is no SOAP fault returned by MSign, the service consumer should expect that the returned operation result, according to MSign service contract, is valid and can be used directly without additional error checking.

Note that a SignResponse contains SignStatus, which can have Pending, Failure or Expired values, meaning there is are no signing Results returned.

Fault Code	Description
AuthenticationFailed	Service consumer authentication process failed. See Authentication
AuthorizationFailed	Service consumer authorization process failed. See Authorization
InvalidParameter	Some input parameter is invalid. Please review the returned Fault Reason text and called operation description.
RequestNotFound	The provided requestID when calling GetSignResponse was not found by MSign. It might be incorrect or expired (i.e. removed from online DB).

The consumers using programming languages that support try… catch blocks, catching framework specific SOAP Fault exceptions is the correct way to handle service invocation errors.

Service operations¶

PostSignRequest¶

Signature	PostSignRequest(request: SignRequest): string
Description	Post a signature request for later signing.
Returns	A string representing the request ID that can be later used with GetSignResponse.

Input parameters

Name	Type	Description
request	SignRequest	A structure representing the signature request.

Faults

Code	Reason
AuthenticationFailed	Invalid authentication certificate provided, Unknown service consumer: {certificate serial number}
InvalidParameter	Some input parameter is invalid. Please review the returned Fault Reason text and called operation description.

GetSignResponse¶

Signature	GetSignResponse(requestID: string, language: string): SignResponse
Description	Get the status and result of the related signature request.
Returns	A structure that contains the status and signature results.

Input parameters

Name	Type	Description
requestID	string	The ID of SignRequest posted earlier using PostSignRequest operation.
language	string	The language to be used for response localization. Allowed values: “ro”, “ru”, “en”. For backward compatibility, this parameter is optional and the default value is “ro”.

Faults

Code	Reason
AuthenticationFailed	Invalid authentication certificate provided, Unknown or unregistered system: {certificate serial number}
AuthorizationFailed	This signature request was not initiated by this system
InvalidParameter	Some input parameter is invalid. Please review the returned Fault Reason text and called operation description
RequestNotFound	Cannot find such request

VerifySignatures¶

Signature	VerifySignatures(request: VerificationRequest): VerificationResponse
Description	Request signature verification. Due to the fact that the process of verification might take more time than expected, it is advised to invoke this operation asynchronously so that the invoking application does not appear as blocked.
Returns	A structure that contains the result and signature verification.

Input parameters

Name	Type	Description
request	VerificationRequest	A structure representing the verification request.

Faults

Code	Reason
AuthenticationFailed	Invalid authentication certificate provided or Unknown service consumer: {certificate serial number}
InvalidParameter	Some input parameter is invalid. Please review the returned Fault Reason text and called operation description.
RequestNotFound	Cannot find such request

Structures¶

Important. The order in which the members are described below is for description purposes only. The order of the elements in the actual XML structures, as defined in WSDL, is alphabetical. To get a correct implementation, it is recommended to use an automatic conversion tool from WSDL to your programming language or environment.

Member	Type	Required/Optional	Description
SignRequest
ContentDescription	string (512)	Optional, default: same as ShortContentDescription	The description of the content to be signed. Displayed by MSing web pages.
ShortContentDescription	string (90)	Required	The short description of the content to be signed. Displayed by mobile phone if Mobile Signature is used.
SignatureReason	string (255)	Optional	The reason for signature, e.g. Resolution, Approved, Reviewed, etc. Currently applicable to PDF only.
ContentType	ContentType enumeration	Required	The type of the content to be signed.
Contents	Array of SignContent	Required, at least one element	The actual batch of contents to be signed.
ExpectedSigner	ExpectedSigner	Optional	If provided, MSign will verify the actual signer to match the provided information.
SignResponse
Status	SignStatus enumeration	Required	Signature request status
Message	string (100)	Optional, returned for requests that have Failure or Expired status	Signature request failure message, localized according to language parameter.
Results	Array of SignResult	Available when Status is not Pending	Signature results for the requested signature request.
VerificationRequest
SignedContentType	ContentType enumeration	Required	The type of the content that was previously signed.
Language	string (2)	Optional, default: ro	The language to be used for response localization. Allowed values: “ro”, “ru”, “en”
Contents	Array of VerificationContent	Required, at least one element	The actual batch of signatures to be verified.
VerificationResponse
Results	Array of VerificationResult	Required	Verification results for the verification request.
SignRequest
CorrelationID	string (36)	Optional	The correlation ID for this content. Must be unique within a signature request.
MultipleSignatures	Bool	Optional, default: false	Specifies if the content could have multiple signatures (i.e. it can be co-signed). Currently, this setting applies only to PDF.
Name	string (256)	Optional	Name of the PDF file, for Hash this property is redundant.
Content	Array of byte	Required	The actual content to be signed. Currently this can be 20-bytes SHA1 hash or a PDF file.
ExpectedSigner
ID	String	Required	Personal identifier number of the expected signer. Note that if not provided, user will be asked to enter it when signing PDF using mobile signature.
DelegatorType	DelegatorType enumeration	Optional, default: None	The type of the delegator.
DelegatorID	String	Required when DelegatorType is not None	The identifier of the person or organization that the expected signer can represent (is delegated by).
DelegatedRoleID	Int	Optional, default: 0	The role of the expected signer in relationship with the delegator.
SignResult
CorrelationID	string (36)	Returned as in SignContent	The correlation ID for the signed content, as originally given in SignContent.
Certificate	Array of byte	Optional, present if signature succeeded	Certificate of the signer in X509 v3 format.
Signature	Array of byte	Optional, present if signature succeeded	For hash content type this is the actual digital signature in XAdES-T format, for PDF content type - the signed PDF document.
VerificationContent
CorrelationID	string (36)	Optional	The correlation ID for this content. Must be unique within a verification request.
Content	Array of byte	Required only for Hash content.	The hash that was originally signed. Note that this parameter is required only for checking hash signatures. Its value is required for complete signature verification.
Signature	Array of byte	Required	The actual signature to be verified. This must be a XAdES or signed PDF.
VerificationResult
CorrelationID	string (36)	Returned as in VerificationContent	The correlation ID for the verification content, as originally given in VerificationContent.
SignaturesValid	Bool	Required	Returned as true if all signatures applied to the content are valid.
Message	string (100)	Required	Verification result message, localized according to VerificationRequest.Language.
Certificates	Array of VerificationCertificate	Optional, present if any certificates where identified in the signature	The list of certificates (one for signed hash in XAdES case) of the signers. Returned for display purposes.
VerificationCertificate
SignatureValid	Bool	Required	Returned as true if the signature corresponding to this certificate is valid.
Subject	string (250)	Required	Subject details from certificate. Returned as convenience for display purposes.
Certificate	Array of byte	Required	Certificate of the signer in X509 v3 format.
SignedAt	Datetime	Optional	Date and time of the signature. Returned only if a valid timestamp was applied.

Enumerations¶

Member	Description
ContentType
Hash	The content to be signed is a SHA1 hash.
Pdf	The content to be signed is a PDF file.
DelegatorType
None	There is no delegator.
Person	The delegator is a person.
Organization	The delegator is an organization.
SignStatus
Pending	The signing is pending.
Success	The signing is finished and the signature is valid.
Failure	The signing failed. The signature request is now invalid.
Expired	The signature request is expired. The signature request is now invalid.

Web forms integration¶

Signing request¶

Method	POST (recommended) or GET
URL	https://msign.gov.md/{requestID}
Description	Direct user to perform the actual signing. Notice that the requestID is embedded in the method URL

Form or URL parameters

Name	Type	Required/Optional	Description
ReturnUrl	string	Required	The URL that will receive the result of transaction signing
Instrument	string	Optional and not recommended	The signing instrument to be used, i.e. skipping signing instrument selection page. Allowed values: “mobile”, “moldsign”, “nationalid”, “securesign”, “tax”. Note that for “mobile” instrument to work without instrument selection, you have to provide MSISDN and ExpectedSigner.ID of the expected signer.
MSISDN	string containing digits	Optional	The mobile phone number of the expected signer, if known
RelayState	string	Optional	Optional string that will be returned back unmodified after signing
lang	string	Optional	Language to be used by MSign user interface. Allowed values: “ro”, “ru”, “en”

Signing callback¶

Method	POST
URL	The provided ReturnUrl in the signing request
Description	Redirects user to the information system that requested the signature, while informing the system about finished SignRequest processing. This Url is open only after the result of the signing is known (i.e. SignStatus is either Failure or Success).

Form parameters

Name	Type	Required/Optional	Description
RequestID	string	Required	The ID of the finished SignRequest
RelayState	string	Optional and not recommended	The unmodified value of RelayState, as sent in request

SOAP message samples¶

Manual implementation

We will present here samples of exchanged SOAP messages. This might be useful for those that integrate with MSign but do not fully support WSDL-based service proxy generation.

Method: PostSignRequest¶

request.xmlresponse.xml

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">https://msign.gov.md/IMSign/PostSignRequest</Action>
  </s:Header>
  <s:Body>
    <PostSignRequest xmlns="https://msign.gov.md">
      <request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <ContentDescription>Sample long description</ContentDescription>
        <ContentType>Hash</ContentType>
        <Contents>
          <SignContent>
            <Content>ZhKVycv51rL2QoQUUEqN7tMCBkE=</Content>
            <CorrelationID>3408cc344e474a529f3425176a75d08e</CorrelationID>
          </SignContent>
        </Contents>
        <ShortContentDescription>MSign Sample.</ShortContentDescription>
      </request>
    </PostSignRequest>
  </s:Body>
</s:Envelope>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <PostSignRequestResponse xmlns="https://msign.gov.md">
      <PostSignRequestResult>eec7709d372b41109e2ea3e200e99727</PostSignRequestResult>
    </PostSignRequestResponse>
  </s:Body>
</s:Envelope>

Method: GetSignResponse¶

request.xmlresponse.xml

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">https://msign.gov.md/IMSign/GetSignResponse</Action>
  </s:Header>
  <s:Body>
    <GetSignResponse xmlns="https://msign.gov.md">
      <requestID>eec7709d372b41109e2ea3e200e99727</requestID>
      <language>en</language> 
    </GetSignResponse> 
  </s:Body> 
</s:Envelope>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetSignResponseResponse xmlns="https://msign.gov.md">
      <GetSignResponseResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <Results>
          <SignResult>
            <Certificate>MIIG… </Certificate>
            <CorrelationID>3408cc344e474a529f3425176a75d08e</CorrelationID>
            <Signature>PD94… </Signature>
          </SignResult>
        </Results>
        <Status>Success</Status>
      </GetSignResponseResult>
    </GetSignResponseResponse>
  </s:Body>
</s:Envelope>

Method: VerifySignatures¶

request.xmlresponse.xml

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <Action s:mustUnderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">https://msign.gov.md/IMSign/VerifySignatures</Action>
  </s:Header>
  <s:Body>
    <VerifySignatures xmlns="https://msign.gov.md">
      <request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <Contents>
          <VerificationContent>
            <Content>ZhKVycv51rL2QoQUUEqN7tMCBkE=</Content>
            <CorrelationID>bd73ed7eabc44ab290b18181a9e7fd2b</CorrelationID>
            <Signature>PD94… </Signature>
          </VerificationContent>
        </Contents>
        <Language>en</Language>
        <SignedContentType>Hash</SignedContentType>
      </request>
    </VerifySignatures>
  </s:Body>
</s:Envelope>

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <VerifySignaturesResponse xmlns="https://msign.gov.md">
      <VerifySignaturesResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <Results>
          <VerificationResult>
            <Certificates>
              <VerificationCertificate>
                <Certificate>MIIG… </Certificate>
                <SignatureValid>true</SignatureValid>
                <Subject>O=Centrul de Guvernare Electronică (e-government) 1010600034203, OU=IT, C=MD, PostalCode=MD-2033, T=Functia, STREET=Piața Marii Adunări Naționale 1, Phone=022250234, S=Republica Moldova, L=Chișinău, SERIALNUMBER=IDNP, CN=Nume Prenume</Subject>
              </VerificationCertificate>
            </Certificates>
            <CorrelationID>bd73ed7eabc44ab290b18181a9e7fd2b</CorrelationID>
            <Message>The signature is valid</Message>
            <SignaturesValid>true</SignaturesValid>
          </VerificationResult>
        </Results>
      </VerifySignaturesResult>
    </VerifySignaturesResponse>
  </s:Body>
</s:Envelope>