|
XMLRPC API for DMT Digital Bearer Certificates Version 1.3.1, 2002-10-18 Corrected id typo, added errcode 514 description DMT Digital Bearer Certificates are representations of value, withdrawn from an ALTA/DMT anonymous account, protected by a user-selected password. Digital bearer certificates can be issued from any ALTA/DMT account, either via the ALTA web interface or by using a DMT Java Client. (See https://dmt.orlingrabbe.com.) The textual format is a base64 encoded ASN.1/DER structure, describing the encrypted certificate. The certificate is enclosed by the lines '-----BEGIN CERTIFICATE-----' and '-----END CERTIFICATE-----'. Here is an example: -----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbAPEtiSX0Vt+BOw8gqVejjccgVQoa63liHdg07pScA7hOk4kkhBnmeB2Kso
iW7ltLVKogz0lMWusept+yNiuPxwApASYytT+K6YGjOI4e8nEH7kaYRzo5dGjRls76Sg5iXF
e4cSnQ1IQssw1qp1yzW+9YkdTVBRmwMRt70nAZgwYJ2e6RZwiaONPNhbIxMqbt6zWjN+jTrz
ohDupEtTJBJ34adOHyjBPm5O6EQk+eHdzIOBgJXeEq8XV4T3p3sFEedEFG7XfSjBckvcZfWF
T2mAG3Rfl0e+Px4y6DpltcIIV9LEB1eXhq3H2RVCioxOK3pvAmNJgLO6AlC36C4YGxyBWZBh
dWOy2UfUnfO0MOchDsx27BYoSrukq/9Z52S6y2f3KnNjWc95Z2k9EpRK5b1o3DSa
-----END CERTIFICATE-----
These certificates can be used for storage of value outside the ALTA/DMT system or for payment to anyone who accepts such bearer certificates. The recipient of a DMT Digital Bearer Certificate can anonymously validate, reissue or deposit the certificate. To make it convenient to accept payments automatically, for instance via a web page, or via email, DMT offers a publically available XMLRPC interface (see http://www.xmlrpc.org). Anyone who wants to pay with a DMT Digital Bearer Certificate supplies the certificate and the password to the recipient. The recipient can then either reissue the certificate or deposit its value into any ALTA/DMT account. The payer does not need to know if the recipient even has such an account. The XMLRPC interface will accept external anonymous requests for the three basic operations. All such external requests have to be made over a SSL/TLS.1 encrypted connection. Information about the DMT SSL servers and their certificates is included at the end of this document. This version of the API now shows how to split a certificate into several new ones. Each new 'split' certificate is identified by a unique 'tag', i.e. a user-selected name that makes it possible to have separate certificate passwords for each new certificate. There is no practical limit to the number of certificates you can split an existing certificate into. The fee for the transaction will be deducted from the newly generated 'remainder certificate': original amount = remainder + fee + sum of additionally requested certificates. If no additional certificates are requested then the 'remainder certificate' contains the amount of the original certificate minus the transaction fee. To ensure that an issued certificate is not lost due to e.g. browser crashes, this version of the API allows the requestor to optionally retrieve a certificate at a later time. The mechanism is as follows:
The server will keep a certificate stored for a limited time, currently 60 minutes. All references to the certificate will be erased after this time-out. NOTE: All amounts and fees in the XMLRPC specification below are of type 'string', not of type 'double'. This is intentional. The amount and fee strings in the XMLRPC responses are pre-formatted as 'xx,xxx,xxx.xx', that is in groups of three digits (thousands) separated by comma characters (','). Developers who want to use the amount and fee values for arithmetic have to remove the comma characters when converting the string representation into some other representation. NOTE 2: The XMLRPC request needs to be prefixed in HTTP according to this template: POST /RPC2 HTTP/1.0 Host: 123.45.67.89 Content-Length: 123 Content-Type: text/xml <?xml version=\"1.0\"?> (The XML follows here, from the specification below) 1. Validate certificate The holder of a DMT Digital Bearer Certificate can at any moment validate the certificate. As long as noone else has access to the corresponding password, this validation process might be good enough. Someone who is receiving a certificate as a payment may want to validate the certificate as a first step before either reissuing the certificate (see below) or depositing it into an ALTA/DMT account. There are no fees for validating a DMT Digital Bearer Certificate. method: dbc.validate_cert
parameters:
struct {
string: cert // The certificate
string: certpass // The certificate password
}
returns:
struct {
string: asset
string: amount
}
Example:
<methodCall>
<methodName>dbc.validate_cert</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>cert</name>
<value> <string>-----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbAPEtiSX0Vt+BOw8gqVejjccgVQoa63liHdg07pScA7hOk4kkhBnmeB2Kso
iW7ltLVKogz0lMWusept+yNiuPxwApASYytT+K6YGjOI4e8nEH7kaYRzo5dGjRls76Sg5iXF
e4cSnQ1IQssw1qp1yzW+9YkdTVBRmwMRt70nAZgwYJ2e6RZwiaONPNhbIxMqbt6zWjN+jTrz
ohDupEtTJBJ34adOHyjBPm5O6EQk+eHdzIOBgJXeEq8XV4T3p3sFEedEFG7XfSjBckvcZfWF
T2mAG3Rfl0e+Px4y6DpltcIIV9LEB1eXhq3H2RVCioxOK3pvAmNJgLO6AlC36C4YGxyBWZBh
dWOy2UfUnfO0MOchDsx27BYoSrukq/9Z52S6y2f3KnNjWc95Z2k9EpRK5b1o3DSa
-----END CERTIFICATE-----</string> </value>
</member>
<member>
<name>certpass</name>
<value> <string>none</string> </value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>asset</name>
<value> <string>USD</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>100</string> </value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
2. Reissue certificate For anyone receiving a DMT Digital Bearer Certificate as a payment the validation function above is not enough, since the sender of the certificate still has a copy of not only the certificate but also of the corresponding password. The recipient of a certificate should therefore immediately reissue the certificate and then also change the corresponding password. Once a certificate is reissued, the original certificate becomes void and can not be used for further payments or deposits. By adding an optional array of additional certificate requests, an existing certificate can be split into any number of certificates. For such requests a corresponding array of generated certificates will be returned from the server, together with the remainder certificate. There is a fee for reissuing a DMT Digital Bearer Certificate. The transaction fee will be deducted from the reissued certificate. methodName: dbc.reissue_cert
parameters:
struct {
string: cert // The original certificate
string: certpass // The certificate password
string: newcertpass // The new certificate password
string: id // Optional transaction id
}
array { // Optional array, for splits
struct {
string: tag // A unique name for each cert
string: amount // The requested amount
string: certpass // The new certificate password
}
}
returns:
struct {
string: asset
string: amount
string: fee
string: cert // The new certificate
array additional { // Array returned only for requested splits
struct {
string: tag // Same tag as in the call
string: amount // The requested amount
string: cert // The new certificate
}
}
}
Example:
<methodCall>
<methodName>dbc.reissue_cert</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>cert</name>
<value> <string>-----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbAPEtiSX0Vt+BOw8gqVejjccgVQoa63liHdg07pScA7hOk4kkhBnmeB2Kso
iW7ltLVKogz0lMWusept+yNiuPxwApASYytT+K6YGjOI4e8nEH7kaYRzo5dGjRls76Sg5iXF
e4cSnQ1IQssw1qp1yzW+9YkdTVBRmwMRt70nAZgwYJ2e6RZwiaONPNhbIxMqbt6zWjN+jTrz
ohDupEtTJBJ34adOHyjBPm5O6EQk+eHdzIOBgJXeEq8XV4T3p3sFEedEFG7XfSjBckvcZfWF
T2mAG3Rfl0e+Px4y6DpltcIIV9LEB1eXhq3H2RVCioxOK3pvAmNJgLO6AlC36C4YGxyBWZBh
dWOy2UfUnfO0MOchDsx27BYoSrukq/9Z52S6y2f3KnNjWc95Z2k9EpRK5b1o3DSa
-----END CERTIFICATE----- </string> </value>
</member>
<member>
<name>certpass</name>
<value> <string>none</string> </value>
</member>
<member>
<name>newcertpass</name>
<value> <string>none</string> </value>
</member>
</struct>
</value>
</param>
<param>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>tag</name>
<value> <string>cert 1</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>10</string> </value>
</member>
<member>
<name>certpass</name>
<value> <string>10</string> </value>
</member>
</struct>
</value>
</data>
<data>
<value>
<struct>
<member>
<name>tag</name>
<value> <string>cert 2</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>20</string> </value>
</member>
<member>
<name>certpass</name>
<value> <string>20</string> </value>
</member>
</struct>
</value>
</data>
</array>
</value>
</param>
</params>
</methodCall>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>asset</name>
<value> <string>USD</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>99.90</string> </value>
</member>
<member>
<name>fee</name>
<value> <string>0.10</string> </value>
</member>
<member>
<name>cert</name>
<value> <string>-----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbAEJr3PA+I+Vcu4jaDIvSoBRC3SBcd1Y1DxH1WnRlJUTbFbjtjo4N3cTJ/C
ehmaDfnkTn262PcVlnhyKBaEHGH70bpxh+aGLidhMOKC1pQOilaIw7niKs27gvKH9Y5IP5Zc
nsA2yJg4uY1IqsWmBzJaI/PxfDKE6hZPdNyif1wAhKqr8T8g7N5kBFufLN5CQWzROorETRDC
CZRkViGB0zp5f8XlL7iuzVF9ahvlovK+I4OBgKtUYSYR8dvPLwFK6moRWUAiHA9qFLkZFQf4
Nd2eVC8KzpuTS4UH6IBloYEl/JgnlHwN672KmbfU88iE09pgDv26LT/7AV7KzpHo8jTZ9F8J
osCfffE8TeZge9mNI1q+HSyhaEbtaF9ZXtUKmNADKgrZwC2qkMgcoXLwrJJHHWnq
-----END CERTIFICATE-----</string> </value>
</member>
<member>
<name>additional</name>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>tag</name>
<value> <string>cert 1</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>10.00</string> </value>
</member>
<member>
<name>cert</name>
<value> <string>-----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbBKcn0oaVmd24/GKo04fM/eBMI7lAzEEfIVw4/UH332DfIA03ZGz+pYEKrB
zt3e42Ax8PDJ1wG2g076rGERE60MV2jOPfCbMeIfQCXatAoZQr/upVcjOY8cH6RAsrDMu+tv
+ewjxBYcmnE3rortb8XkAqVmkhYK1q2Htde+Q3+R/3ep9X7pBM5cXOXSQjvx7lddSD6Qw5V6
7OUYh3Gcd7kv/Hp38H/UqqQ+BrjonULwfIOBgFRVGrZDlN4hvCN43mgJG53NH8HQpA+/Gc8B
+iVRQbea2580O8ObpOgp9k18l2TyZnN0zdLH92Gq0c6r6o6IeC0eIeIaHqNuRZ/z22WDRxc0
Y3TNavI1pX5CnPy3/q0axlXU/4OC40LTC27I6ciQO8wrFxoZBQcFJ6zZAaI0P+Zg
-----END CERTIFICATE----- </string> </value>
</member>
</struct>
</value>
<value>
<struct>
<member>
<name>tag</name>
<value> <string>cert 2</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>20.00</string> </value>
</member>
<member>
<name>cert</name>
<value> <string>-----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbA8PjcMxQy+HRGpdaXAHUb0gb+njBlpyStKP6ruhNcBDGJxD3mPzVx/p/bh
yZoP7aCCg0V2uk07wPIcedL3OTl4zlZlglDtY0iFji5NC8rZzyyeuVMufLVikIREWaNPDVOa
+PyQZvp/0HCj09SqBf2SZ/Z/TBL4aqqrEtN+bwWUv5ZPJBJF4lUwHwq/H5V7uSOAgmfqqAe6
VsevexpKEJF0Dc533uqFzwpHLV093zkls4OBgOg20+1sFgYsQ0zAxVTXz4ot433dVUykKfpf
pUBjhT/rxU2Da4qmA8zH9KKVAwgIwimh9PpCP3HCH3usq6AkHoy9gzCk029BqaD7qGlriiAk
aHQ8RCTQQo6XLNfCPiMijGvn/38cr1EedfbbUS5isHgDPuUHt6wax09WK+3BJ5pq
-----END CERTIFICATE----- </string> </value>
</member>
</struct>
</value>
</data>
</array>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
3. Deposit certificate For anyone receiving a DMT Digital Bearer Certificate as a payment the validation function above is not enough, since the sender of the certificate still has a copy of not only the certificate but also of the corresponding password. The recipient of a certificate therefore has the option to either immediately reissue the certificate (as above) and then also change the corresponding password) or alternatively immediately deposit the value of the certificate into a ALTA/DMT account. The receiving ALTA/DMT account must be of the same asset type as the certificate itself, otherwise the deposit request will be denied. Once a certificate is deposited, the original certificate becomes void and can not be used for further payments or deposits. Payments to an ALTA/DMT account using DMT Digital Bearer Certificates are completely indistinguishable from any other type of payments. When the owner of the ALTA/DMT account (claim number) makes a claim of the payment, any (optional) message included will also be shown. There is a fee for depositing a DMT Digital Bearer Certificate. methodName dbc.deposit_cert
parameters:
struct {
string: cert // The certificate
string: certpass // The certificate password
string: asset
string: to // The claim number to pay to
string: message // An optional payment message,
// max 80 characters long
}
returns:
struct {
string: asset
string: amount
string: fee
}
Example:
<methodCall>
<methodName>dbc.deposit_cert</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>cert</name>
<value> <string>-----BEGIN CERTIFICATE-----
4IIBOoECMQCCgbAPEtiSX0Vt+BOw8gqVejjccgVQoa63liHdg07pScA7hOk4kkhBnmeB2Kso
iW7ltLVKogz0lMWusept+yNiuPxwApASYytT+K6YGjOI4e8nEH7kaYRzo5dGjRls76Sg5iXF
e4cSnQ1IQssw1qp1yzW+9YkdTVBRmwMRt70nAZgwYJ2e6RZwiaONPNhbIxMqbt6zWjN+jTrz
ohDupEtTJBJ34adOHyjBPm5O6EQk+eHdzIOBgJXeEq8XV4T3p3sFEedEFG7XfSjBckvcZfWF
T2mAG3Rfl0e+Px4y6DpltcIIV9LEB1eXhq3H2RVCioxOK3pvAmNJgLO6AlC36C4YGxyBWZBh
dWOy2UfUnfO0MOchDsx27BYoSrukq/9Z52S6y2f3KnNjWc95Z2k9EpRK5b1o3DSa
-----END CERTIFICATE----- </string> </value>
</member>
<member>
<name>certpass</name>
<value> <string>none</string> </value>
</member>
<member>
<name>asset</name>
<value> <string>USD</string> </value>
</member>
<member>
<name>to</name>
<value> <string>FEFCD5A2E4385C6CB38B086F8D084A566C3EE5B831</string> </value>
</member>
<member>
<name>message</name>
<value> <string>42</string> </value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>asset</name>
<value> <string>USD</string> </value>
</member>
<member>
<name>amount</name>
<value> <string>99.90</string> </value>
</member>
<member>
<name>fee</name>
<value> <string>0.10</string> </value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
4. Get a reissue transaction id. Due to network problems or software/hardware crashes there is a risk of not being able to complete all the steps in reissuing a certificate. To increase the level of trust in DMT Digital Bearer Certificates it is now possible to safe-guard such transactions. The method chosen is to attach a unique transaction id to each reissue processing. By referring to this transaction id it is possible to later retrieve a certificate in spite of (temporary) communication loss.
The server will keep a certificate accesible via the transaction id for a limited time, currently 60 minutes. All references to the certificate will be completely erased after this time-out. methodName: dbc.get_transid parameters: None returns: string: id // Transaction id Example: <methodCall> <methodName>dbc.get_transid</methodName> <params> <param> <value/> </param> </params> </methodCall> <methodResponse> <params> <param> <value> <string>123456</string> </value> </param> </params> </methodResponse> 5. Retrieve a previously reissued certificate. methodName: dbc.retrieve_cert
parameters:
struct {
string: id // Transaction id
}
returns: (same as dbc.retrieve_cert)
struct {
string: asset
string: amount
string: fee
string: cert // The new certificate
array additional { // Array returned only for requested splits
struct {
string: tag // Same tag as in the call
string: amount // The requested amount
string: cert // The new certificate
}
}
}
Example:
<methodCall>
<methodName>dbc.retrieve_cert</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>id</name>
<value> <string>123456</string> </value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
The data returned will be exactly the same as the data returned from the corresponding previous call to dbc.reissue_cert. Appendix A, XMLRPC errors Connections to the DMT XMLRPC servers can result in error messages, either due to badly formed requests or because the DMT Digital Bearer Certificate is not valid. The following two XMLRPC errors are specified: 591 Void. Certificate has already been reissued or deposited.
Example:
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value>
<i4>591</i4>
</value>
</member>
<member>
<name>faultString</name>
<value>
<string>Void</string>
</value>
</member>
</struct>
</value>
</fault>
</methodResponse>
592 Not valid. Not a DMT Digital Bearer Certificate.
This error will also be returned if the supplied certificate password is not correct.
Example:
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value>
<i4>592</i4>
</value>
</member>
<member>
<name>faultString</name>
<value>
<string>Not valid</string>
</value>
</member>
</struct>
</value>
</fault>
</methodResponse>
The following XMLRPC errors are specified:
faultCode: 514
faultString: Not enough funds
Explanation: The fee is greater than the certificate value.
faultCode: 533
faultString: Illegal document
Explanation: The XMLRPC request was not well-formed.
faultCode: 551
faultString: Deposit cert error: missing to
Explanation: The destination account claim number is missing or invalid.
faultCode: 560
faultString: Retrieve cert error: missing or illegal id
Explanation: The transaction reference number is not recognized.
faultCode: 568
faultString: Message is too long
Explanation: The optional deposit message is limited to 80 characters.
faultCode: 575
faultString: No stored certificate available
Explanation: The transaction id is invalid or expired.
faultCode: 591
faultString: Void
Explanation: Certificate has already been reissued or deposited.
faultCode: 592
faultString: Not valid
Explanation: The certificate is not valid or the supplied
password is incorrect.
faultCode: 593
faultString: Try Again
Explanation: Your request could not be processed at this time.
Please try again.
faultCode: 594
faultString: ILLEGAL REQUEST
Explanation: The deposit claim number is not valid.
faultCode: 599
faultString: Timeout
Explanation: Your request could not be processed at this time.
Please try again.
Appendix B, SSL/TLS1 servers and certificates The DMT server network is accessible via gateway sites. The actual gateway sites used can (and will) change over time. For the time being DMT is offering XMLRPC connections over SSL/TLS1 to the following gateway site: 196.40.46.24 port 444. The X509 certificates used for SSL/TLS1 connections by the XMLRPC servers are issued by the DMT CA. A connection can be validated by the client based on a certificate chain originating from the following DMT CA root certificate: -----BEGIN CERTIFICATE-----
MIIC9zCCAd+gAwIBAgIBADANBgkqhkiG9w0BAQUFADA/MQswCQYDVQQGEwJMRjEf
MB0GA1UEChMWRGlnaXRhbCBNb25ldGFyeSBUcnVzdDEPMA0GA1UEAxMGRE1UIENB
MB4XDTAxMTIwMzEzNTczN1oXDTExMTIwMTEzNTczN1owPzELMAkGA1UEBhMCTEYx
HzAdBgNVBAoTFkRpZ2l0YWwgTW9uZXRhcnkgVHJ1c3QxDzANBgNVBAMTBkRNVCBD
QTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJi64yN9T/KGwDgjXg6a
Ocqk5Mac7ai51Hlx82T3A8JyXIUCfB6FFuc2vEDJhZUgu0TW4DJNFOxaNsHKjpKV
pXhaLLemfylJPPGeCRkMLOt2Tg3bQc49rBGLsqspdLnx3iLMgZglOtRCUiNAqMPq
SyYLL4taa+jTkX7tlgbYQDBeUTXLteAvFul7CYEuXoUSLBoVR4w+w9Bk5dGTd2N8
9XDCgZPAiAmKn7NwFCs4Bs9+OXmEeJDhHdaMQuETli2FygkUFkSLMw79sO6ouX+7
jbKPLH1QXfkJQJoUJkGUn6wtVpNJZL1G22LU/Ygri+UOSh0yy1OHJFPWWo6r7bSO
AScCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEAVdsl+51YFqunBoj/QKgaEanEWSki
GzW8meSMewel6M6ni+EKHydheZH98zrlL6qkhxlFZmV4IefIrCXzMwDcbePYpz4M
gV+5imQL70NBqba+AMOZwO5PRHoO7obLHfZv/FGouWPGJv880zIQRrtwDC5MQ9cN
tONaJfgWA1uibD59vxp4z+qIZMqg5rIPLrBhz+PZpL4tJmIRfvrsIy0jGKFcpgOP
DscLULkE9/lZ0pbKMxDmFcL3FRX04i5xTL2WZJzLgZ/IUJInvtVjkfDEmgjijCg/
5kYiVjSNmRd+lJRBTu7AJHOfdNvqxrc/lEczxk9l32QrE4aT8I3HgXWZaw==
-----END CERTIFICATE-----
Further Reading |
