[GR-69858] Make Native Image security provider inclusion metadata-driven

compiler/src/jdk.graal.compiler.processor/src/jdk/graal/compiler/options/processor/OptionProcessor.java

@@ -325,7 +325,7 @@ static void createOptionsDescriptorsFile(ProcessingEnvironment processingEnv, Op
                 out.printf("                /*fieldName*/ \"%s\",\n", fieldName);
                 out.printf("                /*stability*/ %s.%s,\n", getSimpleName(OPTION_STABILITY_CLASS_NAME), stability);
                 out.printf("                /*deprecated*/ %b,\n", deprecated);
-                out.printf("                /*deprecationMessage*/ \"%s\");\n", deprecationMessage);
+                out.printf("                /*deprecationMessage*/ %s);\n", literal(deprecationMessage));
                 out.println("        }");
             }
             out.println("        // CheckStyle: resume line length check");

docs/reference-manual/native-image/BuildOptions.md

@@ -51,7 +51,7 @@ These deprecated URL protocol options are omitted from the generated table; see
 | `--exact-reachability-metadata` | String | enables exact and user-friendly handling of reflection, resources, JNI, and serialization. |  | `--exact-reachability-metadata=exact-reachability-metadata` |
 | `--exact-reachability-metadata-path` | String | trigger exact handling of reflection, resources, JNI, and serialization from all types in the given class-path or module-path entries. | None | `--exact-reachability-metadata-path=exact-reachability-metadata-path` |
 | `--features` | String | a comma-separated list of fully qualified Feature implementation classes | None | `--features=features` |
-| `--future-defaults` | String | enable options that are planned to become defaults in future releases. Comma-separated list can contain 'all', 'none', 'run-time-initialize-jdk', 'class-for-name-respects-class-loader', 'run-time-initialize-file-system-providers', 'run-time-initialize-security-providers', 'run-time-initialize-resource-bundles', 'explicit-feature-singleton-registration'. The preferred usage is '--future-defaults=all'. | <default-value> | `--future-defaults=future-defaults` |
+| `--future-defaults` | String | enable options that are planned to become defaults in future releases. Comma-separated list can contain 'all', 'none', 'run-time-initialize-jdk', 'class-for-name-respects-class-loader', 'run-time-initialize-file-system-providers', 'run-time-initialize-security-providers', 'run-time-initialize-resource-bundles', 'explicit-feature-singleton-registration', 'explicit-security-provider-registration', 'exact-reflection'. The preferred usage is '--future-defaults=all'. | <default-value> | `--future-defaults=future-defaults` |
 | `--initialize-at-build-time` | String | a comma-separated list of packages and classes (and implicitly all of their superclasses) that are initialized during image generation. An empty string designates all packages. |  | `--initialize-at-build-time=initialize-at-build-time` |
 | `--initialize-at-run-time` | String | a comma-separated list of packages and classes (and implicitly all of their subclasses) that must be initialized at runtime and not during image building. An empty string is currently not supported. |  | `--initialize-at-run-time=initialize-at-run-time` |
 | `--libc` | String | selects the libc implementation to use. Available implementations: glibc, musl, bionic | None | `--libc=libc` |

docs/reference-manual/native-image/JCASecurityServices.md

@@ -18,18 +18,40 @@ By default the `native-image` builder uses static analysis to discover which of
 The automatic registration of security services can be disabled with `-H:-EnableSecurityServicesFeature`.
 Then a custom reflection configuration file or feature can be used to register the security services required by a specific application.
 Note that when automatic registration of security providers is disabled, all providers are, by default, filtered from special JDK caches that are necessary for security functionality.
