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 |
Last updated