diff --git a/.openpublishing.redirection.ai.json b/.openpublishing.redirection.ai.json index f007f29d0a3a2..da61574c73a57 100644 --- a/.openpublishing.redirection.ai.json +++ b/.openpublishing.redirection.ai.json @@ -72,6 +72,10 @@ "redirect_url": "/dotnet/ai/quickstarts/prompt-model", "redirect_document_id": true }, + { + "source_path_from_root": "/docs/ai/semantic-kernel-dotnet-overview.md", + "redirect_url": "/semantic-kernel/overview" + }, { "source_path_from_root": "/docs/ai/tutorials/llm-eval.md", "redirect_url": "/dotnet/ai/evaluation/evaluate-ai-response" diff --git a/docs/ai/conceptual/prompt-engineering-dotnet.md b/docs/ai/conceptual/prompt-engineering-dotnet.md index 02e59fa8d768f..f9f0ac09f0213 100644 --- a/docs/ai/conceptual/prompt-engineering-dotnet.md +++ b/docs/ai/conceptual/prompt-engineering-dotnet.md @@ -76,7 +76,7 @@ John Adams ...' ///Text truncated An example is text that shows the model how to respond by providing sample user input and model output. The model uses examples to infer what to include in completions. Examples can come either before or after the instructions in an engineered prompt, but the two shouldn't be interspersed. -An example starts with a prompt and can optionally include a completion. A completion in an example doesn't have to include the verbatim response—it might just contain a formatted word, the first bullet in an unordered list, or something similar to indicate how each completion should start. +An example starts with a prompt and can optionally include a completion. A completion in an example doesn't have to include the verbatim response—it might just contain a formatted word, the first bullet in an unordered list, or something similar to indicate how each completion should start. Examples are classified as [zero-shot learning](zero-shot-learning.md) or [few-shot learning](zero-shot-learning.md) based on whether they contain verbatim completions. @@ -103,7 +103,7 @@ First president to be declared an honorary citizen of a foreign country, and an John Adams ... /// Text truncated DOMESTIC POLICY -- George Washington: +- George Washington: - John Adams: """; ``` @@ -114,7 +114,7 @@ DOMESTIC POLICY ## Example prompt using .NET -.NET provides various tools to prompt and chat with different AI models. Use [Semantic Kernel](../semantic-kernel-dotnet-overview.md) to connect to a wide variety of AI models and services, as well as other SDKs such as the official [OpenAI .NET library](https://www.nuget.org/packages/OpenAI-DotNet/). Semantic Kernel includes tools to create prompts with different roles and maintain chat history, as well as many other features. +.NET provides various tools to prompt and chat with different AI models. Use [Semantic Kernel](/semantic-kernel/overview/) to connect to a wide variety of AI models and services, as well as other SDKs such as the official [OpenAI .NET library](https://www.nuget.org/packages/OpenAI-DotNet/). Semantic Kernel includes tools to create prompts with different roles and maintain chat history, as well as many other features. Consider the following code example: diff --git a/docs/ai/dotnet-ai-ecosystem.md b/docs/ai/dotnet-ai-ecosystem.md index ca6b70fccfaf8..fa8b677076a2d 100644 --- a/docs/ai/dotnet-ai-ecosystem.md +++ b/docs/ai/dotnet-ai-ecosystem.md @@ -20,7 +20,7 @@ The .NET ecosystem provides many powerful tools, libraries, and services to deve ## Semantic Kernel for .NET -If you just want to use the low-level services, such as and , you can reference the `Microsoft.Extensions.AI.Abstractions` package directly from your app. However, if you want to use higher-level, more opinionated approaches to AI, then you should use [Semantic Kernel](semantic-kernel-dotnet-overview.md). +If you just want to use the low-level services, such as and , you can reference the `Microsoft.Extensions.AI.Abstractions` package directly from your app. However, if you want to use higher-level, more opinionated approaches to AI, then you should use [Semantic Kernel](/semantic-kernel/overview/). Semantic Kernel, which has a dependency on the `Microsoft.Extensions.AI.Abstractions` package, is an open-source library that enables AI integration and orchestration capabilities in your .NET apps. Its connectors provides concrete implementations of and for different services, including OpenAI, Amazon Bedrock, and Google Gemini. diff --git a/docs/ai/get-started-mcp.md b/docs/ai/get-started-mcp.md index 9b39e257df3ce..40ed5b09668eb 100644 --- a/docs/ai/get-started-mcp.md +++ b/docs/ai/get-started-mcp.md @@ -96,4 +96,3 @@ Learn more about .NET and MCP using these resources: - [Overview of the .NET + AI ecosystem](dotnet-ai-ecosystem.md) - [Microsoft.Extensions.AI](/dotnet/ai/ai-extensions) -- [Semantic Kernel overview for .NET](semantic-kernel-dotnet-overview.md) diff --git a/docs/ai/semantic-kernel-dotnet-overview.md b/docs/ai/semantic-kernel-dotnet-overview.md deleted file mode 100644 index 0428cfa968e15..0000000000000 --- a/docs/ai/semantic-kernel-dotnet-overview.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Semantic Kernel overview for .NET -description: Learn how to add the Semantic Kernel SDK to your .NET projects and explore fundamental concepts -ms.date: 04/09/2025 -ms.topic: quickstart -author: alexwolfmsft -ms.author: alexwolf ---- - -# Semantic Kernel overview for .NET - -In this article, you explore [Semantic Kernel](/semantic-kernel/overview) core concepts and capabilities. Semantic Kernel is a powerful and recommended choice for working with AI in .NET applications. In the sections ahead, you learn: - -- How to add semantic kernel to your project -- Semantic Kernel core concepts - -This article serves as an introductory overview of Semantic Kernel specifically in the context of .NET. For more comprehensive information and training about Semantic Kernel, see the following resources: - -- [Semantic Kernel documentation](/semantic-kernel/overview) -- [Semantic Kernel training](/training/paths/develop-ai-agents-azure-open-ai-semantic-kernel-sdk/) - -## Add Semantic Kernel to a .NET project - -The Semantic Kernel SDK is available as a NuGet package for .NET and integrates with standard app configurations. - -Install the [`Microsoft.SemanticKernel`](https://www.nuget.org/packages/Microsoft.SemanticKernel) package using the following command: - -```dotnetcli -dotnet add package Microsoft.SemanticKernel -``` - -Or, in .NET 10+: - -```dotnetcli -dotnet package add Microsoft.SemanticKernel -``` - -> [!NOTE] -> Although `Microsoft.SemanticKernel` provides core features of Semantic Kernel, additional capabilities require you to install additional packages. For example, the [`Microsoft.SemanticKernel.Plugins.Memory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Plugins.Memory) package provides to access memory related features. For more information, see the [Semantic Kernel documentation](/semantic-kernel/overview). - -Create and configure a `Kernel` instance using the `KernelBuilder` class to access and work with Semantic Kernel. The `Kernel` holds services, data, and connections to orchestrate integrations between your code and AI models. - -Configure the `Kernel` in a .NET console app: - -```csharp -var builder = Kernel.CreateBuilder(); - -// Add builder configuration and services - -var kernel = builder.Build(); -``` - -Configure the Kernel in an ASP.NET Core app: - -```csharp -var builder = WebApplication.CreateBuilder(); -builder.Services.AddKernel(); - -// Add builder configuration and services - -var app = builder.Build(); -``` - -## Understand Semantic Kernel - -[Semantic Kernel](/semantic-kernel/overview/) is an open-source SDK that integrates and orchestrates AI models and services like OpenAI, Azure OpenAI, and Hugging Face with conventional programming languages like C#, Python, and Java. - -The Semantic Kernel SDK benefits enterprise developers in the following ways: - -- Streamlines integration of AI capabilities into existing applications to enable a cohesive solution for enterprise products. -- Minimizes the learning curve of working with different AI models or services by providing abstractions that reduce complexity. -- Improves reliability by reducing the unpredictable behavior of prompts and responses from AI models. You can fine-tune prompts and plan tasks to create a controlled and predictable user experience. - -Semantic Kernel is built around several core concepts: - -- **Connections**: Interface with external AI services and data sources. -- **Plugins**: Encapsulate functions that applications can use. -- **Planner**: Orchestrates execution plans and strategies based on user behavior. -- **Memory**: Abstracts and simplifies context management for AI apps. - -These building blocks are explored in more detail in the following sections. - -### Connections - -The Semantic Kernel SDK includes a set of connectors that enable developers to integrate LLMs and other services into their existing applications. These connectors serve as the bridge between the application code and the AI models or services. Semantic Kernel handles many common connection concerns and challenges for you so you can focus on building your own workflows and features. - -The following code snippet creates a `Kernel` and adds a connection to an Azure OpenAI model: - -```csharp -using Microsoft.SemanticKernel; - -// Create kernel -var builder = Kernel.CreateBuilder(); - -// Add a chat completion service: -builder.Services.AddAzureOpenAIChatCompletion( - "your-resource-name", - "your-endpoint", - "your-resource-key", - "deployment-model"); -var kernel = builder.Build(); -``` - -### Plugins - -Semantic Kernel [plugins](/semantic-kernel/agents/plugins) encapsulate standard language functions for applications and AI models to consume. You can create your own plugins or rely on plugins provided by the SDK. These plugins streamline tasks where AI models are advantageous and efficiently combine them with more traditional C# methods. Plugin functions are generally categorized into two types: *semantic functions* and *native functions*. - -#### Semantic functions - -Semantic functions are essentially AI prompts defined in your code that Semantic Kernel can customize and call as needed. You can templatize these prompts to use variables, custom prompt and completion formatting, and more. - -The following code snippet defines and registers a semantic function: - -```csharp -var userInput = Console.ReadLine(); - -// Define semantic function inline. -string skPrompt = @"Summarize the provided unstructured text in a sentence that is easy to understand. - Text to summarize: {{$userInput}}"; - -// Register the function -kernel.CreateSemanticFunction( - promptTemplate: skPrompt, - functionName: "SummarizeText", - pluginName: "SemanticFunctions" -); -``` - -#### Native functions - -Native functions are C# methods that Semantic Kernel can call directly to manipulate or retrieve data. They perform operations that are better suited for traditional code instructions instead of LLM prompts. - -The following code snippet defines and registers a native function: - -```csharp -// Define native function -public class NativeFunctions { - - [SKFunction, Description("Retrieve content from local file")] - public async Task RetrieveLocalFile(string fileName, int maxSize = 5000) - { - string content = await File.ReadAllTextAsync(fileName); - if (content.Length <= maxSize) return content; - return content.Substring(0, maxSize); - } -} - -//Import native function -string plugInName = "NativeFunction"; -string functionName = "RetrieveLocalFile"; - -var nativeFunctions = new NativeFunctions(); -kernel.ImportFunctions(nativeFunctions, plugInName); -``` - -### Planner - -The [planner](/semantic-kernel/agents/planners) is a core component of Semantic Kernel that provides AI orchestration to manage seamless integration between AI models and plugins. This layer devises execution strategies from user requests and dynamically orchestrates Plugins to perform complex tasks with AI-assisted planning. - -Consider the following pseudo-code snippet: - -```csharp -// Native function definition and kernel configuration code omitted for brevity - -// Configure and create the plan -string planDefinition = "Read content from a local file and summarize the content."; -SequentialPlanner sequentialPlanner = new SequentialPlanner(kernel); - -string assetsFolder = @"../../assets"; -string fileName = Path.Combine(assetsFolder,"docs","06_SemanticKernel", "aci_documentation.txt"); - -ContextVariables contextVariables = new ContextVariables(); -contextVariables.Add("fileName", fileName); - -var customPlan = await sequentialPlanner.CreatePlanAsync(planDefinition); - -// Execute the plan -KernelResult kernelResult = await kernel.RunAsync(contextVariables, customPlan); -Console.WriteLine($"Summarization: {kernelResult.GetValue()}"); -``` - -The preceding code creates an executable, sequential plan to read content from a local file and summarize the content. The plan sets up instructions to read the file using a native function and then analyze it using an AI model. - -### Memory - -Semantic Kernel's [Vector stores](/semantic-kernel/concepts/vector-store-connectors/) provide abstractions over embedding models, vector databases, and other data to simplify context management for AI applications. Vector stores are agnostic to the underlying LLM or Vector database, offering a uniform developer experience. You can configure memory features to store data in a variety of sources or service, including Azure AI Search and Azure Cache for Redis. - -Consider the following code snippet: - -```csharp -var facts = new Dictionary(); -facts.Add( - "Azure Machine Learning; https://learn.microsoft.com/en-us/azure/machine-learning/", - @"Azure Machine Learning is a cloud service for accelerating and - managing the machine learning project lifecycle. Machine learning professionals, - data scientists, and engineers can use it in their day-to-day workflows" -); - -facts.Add( - "Azure SQL Service; https://learn.microsoft.com/en-us/azure/azure-sql/", - @"Azure SQL is a family of managed, secure, and intelligent products - that use the SQL Server database engine in the Azure cloud." -); - -string memoryCollectionName = "SummarizedAzureDocs"; - -foreach (var fact in facts) { - await memoryBuilder.SaveReferenceAsync( - collection: memoryCollectionName, - description: fact.Key.Split(";")[0].Trim(), - text: fact.Value, - externalId: fact.Key.Split(";")[1].Trim(), - externalSourceName: "Azure Documentation" - ); -} -``` - -The preceding code loads a set of facts into memory so that the data is available to use when interacting with AI models and orchestrating tasks. - ->[!div class="step-by-step"] ->[Quickstart - Summarize text with OpenAI](quickstarts/prompt-model.md) ->[Quickstart - Chat with your data](quickstarts/build-vector-search-app.md) diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 345635417f565..be201f82f0dd6 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -464,7 +464,7 @@ | Common | NuGet [2.2.1](https://www.nuget.org/packages/Microsoft.Azure.Common/2.2.1) | | | | Common - Dependencies | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Common.Dependencies/1.0.0) | | | | Computer Vision | NuGet [7.0.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ComputerVision/7.0.1) | | GitHub [7.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.ComputerVision_6.0.0-preview.1/sdk/cognitiveservices/Vision.ComputerVision) | -| Cosmos DB | NuGet [3.47.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.47.0)
NuGet [3.55.0-preview.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.55.0-preview.0) | [docs](/dotnet/api/overview/azure/cosmosdb) | GitHub [3.47.0](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | +| Cosmos DB | NuGet [3.47.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.47.0)
NuGet [3.55.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.55.0-preview.1) | [docs](/dotnet/api/overview/azure/cosmosdb) | GitHub [3.47.0](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | | Custom Vision Prediction | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Prediction) | | Custom Vision Training | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.0.0)
NuGet [2.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.1.0-preview) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Training) | | Data Lake Analytics | NuGet [1.4.211011](https://www.nuget.org/packages/Microsoft.Azure.DataLake.USQL.SDK/1.4.211011) | | | @@ -524,7 +524,7 @@ | App Service - API Apps Service | NuGet [0.9.64](https://www.nuget.org/packages/Microsoft.Azure.AppService.ApiApps.Service/0.9.64) | | | | Code Analyzers for Durable Functions | NuGet [0.5.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask.Analyzers/0.5.0) | | GitHub [0.5.0](https://github.com/Azure/azure-functions-durable-extension/tree/Analyzer-v0.3.0/src/WebJobs.Extensions.DurableTask.Analyzers) | | Cosmos DB - BulkExecutor | NuGet [2.5.1-preview](https://www.nuget.org/packages/Microsoft.Azure.CosmosDB.BulkExecutor/2.5.1-preview) | | GitHub [2.5.1-preview](https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started) | -| Cosmos DB - Direct | NuGet [3.41.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.41.1) | | GitHub [3.41.1](https://github.com/Azure/azure-cosmos-dotnet-v3) | +| Cosmos DB - Direct | NuGet [3.41.2](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.41.2) | | GitHub [3.41.2](https://github.com/Azure/azure-cosmos-dotnet-v3) | | Cosmos DB - Encryption | NuGet [2.0.3](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/2.0.3)
NuGet [2.1.0-preview4](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/2.1.0-preview4) | | GitHub [2.0.3](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/encryption/1.0.0-preview4/Microsoft.Azure.Cosmos.Encryption) | | Cosmos DB - Encryption | NuGet [1.0.0-preview07](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption.Custom/1.0.0-preview07) | | | | Extensions - Caching Cosmos | NuGet [1.8.0](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Cosmos/1.8.0) | | GitHub [1.8.0](https://github.com/Azure/Microsoft.Extensions.Caching.Cosmos/tree/v1.0.0-preview4) | diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 2d92b51f5a69a..07d6f374888e2 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -64,6 +64,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [CoseSigner.Key can be null](cryptography/10.0/cosesigner-key-null.md) | Behavioral/source incompatible change | Preview 7 | | [MLDsa and SlhDsa 'SecretKey' members renamed](cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md) | Source incompatible | RC 1 | | [OpenSSL cryptographic primitives aren't supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 | +| [OpenSSL 1.1.1 or later required on Unix](cryptography/10.0/openssl-version-requirement.md) | Behavioral change | GA | | [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 | | [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md) | Behavioral/source incompatible change | Preview 3 | | [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/cryptography/10.0/openssl-version-requirement.md b/docs/core/compatibility/cryptography/10.0/openssl-version-requirement.md new file mode 100644 index 0000000000000..3c9c7da74ae40 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/openssl-version-requirement.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: .NET 10 requires OpenSSL 1.1.1 or later on Unix" +description: "Learn about the breaking change in .NET 10 where OpenSSL 1.1.1 or later is required on Unix platforms." +ms.date: 11/04/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/49487 +--- +# .NET 10 requires OpenSSL 1.1.1 or later on Unix + +Starting in .NET 10, OpenSSL 1.1.1 or later is required on Unix platforms where .NET uses OpenSSL for cryptography, such as Linux. If OpenSSL 1.1.1 isn't available on a platform that requires it, the application will fail to start. .NET 10 on macOS doesn't use OpenSSL and isn't impacted by this change. + +## Version introduced + +.NET 10 GA + +## Previous behavior + +.NET applications supported OpenSSL versions prior to 1.1.1, such as 1.0.2 and 1.1.0. + +## New behavior + +Starting in .NET 10, .NET applications require OpenSSL 1.1.1 or later. If OpenSSL 1.1.1 isn't available on a platform that requires it, the application will fail to start. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +OpenSSL prior to OpenSSL 1.1.1 is outdated and isn't supported by mainstream Linux or Unix distributions. Supporting these out-of-date OpenSSL versions increases complexity of maintenance, and that effort is better spent on supporting modern versions of OpenSSL. + +## Recommended action + +Use a distribution of Linux or Unix that includes OpenSSL 1.1.1 or later. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index ec9c94695b2f9..084502fd419de 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -78,6 +78,8 @@ items: href: cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md - name: OpenSSL cryptographic primitives not supported on macOS href: cryptography/10.0/openssl-macos-unsupported.md + - name: OpenSSL 1.1.1 or later required on Unix + href: cryptography/10.0/openssl-version-requirement.md - name: X500DistinguishedName validation is stricter href: cryptography/10.0/x500distinguishedname-validation.md - name: X509Certificate and PublicKey key parameters can be null diff --git a/docs/core/introduction.md b/docs/core/introduction.md index 2fdcc8d6fcc90..0cf32601d7fcd 100644 --- a/docs/core/introduction.md +++ b/docs/core/introduction.md @@ -14,7 +14,7 @@ The .NET platform has been designed to deliver productivity, performance, securi .NET has the following [design points](https://devblogs.microsoft.com/dotnet/why-dotnet/): -* **Productivity is full-stack** with runtime, libraries, language, and tools all contributing to developer user experience. +* **Productivity is full-stack** with runtime, libraries, languages, and tools all contributing to developer user experience. * **Safe code** is the primary compute model, while [unsafe code](../csharp/language-reference/unsafe-code.md) enables additional manual optimizations. * **Static and dynamic code** are both supported, enabling a broad set of distinct scenarios. * **Native code interop and hardware intrinsics** are low cost and high-fidelity (raw API and instruction access). diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index ab35dd0f8a409..dd8f1a3198b2d 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -114,7 +114,7 @@ For more information, see [Target frameworks in SDK-style projects](../../standa Use the `TargetFrameworks` property when you want your app to target multiple platforms. For a list of valid target framework monikers, see [Target frameworks in SDK-style projects](../../standard/frameworks.md#supported-target-frameworks). > [!NOTE] -> This property is ignored if `TargetFramework` (singular) is specified. +> If `TargetFrameworks` (plural) is specified, `TargetFramework` (singular) is ignored. ```xml diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index 08e4bd195bf13..0cc2f22342903 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -315,6 +315,8 @@ items: href: ../../core/deploying/single-file/overview.md - name: ReadyToRun href: ../../core/deploying/ready-to-run.md + - name: Publish .NET apps for macOS + href: ../../core/deploying/macos.md - name: Trim self-contained deployments items: - name: Overview and how-to diff --git a/docs/standard/security/cross-platform-cryptography.md b/docs/standard/security/cross-platform-cryptography.md index 34efde3620aec..d80e48715556d 100644 --- a/docs/standard/security/cross-platform-cryptography.md +++ b/docs/standard/security/cross-platform-cryptography.md @@ -1,7 +1,7 @@ --- title: "Cross-platform cryptography in .NET" description: Learn about cryptographic capabilities on platforms supported by .NET. -ms.date: "06/19/2020" +ms.date: "11/04/2025" ms.subservice: standard-library helpviewer_keywords: - "cryptography, cross-platform" @@ -81,14 +81,12 @@ Since authenticated encryption requires newer platform APIs to support the algor | Cipher + Mode | Windows | Linux | macOS | iOS, tvOS, MacCatalyst | Android | Browser | |-------------------|-------------------------|----------------|---------|------------------------|---------------|---------| | AES-GCM | ✔️ | ✔️ | ✔️ | ⚠️ | ✔️ | ❌ | -| AES-CCM | ✔️ | ✔️ | ⚠️ | ❌ | ✔️ | ❌ | +| AES-CCM | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | | ChaCha20Poly1305 | Windows 10 Build 20142+ | OpenSSL 1.1.0+ | ✔️ | ⚠️ | API Level 28+ | ❌ | ### AES-CCM on macOS -On macOS, the system libraries don't support AES-CCM for third-party code, so the class uses OpenSSL for support. Users on macOS need to obtain an appropriate copy of OpenSSL (libcrypto) for this type to function, and it must be in a path that the system would load a library from by default. We recommend that you install OpenSSL from a package manager such as Homebrew. - -The `libcrypto.0.9.7.dylib` and `libcrypto.0.9.8.dylib` libraries included in macOS are from earlier versions of OpenSSL and will not be used. The `libcrypto.35.dylib`, `libcrypto.41.dylib`, and `libcrypto.42.dylib` libraries are from LibreSSL and will not be used. +Prior to .NET 10, AES-CCM worked if a supported version of OpenSSL was present and the dynamic library loader could locate it. OpenSSL support on macOS was removed in .NET 10. ### AES-GCM and ChaCha20Poly1305 on iOS, tvOS, and MacCatalyst @@ -173,11 +171,11 @@ Padding and digest support vary by platform: |--------------------------------------------------------------|---------|---------------|-----------------|-------------------------|-----------------| | | ✔️ | ⚠️1 | ⚠️1 | ⚠️1 | ⚠️1 | | | ✔️ | ❌ | ❌ | ❌ | ❌ | -| | ❌ | ✔️ | ⚠️2 | ❌ | ❌ | +| | ❌ | ✔️ | ❌2 | ❌ | ❌ | 1 On non-Windows, can be used for compatibility with existing programs. In that case, any method that requires OS interop, such as opening a named key, throws a . -2 On macOS, works if OpenSSL is installed and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown. +2 On macOS, prior to .NET 10, worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10. ### ECDSA @@ -210,9 +208,9 @@ ECDSA key curves are defined by the OS libraries and are subject to their limita | Type | Windows | Linux | macOS | iOS, tvOS, MacCatalyst | Android | |--------------------------------------------------|---------|-------|-------|------------------------|---------| | | ✔️ | ❌ | ❌ | ❌ | ❌ | -| | ❌ | ✔️ | ⚠️\* | ❌ | ❌ | +| | ❌ | ✔️ | ❌\* | ❌ | ❌ | -\* On macOS, works if OpenSSL is installed in the system and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown. +\* On macOS, prior to .NET 10, worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10. ### ECDH @@ -230,7 +228,7 @@ The class supports the "raw" ECDH key curves are defined by the OS libraries and are subject to their limitations. -| Elliptic Curve | Windows 10 | Windows 7 - 8.1 | Linux | macOS | iOS, tvOS, MacCatalyst | Android | +| Elliptic Curve | Windows 10+ | Windows 7 - 8.1 | Linux | macOS | iOS, tvOS, MacCatalyst | Android | |------------------------------------|----------------|-----------------|----------------|-----------------|------------------------|----------------| | NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | @@ -255,9 +253,9 @@ ECDH key curves are defined by the OS libraries and are subject to their limitat | Type | Windows | Linux | macOS | iOS, tvOS, MacCatalyst | Android | |------------------------------------------------------------|---------|-------|-------|------------------------|----------| | | ✔️ | ❌ | ❌ | ❌ | ❌ | -| | ❌ | ✔️ | ⚠️\* | ❌ | ❌ | +| | ❌ | ✔️ | ❌\* | ❌ | ❌ | -\* On macOS, works if OpenSSL is installed and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown. +\* On macOS, prior to .NET 10, worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10. ### DSA @@ -290,11 +288,103 @@ DSA (Digital Signature Algorithm) key generation is performed by the system libr |--------------------------------------------------------------|---------|----------------|-----------------|------------------------|----------------| | | ✔️ | ⚠️1 | ⚠️1 | ❌ | ⚠️1 | | | ✔️ | ❌ | ❌ | ❌ | ❌ | -| | ❌ | ✔️ | ⚠️2 | ❌ | ❌ | +| | ❌ | ✔️ | ❌2 | ❌ | ❌ | 1 On non-Windows, can be used for compatibility with existing programs. In that case, any method that requires system interop, such as opening a named key, throws a . -2 On macOS, works if OpenSSL is installed and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown. +2 On macOS, prior to .NET 10, worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10. + +## Post-quantum cryptography + +Post-quantum algorithms are available starting in .NET 10. They're also available for .NET Framework using the Microsoft.Bcl.Cryptography NuGet package. The following support table indicates the platform support for the built-in operating system cryptographic components, such as those created from `Generate` or `ImportFromPem`. Implementations that derive from the base class might have different support behaviors. + +For the built-in algorithms, an `IsSupported` static property is available to determine if the platform supports any of the parameter sets. + +The native interop types for post-quantum algorithms do not support key generation or importing. They exist specifically for interop scenarios with the native platform types, such as an `EVP_PKEY` on OpenSSL or `CngKey` on Windows. + +### ML-KEM + +| Algorithm | Windows | Linux | Apple | Android | Browser | +|--------------|-------------------------------|----------------|-------|---------|---------| +| ML-KEM-512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-KEM-768 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-KEM-1024 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | + +#### Native interop ML-KEM + +* : OpenSSL 3.5.0+ +* : Windows 11 Insiders (Latest) + +### ML-DSA + +ML-DSA has a pure and prehash variant (HashML-DSA). The following table reflects both the pure and prehash variants. + +| Algorithm | Windows | Linux | Apple | Android | Browser | +|---------------------------------------------|-------------------------------|----------------|-------|---------|---------| +| ML-DSA-44 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-DSA-65 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-DSA-87 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-DSA-44 External Mu (μ)1 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-DSA-65 External Mu (μ)1 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| ML-DSA-87 External Mu (μ)1 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | + +1 External Mu support is for signing and verifying Mu only. Computation of Mu isn't supported. + +#### Native interop ML-DSA + +* : OpenSSL 3.5.0+ +* : Windows 11 Insiders (latest) + +### SLH-DSA + +SLH-DSA has a pure and prehash variant (HashSLH-DSA). The following table reflects both the pure and prehash variants. + +| Algorithm | Windows | Linux | Apple | Android | Browser | +|---------------------|---------|----------------|-------|---------|---------| +| SLH-DSA-SHA2-128f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHA2-128s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHA2-192f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHA2-192s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHA2-256f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHA2-256s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHAKE-128f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHAKE-128s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHAKE-192f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHAKE-192s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHAKE-256f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| SLH-DSA-SHAKE-256s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | + +#### Native interop SLH-DSA + +* : OpenSSL 3.5.0+ +* : Not supported + +### Composite ML-DSA + +| Algorithm | Windows | Linux | Apple | Android | Browser | +|----------------------------------------|-------------------------------|----------------|-------|---------|---------| +| MLDSA44-RSA2048-PSS-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA44-RSA2048-PKCS15-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA44-Ed25519-SHA512 | ❌ | ❌ | ❌ | ❌ | ❌ | +| MLDSA44-ECDSA-P256-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA3072-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA3072-PKCS15-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA4096-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA4096-PKCS15-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-ECDSA-P256-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-ECDSA-P384-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-ECDSA-brainpoolP256r1-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-Ed25519-SHA512 | ❌ | ❌ | ❌ | ❌ | ❌ | +| MLDSA87-ECDSA-P384-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-ECDSA-brainpoolP384r1-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-Ed448-SHAKE256 | ❌ | ❌ | ❌ | ❌ | ❌ | +| MLDSA87-RSA3072-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-RSA4096-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-ECDSA-P521-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | + +#### Native interop composite ML-DSA + +* : Not supported ## X.509 Certificates @@ -411,6 +501,24 @@ macOS doesn't support Offline CRL utilization, so `X509RevocationMode.Offline` i macOS doesn't support a user-initiated timeout on CRL (Certificate Revocation List) / OCSP (Online Certificate Status Protocol) / AIA (Authority Information Access) downloading, so `X509ChainPolicy.UrlRetrievalTimeout` is ignored. +### Post-quantum cryptography certificates and PKCS12/PFX + +Post-quantum certificate support also requires support from the primitive algorithm. + +| Operation | Algorithm | Windows | Linux | Apple | Android | Browser | +|-------------------------|-----------|---------|-------|-------|---------|---------| +| PKCS#12 Import | ML-DSA | ✔️ | ✔️ | ❌ | ❌ | ❌ | +| PKCS#12 Export | ML-DSA | ✔️ | ✔️ | ❌ | ❌ | ❌ | +| Private Key Association | ML-DSA | ✔️ | ✔️ | ❌ | ❌ | ❌ | +|   | | | | | | | +| PKCS#12 Import | ML-KEM | ❌ | ✔️ | ❌ | ❌ | ❌ | +| PKCS#12 Export | ML-KEM | ❌ | ✔️ | ❌ | ❌ | ❌ | +| Private Key Association | ML-KEM | ❌ | ✔️ | ❌ | ❌ | ❌ | +|   | | | | | | | +| PKCS#12 Import | SLH-DSA | ❌ | ✔️ | ❌ | ❌ | ❌ | +| PKCS#12 Export | SLH-DSA | ❌ | ✔️ | ❌ | ❌ | ❌ | +| Private Key Association | SLH-DSA | ❌ | ✔️ | ❌ | ❌ | ❌ | + ## Additional resources * [.NET Cryptography Model](cryptography-model.md)