AzureKeys Component

Properties   Methods   Events   Config Settings   Errors  

The AzureKeys component makes it easy to interact with keys in Azure Key Vaults.

Syntax

nsoftware.CloudKeys.Azurekeys

Remarks

The AzureKeys component provides an easy-to-use interface for the key-related functionality of the Azure Key Vault service. Azure Key Vault allows you to works with a few different kinds of resources, one of which is asymmetric key pairs. This component helps you to create, manage, and use said key pairs (or just "keys", for short) for cryptographic operations. To work with "secrets" instead, refer to the AzureSecrets component.

To begin, register for an Azure account and create one or more Key Vaults via the Azure Portal. Set the Vault property to the name of the vault you wish to work with.

This component requires authentication via OAuth 2.0. First, perform OAuth authentication using the OAuth property to set the appropriate fields for the chosen ClientProfile and GrantType.

The component has the following defaults:

Additionaly, depending on how the application is registered (Ex. Single-tenant, Multi-tenant) and what GrantType is selected (Ex. Authorization Code, Password), it may be required to use the tenant ID rather than "common" in the ServerAuthURL, and ServerTokenURL fields. See below for examples of the modified URLs:

Application Profile

This profile encompasses the most basic grant types that OAuth supports. When this profile is set, all the requests and response handling is done by the component. Depending on the grant type, this may involve launching a browser so a user can login to authenticate with a authorization server. It may also involve starting an embedded web server to receive a response from a redirect.

To start the authentication and authorization process, the Authorize method should be called. If the authorization and authentication was successful, then the AccessToken field will be populated. Additionally, if a refresh token was provided the RefreshToken field will be populated as well. These values of the fields are for informational purposes. The component will also cache these tokens along with when the AccessToken will be expired. When a method that makes requests to the service provider is called or the Authorize method is called the component will automatically check to see if the access token is expired. If it is, it will then automatically try to get a new AccessToken. If the Authorize method was not used and user interaction would be required, the component will throw an error which can be caught. When user interaction is needed depends on what grant type is set in the GrantType field. To force the component to only check the access token when the Authorize method is called, the OAuthAutomaticRefresh configuration setting can be set to false.

A brief description of the supported values for the GrantType field are below. For more information, see the service documentation.

Authorization Code

When using the Authorization Code grant type, the component will use an authorization code to get an access token. For this GrantType the component expects a ClientId, ClientSecret, ServerAuthURL, and ServerTokenURL to be set. When the Authorize method is called, the component will start the embedded web server and launch the browser so the user can authorize the application. Once the user authorizes, the service provider will redirect them to the embedded web server and the component will parse the authorization code, setting the AuthorizationCode field, from the redirect. Immediately, the component will make a request to the token server to exchange the authorization code for an access token. The token server will return an access token and possibly a refresh token. If the RefreshToken field is set, or a refresh token is cached, then the component will not launch the browser and use the refresh token in its request to the token server instead of an authorization code.

Example: AzureKeys azurekeys = new AzureKeys(); azurekeys.OAuth.ClientProfile = OAuthClientProfiles.cocpApplication; azurekeys.OAuth.GrantType = OAuthGrantTypes.cogtAuthorizationCode; azurekeys.OAuth.ClientId = CLIENT_ID; azurekeys.OAuth.ClientSecret = SECRET_ID; azurekeys.OAuth.AuthorizationScope = "offline_access https://vault.azure.net/user_impersonation"; azurekeys.OAuth.ServerAuthURL = "https://login.microsoftonline.com/" + TENANT_ID + "/oauth2/v2.0/authorize"; azurekeys.OAuth.ServerTokenURL = "https://login.microsoftonline.com/" + TENANT_ID + "/oauth2/v2.0/token"; azurekeys.Authorize(); Implicit

Note: This grant type is considered insecure and should only be used when necessary.

When using the Implicit grant type, the component will request the authorization server to get an access token. For this GrantType the component expects a ClientId, ClientSecret, and ServerAuthURL to be set. When the Authorize method is called, the component will start the embedded web server and launch the browser so the user can authorize the application. Once the user authorizes, the service provider will redirect them to the embedded web server and the component will parse the access token from the redirect.

A disadvantage of the grant type is that can not use a refresh token to silently get a new access token. Most service providers offer a way to silently get a new access token. See the service documentation for specifics. This means the component will not be able to automatically get a fresh token once it expires.

Password

Note: This grant type is considered insecure and should only be used when necessary.

When using the Resource Owner Password Credentials grant type, the component will authenticate as the resource owner. This allows for the component to avoid user interaction. This grant type often has specific limitations put on it by the service provider. See the service documentation for more details.

For this GrantType the component requires OAuthPasswordGrantUsername, ClientSecret, and ServerTokenURL to be set. The ClientSecret should be set to the password of the account instead of a typical secret. In some cases, the ClientId also needs to be set. When the Authorize method is called, the component will make a request to the token server for an access token using the username and password. The token server will return an access token if the authentication was successful. When this access token is expired, the component will automatically (see above for detailed description) make a new request to get a fresh one.

Web Profile

External OAuth Support

Bearer ACCESS_TOKEN_VALUE

Assign this value to the Authorization property before attempting any operations. Setting the Authorization property will cause the component to ignore the values set in the OAuth property.

For Example: Oauth oauth = new Oauth(); oauth.ClientId = "CLIENT_ID"; oauth.ClientSecret = "CLIENT_SECRET"; oauth.ServerAuthURL = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"; oauth.ServerTokenURL = "https://login.microsoftonline.com/common/oauth2/v2.0/token"; oauth.AuthorizationScope = "offline_access https://vault.azure.net/user_impersonation"; oauth.GrantType = OauthGrantTypes.ogtAuthorizationCode; azurekeys.Authorization = oauth.GetAuthorization(); Consult the documentation for the service for more information about supported scope values and more details on OAuth authentication.

Using the Component

Keys can be created using the CreateKey method. A key's name and type (i.e., whether it is RSA or EC, and its size or curve, respectively) must be set at the time of creation, and cannot be changed later. A list of cryptographic operations that the key is valid for must also be set, but can be changed at any time using the UpdateKey. If a key with the specified name already exists, a new version of it is created; this makes it easy to "rotate" a key.

When a key will no longer be used, it can be deleted using the DeleteKey method. However, the key will only be soft-deleted; by default, Azure will permanently delete it after the waiting period configured for the vault. During this waiting period, the soft-deleted key may be recovered using RecoverKey, or permanently deleted using PurgeKey (assuming the currently-authenticated user has the permissions to do so). azurekeys.CreateKey("mykey", "RSA_2048", "encrypt,decrypt,sign,verify,wrapKey,unwrapKey"); // ... Some time later, when the key is no longer needed ... azurekeys.DeleteKey("mykey"); // At this point, the key is only soft-deleted. It could be recovered... azurekeys.RecoverKey("mykey"); // ...or permanently deleted. azurekeys.PurgeKey("mykey");

