An implementation of the CNG (Cryptography, Next Generation) security system is implemented on the Xbox One console.
CNG is intended for use by developers of apps that will enable users to create and exchange documents and other data in a secure environment, especially over nonsecure media such as the Internet.
The CNG API provides a set of functions that perform basic cryptographic operations such as creating hashes or encrypting and decrypting data. CNG implements numerous cryptographic algorithms. Each algorithm or class of algorithms exposes its own primitive API. Multiple implementations of a given algorithm can be installed at the same time; however, only one implementation will be the default at any given time.
For more information on the overall concepts of security refer to Security and Identity. Consider conducting a threat model analysis of your application, in particular deciding what needs to be encrypted and noting that some storage is already encrypted. For Xbox One consider the following scenarios.
Each algorithm class in CNG is represented by a primitive router. Applications using the CNG primitive functions will link to the router binary file—Bcrypt.dll in user mode, or cng.sys in kernel mode—before calling the functions. Various router routines manage all of the algorithm primitives. These routers track each algorithm implementation installed on the system and route each function call to the appropriate primitive provider module.
CNG provides primitives for the following classes of algorithms.
| Algorithm class | Description |
|---|---|
| Random number generator | Pluggable random number generation (RNG). |
| Hashing | Algorithms used for hashing, such as SHA1 and SHA2. |
| Symmetric encryption | Algorithms used for symmetric encryption, such as AES, 3DES, and RC4. |
| Asymmetric encryption | Asymmetric (public key) algorithms that support encryption, such as RSA. |
| Signature | Signature algorithms such as DSA and ECDSA. This class can also be used with RSA. |
| Secret agreement | Secret agreement algorithms such as Diffie-Hellman (DH) and elliptic curve Diffie-Hellman (ECDH). |
The CNG API implements an extensible provider model that lets you load a provider by specifying the required cryptographic algorithm rather than a particular provider. The advantage is that an algorithm provider can be replaced or upgraded and you will not have to change your code in any way to use the new provider. Also, if some algorithm is determined to be unsafe in the future, a more secure version of that algorithm can be installed without affecting your code. Most of the CNG APIs require a provider or an object created by a provider.
The typical steps involved in using the CNG API for cryptographic primitive operations are as follows:
The BCryptOpenAlgorithmProvider function provides you with an algorithm provider handle that is used in subsequent CNG APIs, such as BCryptCreateHash or BCryptGenerateKeyPair.
You can use the algorithm provider handle to get implementation details for the algorithm, such as the key size or the current mode of operation. You use the BCryptGetProperty function to obtain specific properties. You can also modify the properties of the algorithm. For example, If you want to use ECB block cipher chaining with AES, you set the BCRYPT_CHAINING_MODE property of an AES algorithm to BCRYPT_CHAIN_MODE_ECB; the property is assigned to all AES keys created using this algorithm handle, without the need to configure each and every AES key. You use the BCryptSetProperty function to modify these properties.
Depending on the type of algorithm you use, you may need to create or load a key. For example, the BCryptEncrypt function takes a key handle for the first parameter. If you want that function to encrypt data with a symmetric encryption algorithm such as AES, you must first obtain a key. How you obtain the key depends on the type of algorithm being used and the source of the key.
You can create ephemeral keys with the BCryptGenerateSymmetricKey and BCryptGenerateKeyPair functions. You can also import ephemeral keys from a memory BLOB with the BCryptImportKey and BCryptImportKeyPair functions.
For persisted keys, you use the key storage functions to load a key storage provider, and then create or load the keys. You can also use these functions to create or load ephemeral keys by passing NULL for any container names.
You are now ready to perform the cryptographic operation, such as encrypting or decrypting data by using the BCryptEncrypt or BCryptDecrypt functions, respectively.
When the provider is no longer needed, you must pass the handle to the BCryptCloseAlgorithmProvider function to close the provider. This causes the provider to release any resources that have been allocated for that algorithm provider instance. After a provider handle is closed, it cannot be reused.
Loading a provider can be a relatively time-intensive process. You should therefore cache any provider handles that you will reference multiple times during the lifetime of your application.
The following examples (from MSDN for the Windows platform) describe how to perform specific cryptographic operations using CNG.