-In this case, you must manually mark used providers with `-H:AdditionalSecurityProviders`.
+In this case, register the provider class and its nullary constructor for reflection in _reachability-metadata.json_, for example:
+
+```json
+{
+  "reflection": [
+    {
+      "type": "com.example.security.CustomProvider",
+      "methods": [
+        {
+          "name": "<init>",
+          "parameterTypes": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+Alternatively, collect the metadata by running your application on the JVM with the [Tracing Agent](AutomaticMetadataCollection.md).
 
 ## Security Services Automatic Registration
 
-The mechanism, implemented in the `com.oracle.svm.hosted.SecurityServicesFeature` class, uses reachability of specific API methods in the JCA framework to determine which security services are used.
+The mechanism, implemented in the `com.oracle.svm.hosted.jca.SecurityServicesFeature` class, uses reachability of specific API methods in the JCA framework to determine which security services are used.
 
 Each JCA provider registers concrete implementation classes for the algorithms it supports.
 Each of the service classes (`Signature`, `Cipher`, `Mac`, `KeyPair`, `KeyGenerator`, `KeyFactory`, `KeyStore`, etc.) declares a series of `getInstance(<algorithm>, <provider>` factory methods which provide a concrete service implementation.
 When a specific algorithm is requested, the framework searches the registered providers for the corresponding implementation classes and dynamically allocates objects for concrete service implementations.
 The `native-image` builder uses static analysis to discover which of these services are used.
 It does so by registering reachability handlers for each of the `getInstance()` factory methods.
 When it determines that a `getInstance()` method is reachable at run time, it automatically performs the reflection registration for all the concrete implementations of the corresponding service type.
+Provider classes discovered as reachable subtypes of `java.security.Provider` are treated only as candidates for provider inclusion.
+The builder includes such a provider and all of its services only when the provider class is registered for reflection, either by type access, its declared nullary constructor, or its static `provider()` method.
+To apply this reflection requirement to providers selected by reachable service factories, use `--future-defaults=explicit-security-provider-registration`.
+With this future default, a factory does not make an unregistered provider or its services available.
 
 Tracing of the security services automatic registration can be enabled with `-H:+TraceSecurityServices`.
 The report will detail all registered service classes, the API methods that triggered registration, and the parsing context for each reachable API method.
@@ -40,7 +62,8 @@ The report will detail all registered service classes, the API methods that trig
 
 Currently, security providers are initialized at build time.
 To move their initialization to run time, use the option `--future-defaults=run-time-initialize-security-providers`, `--future-defaults=all`, or `--future-defaults=run-time-initialize-jdk`.
-Provider verification will still occur at build time.
+Providers listed in the build-time `java.security` configuration are still verified at build time.
+Providers included only through reflection metadata are treated as explicitly configured, since run-time codebase verification is not available in Native Image.
 Run-time initialization of security providers helps reduce image heap size.
 
 ## Provider Registration
@@ -65,17 +88,26 @@ The same approach to manipulating providers can then be used.
 
 ## SecureRandom
 
-The `SecureRandom` implementations open the `/dev/random` and `/dev/urandom` files which are used as sources.
-These files are usually opened in class initializers.
-To avoid capturing state from the machine that runs the `native-image` builder, these classes need to be initialized at run time.
+Native Image initializes `NativePRNG`, its seed generators, and related entropy-holding classes at
+run time.
+This prevents `/dev/random`, `/dev/urandom`, and machine-specific seed state from being captured
+on the image builder.
+Class-initialization safety is separate from provider registration: a reachable `SecureRandom`
+acquisition also triggers registration of the complete configured-provider set that declares
+`SecureRandom` services.
 
 ## Custom Service Types
 
-By default, only services specified in the JCA framework are automatically registered. To automatically register custom service types, you can use the `-H:AdditionalSecurityServiceTypes` option.
-Note that for automatic registration to work, the service interface must have a `getInstance` method and have the same name as the service type.
-If relying on the third-party code that does not comply to the above requirements, a manual configuration will be required. In that case, providers for such services must explicitly be registered using the `-H:AdditionalSecurityProviders` option. Note that these options are only required in very specific cases and should not normally be needed.
+By default, Native Image automatically detects only service types specified in the JCA framework.
+The `-H:AdditionalSecurityServiceTypes` option is deprecated.
+Register the provider class and its supported construction path in _reachability-metadata.json_ so
+Native Image retains its complete service catalog, including custom service types.
+Alternatively, collect this metadata with the Tracing Agent.
+For compatibility with automatic service-driven registration, the service interface must have a
+`getInstance` method and the same name as the service type.
+If you rely on third-party code that does not comply with these requirements, manual configuration is required.
 
 ### Further Reading
 
 * [URL Protocols in Native Image](URLProtocols.md)
-* [Jipher JCE with Native Image](../../security/JipherJCE.md)
+* [Jipher JCE with Native Image](../../security/JipherJCE.md)

docs/reference-manual/native-image/guides/troubleshoot-run-time-errors.md

@@ -62,13 +62,7 @@ Other handy options are `-H:+AddAllCharsets` to add charsets support, and `-H:+I
 Pass those options at build time.
 This might increase the size of the resulting binary.
 
-### 4. Add Missing Security Providers
-
-If your application is using Security Providers, try to pre-initialize security providers by passing the option `-H:AdditionalSecurityProviders=<list-of-providers>` at build time. 
-Here is a list of all JDK security providers to choose from:
-`sun.security.provider.Sun,sun.security.rsa.SunRsaSign,sun.security.ec.SunEC,sun.security.ssl.SunJSSE,com.sun.crypto.provider.SunJCE,sun.security.jgss.SunProvider,com.sun.security.sasl.Provider,org.jcp.xml.dsig.internal.dom.XMLDSigRI,sun.security.smartcardio.SunPCSC,sun.security.provider.certpath.ldap.JdkLDAP,com.sun.security.sasl.gsskerb.JdkSASL`.
-
-### 5. File a Native Image Run-Time Issue
+### 4. File a Native Image Run-Time Issue
 
 Only if you tried all the above suggestions, file a [Native Image Run-Time Issue Report](https://github.com/oracle/graal/issues/new?assignees=&labels=native-image%2Cbug%2Crun-time&projects=&template=1_1_native_image_run_time_bug_report.yml&title=%5BNative+Image%5D+) at GitHub, filling out the necessary information. 
 

substratevm/CHANGELOG.md

@@ -9,6 +9,7 @@ This changelog summarizes major changes to GraalVM Native Image.
 * (GR-77670) Chunk up digest generation for Native Image Layers, to allow for large layer files to be checked. This makes older layer files potentially incompabile with layers created after this change.
 * (GR-73199) When native executables are built with `-H:-LegacyJavaOptionMode`, VM options are parsed only before the first `--` argument. Arguments after `--` are passed unchanged to the application main method. The legacy behavior remains unchanged.
 * (GR-77977) Added control flow integrity options, available via `-H:CFI`. Indirect branches on AMD64 can be guarded with software-based checks that ensure that they land on valid targets. On AArch64, PAC is supported to protect return addresses on the stack.
+* (GR-69858) Deprecated `-H:AdditionalSecurityProviders` and `-H:AdditionalSecurityServiceTypes`. Register each security provider class for reflection in `reachability-metadata.json` using `{"reflection":[{"type":"<fully-qualified-provider-class-name>"}]}` instead. The Tracing Agent generates this metadata automatically. When provider initialization occurs at run time, Native Image preserves a reachable `META-INF/services/java.security.Provider` descriptor even if its provider is not registered; iterating that entry reports the standard service-loading or missing-reflection error.
 
 ## GraalVM 25.2 (Internal Version 25.2.4)
 * (GR-77358) Introduced compressed (32-bit) references, enabled by default. This generally improves memory usage and performance, but limits heap memory to 32 GB. Disable with `-H:-UseCompressedReferences`.

substratevm/docs/README.md

@@ -43,3 +43,8 @@ Consulting the CI configurations in ci/ci.jsonnet may help understand how `mx ga
 ## Project Terminus
 
 - [Project Terminus](project-terminus.md): overview and design direction for self-hosting Native Image.
+
+## Security Providers
+
+- [JCA Security Provider Inclusion](functional-spec/security-providers.md): required provider inclusion and run-time behavior.
+- [Security Provider Architecture](architecture/security-providers.md): provider inclusion, verification, and metadata tracing.

substratevm/docs/architecture/README.md

@@ -0,0 +1,6 @@
+# Architecture
+
+This directory contains developer-facing architecture records for Native Image.
+
+- [Security Provider Architecture](security-providers.md): provider inclusion, verification, and
+  metadata tracing ([§AR-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java)).

substratevm/docs/architecture/security-providers.md

@@ -0,0 +1 @@
+# AR-security-providers: [SecurityServicesFeature](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java)

substratevm/docs/functional-spec/README.md

@@ -0,0 +1,6 @@
+# Functional Specifications
+
+This directory contains functional specifications for Native Image.
+
+- [JCA Security Provider Inclusion](security-providers.md): provider lookup and factory-call behavior based on metadata.
+- [Functional Decisions](decisions/): product behavior decisions and tradeoffs for the specifications.

substratevm/docs/functional-spec/decisions/README.md

@@ -0,0 +1,9 @@
+# Functional Decisions
+
+This directory contains product behavior decisions and tradeoffs for Native Image functional
+specifications.
+
+- [Register Providers as Complete Service Units](complete-security-provider-registration.md)
+- [Retain the Complete Default Provider for SecureRandom](default-secure-random-provider.md)
+- [Keep Run-Time Semantics Independent of Reachability](reachability-independent-runtime-semantics.md)
+- [Preserve Standard JCA Semantics Without Provider-Specific Flags](standard-jca-semantics.md)