To list keys, use the ListKeys method. This method is also used to list soft-deleted keys if the GetDeleted configuration setting has been enabled first. To list a key's versions, use the ListVersions method. (You cannot list a deleted key's versions.) In all cases, the IncludeKeyDetails property can optionally be enabled to have the component attempt to retrieve the full information for each key (Azure leaves out certain fields by default when listing). // If there are many keys to list, there may be multiple pages of results. This will // cause all pages of results to be accumulated into the Keys collection property. do { azurekeys.ListKeys(); } while (!string.IsNullOrEmpty(azurekeys.KeyMarker)); // A similar thing applies to key versions as well. do { azurekeys.ListVersions("mykey"); } while (!string.IsNullOrEmpty(azurekeys.VersionMarker));

Depending on a key's "key ops" list, it can be used to perform different cryptographic operations. Keys with the encrypt and decrypt ops can be used in Encrypt and Decrypt operations. Keys with the sign and verify ops can be used in Sign and Verify. Finally, keys with the wrapKey and unwrapKey ops can be used in WrapKey and UnwrapKey operations (which are just like encryption and decryption, but which are intended to be used for wrapping a symmetric key, and which require different permissions to call successfully).

To perform a cryptographic operation, use InputData, InputFile, or SetInputStream to supply the input data that should be processed. All operations will output the result data to OutputData, OutputFile, or SetOutputStream (except Verify; refer to its documentation for more information). azurekeys.CreateKey("mykey", "RSA_2048", "encrypt,decrypt"); azurekeys.InputData = "Test123"; azurekeys.OutputFile = "C:/temp/enc.dat"; azurekeys.Encrypt("mykey", "RSA-OAEP-256"); azurekeys.InputFile = "C:/temp/enc.dat"; azurekeys.OutputFile = ""; // So that the data will be output to the OutputData property. azurekeys.Decrypt("mykey", "RSA-OAEP-256");

The component also supports a variety of other functionality, including:

• Retrieval of a single key's information (including public key) with GetKeyInfo.
• Enabling and disabling keys with SetKeyEnabled.
• Tagging support using AddTag and the Tags collection.
• Secure key backup and restoration using BackupKey and RestoreKey.
• And more!

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Authorization Property (AzureKeys Component)

OAuth 2.0 Authorization Token

Syntax

• C#
• VB.NET

public string Authorization { get; set; }

Public Property Authorization As String

Default Value

""

Remarks

This component supports authentication via OAuth 2.0. First, perform OAuth authentication using the OAuth component or a separate process. Once complete you should have an authorization string which looks like:

Bearer ACCESS_TOKEN

Firewall Property (AzureKeys Component)

A set of properties related to firewall access.

Syntax

• C#
• VB.NET

public Firewall Firewall { get; set; }

Public Property Firewall As Firewall

Remarks

This is a Firewall type property which contains fields describing the firewall through which the component will attempt to connect.

Idle Property (AzureKeys Component)

The current status of the component.

Syntax

• C#
• VB.NET

public bool Idle { get; }

Public ReadOnly Property Idle As Boolean

Default Value

True

Remarks

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

This property is read-only.

IncludeKeyDetails Property (AzureKeys Component)

Whether to attempt to retrieve fill details when listing keys.

Syntax

• C#
• VB.NET

public bool IncludeKeyDetails { get; set; }

Public Property IncludeKeyDetails As Boolean

Default Value

False

Remarks

