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