Digital signature (new)
You can refer this document to sign New API requests. However,If you are integrated with Global APIs, see Digital Sigature for details.
Digital signatures can ensure the reliability and anti-repudiation of the API data transmitted. Each qualified API caller, also called client, is assigned a clientId by Alipay. The API access is authenticated against the clientId by the RSA signature.
Client and Alipay must exchange RSA keys before making API calls, and the length of RSA key must be 2048 bits. When making API call to Alipay, client uses the RSA private key to sign the API request. After receiving the API request, Alipay will use the client’s RSA public key to verify whether the signature is matched to the content of API request. Similarly, when client receives the API response, it is highly recommended that client verifies the signature of API response by using Alipay’s RSA public key. The following figure illustrates the interaction flow:
Signing the request
The following figure illustrates a sample API request. The content enclosed by the two curly braces (inclusive) is what needs to be signed to create the RSA signature. And the generated signature is put in the signature parameter.
Perform the following steps to sign the message:
1、Extract the content to be signed. For example:
{
"head":{
"version":"2.0.0",
"function":"alipay.intl.acquiring.agreement.payCancel",
"clientId":"211xxxxxxxxxxxxxxx044",
"reqTime":"2001-07-04T12:08:56+05:30",
"reqMsgId":"1234567asdfasdf1123fda",
"reserve":"{}"
},
"body":{
"merchantId":"218xxxxxxxxxxxxxxx023",
"acquirementId":"2015xxxxxxxxxxxxxxxxxxxxx747"
}
}2、Hash the JSON content by using the SHA256withRSA algorithm. Then use the client's RSA private key to sign the value to obtain the signature. To achieve a better security level, the length of the RSA key/pairs must be 2048 bits. The following sample illustrates a raw signature:
sXSGdA4tR4B0wnF6Nr8ShpfNMtHISWuzLpdKoNWskIgCcspMVFFzgkez4BrmtYXkMqZh1tyz/8sNNU3F2VTu0fOx+ZP4CnmVjNu8bciu4hTtnytA3Y1GZ/yXAUD+mVYGXeyDO3fHrqDdI7k3xV/Q8FCOd0culTsN6RRMxMZq+oqR2x+EjOXVofp7BZJwhQE8Us4Al573FQz5EHDvCLx35lq2hoMhXLCVLVDBHcpCgotuY4mg91MXh/qqcFGY/hQKhGdWAbZ9tcp2Q5s2ESh37rqxnOwZrrepK8NC6vMBPUiSPxQefpev2nG0JzAHOjRPbBXYw1XBS6RBYKAmufZZiQ==3、Base64-encode the signature. A sample result is listed below:
c1hTR2RBNHRSNEIwd25GNk5yOFNocGZOTXRISVNXdXpMcGRLb05Xc2tJZ0Njc3BNVkZGemdrZXo0QnJtdFlYa01xWmgxdHl6LzhzTk5VM0YyVlR1MGZPeCtaUDRDbm1Wak51OGJjaXU0aFR0bnl0QTNZMUdaL3lYQVVEK21WWUdYZXlETzNmSHJxRGRJN2szeFYvUThGQ09kMGN1bFRzTjZSUk14TVpxK29xUjJ4K0VqT1hWb2ZwN0JaSndoUUU4VXM0QWw1NzNGUXo1RUhEdkNMeDM1bHEyaG9NaFhMQ1ZMVkRCSGNwQ2dvdHVZNG1nOTFNWGgvcXFjRkdZL2hRS2hHZFdBYlo5dGNwMlE1czJFU2gzN3JxeG5Pd1pycmVwSzhOQzZ2TUJQVWlTUHhRZWZwZXYybkcwSnpBSE9qUlBiQlhZdzFYQlM2UkJZS0FtdWZaWmlRPT0=4、Use the obtained string as the value of the Signature parameter. The following sample shows a whole API request:
{
"request":{
"head":{
"version":"2.0.0",
"function":"alipay.intl.acquiring.agreement.payCancel",
"clientId":"211xxxxxxxxxxxxxxx044",
"reqTime":"2001-07-04T12:08:56+05:30",
"reqMsgId":"1234567asdfasdf1123fda",
"reserve":"{}"
},
"body":{
"merchantId":"218xxxxxxxxxxxxxxx023",
"acquirementId":"2015xxxxxxxxxxxxxxxxxxxxx747"
}
},
"signature":"c1hTR2RBNHRSNEIwd25GNk5yOFNocGZOTXRISVNXdXpMcGRLb05Xc2tJZ0Njc3BNVkZGemdrZXo0QnJtdFlYa01xWmgxdHl6LzhzTk5VM0YyVlR1MGZPeCtaUDRDbm1Wak51OGJjaXU0aFR0bnl0QTNZMUdaL3lYQVVEK21WWUdYZXlETzNmSHJxRGRJN2szeFYvUThGQ09kMGN1bFRzTjZSUk14TVpxK29xUjJ4K0VqT1hWb2ZwN0JaSndoUUU4VXM0QWw1NzNGUXo1RUhEdkNMeDM1bHEyaG9NaFhMQ1ZMVkRCSGNwQ2dvdHVZNG1nOTFNWGgvcXFjRkdZL2hRS2hHZFdBYlo5dGNwMlE1czJFU2gzN3JxeG5Pd1pycmVwSzhOQzZ2TUJQVWlTUHhRZWZwZXYybkcwSnpBSE9qUlBiQlhZdzFYQlM2UkJZS0FtdWZaWmlRPT0="
}Verifying the signature
A sample response is shown as below:
After receiving a response, perform the following steps to verify the signature:
Split the full response contents to 2 parts, the response JSON string and the signature string, by using the regular expression instead of JSON object.
Hash the response JSON string by using the SHA256 algorithm to obtain a message digest.
Use the public key to decrypt the signature to a message digest.
Compare the two message digests obtained in step 2 and step 3. If the digests are the same, then it indicates that the signed data has not been changed.
Sample codes
The following exampls assume that you use the Java language.
Signature generation
private String doSign(String content, String privateKey, String charset)
throws SignatureException {
try {
PrivateKey priKey = KeyReader.getPrivateKeyFromPKCS8("RSA", new ByteArrayInputStream(
privateKey.getBytes()));
java.security.Signature signature = java.security.Signature
.getInstance("SHA256withRSA");
signature.initSign(priKey);
signature.update(getContentBytes(content, charset));
byte[] signed = signature.sign();
return new String(Base64.encodeBase64(signed));
} catch (Exception e) {
throw new SignatureException("Failed to create RSA signature! [content = " + content + "; charset = " + charset
+ "]", e);
}
}Signature Verification
private boolean doCheck(String content, String sign, String publicKey, String charset)
throws SignatureException {
try {
PublicKey pubKey = KeyReader.getPublicKeyFromX509("RSA", new ByteArrayInputStream(
publicKey.getBytes()));
java.security.Signature signature = java.security.Signature
.getInstance("SHA256withRSA");
signature.initVerify(pubKey);
signature.update(getContentBytes(content, charset));
return signature.verify(Base64.decodeBase64(sign.getBytes()));
} catch (Exception e) {
throw new SignatureException("Failed to verify RSA signature! [content = " + content + "; charset = " + charset
+ "; signature = " + sign + "]", e);
}
}RSA key pair
An RSA key pair contains the private key and the public key. The private key is required for generating the signature, while the public key is used for verifying the signature.
Generating an RSA key pair
Many tools can be used to generate the RSA key pair. The following steps assume that you use OpenSSL to generate the RSA key pair.
1、Install OpenSSL.
For linux system, use the following command:
copysudo apt-get install openssl
For windows system, download and then install OpenSSL from the official site.
2、 Generate RSA key pair.
For linux system, use the following command:
copy$ openssl OpenSSL> genrsa -out rsa_private_key.pem 2048 ##generate private key OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM - nocrypt ##transform private key into PKCS8 format OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem ##Generate public key OpenSSL> exit
For windows system, use the following command:
copyC:\Users\Hammer>cd C:\OpenSSL-Win32\bin ##enter OpenSSL directory C:\OpenSSL-Win32\bin>openssl.exe ##enter OpenSSL OpenSSL> genrsa -out rsa_private_key.pem 2048 ##Generate private key OpenSSL> pkcs8 -topk8 -inform PEM -in rsa_private_key.pem -outform PEM -nocrypt ##Transform private key into PKCS8 format OpenSSL> rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem ##Generate public key OpenSSL> exit
After that, you can see two files under current folder, rsaprivatekey.pem and rsapublickey.pem. The former is the private key and the latter is the public key.
Uploading RSA public key
After the RSA2 key pair is generated, you must exchange the public key with the Alipay server for signature verification by completing the following steps:
Upload your public key to Alipay
Obatin Alipay public key