Creating CSR (#749)

Author: kober32

docs/PowerAuth-SDK-for-Android.md

@@ -35,6 +35,7 @@
 - [Common SDK Tasks](#common-sdk-tasks)
 - [Additional Features](#additional-features)
   - [Obtaining User's Claims](#obtaining-users-claims)
+  - [Creating Certificate Signing Request](#creating-certificate-signing-request)
   - [Password Strength Indicator](#password-strength-indicator)
   - [Debug Build Detection](#debug-build-detection)
   - [Request Interceptors](#request-interceptors)
@@ -2990,6 +2991,46 @@ If the `address` is provided, then `UserAddress` contains the following properti
 Be aware that all properties in the `UserInfo` and `UserAddress` objects are optional and the availability of information depends on actual implementation on the server.
 <!-- end -->
 
+### Creating Certificate Signing Request
+
+The PowerAuth SDK can create a Certificate Signing Request (CSR) that can be used to request an X.509 certificate from a Public Key Infrastructure (PKI). 
+The CSR contains a public key generated by the SDK and is signed with the activation-bound private key.
+
+The created CSR in the PEM format (including `-----BEGIN CERTIFICATE REQUEST-----` and `-----END CERTIFICATE REQUEST-----` lines and newlines `\n`).
+
+To create a CSR, use the following code:
+
+```kotlin
+// Assume this is your PowerAuthSDK instance
+// The instance must have a valid and active activation
+val powerAuth: PowerAuthSDK!!
+
+val authentication = PowerAuthAuthentication.possessionWithPassword("1111") // assume this is your password
+
+powerAuth.createSignedCSR(
+    appContext, // Android context
+    authentication, // authentication object
+    mapOf( // subject's distinguished names (DN)
+        Pair("CN", "wultra.com"),
+        Pair("O", "Wultra"),
+        Pair("C", "CZ")
+    ),
+    arrayOf( // subject's alternative names (SAN)
+        "IP: 192.168.1.10",
+        "email: admin@example.com"
+    ),
+    object : ICreateCSRListener {
+        override fun onCSRCreateSucceed(csr: String) {
+            Log.d("CSR", "CSR: ${csr}")
+            // Use the CSR
+        }
+
+        override fun onCSRCreateFailed(error: PowerAuthErrorException) {
+            // Handle error
+        }
+    }
+)
+```
 
 ### Password Strength Indicator
 

docs/PowerAuth-SDK-for-iOS.md

@@ -49,6 +49,7 @@
 - [Common SDK Tasks](#common-sdk-tasks)
 - [Additional Features](#additional-features)
   - [Obtaining User's Claims](#obtaining-users-claims)
+  - [Creating Certificate Signing Request](#creating-certificate-signing-request)
   - [Password Strength Indicator](#password-strength-indicator)
   - [Debug Build Detection](#debug-build-detection)
   - [Request Interceptors](#request-interceptors)  
@@ -2240,6 +2241,45 @@ If the `address` is provided, then `PowerAuthUserAddress` contains the following
 Be aware that all properties in the `PowerAuthUserInfo` and `PowerAuthUserAddress` objects are optional and the availability of information depends on actual implementation on the server.
 <!-- end -->
 
+### Creating Certificate Signing Request
+
+The PowerAuth SDK can create a Certificate Signing Request (CSR) that can be used to request an X.509 certificate from a Public Key Infrastructure (PKI). 
+The CSR contains a public key generated by the SDK and is signed with the activation-bound private key.
+
+The created CSR in the PEM format (including `-----BEGIN CERTIFICATE REQUEST-----` and `-----END CERTIFICATE REQUEST-----` lines and newlines `\n`).
+
+To create a CSR, use the following code:
+
+```swift
+// Assume this is your PowerAuthSDK instance
+// The instance must have a valid and active activation
+let powerAuth: PowerAuthSDK!
+
+let password = PowerAuthCorePassword(string: "1234") // assume this is your password
+let authentication = PowerAuthAuthentication.possessionWithPassword(password: password)
+
+powerAuth.createSignedCSR(
+    with: authentication, // authentication object
+    distinguishedNames: [ // subject's distinguished names (DN)
+        "CN": "wultra.com",
+        "O": "Wultra",
+        "C": "CZ"
+    ],
+    subjectAltNames: [ // subject's alternative names (SAN)
+        "IP: 192.168.1.10",
+        "email: admin@example.com"
+    ]
+) { csr, error in
+
+    if let csr {
+        print("CSR: \(csr)")
+        // Use the CSR
+    } else {
+        // Handle error
+    }
+}
+```
+
 ### Password Strength Indicator
 
 Choosing a weak passphrase in applications with high-security demands can be potentially dangerous. You can use our [Wultra Passphrase Meter](https://github.com/wultra/passphrase-meter) library to estimate the strength of the passphrase and warn the user when he tries to use such a passphrase in your application.

include/PowerAuth/Session.h

@@ -441,6 +441,23 @@ namespace powerAuth
         ErrorCode decryptVaultKey(const std::string & c_vault_key, const SignatureUnlockKeys & keys,
                                   cc7::ByteArray & out_key);
 
+    public:
+        
+        // MARK: - Certificate Signing Request -
+        
+        /**
+         Creates X.509 CSR (Certificate Signing Request) with given Distinguished Names and optional Subject Alternative Names, embedded device public key and signed with the device private key.
+         
+         You have to provide at keys.userPassword and keys.possessionUnlockKey.
+
+        
+        Returns EC_Ok          if operation succeeded
+                EC_Encryption  if general encryption error occurs
+                EC_WrongState  if the session has no valid activation
+                EC_WrongParam  if some required parameter is missing
+         */
+        ErrorCode createPrivateKeySignedCSR(const std::string & c_vault_key, const SignatureUnlockKeys & keys, const std::map<std::string, std::string>& dn_items, const std::vector<std::string>& san_items, std::string &out_csr);
+        
     public:
 
         // MARK: - External encryption key -

proj-android/PowerAuthLibrary/gradle.properties

@@ -1,3 +1,3 @@
-VERSION_NAME=1.9.5
+VERSION_NAME=1.9.6-SNAPSHOT
 GROUP_ID=com.wultra.android.powerauth
 ARTIFACT_ID=powerauth-sdk

proj-android/PowerAuthLibrary/src/main/java/io/getlime/security/powerauth/core/Session.java

@@ -483,6 +483,46 @@ public byte[] prepareKeyValueDictionaryForDataSigning(Map<String, String> keyVal
      */
     public native byte[] signDataWithDevicePrivateKey(String cVaultKey, SignatureUnlockKeys unlockKeys, byte[] data, @SignatureFormat int signatureFormat);
 
+    /**
+     * Creates X.509 CSR (Certificate Signing Request) with given Distinguished Names and optional Subject Alternative Names, embedded device public key and signed with the device private key.
+     * <p>
+     *  You have to provide encrypted vault key |cVaultKey| in Base64 format and |unlockKeys| object where the valid userPassword is set.
+     *
+     * <h2>Discussion</h2>
+     *
+     * The session's state contains device private key but it is encrypted with a vault key, which is normally not
+     * available on the device. Just like other vault related operations, you have to properly sign HTTP request
+     * with using PA2SignatureFactor_PrepareForVaultUnlock flag, otherwise the operation will fail.
+     *
+     * @param cVaultKey encrypted vault key
+     * @param unlockKeys unlock keys object with required possession factor
+     * @param distinguishedNames Distinguished Names (DN) to be embedded in the CSR.
+     * @param subjectAltNames Subject Alternative Names (SAN)
+     *
+     * @return Returns CSR in PEM format or null in case of failure.
+     */
+    public String createPrivateKeySignedCSR(
+            @NonNull String cVaultKey,
+            @NonNull SignatureUnlockKeys unlockKeys,
+            @NonNull Map<String, String> distinguishedNames,
+            @Nullable String[] subjectAltNames) {
+
+        ArrayList<String> dnKeys = new ArrayList<>();
+        ArrayList<String> dnValues = new ArrayList<>();
+        for (Map.Entry<String, String> entry : distinguishedNames.entrySet()) {
+            dnKeys.add(entry.getKey());
+            dnValues.add(entry.getValue());
+        }
+        return createPrivateKeySignedCSR(cVaultKey, unlockKeys, dnKeys.toArray(new String[0]), dnValues.toArray(new String[0]), subjectAltNames);
+    }
+
+    private native String createPrivateKeySignedCSR(
+            @NonNull String cVaultKey,
+            @NonNull SignatureUnlockKeys unlockKeys,
+            @Nullable String[] dnKeys,
+            @Nullable String[] dnValues,
+            @Nullable String[] subjectAltNames);
+
     //
     // External encryption key
     //

proj-android/PowerAuthLibrary/src/main/java/io/getlime/security/powerauth/networking/response/ICreateCSRListener.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 Wultra s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.getlime.security.powerauth.networking.response;
+
+import androidx.annotation.MainThread;
+import androidx.annotation.NonNull;
+
+import io.getlime.security.powerauth.exception.PowerAuthErrorException;
+
+/**
+ * Listener for Creating PowerAuth signed CSR.
+ */
+public interface ICreateCSRListener {
+
+    /**
+     * When CSR is successfully created, this method is called with CSR string in PEM format.
+     */
+    @MainThread
+    void onCSRCreateSucceed(@NonNull String csr);
+
+    /**
+     * Called when CSR creation fails.
+     *
+     * @param error Error that occurred during the CSR creation.
+     */
+    @MainThread
+    void onCSRCreateFailed(@NonNull PowerAuthErrorException error);
+}

proj-android/PowerAuthLibrary/src/main/java/io/getlime/security/powerauth/sdk/PowerAuthSDK.java

@@ -2348,6 +2348,63 @@ public void onDataSignedFailed(@NonNull Throwable t) {
         });
     }
 
+    /**
+     * Creates X.509 CSR (Certificate Signing Request) with given Distinguished Names and optional Subject Alternative Names, embedded device public key and signed with the device private key.
+     * <p>
+     * This method calls PowerAuth Standard RESTful API endpoint '/pa/vault/unlock' to obtain the vault encryption key used for private recovery data decryption.
+     *
+     * @param context Android context.
+     * @param authentication Authentication object that must contain the possession and password factor.
+     * @param distinguishedNames Distinguished Names (DN) to be embedded in the CSR. The dictionary keys are DN types (like "CN", "O", etc.) and values are corresponding DN values.
+     * @param subjectAltNames Optional array of Subject Alternative Names (SAN)
+     * @param listener Listener with the callback methods. CSR in PEM format with lines separated by `\n` (including `-----BEGIN CERTIFICATE REQUEST`----- and `-----END CERTIFICATE REQUEST-----` lines) is returned in case of success.
+     * @return {@link ICancelable} object associated with the underlying HTTP request.
+     */
+    @Nullable
+    public ICancelable createSignedCSR(
+            @NonNull Context context,
+            @NonNull PowerAuthAuthentication authentication,
+            @NonNull Map<String, String> distinguishedNames,
+            @Nullable String[] subjectAltNames,
+            @NonNull ICreateCSRListener listener) {
+        // Fetch vault unlock key
+        final CompositeCancelableTask compositeCancelableTask = new CompositeCancelableTask(true);
+
+        final ICancelable httpRequest = fetchEncryptedVaultUnlockKey(context, authentication, VaultUnlockReason.SIGN_WITH_DEVICE_PRIVATE_KEY, new IFetchEncryptedVaultUnlockKeyListener() {
+
+            @Override
+            public void onFetchEncryptedVaultUnlockKeySucceed(final String encryptedEncryptionKey) {
+                if (encryptedEncryptionKey != null) {
+                    SignatureUnlockKeys keys = new SignatureUnlockKeys(deviceRelatedKey(context), null, authentication.getPassword());
+                    String csr = mSession.createPrivateKeySignedCSR(encryptedEncryptionKey, keys, distinguishedNames, subjectAltNames);
+                    if (compositeCancelableTask.setCompleted()) {
+                        if (csr != null) {
+                            listener.onCSRCreateSucceed(csr);
+                        } else {
+                            listener.onCSRCreateFailed(new PowerAuthErrorException(PowerAuthErrorCodes.SIGNATURE_ERROR));
+                        }
+                    }
+                } else {
+                    if (compositeCancelableTask.setCompleted()) {
+                        listener.onCSRCreateFailed(new PowerAuthErrorException(PowerAuthErrorCodes.SIGNATURE_ERROR));
+                    }
+                }
+            }
+
+            @Override
+            public void onFetchEncryptedVaultUnlockKeyFailed(Throwable t) {
+                if (compositeCancelableTask.setCompleted()) {
+                    listener.onCSRCreateFailed(PowerAuthErrorException.wrapException(PowerAuthErrorCodes.NETWORK_ERROR, t));
+                }
+            }
+        });
+        if (httpRequest != null) {
+            compositeCancelableTask.addCancelable(httpRequest);
+            return compositeCancelableTask;
+        }
+        return null;
+    }
+
     // E2EE
 
     /**

proj-xcode/PowerAuth2/PowerAuthSDK.h

@@ -550,6 +550,21 @@
                                                              claims:(nonnull NSDictionary<NSString*, NSObject*>*)claims
                                                            callback:(nonnull void(^)(NSString * _Nullable jwt, NSError * _Nullable error))callback;
 
+/** Creates X.509 CSR (Certificate Signing Request) with given Distinguished Names and optional Subject Alternative Names, embedded device public key and signed with the device private key.
+ 
+ This method calls PowerAuth Standard RESTful API endpoint '/pa/vault/unlock' to obtain the vault encryption key used for private recovery data decryption.
+ 
+ @param authentication Authentication used for vault unlocking call.
+ @param distinguishedNames Distinguished Names (DN) to be embedded in the CSR. The dictionary keys are DN types (like "CN", "O", etc.) and values are corresponding DN values.
+ @param subjectAltNames Optional array of Subject Alternative Names (SAN)
+ @param callback The callback method with the CSR in PEM format with lines separated by `\n` (including `-----BEGIN CERTIFICATE REQUEST`----- and `-----END CERTIFICATE REQUEST-----` lines).
+ @return PowerAuthOperationTask associated with the running request.
+ */
+- (nullable id<PowerAuthOperationTask>) createSignedCSRWithAuthentication:(nonnull PowerAuthAuthentication*)authentication
+                                                       distinguishedNames:(nonnull NSDictionary<NSString*, NSString*>*)distinguishedNames
+                                                          subjectAltNames:(nullable NSArray<NSString*>*)subjectAltNames
+                                                                 callback:(nonnull void(^)(NSString * _Nullable csr, NSError * _Nullable error))callback;
+
 @end
 
 

proj-xcode/PowerAuth2/PowerAuthSDK.m

@@ -1523,6 +1523,35 @@ - (NSData*) generateInvalidBiometricKey
     }];
 }
 
+- (nullable id<PowerAuthOperationTask>) createSignedCSRWithAuthentication:(PowerAuthAuthentication*)authentication
+                                                       distinguishedNames:(NSDictionary<NSString*, NSString*>*)distinguishedNames
+                                                          subjectAltNames:(NSArray<NSString*>*)subjectAltNames
+                                                                 callback:(void(^)(NSString * csr, NSError * error))callback
+{
+    if (!distinguishedNames) {
+        callback(nil, PA2MakeError(PowerAuthErrorCode_WrongParameter, @"Distinguished names are missing"));
+        return nil;
+    }
+    return [self fetchEncryptedVaultUnlockKey:authentication reason:PA2VaultUnlockReason_SIGN_WITH_DEVICE_PRIVATE_KEY callback:^(NSString *encryptedEncryptionKey, NSError *error) {
+        NSString *csr = nil;
+        if (!error) {
+            // Let's create the CSR
+            PowerAuthCoreSignatureUnlockKeys *keys = [[PowerAuthCoreSignatureUnlockKeys alloc] init];
+            keys.possessionUnlockKey = [self deviceRelatedKey];
+            keys.userPassword = authentication.password;
+            csr = [_sessionInterface readTaskWithSession:^id (PowerAuthCoreSession * session) {
+                return [session createPrivateKeySignedCSR:encryptedEncryptionKey keys:keys distinguishedNames:distinguishedNames subjectAltNames:subjectAltNames];
+            }];
+            // Propagate error
+            if (!csr) {
+                error = PA2MakeError(PowerAuthErrorCode_SignatureError, @"Failed to create CSR");
+            }
+        }
+        // Call back to application
+        callback(csr, error);
+    }];
+}
+
 @end
 
 #pragma mark - End-2-End Encryption

proj-xcode/PowerAuthCore.xcodeproj/project.pbxproj

@@ -171,6 +171,8 @@
 		BFFE1D57264D688F00D5B985 /* pa2CryptoECDSATests.cpp in Sources */ = {isa = PBXBuildFile; fileRef = BFFE1D51264D688F00D5B985 /* pa2CryptoECDSATests.cpp */; };
 		BFFE1D58264D688F00D5B985 /* pa2CryptoECCTests.cpp in Sources */ = {isa = PBXBuildFile; fileRef = BFFE1D55264D688F00D5B985 /* pa2CryptoECCTests.cpp */; };
 		BFFE1D59264D688F00D5B985 /* pa2CryptoECCTests.cpp in Sources */ = {isa = PBXBuildFile; fileRef = BFFE1D55264D688F00D5B985 /* pa2CryptoECCTests.cpp */; };
+		DCE5FEC92E687C8A00ED8C32 /* CSR.cpp in Sources */ = {isa = PBXBuildFile; fileRef = DCE5FEC82E687C8A00ED8C32 /* CSR.cpp */; };
+		DCE5FECA2E687C8A00ED8C32 /* CSR.cpp in Sources */ = {isa = PBXBuildFile; fileRef = DCE5FEC82E687C8A00ED8C32 /* CSR.cpp */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXContainerItemProxy section */
@@ -492,6 +494,8 @@
 		BFEEEBEA2A3B067B007C6737 /* pa2ByteUtilsTests.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = pa2ByteUtilsTests.cpp; sourceTree = "<group>"; };
 		BFFE1D51264D688F00D5B985 /* pa2CryptoECDSATests.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = pa2CryptoECDSATests.cpp; sourceTree = "<group>"; };
 		BFFE1D55264D688F00D5B985 /* pa2CryptoECCTests.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = pa2CryptoECCTests.cpp; sourceTree = "<group>"; };
+		DCE5FEB82E68626900ED8C32 /* CSR.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = CSR.h; sourceTree = "<group>"; };
+		DCE5FEC82E687C8A00ED8C32 /* CSR.cpp */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = CSR.cpp; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -762,6 +766,8 @@
 				BF99D8D52073E00D00735ED2 /* KDF.cpp */,
 				BF99D8DE2073E00D00735ED2 /* MAC.h */,
 				BF99D8DB2073E00D00735ED2 /* MAC.cpp */,
+				DCE5FEB82E68626900ED8C32 /* CSR.h */,
+				DCE5FEC82E687C8A00ED8C32 /* CSR.cpp */,
 			);
 			path = crypto;
 			sourceTree = "<group>";
@@ -1286,6 +1292,7 @@
 				BF99D90F2073E15100735ED2 /* KDF.cpp in Sources */,
 				BF99D9022073E14100735ED2 /* Debug.cpp in Sources */,
 				BFEEEBE12A3ADEA8007C6737 /* ByteUtils.cpp in Sources */,
+				DCE5FEC92E687C8A00ED8C32 /* CSR.cpp in Sources */,
 				BFB47D1620753324008A6A52 /* DataReader.cpp in Sources */,
 				BF99D9092073E14700735ED2 /* ProtocolUtils.cpp in Sources */,
 			);
@@ -1349,6 +1356,7 @@
 				BF6ADD7C24C84C0C001B3E5E /* KDF.cpp in Sources */,
 				BF6ADD7D24C84C0C001B3E5E /* Debug.cpp in Sources */,
 				BFEEEBE22A3ADEA8007C6737 /* ByteUtils.cpp in Sources */,
+				DCE5FECA2E687C8A00ED8C32 /* CSR.cpp in Sources */,
 				BF6ADD7E24C84C0C001B3E5E /* DataReader.cpp in Sources */,
 				BF6ADD7F24C84C0C001B3E5E /* ProtocolUtils.cpp in Sources */,
 			);