ePassport Certificate API Methods

Distribution of CV Certificates

The following messages are used for the management of CV certificates at a national level.

Request Certificate

This message is used by a DV or by a terminal for requesting the generation of a new certificate for one of its keys from the national CVCA or the DV, respectively.

Input parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
callbackIndicator *	String	With this parameter the originator of the message informs the receiver if it can handle callbacks as response to this message.
messageID [C]	String	This parameter contains the identification of the message. It MUST identify the message uniquely within all messages of the originator. If a response message will be send to the originator as a result of this message, the response message SHALL contain the same messageID.
responseURL [C]	String	This parameter contains the URL, at which the originator expects the response message to be sent, if the message will be processed asynchronously.
certReq*	String	This parameter contains the certificate request.

certReq: It is necessary to use the Certificate Request Structure and follow the encoding specifications for Machine Readable Travel Documents.

Output parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
certificateSeq [C]	String	This parameter contains one or more certificates, if the message has been processed successfully. It is REQUIRED if certificates have to be sent with the response. It MUST be missing if no certificates will be sent with the message.

Return Codes

Return codes	Description
ok_cert_available	The message has been processed successfully. The parameter certificateSeq contains one or more certificates.
ok_syntax	The reception of the message is acknowledged. The syntax of the message has been verified successfully. The further processing of the message will be done asynchronously.
ok_reception_ack	The reception of the message is acknowledged. No further verification of the message has been done yet. The processing of the message will be done asynchronously.
failure_inner_signature	The verification of the inner signature of the actual certificate request failed
failure_outer_signature	The verification of the outer signature of the actual certificate request failed.
failure_expired	The certificate used to verify the outer signature is expired.
failure_domain_parameters	The domain parameters contained in the request do not match the domain parameters of the corresponding CVCA certificate.
failure_request_not_accepted	The message has been processed correctly but the request has not been accepted. In this case further procedures must be determined by organizational measures.
failure_syntax	The received message is syntactically not correct.
failure_synchronous_processing_not_possible	The sender has indicated that he does not accept callback messages, hence the message must be processed synchronously by the receiver. But the receiver cannot process this message synchronously. In this case further procedures must be determined by organizational measures.
failure_internal_error	Any other error.

RequestForeignCertificate

This message is used by a DV to initiate the request for a new certificate for one of its keys from a CVCA in another country. This message is not sent to the foreign CVCA which is intended to generate the certificate, instead, it is sent to the national SPOC of the country of the DV. This national SPOC verifies the request of the DV according to national regulations. If the request meets the national regulations it is forwarded to the SPOC of the other country.

Input parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
callbackIndicator *	String	With this parameter the originator of the message informs the receiver if it can handle callbacks as response to this message.
messageID [C]	String	This parameter contains the identification of the message. It MUST identify the message uniquely within all messages of the originator. If a response message will be send to the originator as a result of this message, the response message SHALL contain the same messageID.
responseURL [C]	String	This parameter contains the URL, at which the originator expects the response message to be sent, if the message will be processed asynchronously.
foreignCAR*	String	This parameter contains the reference to the (expected) signature key of the foreign certification authority which also should be contained in the body of the certificate request contained in the parameter certReq.
certReq*	String	This parameter contains the certificate request.

certReq: It MUST be constructed according to the Certificate Request Structure. The coding must follow the specifications in Encoding of Values. (Reference: Machine Readable Travel Documents)

Output parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
certificateSeq [C]	String	This parameter contains one or more certificates, if the message has been processed successfully. It is REQUIRED if certificates have to be sent with the response. It MUST be missing if no certificates will be sent with the message.

Return Codes

Return codes	Description
ok_cert_available	The message has been processed successfully. The parameter certificateSeq contains one or more certificates.
ok_request_forwarded	The message has been processed successfully and synchronously by the SPOC. It has been forwarded to the intended foreign SPOC. The foreign SPOC has acknowledged the reception of the message.
ok_syntax	The reception of the message is acknowledged. The syntax of the message has been verified successfully. The further processing of the message will be done asynchronously.
ok_reception_ack	The reception of the message is acknowledged. No further verification of the message has been done yet. The processing of the message will be done asynchronously.
failure_inner_signature	The verification of the inner signature of the actual certificate request failed
failure_outer_signature	The verification of the outer signature of the actual certificate request failed.
failure_expired	The certificate used to verify the outer signature is expired.
failure_domain_parameters	The domain parameters contained in the request do not match the domain parameters of the corresponding CVCA certificate.
failure_request_not_accepted	The message has been processed correctly but the request has not been accepted. In this case further procedures must be determined by organizational measures.
failure_syntax	The received message is syntactically not correct.
failure_synchronous_processing_not_possible	The sender has indicated that he does not accept callback messages, hence the message must be processed synchronously by the receiver. But the receiver cannot process this message synchronously. In this case further procedures must be determined by organizational measures.
failure_internal_error	Any other error.

GetCACertificates

This message is sent by a DV or by a terminal to a CVCA or to a DV, respectively, in order to get all relevant CA certificates of the national CVCA or foreign CVCAs. In this sense, a CA certificate is regarded as relevant if it is still valid and if it is needed for the verification of a (valid) certificate of the DV (generated by the CVCA).

