Rp SDK is an App2App SDK for Samsung Wallet driver's license service online scenarios.
This SDK provides an implementation for direct communication between the Samsung Wallet and Partner applications.
The specific rules are already bundled into the AAR which can be interpreted by R8 automatically
App2App SDK supports one method.
The API specifications that need to be implemented by the RP partner are described below:
Send the Wallet application key info and return the data field types requested to the client for authentication of the mDL
The data is encrypted according to the requested data and then transmitted along with the data card information.
-
JWT (JWS + JWE) decryption between the Wallet Backed Server and partner server
1. Verify by generating a JWS using the body data
// Generate JWS by the body data
private static SignedJWT parseJWT(final String data) {
try {
return SignedJWT.parse(data);
} catch (ParseException e) {
log.error("parserJWT error class : {}, error message : {}", e.getClass(), e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "parserJWT error");
}
}
// Verify JWS using Samsung Public key
public RequestBody getRequestBody(final KeyRing keyRing) {
final SignedJWT signedJWT = JWTUtils.verify(keyRing.getTargetPublicKey(), encryptedData, 60 * 10000); // Verify and generate JWS
try {
final String strBody = JWTUtils.getDecryptedPayloadFrom(keyRing.getSourcePrivateKey(), JWEObject.parse(signedJWT.getPayload().toString())); // Decryption JWE by the JWS
return objectMapper.readValue(strBody, RequestBody.class); // Convert to data format requested by client
} catch (ParseException | JsonProcessingException e) {
log.error("getRequestBody : {}", e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "data body parse error");
}
}
2. Decrypt the JWE using the JWS
JWEObject.parse(signedJWT.getPayload().toString())
public static String getDecryptedPayloadFrom(final Key privateKey, final JWEObject data) {
try {
data.decrypt(new RSADecrypter((PrivateKey) privateKey)); // Decryption JWE using Partner Private Key
return data.getPayload().toString();
} catch (JOSEException e) {
log.error("JOSEException message : {}", e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "getDecryptedPayloadFrom error");
}
}
3. Convert to the format send by the client
public RequestBody getRequestBody(final KeyRing keyRing) {
final SignedJWT signedJWT = JWTUtils.verify(keyRing.getTargetPublicKey(), encryptedData, 60 * 10000); // Verify and generate JWS
try {
final String strBody = JWTUtils.getDecryptedPayloadFrom(keyRing.getSourcePrivateKey(), JWEObject.parse(signedJWT.getPayload().toString())); // Decryption JWE by the JWS
return objectMapper.readValue(strBody, RequestBody.class); // Convert to data format requested by client
} catch (ParseException | JsonProcessingException e) {
log.error("getRequestBody : {}", e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "data body parse error");
}
}
-
Generate MdocEstablishment
1. Generate RSA Key per refId
public class TransactionContext {
private final KeyPair keyPair; // RSA Key
private final byte[] clientEngagement; // Body data received through key API, base64URL decoded value
@EqualsAndHashCode.Exclude
private int encryptMessageCounter = 0; // Count value when encrypted
@EqualsAndHashCode.Exclude
private int decryptMessageCounter = 0; // Count value when decrypted
}
private Cache<String, TransactionContext> contextCache; // RSA key management per refid with memory cache
// Generate and store RSA Key per refId only once upon first request
public TransactionContext setTransactionContext(final String key, final String base64EncodedClientEngagement) {
log.info("base64EncodedClientPublicKey : {}", base64EncodedClientEngagement);
this.contextCache.put(key, new TransactionContext(KeyUtils.generateKeyPair() , Base64Utils.decode(base64EncodedClientEngagement.getBytes())));
return this.getTransactionContextBy(key);
}
// Part of retrieving RAS Key based on refId
public TransactionContext getTransactionContextBy(final String key) {
return Optional.ofNullable(this.contextCache.getIfPresent(key)).orElseThrow(() -> {
log.info("{} is empty", key);
return new CustomException(HttpStatus.BAD_REQUEST, "No key matching the refId");
});
}
2. Create request field values
@Override
public Mono<List<String>> createRequest(final PartnerInputDTO inputDTO) {
final String mockData = "{ \"docType\": \"org.iso.18013.5.1.mDL\", \"nameSpaces\": { \"org.iso.18013.5.1\": { \"sex\": false, \"portrait\": false, \"given_name\": false, \"issue_date\": false, \"expiry_date\": false, \"family_name\": false, \"document_number\": false, \"issuing_authority\": false }, \"org.iso.18013.5.1.aamva\": { \"DHS_compliance\": false, \"EDL_credential\": false } } }";
return Mono.just(Collections.singletonList(mockData));
}
3. Generate Establishment
@AllArgsConstructor
public class Establishment {
private final TransactionContext context; // Info of client public key , partner private key, public key
private final List<String> strReqs; // Data field information required for authentication to the client
private final KeyRing keyRing; // RSA Key information for JWT(JWS + JWE) encryption and decryption between Wallet Backed Server and partner server.
}
protected CBORObject generate() {
final CBORObject sessionEstablishment = CBORObject.NewMap();
sessionEstablishment.set(E_READER_KEY, CBORObject.FromObjectAndTag(KeyUtils.getEReaderKey(context), TAG_SIZE)); // Generate oneKey by public key in transactionContext
sessionEstablishment.set(DATA, CBORObject.FromObject(CipherUtils.encrypt(context, generateRequestFormat(getRequestCBORObjectsFrom(strReqs))))); // Add request data field information for authentication.
return sessionEstablishment;
}
```
-
Generate the response value JWT (JWS + JWE)
1. Generate establishment with JWE
public static String encryptedStringJWE(final Key publicKey, final String data) { // Please enter Samsung Public Key and establishment data
final JWEObject jwe = new JWEObject(
new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM).build(), new Payload(data));
try {
jwe.encrypt(new RSAEncrypter((RSAPublicKey) publicKey));
return jwe.serialize();
} catch (JOSEException e) {
log.error("encryptedStringJWE Exception message : {}", e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "encryptedStringJWE error");
}
}
2. Generate JWS by JWE
public static String generateSignedStringJWS(final Key privateKey, final Key publicKey, final String payload) { // Enter your partner’s public key, private key, and JWE data.
try {
final JWSObject jwsObj = new JWSObject(getDefaultJWSHeader(), new Payload(payload));
JWSSigner signer = new RSASSASigner(new RSAKey.Builder((RSAPublicKey) publicKey).privateKey((RSAPrivateKey) privateKey).build());
jwsObj.sign(signer);
return jwsObj.serialize();
} catch (JOSEException e) {
log.error("encryptedStringJWS Exception message : {}", e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "generateSignedStringJWS error");
}
}
3. Generate JWT(JWS + JWE)
public PartnerOutputDTO toPartnerOutputDTO() {
final CBORObject generate = this.generate();
final String establishment = Base64.getUrlEncoder().encodeToString(generate.EncodeToBytes());
final String strJWE = JWTUtils.encryptedStringJWE(keyRing.getTargetPublicKey(), establishment);
final JWSHeader jwsHeader = JWTUtils.getDefaultJWSHeader(keyRing.getVersion(), keyRing.getCertificateId(), "partnerId");
return new PartnerOutputDTO(JWTUtils.generateSignedStringJWS(jwsHeader, keyRing.getSourcePrivateKey(), keyRing.getSourcePublicKey(),strJWE));
}
-
Authentication processing for values in data fields requested for authentication
1. Retrieve transactionContext value stored in cache using refId value
@Override
public Mono<TransactionContext> getContext(final PartnerInputDTO inputDTO) {
return Mono.just(this.transactionContextManager.getTransactionContextBy(inputDTO.getRefId()));
}
2. Processes the decryption process of the request body data like JWT (JWS + JWE) decryption between Wallet Backed Server and partner server.
3. Generate MdocResponse
public class MdocResponse {
private final TransactionContext context; // Managed tranactionContext by refId
private final byte[] data; // Base64URL decoded data after decrypting JWT (JWS + JWE) data.
public MdocResponse(final TransactionContext context, final String inputDTO) {
this.context = context;
this.data = Base64Utils.decode(inputDTO.getBytes(StandardCharsets.UTF_8));
}
}
4. Get the field values requested for authentication from the data in mDocResponse.
public String getData() {
// SessionData = {
// ? "data" : bstr ; Encrypted mdoc response or mdoc request
// ? "status" : uint ; Status code
// }
final CBORObject response = CBORObject.DecodeFromBytes(data);
checkType(response, CBORType.Map);
final CBORObject data = response.get(DATA);
checkType(data, CBORType.ByteString);
return CBORObject.DecodeFromBytes(isEncryptedMode ? CipherUtils.decrypt(this.context, data.GetByteString()) : data.GetByteString()).ToJSONString();
}
5. Create a Session value using the transactionContext value managed by refId and then decrypt it.
private static byte[] processCipher(final CipherMode cipherMode, final TransactionContext context, final byte[] bytes) { // CipherMode : encrypt or decrypt, bytes : Data passed by the client
try {
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
final int counter = CipherMode.ENCRYPT == cipherMode ? context.getEncryptMessageCounter() : context.getDecryptMessageCounter();
GCMParameterSpec parameterSpec = new GCMParameterSpec(128, getSessionKeyIv(cipherMode.identifier, counter));
cipher.init(cipherMode.cipherMode , getSecretKeySpec(context, cipherMode.info), parameterSpec);
return cipher.doFinal(bytes);
} catch (InvalidAlgorithmParameterException | NoSuchPaddingException | IllegalBlockSizeException |
NoSuchAlgorithmException | BadPaddingException | InvalidKeyException e) {
log.error("error type : {}, message :{}", e.getClass(), e.getMessage());
throw new CustomException(HttpStatus.INTERNAL_SERVER_ERROR, "processCipher error");
}
}
6. Examining data received from the client.
@Override
public Mono<Void> authentication(final String response) {
log.info("response info : {}", response);
return Mono.empty();
}