BCryptSetProperty function (bcrypt.h)

The BCryptSetProperty function sets the value of a named property for a CNG object.

Syntax

NTSTATUS BCryptSetProperty(
  [in, out] BCRYPT_HANDLE hObject,
  [in]      LPCWSTR       pszProperty,
  [in]      PUCHAR        pbInput,
  [in]      ULONG         cbInput,
  [in]      ULONG         dwFlags
);

Parameters

[in, out] hObject

A handle that represents the CNG object to set the property value for.

[in] pszProperty

A pointer to a null-terminated Unicode string that contains the name of the property to set. This can be one of the predefined Cryptography Primitive Property Identifiers or a custom property identifier.

[in] pbInput

The address of a buffer that contains the new property value. The cbInput parameter contains the size of this buffer.

[in] cbInput

The size, in bytes, of the pbInput buffer.

[in] dwFlags

A set of flags that modify the behavior of this function. No flags are defined for this function.

Return value

Returns a status code that indicates the success or failure of the function.

Possible return codes include, but are not limited to, the following:

Return code	Description
STATUS_SUCCESS	The function was successful.
STATUS_INVALID_HANDLE	The handle in the hObject parameter is not valid.
STATUS_INVALID_PARAMETER	One or more parameters are not valid.
STATUS_NOT_SUPPORTED	The named property specified by the pszProperty parameter is not supported or is read-only.

Remarks

When using a supported algorithm provider, BCryptSetProperty can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVEL IRQL or DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL, any pointers passed to BCryptSetProperty must refer to nonpaged (or locked) memory. If the object specified in the hObject parameter is a handle, it must have been opened by using the BCRYPT_PROV_DISPATCH flag.

To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows Server 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

When generating keys for ML-DSA and ML-KEM, the BCRYPT_PARAMETER_SET_NAME property must be set on the key handle, before the key can be finalized.

When setting the value for the property BCRYPT_CHAINING_MODE, the pbInput parameter is unbounded by cbInput. The caller needs to ensure a valid null-terminated Unicode string is provided.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps | UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps | UWP apps]
Target Platform	Windows
Header	bcrypt.h
Library	Bcrypt.lib
DLL	Bcrypt.dll

See also

Cryptography Primitive Property Identifiers