Input parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
callbackIndicator *	String	With this parameter the originator of the message informs the receiver if it can handle callbacks as response to this message.
messageID [C]	String	This parameter contains the identification of the message. It MUST identify the message uniquely within all messages of the originator. If a response message will be send to the originator as a result of this message, the response message SHALL contain the same messageID.
responseURL [C]	String	This parameter contains the URL, at which the originator expects the response message to be sent, if the message will be processed asynchronously.

Output parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
certificateSeq [C]	String	This parameter contains one or more certificates, if the message has been processed successfully. It is REQUIRED if certificates have to be sent with the response. It MUST be missing if no certificates will be sent with the message.

Return Codes

Return codes	Description
ok_cert_available	The message has been processed successfully. The parameter certificateSeq contains one or more certificates.
ok_syntax	The reception of the message is acknowledged. The syntax of the message has been verified successfully. The further processing of the message will be done asynchronously.
ok_reception_ack	The reception of the message is acknowledged. No further verification of the message has been done yet. The processing of the message will be done asynchronously.
failure_syntax	The received message is syntactically not correct.
failure_synchronous_processing_not_possible	The sender has indicated that he does not accept callback messages, hence the message must be processed synchronously by the receiver. But the receiver cannot process this message synchronously. In this case further procedures must be determined by organizational measures.
failure_internal_error	Any other error.

Remarks:

If the message is processed successfully and accepted the CVCA MUST send all relevant CA certificates (see above) within the response, either in the output parameter certificateSeq(synchronous processing) or in the corresponding response message SendCertificates(asynchronous processing).

Send Certificate

• If a certification authority or a SPOC processes one of the messages RequestCertificate, RequestForeignCertificate or GetCACertificates asynchronously, it uses a response message SendCertificates to communicate the result of its processing. It sends the response message always to that URL which is contained in the parameter responseURL of the received message.

• This message can also be used to notify registered entities about the availability of new certificates. In this case the messageID must be omitted.

• This message itself must always be processed synchronously by its receiver.

Input parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
messageID [C]	String	This parameter contains the identification of the message. It MUST identify the message uniquely within all messages of the originator. If a response message will be send to the originator as a result of this message, the response message SHALL contain the same messageID.
statusInfo [C]	String	This parameter contains the URL, at which the originator expects the response message to be sent, if the message will be processed asynchronously.

Output parameters

None.

Return Codes

Return codes	Description
ok_received_correctly	The message has been received and processed synchronously. No output is generated.
failure_syntax	The received message is syntactically not correct.
failure_messageID_unknown	The contained messageID cannot be matched with a message formerly sent.
failure_internal_error	Any other error.

Distribution of Document Signer Lists

The following messages are used for the distribution of Document Signer Lists.

GetDocumentSignerList

• This message is sent by a terminal to its DV in order to get one or more signed lists of document signers.

• Input, Output and Return Codes parameters for message GetDocumentSignerList

Input parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type	Description
messageID [C]	String	This parameter contains the identification of the message. It MUST identify the message uniquely within all messages of the originator. If a response message will be send to the originator as a result of this message, the response message SHALL contain the same messageID.
callbackIndicator *	String	With this parameter the originator of the message informs the receiver if it can handle callbacks as response to this message. If the originator can handle callbacks, this parameter MUST be set to callback_possible. In this case, the receiver can decide if it processes this message synchronously or asynchronously. If the receiver processes this message asynchronously, it will send the response using the appropriate callback message. If the originator cannot handle callbacks, this parameter MUST be set to callback_not_possible.
responseURL [C]	String	This parameter contains the URL, at which the originator expects the response message to be sent, if the message will be processed asynchronously. This parameter is REQUIRED if the originator of the message indicates that it can handle a callback as response to this message (i.e., parameter callbackIndicator = callback_possible). It MUST be missing, if the originator of the message indicates, that it cannot handle callbacks as response to this message (i.e., parameter callbackIndicator = callback_not_possible).

Output parameters

* - Mandatory parameter, C - Conditional

Parameter	Data Type
documentSignerList [C]	String

Return Codes

Return codes	Description
ok_list_available	The request has been processed successfully. The input or output parameter contains the requested list.
ok_syntax	The reception of the message is acknowledged. The syntax of the message has been verified successfully. The further processing of the message will be done asynchronously. The result of the processing will be sent to the URL contained in the parameter responseURL using the corresponding response message.
ok_reception_ack	The reception of the message is acknowledged. No further verification of the message has been done yet. The processing of the message will be done asynchronously. The result of the processing will be sent to the URL contained in the parameter responseURL using the corresponding response message.
failure_list_not_available	The corresponding message has been processed correctly but the requested list is not available.
failure_syntax	The received message is syntactically not correct.
failure_synchronous_processing_not_possible	The sender has indicated that he does not accept callback messages, hence the message must be processed synchronously by the receiver. But the receiver cannot process this message synchronously. In this case further procedures must be determined by organizational measures.
failure_internal_error	Any other error