NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Shared Name Cryptographic Key Management

A set of helper APIs are provided to support key generation and management by compiler vendors. These are designed to provide the flexibility needed to address common development scenarios while still being easy to use.

Using these APIs, it is possible for compilers to:

In addition, the design provides assurance that shared name key operations will not impact the use of cryptographic functionality by other applications on the user’s machine.

Typical scenarios supported include:

In using these APIs, the following cautionary issues should be considered.

Key Management APIs

The following function will create a new key pair for shared name use and export it to the calling program.

   BOOL StrongNameKeyGen(  
      // [in] desired key container name, must be a non-empty string
      LPCWSTR         szKeyContainer, 
      // [in] flag parameter, leave key installed is only option 
      DWORD            dwFlags,
      // [out] public/private key blob
      BYTE            **ppbKeyBlob,
      ULONG            *pcbKeyBlob)

The container name is a user defined string. CryptoAPI does not specify a size limit on this string, but individual CSPs may. It should generally be a short descriptive name. We allow user defined names so that multiple shared name keypairs (e.g., project1 vs project2, test vs deploy) can be managed. The dwFlags parameter is used to control optional actions. The only defined flag for this version is SN_LEAVE_KEY (value is 1). If set, then the key pair will be left installed in the shared name CSP.

This function will attempt to create a new signing keypair using the supplied container name. The CSP to use, and signing algorithm, are determined by the default settings described earlier.

The generated key will be marked exportable (if supported by the CSP) and the public/private keys exported in an unencrypted keyblob. This is returned to the caller. The keyblob may be stored in any way convenient for the calling application. If modified, it will no longer be usable.

To simplify use of this, and other functions, we will allocate the buffer to hold the protable key blob. The calling program should call StrongNameFreeBuffer() when the buffer is no longer needed to insure its properly de-allocated.

The following function may be used to install a portable key blob into a machine CSP. Its purpose is to support installation of default shared name keys.

   BOOL StrongNameKeyInstall(  
      // [in] desired key container name, must be a non-empty string
      LPCWSTR        szKeyContainer, 
      // [in] public/private key blob
      BYTE            *pbKeyBlob,
      ULONG            cbKeyBlob)

This function attempts to install the key pair provided in the key blob into the shared name CSP using the provided container name. If the container name already exists or an invalid key blob is supplied, an error is returned.

The following function may be used to delete a shared name key pair from the CSP. This will only be required if the SN_LEAVE_KEY option was selected at key generation time, or the key was subsequently installed loaded into the CSP. UI should make it very clear to the user that this will result in permanent deletion of the keys. If the corresponding portable key blob was not stored, they will be unable to create any future shared names in the associated namespace.

   BOOL StrongNameKeyDelete(  
      // [in] desired key container name
      LPCWSTR         szContainer)

This function will acquire the shared name CSP context for the given key container name with the flag CRYPT_DELETEKEYSET.

The following function is used to free memory allocated by the shared name functions.

VOID StrongNameFreeBuffer(
   // [in] pointer to memory to be freed
   BYTE            *pbMemory)

pbMemory should only refer to memory allocated by the shared name functions when return key blobs to the calling program.