This property specifies whether the component should make additional requests when ListKeys or ListVersions is called in order to retrieve full information for each key. By default, Azure will omit certain fields when one of those methods is called (refer to each one's documentation for more information).

If this property is enabled, then after the initial listing is returned, the component will call GetKeyInfo internally for each key returned. For all keys for which this call is successful, the additional information will be used to populate the Keys collection. Any keys for which the GetKeyInfo call fails will not have the additional fields populated.

This property is not available at design time.

InputData Property (AzureKeys Component)

The data to process.

Syntax

• C#
• VB.NET

public string InputData { get; set; }
public byte[] InputDataB { get; set; }

Public Property InputData As String
Public Property InputDataB As Byte()

Default Value

""

Remarks

This property specifies the data that should be processed in a cryptographic operation.

Input Sources & Output Destinations

The component automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

This property is not available at design time.

InputFile Property (AzureKeys Component)

The file whose data should be processed.

Syntax

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

This property specifies the file whose data should be processed in a cryptographic operation. It accepts both absolute and relative file paths.

Setting this property to a non-empty value will discard any stream set using the SetInputStream method. Similarly, passing a non-null value to the aforementioned method will clear this property.

Input Sources & Output Destinations

The component automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

KeyMarker Property (AzureKeys Component)

A marker indicating what page of keys to return next.

Syntax

• C#
• VB.NET

public string KeyMarker { get; set; }

Public Property KeyMarker As String

Default Value

""

Remarks

This property will be populated when ListKeys is called if the results are paged and there are more pages. To list all keys, continue to call ListKeys until this property returns empty string.

Refer to ListKeys for more information.

This property is not available at design time.

Keys Property (AzureKeys Component)

A collection of keys.

Syntax

• C#
• VB.NET

public AzureKeyList Keys { get; }

Public ReadOnly Property Keys As AzureKeyList

Remarks

This collection holds a list of AzureKey items.

Calling ListKeys, ListVersions, or GetKeyInfo will populate this collection.

This property is read-only and not available at design time.

LocalHost Property (AzureKeys Component)

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

• C#
• VB.NET

public string LocalHost { get; set; }

Public Property LocalHost As String

Default Value

""

Remarks

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the component initiate connections (or accept in the case of server components) only through that interface.

If the component is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

OAuth Property (AzureKeys Component)

This property holds the OAuth Settings.

Syntax

• C#
• VB.NET

public OAuthSettings OAuth { get; }

Public ReadOnly Property OAuth As OAuthSettings

Remarks

This property is used to define the necessary fields to authenticate with the service provider. See the introduction for more information.

This property is read-only and not available at design time.

OtherHeaders Property (AzureKeys Component)

This property includes other headers as determined by the user (optional).

Syntax

• C#
• VB.NET

public string OtherHeaders { get; set; }

Public Property OtherHeaders As String

Default Value

""

Remarks

This property can be set to a string of headers to be appended to the HTTP request headers created from other properties like ContentType and From.

The headers must follow the format Header: Value as described in the HTTP specifications. Header lines should be separated by CRLF ("\r\n") .

Use this property with caution. If this property contains invalid headers, HTTP requests may fail.

This property is useful for extending the functionality of the component beyond what is provided.

This property is not available at design time.

OutputData Property (AzureKeys Component)

The output data.

Syntax

• C#
• VB.NET

public string OutputData { get; set; }
public byte[] OutputDataB { get; set; }

Public Property OutputData As String
Public Property OutputDataB As Byte()

Default Value

""

Remarks

This property is populated with the data that was output from a successful cryptographic operation.

Note: For the Verify operation, this property functions as a secondary input property instead (along with InputData); refer to the Verify method for more information.

Input Sources & Output Destinations

The component automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

This property is not available at design time.

OutputFile Property (AzureKeys Component)

The file to which output data should be written.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

This property specifies the file to which data output from a successful cryptographic operation should be written.

Setting this property to a non-empty value will discard any stream set using the SetOutputStream method. Similarly, passing a non-null value to the aforementioned method will clear this property.

Note: For the Verify operation, the specified file functions as a secondary input file instead (along with InputFile); refer to the Verify method for more information.

Input Sources & Output Destinations

The component automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

Overwrite Property (AzureKeys Component)

Whether the output file should be overwritten if necessary.

Syntax

• C#
• VB.NET

public bool Overwrite { get; set; }

Public Property Overwrite As Boolean

Default Value

False

Remarks

This property controls whether the specified OutputFile should be overwritten if it already exists.

ParsedHeaders Property (AzureKeys Component)

This property includes a collection of headers returned from the last request.

Syntax

• C#
• VB.NET

public HeaderList ParsedHeaders { get; }

Public ReadOnly Property ParsedHeaders As HeaderList

Remarks

This property contains a collection of headers returned from the last request. Whenever headers are returned from the server, the headers are parsed into a collection of headers. Each Header in this collection contains information describing that header.

MaxHeaders can be used to control the maximum number of headers saved.

This collection is indexed from 0 to count -1.

This property is read-only and not available at design time.

Proxy Property (AzureKeys Component)

This property includes a set of properties related to proxy access.

Syntax

• C#
• VB.NET

public Proxy Proxy { get; set; }

Public Property Proxy As Proxy

Remarks

This property contains fields describing the proxy through which the component will attempt to connect.

QueryParams Property (AzureKeys Component)

Additional query parameters to be included in the request.

Syntax

• C#
• VB.NET

public QueryParamList QueryParams { get; }

Public Property QueryParams As QueryParamList

Remarks

This is a collection of query parameters that will be added to the request. Parameters can be added via the AddQueryParam method.

SSLAcceptServerCert Property (AzureKeys Component)

Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

• C#
• VB.NET

public Certificate SSLAcceptServerCert { get; set; }

Public Property SSLAcceptServerCert As Certificate

Remarks

If it finds any issues with the certificate presented by the server, the component will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

SSLCert Property (AzureKeys Component)

The certificate to be used during SSL negotiation.

Syntax

• C#
• VB.NET

public Certificate SSLCert { get; set; }

Public Property SSLCert As Certificate

Remarks

The digital certificate that the component will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

SSLProvider Property (AzureKeys Component)

This specifies the SSL/TLS implementation to use.

Syntax

• C#
• VB.NET

public AzurekeysSSLProviders SSLProvider { get; set; }

enum AzurekeysSSLProviders {
  sslpAutomatic,
  sslpPlatform,
  sslpInternal
}

Public Property SSLProvider As AzurekeysSSLProviders

Enum AzurekeysSSLProviders
  sslpAutomatic
  sslpPlatform
  sslpInternal
End Enum

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the component will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

In most cases using the default value (Automatic) is recommended. The component will select a provider depending on the current platform.

When Automatic is selected, on Windows the component will use the platform implementation. On Linux/macOS the component will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used on all platforms.

The .NET Standard library will always use the internal implementation on all platforms.

SSLServerCert Property (AzureKeys Component)

The server certificate for the last established connection.

Syntax

• C#
• VB.NET

public Certificate SSLServerCert { get; }

Public ReadOnly Property SSLServerCert As Certificate

Remarks

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

This property is read-only.

Tags Property (AzureKeys Component)

A collection of tags.

Syntax

• C#
• VB.NET

public AzureTagList Tags { get; }

Public Property Tags As AzureTagList

Remarks

This collection holds a list of AzureTag items.

Calling AddTag or GetKeyInfo will populate this collection. The items in this collection are used by the CreateKey and UpdateKey methods.

This property is not available at design time.

Timeout Property (AzureKeys Component)

A timeout for the component.

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If Timeout is set to a positive value, the component will wait for the operation to complete before returning control.

The component will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the component throws an exception.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

The default value for the Timeout property is 60 seconds.

Vault Property (AzureKeys Component)

Selects a vault for the component to interact with.

Syntax

• C#
• VB.NET

public string Vault { get; set; }

Public Property Vault As String

Default Value

""

Remarks

This property specifies the Azure Key Vault vault, by name, that the component should interact with.

VersionMarker Property (AzureKeys Component)

A marker indicating what page of key versions to return next.

Syntax

• C#
• VB.NET

public string VersionMarker { get; set; }

Public Property VersionMarker As String

Default Value

""

Remarks

This property will be populated when ListVersions is called if the results are paged and there are more pages. To list all key versions, continue to call ListVersions until this property returns empty string.

Refer to ListVersions for more information.

This property is not available at design time.

AddQueryParam Method (AzureKeys Component)

Adds a query parameter to the QueryParams properties.

Syntax

• C#
• VB.NET

public void AddQueryParam(string name, string value);

Async Version
public async Task AddQueryParam(string name, string value);
public async Task AddQueryParam(string name, string value, CancellationToken cancellationToken);

Public Sub AddQueryParam(ByVal Name As String, ByVal Value As String)

Async Version
Public Sub AddQueryParam(ByVal Name As String, ByVal Value As String) As Task
Public Sub AddQueryParam(ByVal Name As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add a query parameter to the QueryParams collection. Name specifies the name of the parameter, and Value specifies the value of the parameter.

All specified Values will be URL encoded by the component automatically. Consult the service documentation for details on the available parameters.

AddTag Method (AzureKeys Component)

Adds an item to the Tags properties.

Syntax

• C#
• VB.NET

public void AddTag(string name, string value);

Async Version
public async Task AddTag(string name, string value);
public async Task AddTag(string name, string value, CancellationToken cancellationToken);

Public Sub AddTag(ByVal Name As String, ByVal Value As String)

Async Version
Public Sub AddTag(ByVal Name As String, ByVal Value As String) As Task
Public Sub AddTag(ByVal Name As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method adds an item to the Tags collection. Name specifies the name of the item, and Value specifies the value of the item.

Authorize Method (AzureKeys Component)

Get the authorization string required to access the protected resource.

Syntax

• C#
• VB.NET

public void Authorize();

Async Version
public async Task Authorize();
public async Task Authorize(CancellationToken cancellationToken);

Public Sub Authorize()

Async Version
Public Sub Authorize() As Task
Public Sub Authorize(cancellationToken As CancellationToken) As Task

Remarks

This method is used to get an access token that is required to access the protected resource. The method will act differently based on what is set in the ClientProfile field and the GrantType field. This method is not to be used in conjunction with the Authorization property. It should instead be used when setting the OAuth property.

For more information, see the introduction section.

BackupKey Method (AzureKeys Component)

Backs up a key.

Syntax

• C#
• VB.NET

public void BackupKey(string keyName);

Async Version
public async Task BackupKey(string keyName);
public async Task BackupKey(string keyName, CancellationToken cancellationToken);

Public Sub BackupKey(ByVal KeyName As String)

Async Version
Public Sub BackupKey(ByVal KeyName As String) As Task
Public Sub BackupKey(ByVal KeyName As String, cancellationToken As CancellationToken) As Task

Remarks

This method backs up the key specified by KeyName, returning it in a protected form via the output stream specified via the SetOutputStream method, the specified OutputFile, or the OutputData property.

Note that the protected key cannot be used outside of Azure Key Vault, it must be restored to another vault using the RestoreKey method in order to be used.

Config Method (AzureKeys Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateKey Method (AzureKeys Component)

Creates a new key.

Syntax

• C#
• VB.NET

public string CreateKey(string keyName, string keyType, string keyOps);

Async Version
public async Task<string> CreateKey(string keyName, string keyType, string keyOps);
public async Task<string> CreateKey(string keyName, string keyType, string keyOps, CancellationToken cancellationToken);

Public Function CreateKey(ByVal KeyName As String, ByVal KeyType As String, ByVal KeyOps As String) As String

Async Version
Public Function CreateKey(ByVal KeyName As String, ByVal KeyType As String, ByVal KeyOps As String) As Task(Of String)
Public Function CreateKey(ByVal KeyName As String, ByVal KeyType As String, ByVal KeyOps As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method creates a new key with the given KeyName and KeyType. If a key with the specified KeyName already exists, a new version of it is created. The version Id of the newly-created key is returned.

The value passed for KeyName must consist solely of alphanumeric characters and hyphens (-).

The KeyType parameter specifies the type of key that should be created. Each key type has two variants, a software-based one and an HSM-based one. Possible values are shown in the first two columns of the following table:

The KeyOps parameter specifies which operations the key will be valid for use with. Possible values are as follows; at least one pair of operations must be specified:

• encrypt
• decrypt
• sign
• verify
• wrapKey
• unwrapKey

If there are any items in the Tags collection, they will be applied to the newly-created key. Keys may have up to 15 tags.

The following configuration settings can also be used to send additional values when creating the key, refer to their documentation for more information:

• CreateKeyEnabled
• ExpiryDate
• NotBeforeDate

Note: If there is already a soft-deleted key with the specified KeyName in the currently-selected Vault, then a new key cannot be created with the same name. To resolve such a situation, the soft-deleted key would need to be recovered (using RecoverKey) or permanently deleted (using PurgeKey) first.

Decrypt Method (AzureKeys Component)

Decrypts data using a key.

Syntax

• C#
• VB.NET

public void Decrypt(string keyName, string algorithm);

Async Version
public async Task Decrypt(string keyName, string algorithm);
public async Task Decrypt(string keyName, string algorithm, CancellationToken cancellationToken);

Public Sub Decrypt(ByVal KeyName As String, ByVal Algorithm As String)

Async Version
Public Sub Decrypt(ByVal KeyName As String, ByVal Algorithm As String) As Task
Public Sub Decrypt(ByVal KeyName As String, ByVal Algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

This method decrypts data using the key specified by KeyName and the given Algorithm. The VersionId configuration setting can be used to target a specific key version.

The data to decrypt is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The decrypted data is output to the output stream supplied via the SetOutputStream method, the specified OutputFile, or the OutputData property.

The key specified by KeyName must be an RSA key; EC keys cannot be used for encryption/decryption.

The Algorithm parameter specifies which algorithm to use to decrypt the data; it must match the algorithm used to encrypt the data previously. Possible values are:

DeleteKey Method (AzureKeys Component)

Deletes a key.

Syntax

• C#
• VB.NET

public void DeleteKey(string keyName);

Async Version
public async Task DeleteKey(string keyName);
public async Task DeleteKey(string keyName, CancellationToken cancellationToken);

Public Sub DeleteKey(ByVal KeyName As String)

Async Version
Public Sub DeleteKey(ByVal KeyName As String) As Task
Public Sub DeleteKey(ByVal KeyName As String, cancellationToken As CancellationToken) As Task

Remarks

This method deletes the key specified by KeyName. If there are multiple versions of the key, all of them are deleted.

Note that the key is only soft-deleted; it can be recovered during the retention period using the RecoverKey method, or permanently deleted using the PurgeKey method. The length of the retention period depends on the configuration of the currently-selected Vault, refer to the Azure Key Vault documentation for more information.

DoEvents Method (AzureKeys Component)

Processes events from the internal message queue.

Syntax

• C#
• VB.NET

public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);

Public Sub DoEvents()

Async Version
Public Sub DoEvents() As Task
Public Sub DoEvents(cancellationToken As CancellationToken) As Task

Remarks

When DoEvents is called, the component processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Encrypt Method (AzureKeys Component)

Encrypts data using a key.

Syntax

• C#
• VB.NET

public void Encrypt(string keyName, string algorithm);

Async Version
public async Task Encrypt(string keyName, string algorithm);
public async Task Encrypt(string keyName, string algorithm, CancellationToken cancellationToken);

Public Sub Encrypt(ByVal KeyName As String, ByVal Algorithm As String)

Async Version
Public Sub Encrypt(ByVal KeyName As String, ByVal Algorithm As String) As Task
Public Sub Encrypt(ByVal KeyName As String, ByVal Algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

This method encrypts data using the key specified by KeyName and the given Algorithm. The VersionId configuration setting can be used to target a specific key version.

The data to encrypt is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The encrypted data is output to the output stream supplied via the SetOutputStream method, the specified OutputFile, or the OutputData property.

The key specified by KeyName must be an RSA key; EC keys cannot be used for encryption/decryption.

The Algorithm parameter specifies which algorithm to use to encrypt the data. The type of key and the selected algorithm together dictate the maximum size of the input data. Refer to the following table for possible values and maximum data sizes:

GetKeyInfo Method (AzureKeys Component)

Gets a key's information and public key.

Syntax

• C#
• VB.NET

public void GetKeyInfo(string keyName);

Async Version
public async Task GetKeyInfo(string keyName);
public async Task GetKeyInfo(string keyName, CancellationToken cancellationToken);

Public Sub GetKeyInfo(ByVal KeyName As String)

Async Version
Public Sub GetKeyInfo(ByVal KeyName As String) As Task
Public Sub GetKeyInfo(ByVal KeyName As String, cancellationToken As CancellationToken) As Task

Remarks

This method gets the information, including the public key, for the key specified by KeyName. The VersionId configuration setting can be used to target a specific key version. Alternatively, the GetDeleted configuration setting can be enabled to get a soft-deleted key's information (but only for the last version).

When the information is returned, the component clears the Keys collection and repopulates it with a single item that contains the key's information, and repopulates the Tags collection with the key's tags. The KeyList event is also fired.

ListKeys Method (AzureKeys Component)

Lists keys in the currently-selected vault.

Syntax

• C#
• VB.NET

public void ListKeys();

Async Version
public async Task ListKeys();
public async Task ListKeys(CancellationToken cancellationToken);

Public Sub ListKeys()

Async Version
Public Sub ListKeys() As Task
Public Sub ListKeys(cancellationToken As CancellationToken) As Task

Remarks

This method lists the keys in the currently-selected Vault. If the GetDeleted configuration setting is enabled, it lists the soft-deleted keys in the vault instead.

Calling this method will fire the KeyList event once for each key, and will also populate the Keys collection. However, note that by default the following fields will not be populated, since the server does not return full information for keys when listing them. The IncludeKeyDetails property can be enabled to have the component attempt to retrieve full information for each key; refer to its documentation for more information.

• KeyOps
• KeyType
• PublicKey
• VersionId

If there are still more keys available to list when this method returns, the KeyMarker property will be populated. Continue to call this method until KeyMarker is empty to accumulate all pages of results in the Keys collection.

The MaxKeys configuration setting can be used to control the maximum number of results to return at once.

ListVersions Method (AzureKeys Component)

Lists versions of a key.

Syntax

• C#
• VB.NET

public void ListVersions(string keyName);

Async Version
public async Task ListVersions(string keyName);
public async Task ListVersions(string keyName, CancellationToken cancellationToken);

Public Sub ListVersions(ByVal KeyName As String)

Async Version
Public Sub ListVersions(ByVal KeyName As String) As Task
Public Sub ListVersions(ByVal KeyName As String, cancellationToken As CancellationToken) As Task

Remarks

This method lists the versions of the key specified by KeyName.

Calling this method will fire the KeyList event once for each key version, and will also populate the Keys collection. However, note that by default the following fields will not be populated, since the server does not return full information for key versions when listing them. The IncludeKeyDetails property can be enabled to have the component attempt to retrieve full information for each key version; refer to its documentation for more information.

• KeyOps
• KeyType
• PublicKey

If there are still more key versions available to list when this method returns, the VersionMarker property will be populated. Continue to call this method until VersionMarker is empty to accumulate all pages of results in the Keys collection.

The MaxKeys configuration setting can be used to control the maximum number of results to return at once.

PurgeKey Method (AzureKeys Component)

Permanently deletes a soft-deleted key.

Syntax

• C#
• VB.NET

public void PurgeKey(string keyName);

Async Version
public async Task PurgeKey(string keyName);
public async Task PurgeKey(string keyName, CancellationToken cancellationToken);

Public Sub PurgeKey(ByVal KeyName As String)

Async Version
Public Sub PurgeKey(ByVal KeyName As String) As Task
Public Sub PurgeKey(ByVal KeyName As String, cancellationToken As CancellationToken) As Task

Remarks

This method permanently deletes the soft-deleted key specified by KeyName.

RecoverKey Method (AzureKeys Component)

Recovers a soft-deleted key.

Syntax

• C#
• VB.NET

public void RecoverKey(string keyName);

Async Version
public async Task RecoverKey(string keyName);
public async Task RecoverKey(string keyName, CancellationToken cancellationToken);

Public Sub RecoverKey(ByVal KeyName As String)

Async Version
Public Sub RecoverKey(ByVal KeyName As String) As Task
Public Sub RecoverKey(ByVal KeyName As String, cancellationToken As CancellationToken) As Task

Remarks

This method recovers the soft-deleted key specified by KeyName.

Reset Method (AzureKeys Component)

Resets the component to its initial state.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method resets the component to its initial state.

RestoreKey Method (AzureKeys Component)

Restores a previously backed-up key to the vault.

Syntax

• C#
• VB.NET

public string RestoreKey();

Async Version
public async Task<string> RestoreKey();
public async Task<string> RestoreKey(CancellationToken cancellationToken);

Public Function RestoreKey() As String

Async Version
Public Function RestoreKey() As Task(Of String)
Public Function RestoreKey(cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method restores a key previously backed up using BackupKey to the currently-selected Vault. The key is restored in its entirety, with all of its versions intact. However, note that the restore will fail if the key's name is already in use. The name of the restored key is returned.

The protected key data to restore is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property.

Note: There are certain restrictions on which vaults a key can be restored to. In particular, a key must be restored to a vault owned by the same Azure subscription that owned its original vault, and must be restored to a vault in the same geolocation as its original vault. Refer to the Azure Key Vault documentation for more information.

SendCustomRequest Method (AzureKeys Component)

Sends a custom request to the server.

Syntax

• C#
• VB.NET

public void SendCustomRequest(string httpMethod, string path);

Async Version
public async Task SendCustomRequest(string httpMethod, string path);
public async Task SendCustomRequest(string httpMethod, string path, CancellationToken cancellationToken);

Public Sub SendCustomRequest(ByVal HttpMethod As String, ByVal Path As String)

Async Version
Public Sub SendCustomRequest(ByVal HttpMethod As String, ByVal Path As String) As Task
Public Sub SendCustomRequest(ByVal HttpMethod As String, ByVal Path As String, cancellationToken As CancellationToken) As Task

Remarks

This method can be used to send arbitrary requests to the server.

Valid values for HttpMethod are:

• GET (default if empty)
• HEAD
• POST
• PUT
• PATCH
• DELETE

Path is optional, and if non-empty must be specified without a leading forward slash (/).

When this method is called, the component does the following:

1. Builds a request URL, including query parameters, based on the following:
   • The base URL https://{Vault}.vault.azure.net/keys, where {Vault} is Vault.
   • The specified Path, if any.
   • An api-version query parameter whose value is APIVersion.
   • All query parameters from QueryParams.
2. Adds an Authorization header with the value specified by Authorization.
3. Adds any request headers from OtherHeaders.
4. Adds any request body supplied via the stream specified using SetInputStream, the specified InputFile, or InputData.
5. Sends the request to the server.
6. Stores the response headers in the ParsedHeaders collection; and the response body in the stream specified using SetOutputStream, the specified OutputFile, or OutputData.

If the response body is JSON data, the XPath, XText, and other X* configuration settings can then be used to navigate and extract information from it.

SetInputStream Method (AzureKeys Component)

Sets the stream whose data should be processed.

Syntax

• C#
• VB.NET

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the stream whose data should be processed in a cryptographic operation.

Passing a non-null value for InputStream will cause the InputFile property to be cleared. Similarly, setting InputFile to a non-empty value will discard any stream set using this method.

Input Sources & Output Destinations

The component automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

SetKeyEnabled Method (AzureKeys Component)

Enables or disables a key.

Syntax

• C#
• VB.NET

public void SetKeyEnabled(string keyName, bool enabled);

Async Version
public async Task SetKeyEnabled(string keyName, bool enabled);
public async Task SetKeyEnabled(string keyName, bool enabled, CancellationToken cancellationToken);

Public Sub SetKeyEnabled(ByVal KeyName As String, ByVal Enabled As Boolean)

Async Version
Public Sub SetKeyEnabled(ByVal KeyName As String, ByVal Enabled As Boolean) As Task
Public Sub SetKeyEnabled(ByVal KeyName As String, ByVal Enabled As Boolean, cancellationToken As CancellationToken) As Task

Remarks

This method enables or disables the key specified by KeyName.

SetOutputStream Method (AzureKeys Component)

Sets the stream to which output data should be written.

Syntax

• C#
• VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the stream to which data output from a successful cryptographic operation should be written.

Passing a non-null value for OutputStream will cause the OutputFile property to be cleared. Similarly, setting OutputFile to a non-empty value will discard any stream set using this method.

Input Sources & Output Destinations

The component automatically determines the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

1. An input stream supplied via the SetInputStream method
2. The InputFile property
3. The InputData property

The first valid input source found is used. The order in which the output properties are considered is as follows:

1. An output stream supplied via the SetOutputStream method
2. The OutputFile property
3. The OutputData property

Sign Method (AzureKeys Component)

Signs a message using a key.

Syntax

• C#
• VB.NET

public void Sign(string keyName, string algorithm, bool isDigest);

Async Version
public async Task Sign(string keyName, string algorithm, bool isDigest);
public async Task Sign(string keyName, string algorithm, bool isDigest, CancellationToken cancellationToken);

Public Sub Sign(ByVal KeyName As String, ByVal Algorithm As String, ByVal IsDigest As Boolean)

Async Version
Public Sub Sign(ByVal KeyName As String, ByVal Algorithm As String, ByVal IsDigest As Boolean) As Task
Public Sub Sign(ByVal KeyName As String, ByVal Algorithm As String, ByVal IsDigest As Boolean, cancellationToken As CancellationToken) As Task

Remarks

This method signs a message using the key specified by KeyName and the given Algorithm. The VersionId configuration setting can be used to target a specific key version.

The message data to sign is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The signature data is output to the output stream supplied via the SetOutputStream method, the specified OutputFile, or the OutputData property.

The Algorithm parameter specifies which algorithm to use to sign the data. Possible values are:

• ES256: ECDSA using P-256 and SHA-256.
• ES256K: ECDSA using P-256K and SHA-256.
• ES384: ECDSA using P-384 and SHA-384.
• ES512: ECDSA using P-521 and SHA-512.
• PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256.
• PS384: RSASSA-PSS using SHA-384 and MGF1 with SHA-384.
• PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512.
• RS256: RSASSA-PKCS1-v1_5 using SHA-256.
• RS384: RSASSA-PKCS1-v1_5 using SHA-384.
• RS512: RSASSA-PKCS1-v1_5 using SHA-512.

The IsDigest parameter specifies whether the message data is the original message (false) or a message digest (true). When supplying a message digest, keep in mind that the same digest will need to be provided in order to Verify the signature later.

If IsDigest is false, the component will automatically compute an appropriate message digest before the request is made. In such cases, the computed digest is made available via the MessageDigest configuration setting.

UnwrapKey Method (AzureKeys Component)

Unwraps a symmetric key.

Syntax

• C#
• VB.NET

public void UnwrapKey(string keyName, string algorithm);

Async Version
public async Task UnwrapKey(string keyName, string algorithm);
public async Task UnwrapKey(string keyName, string algorithm, CancellationToken cancellationToken);

Public Sub UnwrapKey(ByVal KeyName As String, ByVal Algorithm As String)

Async Version
Public Sub UnwrapKey(ByVal KeyName As String, ByVal Algorithm As String) As Task
Public Sub UnwrapKey(ByVal KeyName As String, ByVal Algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

This method unwraps (i.e., decrypts) a symmetric key using the key specified by KeyName and the given Algorithm.

This method functions exactly the same way as the Decrypt method, except that it requires the keys/unwrapKey permission instead of the keys/decrypt permission. Refer to the Decrypt method's documentation for more information.

UpdateKey Method (AzureKeys Component)

Updates a key's information.

Syntax

• C#
• VB.NET

public void UpdateKey(string keyName, string keyOps, bool updateTags);

Async Version
public async Task UpdateKey(string keyName, string keyOps, bool updateTags);
public async Task UpdateKey(string keyName, string keyOps, bool updateTags, CancellationToken cancellationToken);

Public Sub UpdateKey(ByVal KeyName As String, ByVal KeyOps As String, ByVal UpdateTags As Boolean)

Async Version
Public Sub UpdateKey(ByVal KeyName As String, ByVal KeyOps As String, ByVal UpdateTags As Boolean) As Task
Public Sub UpdateKey(ByVal KeyName As String, ByVal KeyOps As String, ByVal UpdateTags As Boolean, cancellationToken As CancellationToken) As Task

Remarks

This method updates the information for the key specified by KeyName. The VersionId configuration setting can be used to target a specific key version.

The KeyOps parameter, if non-empty, must be a comma-separated list of operations that the key is valid for. If empty, the key's current operations list remains unchanged. Possible values are as follows; operations should be specified in pairs:

• encrypt
• decrypt
• sign
• verify
• wrapKey
• unwrapKey

The UpdateTags parameter determines whether the component replaces the key's current tags with the items in the Tags collection (which may be empty). Keys may have up to 15 tags.

The ExpiryDate and NotBeforeDate configuration settings may also be used to send additional values, refer to their documentation for more information.

Verify Method (AzureKeys Component)

Verifies a digital signature using a key.

Syntax

• C#
• VB.NET

public bool Verify(string keyName, string algorithm, bool isDigest);

Async Version
public async Task<bool> Verify(string keyName, string algorithm, bool isDigest);
public async Task<bool> Verify(string keyName, string algorithm, bool isDigest, CancellationToken cancellationToken);

Public Function Verify(ByVal KeyName As String, ByVal Algorithm As String, ByVal IsDigest As Boolean) As Boolean

Async Version
Public Function Verify(ByVal KeyName As String, ByVal Algorithm As String, ByVal IsDigest As Boolean) As Task(Of Boolean)
Public Function Verify(ByVal KeyName As String, ByVal Algorithm As String, ByVal IsDigest As Boolean, cancellationToken As CancellationToken) As Task(Of Boolean)

Remarks

This method verifies a digital signature using the key specified by KeyName and the given Algorithm. The VersionId configuration setting can be used to target a specific key version. If the signature is successfully verified, this method returns true, otherwise it returns false.

The message data is taken from the input stream supplied via the SetInputStream method, the specified InputFile, or the InputData property. The digital signature data is taken from the specified OutputFile or the OutputData property.

The Algorithm parameter specifies which algorithm was used to sign the data. Possible values are:

• ES256: ECDSA using P-256 and SHA-256.
• ES256K: ECDSA using P-256K and SHA-256.
• ES384: ECDSA using P-384 and SHA-384.
• ES512: ECDSA using P-521 and SHA-512.
• PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256.
• PS384: RSASSA-PSS using SHA-384 and MGF1 with SHA-384.
• PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512.
• RS256: RSASSA-PKCS1-v1_5 using SHA-256.
• RS384: RSASSA-PKCS1-v1_5 using SHA-384.
• RS512: RSASSA-PKCS1-v1_5 using SHA-512.

The IsDigest parameter specifies whether the message data is the original message (false) or a message digest (true). When a message digest is supplied, keep in mind that it must be the exact same digest that was used at signing time, regardless of whether it has been recomputed.

If IsDigest is false, the component will automatically compute an appropriate message digest before the request is made. In such cases, the computed digest is made available via the MessageDigest configuration setting.

WrapKey Method (AzureKeys Component)

Wraps a symmetric key.

Syntax

• C#
• VB.NET

public void WrapKey(string keyName, string algorithm);

Async Version
public async Task WrapKey(string keyName, string algorithm);
public async Task WrapKey(string keyName, string algorithm, CancellationToken cancellationToken);

Public Sub WrapKey(ByVal KeyName As String, ByVal Algorithm As String)

Async Version
Public Sub WrapKey(ByVal KeyName As String, ByVal Algorithm As String) As Task
Public Sub WrapKey(ByVal KeyName As String, ByVal Algorithm As String, cancellationToken As CancellationToken) As Task

Remarks

This method wraps (i.e., encrypts) a symmetric key using the key specified by KeyName and the given Algorithm. The VersionId configuration setting can be used to target a specific key version.

This method functions exactly the same way as the Encrypt method, except that it requires the keys/wrapKey permission instead of the keys/encrypt permission. Refer to the Encrypt method's documentation for more information.

EndTransfer Event (AzureKeys Component)

This event fires when a document finishes transferring.

Syntax

• C#
• VB.NET

public event OnEndTransferHandler OnEndTransfer;

public delegate void OnEndTransferHandler(object sender, AzurekeysEndTransferEventArgs e);

public class AzurekeysEndTransferEventArgs : EventArgs {
  public int Direction { get; }
}

Public Event OnEndTransfer As OnEndTransferHandler

Public Delegate Sub OnEndTransferHandler(sender As Object, e As AzurekeysEndTransferEventArgs)

Public Class AzurekeysEndTransferEventArgs Inherits EventArgs
  Public ReadOnly Property Direction As Integer
End Class

Remarks

The EndTransfer event is fired when the document text finishes transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

Error Event (AzureKeys Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, AzurekeysErrorEventArgs e);

public class AzurekeysErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As AzurekeysErrorEventArgs)

Public Class AzurekeysErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Header Event (AzureKeys Component)

This event is fired every time a header line comes in.

Syntax

• C#
• VB.NET

public event OnHeaderHandler OnHeader;

public delegate void OnHeaderHandler(object sender, AzurekeysHeaderEventArgs e);

public class AzurekeysHeaderEventArgs : EventArgs {
  public string Field { get; }
  public string Value { get; }
}

Public Event OnHeader As OnHeaderHandler

Public Delegate Sub OnHeaderHandler(sender As Object, e As AzurekeysHeaderEventArgs)

Public Class AzurekeysHeaderEventArgs Inherits EventArgs
  Public ReadOnly Property Field As String
  Public ReadOnly Property Value As String
End Class

Remarks

The Field parameter contains the name of the HTTP header (which is the same as it is delivered). The Value parameter contains the header contents.

If the header line being retrieved is a continuation header line, then the Field parameter contains "" (empty string).

KeyList Event (AzureKeys Component)

Fires once for each key when listing keys.

Syntax

• C#
• VB.NET

public event OnKeyListHandler OnKeyList;

public delegate void OnKeyListHandler(object sender, AzurekeysKeyListEventArgs e);

public class AzurekeysKeyListEventArgs : EventArgs {
  public string Name { get; }
  public string VersionId { get; }
  public string KeyType { get; }
  public string KeyOps { get; }
  public bool Enabled { get; }
  public long CreationDate { get; }
  public long UpdateDate { get; }
  public long DeletionDate { get; }
  public long PurgeDate { get; }
  public string PublicKey { get; }
}

Public Event OnKeyList As OnKeyListHandler

Public Delegate Sub OnKeyListHandler(sender As Object, e As AzurekeysKeyListEventArgs)

Public Class AzurekeysKeyListEventArgs Inherits EventArgs
  Public ReadOnly Property Name As String
  Public ReadOnly Property VersionId As String
  Public ReadOnly Property KeyType As String
  Public ReadOnly Property KeyOps As String
  Public ReadOnly Property Enabled As Boolean
  Public ReadOnly Property CreationDate As Long
  Public ReadOnly Property UpdateDate As Long
  Public ReadOnly Property DeletionDate As Long
  Public ReadOnly Property PurgeDate As Long
  Public ReadOnly Property PublicKey As String
End Class

Remarks

This event fires once for each key (or key version) returned when ListKeys, ListVersions, or GetKeyInfo is called. However, note that the KeyOps, KeyType, PublicKey, and (for ListKeys) VersionId parameters are not populated when one of the listing methods is called unless the IncludeKeyDetails property is enabled; refer to its documentation for more information.

Name reflects the name of the key.

VersionId reflects the Id of the key version.

KeyType reflects the key's type. Each key type has two variants, a software-based one and an HSM-based one. Possible values are shown in the first two columns of the following table:

KeyOps reflects a comma-separated list of operations that the key may be used for. Possible values are:

• encrypt
• decrypt
• sign
• verify
• wrapKey
• unwrapKey

Enabled reflects whether the key is currently enabled.

CreationDate reflects the key's creation date, in seconds since the Unix epoch.

UpdateDate reflects the key's update date, in seconds since the Unix epoch.

DeletionDate reflects the key's deletion date, in seconds since the Unix epoch, or -1 if the key has not been deleted.

PurgeDate reflects the key's purge (i.e., permanent deletion) date, in seconds since the Unix epoch, or -1 if the key has not been deleted.

PublicKey reflects the key's public key, in PEM format.

Log Event (AzureKeys Component)

This event fires once for each log message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, AzurekeysLogEventArgs e);

public class AzurekeysLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As AzurekeysLogEventArgs)

Public Class AzurekeysLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event fires once for each log message generated by the component. The verbosity is controlled by the LogLevel setting.

LogLevel indicates the level of message. Possible values are as follows:

The value 1 (Info) logs basic information, including the URL, HTTP version, and status details.

The value 2 (Verbose) logs additional information about the request and response.

The value 3 (Debug) logs the headers and body for both the request and response, as well as additional debug information (if any).

Message is the log entry.

LogType identifies the type of log entry. Possible values are as follows:

• "Info"
• "RequestHeaders"
• "ResponseHeaders"
• "RequestBody"
• "ResponseBody"
• "ProxyRequest"
• "ProxyResponse"
• "FirewallRequest"
• "FirewallResponse"

SSLServerAuthentication Event (AzureKeys Component)

Fired after the server presents its certificate to the client.

Syntax

• C#
• VB.NET

public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication;

public delegate void OnSSLServerAuthenticationHandler(object sender, AzurekeysSSLServerAuthenticationEventArgs e);

public class AzurekeysSSLServerAuthenticationEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string Status { get; }
  public bool Accept { get; set; }
}

Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler

Public Delegate Sub OnSSLServerAuthenticationHandler(sender As Object, e As AzurekeysSSLServerAuthenticationEventArgs)

Public Class AzurekeysSSLServerAuthenticationEventArgs Inherits EventArgs
  Public ReadOnly Property CertEncoded As String
  Public ReadOnly Property CertEncodedB As Byte()
  Public ReadOnly Property CertSubject As String
  Public ReadOnly Property CertIssuer As String
  Public ReadOnly Property Status As String
  Public Property Accept As Boolean
End Class

Remarks

This event is where the client can decide whether to continue with the connection process or not. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether to continue or not.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string "OK"). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

SSLStatus Event (AzureKeys Component)

Shows the progress of the secure connection.

Syntax

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

public delegate void OnSSLStatusHandler(object sender, AzurekeysSSLStatusEventArgs e);

public class AzurekeysSSLStatusEventArgs : EventArgs {
  public string Message { get; }
}

Public Event OnSSLStatus As OnSSLStatusHandler

Public Delegate Sub OnSSLStatusHandler(sender As Object, e As AzurekeysSSLStatusEventArgs)

Public Class AzurekeysSSLStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Message As String
End Class

Remarks

The event is fired for informational and logging purposes only. Used to track the progress of the connection.

StartTransfer Event (AzureKeys Component)

This event fires when a document starts transferring (after the headers).

Syntax

• C#
• VB.NET

public event OnStartTransferHandler OnStartTransfer;

public delegate void OnStartTransferHandler(object sender, AzurekeysStartTransferEventArgs e);

public class AzurekeysStartTransferEventArgs : EventArgs {
  public int Direction { get; }
}

Public Event OnStartTransfer As OnStartTransferHandler

Public Delegate Sub OnStartTransferHandler(sender As Object, e As AzurekeysStartTransferEventArgs)

Public Class AzurekeysStartTransferEventArgs Inherits EventArgs
  Public ReadOnly Property Direction As Integer
End Class

Remarks

The StartTransfer event is fired when the document text starts transferring from the server to the local host.

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

TagList Event (AzureKeys Component)

Fires once for each tag returned when a key's information is retrieved.

Syntax

• C#
• VB.NET

public event OnTagListHandler OnTagList;

public delegate void OnTagListHandler(object sender, AzurekeysTagListEventArgs e);

public class AzurekeysTagListEventArgs : EventArgs {
  public string KeyName { get; }
  public string VersionId { get; }
  public string Name { get; }
  public string Value { get; }
}

Public Event OnTagList As OnTagListHandler

Public Delegate Sub OnTagListHandler(sender As Object, e As AzurekeysTagListEventArgs)

Public Class AzurekeysTagListEventArgs Inherits EventArgs
  Public ReadOnly Property KeyName As String
  Public ReadOnly Property VersionId As String
  Public ReadOnly Property Name As String
  Public ReadOnly Property Value As String
End Class

Remarks

This event fires once for each tag returned when GetKeyInfo is called.

KeyName reflects the name of the key.

VersionId reflects the Id of the key version.

Name reflects the name of the tag.

Value reflects the value of the tag.

Transfer Event (AzureKeys Component)

This event is fired while a document transfers (delivers document).

Syntax

• C#
• VB.NET

public event OnTransferHandler OnTransfer;

public delegate void OnTransferHandler(object sender, AzurekeysTransferEventArgs e);

public class AzurekeysTransferEventArgs : EventArgs {
  public int Direction { get; }
  public long BytesTransferred { get; }
  public int PercentDone { get; }
  public string Text { get; }
  public byte[] TextB { get; }
}

Public Event OnTransfer As OnTransferHandler

Public Delegate Sub OnTransferHandler(sender As Object, e As AzurekeysTransferEventArgs)

Public Class AzurekeysTransferEventArgs Inherits EventArgs
  Public ReadOnly Property Direction As Integer
  Public ReadOnly Property BytesTransferred As Long
  Public ReadOnly Property PercentDone As Integer
  Public ReadOnly Property Text As String
  Public ReadOnly Property TextB As Byte()
End Class

Remarks

The Text parameter contains the portion of the document text being received. It is empty if data are being posted to the server.

The BytesTransferred parameter contains the number of bytes transferred in this Direction since the beginning of the document text (excluding HTTP response headers).

The Direction parameter shows whether the client (0) or the server (1) is sending the data.

The PercentDone parameter shows the progress of the transfer in the corresponding direction. If PercentDone can not be calculated the value will be -1.

Note: Events are not re-entrant. Performing time-consuming operations within this event will prevent it from firing again in a timely manner and may affect overall performance.

AzureKey Type

An Azure Key Vault key.

Remarks

This type represents an Azure Key Vault key.

Fields

AzureTag Type

An Azure Key Vault tag.

Remarks

This type represents an Azure Key Vault tag.

Fields

Constructors

• C#
• VB.NET

public AzureTag();

Public AzureTag()

• C#
• VB.NET

public AzureTag(string name, string value);

Public AzureTag(ByVal Name As String, ByVal Value As String)

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X509 public key.

• C#
• VB.NET

public Certificate(byte[] certificateData);

Public Certificate(ByVal CertificateData As Byte())

Parses CertificateData as an X509 public key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

Firewall Type

This is the firewall the component will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

Fields

Constructors

• C#
• VB.NET

public Firewall();

Public Firewall()

Header Type

This is an HTTP header as it is received from the server.

Remarks

When a header is received through a Header event, it is parsed into a Header type. This type contains a Field, and its corresponding Value.

Fields

Constructors

• C#
• VB.NET

public Header();

Public Header()

• C#
• VB.NET

public Header(string field, string value);

Public Header(ByVal Field As String, ByVal Value As String)

OAuthSettings Type

The settings to use to authenticate with the service provider.

Remarks

Used to set give the component the necessary information needed to complete OAuth authentication.

Fields

Constructors

• C#
• VB.NET

public OAuthSettings();

Public OAuthSettings()

Proxy Type

This is the proxy the component will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

Fields

Constructors

• C#
• VB.NET

public Proxy();

Public Proxy()

• C#
• VB.NET

public Proxy(string server, int port);

Public Proxy(ByVal Server As String, ByVal Port As Integer)

• C#
• VB.NET

public Proxy(string server, int port, string user, string password);

Public Proxy(ByVal Server As String, ByVal Port As Integer, ByVal User As String, ByVal Password As String)

QueryParam Type

A query parameter to send in the request.

Remarks

This type represents a query parameter to send in the request.

Fields

Constructors

• C#
• VB.NET

public QueryParam();

Public QueryParam()

• C#
• VB.NET

public QueryParam(string name, string value);

Public QueryParam(ByVal Name As String, ByVal Value As String)

Config Settings (AzureKeys Component)

AzureKeys Config Settings

<firstlevel>
  <one>value</one>
  <two>
    <item>first</item>
    <item>second</item>
  </two>
  <three>value three</three>
</firstlevel>

{
  "firstlevel": {
    "one": "value",
    "two": ["first", "second"],
    "three": "value three"
  }
}

HTTP Config Settings