The FE_POLICY_ALGORITHM structure specifies the encryption algorithm and associated information. This information is used by FESF to call CNG.
Starting with FESF V1.11, the preferred way of specifying encryption algorithms is using the “new style” specification by setting the FesfPolicyAlgorithmVersion field to FE2_POLICY_ALGORITHM_VERSION::VERSION2. This is described in more detail below.
typedef struct _FE_POLICY_ALGORITHM {
LPCWSTR PolUniqueAlgorithmId;
LPCWSTR CNGAlgorithmIdentifier;
LPCWSTR CNGAlgorithmImplementation;
DWORD PropertiesCount;
union {
struct {
bool UseESSIV;
UCHAR Mbz1; // Must be zero
UCHAR Mbz2; // Must be zero
UCHAR Mbz3; // Must be zero
};
struct {
bool UseESSIV;
FE2_POLICY_ALGORITHM_VERSION FesfPolicyAlgorithmVersion;
UCHAR Mbz2; // Must be zero
UCHAR Mbz3; // Must be zero
FE2_POLICY_CRYPTO_TYPE CryptoType;
FE2_POLICY_KEY_LENGTH KeyLength;
} FesfPolicyAlgoV2;
FE_POLICY_ALGORITHM_PROPERTY Properties[1];
} FE_POLICY_ALGORITHM;
PolUniqueAlgorithmId
A pointer to a Policy DLL defined null-terminated constant wide character string, that will be used to identify this particular algorithm and specified properties. The Policy DLL provides this string as an output from its PolGetKeyNewFile and PolGetKeyFromHeader callback functions.
CNGAlgorithmIdentifier
A pointer to a null-terminated, constant, wide
character string that will be used by FESF to identify the requested
cryptographic algorithm to CNG. Strings for standard CNG algorithms (such
as BCRYPT_AES_ALGORITHM) are defined in the
standard Windows header file bcrypt.h. The string provided here by the
Policy DLL will be provided to CNG as the pszAlgId argument when
FESF calls BCryptOpenAlgorithmProvider.
See the MSDN documentation for that function for more information.
When
FesfPolicyAlgorithmVersion is set to
FE2_POLICY_ALGORITHM_VERSION::VERSION2, this value is ignored except for
custom cryptographic algorithm providers.
CNGAlgorithmImplementation
A pointer to a null-terminated, constant, wide character string that identifies the specific cryptographic algorithm provider to load. This parameter is optional and is typically NULL. FESF provides this value as the pszImplementation argument when it calls BCryptOpenAlgorithmProvider. See the MSDN documentation for that function for more information.
When FesfPolicyAlgorithmVersion is set to FE2_POLICY_ALGORITHM_VERSION::VERSION2, this value is ignored except for custom cryptographic algorithm providers.
UseESSIV
Set to ‘true’ to have FESF generate and pass an Encrypted salt-sector initialization vector (ESSIV) to CNG when encrypting each block. This parameter is provided for historic compatibility only, with the earliest versions of FESF, and must be set to true. Failure to set this value to ‘true’ in versions of FESF prior to V1.11 will result in non-standard and insecure encryption. FESF V1.11 and later check to ensure this value is set to ‘true’ and will return an error during FESF initialization if it is not and when the default (legacy) style algorithm specification (POLICY_ALGORITHM_VERSION::VERSION1) is being used.
When FesfPolicyAlgorithmVersion is set to FE2_POLICY_ALGORITHM_VERSION::VERSION2, this value is ignored except for custom cryptographic algorithm providers.
FesfPolicyAlgoV2 union
This union allows “new style, simplified” encryption algorithm specification. This is the only style of encryption algorithm specification that will be supported in FESF V2.
When using the new style encryption algorithm specification, the only fields set by the Solution Policy DLL are
PolUniqueAlgorithmId (described above) and FesfPolicyAlgorithmVersion, CryptoType and KeyLength (all three of these are described below). When the CryptoType is FE2_POLICY_CRYPTO_TYPE::CUSTOM (only) the CNGAlgorithmIdentifier, CNGAlgorithmImplementation and UseESSIV fields (described above) are also used.
Important: PropertiesCount and Properties are never used (and are ignored) in the new style algorithm specification. This is true even when the CryptoType is FE2_POLICY_CRYPTO_TYPE::CUSTOM. FESF V1.11 and later check to ensure that when CryptoType is FE2_POLICY_CRYPTO_TYPE::CUSTOM, the PropertiesCount is zero and will return an error during FESF initialization if it is not zero. See more details in the Remarks section, below. Contact the FESF support team if you have questions about implementing your own cryptographic provider using the new style interface.
FesfPolicyAlgorithmVersion
Specify FE2_POLICY_ALGORITHM_VERSION::VERSION2 to use the new style encryption algorithm specification, as supported in FESF V2. Optionally, you can set this field to FE2_POLICY_ALGORITHM_VERSION::VERSION1 to use the original algorithm specification method.
CryptoType
Specify one of the following values to select the cryptographic algorithm to use:
FE2_POLICY_CRYPTO_TYPE::AES_CBC_ESSIV – This selects the “standard” FESF encryption algorithm that has been historically used by almost all FESF licensees.
FE2_POLICY_CRYPTO_TYPE::AES_XTS – This selects AES with XTS mode; This option will be available in FESF V2, but is not currently supported in FESF V1.
FE2_POLICY_CRYPTO_TYPE::CUSTOM – This selects a custom-developed crypto algorithm provider.
KeyLength
Specify one of the following values:
FE2_POLICY_KEY_LENGTH::BITS_128 (this value is not valid with AES_XTS)
FE2_POLICY_KEY_LENGTH::BITS_256
FE2_POLICY_KEY_LENGTH::BITS_512 (this value is not valid with AES_CBC_ESSIV)
Note that this
value is currently unimplemented and is ignored in FESF V1.11.
For AES_XTS, this length specifies the size of the key PAIR that’s being used. The pair of keys is provided by the Policy DLL as a single concatenated value. Thus, for XTS mode, specifying BITS_256 indicates that two (concatenated) 128 bit keys will be supplied by the Policy DLL in a single 256 bit buffer.
PropertiesCount
A count of the number of properties provided in the Properties member of this structure. For FE2_POLICY_ALGORITHM_VERSION::VERSION2 this field is must be zero.
Properties
A vector of FE_POLICY_ALGORITHM_PROPERTY structures, each of which defines a specific algorithm property. For FE2_POLICY_ALGORITHM_VERSION::VERSION2 this field is ignored.
Starting with FESF V1.11, we recommend using new style encryption algorithm selection by setting the FesfPolicyAlgorithmVersion field to FE2_POLICY_ALGORITHM_VERSION::VERSION2. This will be the only specification method available in FESF V2.
Note that the KeyLength field that is present in new style encryption algorithm selection is currently unused by FESF as of FESF V1.11 (and the KeyLength is thus determined as it has previously, according to the length returned by the Solution Policy DLL on calls that return key material).
When using legacy encryption algorithm selection (setting the FesfPolicyAlgorithmVersion field to FE2_POLICY_ALGORITHM_VERSION::VERSION1 or simply allowing it to default to zero) and using AES encryption, you must specify a single property setting the chaining mode to CBC. You also must set UseESSIV to true. This is illustrated in the supplied Sample Solution (see the code in the UM_SAMPLE Visual Studio Solution, the module SampPolicy, the file SampPolicy.cpp, the function PolicyDllInit). Failure to set these options properly will cause unanticipated results, including potential insecure cryptographic methods being used on your user’s data. As noted above, when using new style encryption algorithm selection (by setting the FesfPolicyAlgorithmVersion field to FE2_POLICY_ALGORITHM_VERSION::VERSION2) these details are handled automatically by FESF when you set CryptoType to FE2_POLICY_CRYPTO_TYPE::AES_CBC_ESSIV.
Important notes for developers/users of custom cryptographic algorithm providers (only):
o FESF assumes the cryptographic block size is 16 bytes (as it is in AES)
o FESF uses an encryption block size of 256 bytes; This is the interval at which we compute a new offset and (if specified) ESSIV.
o When using a custom cryptographic algorithm, if you set UseESSIV to true FESF will compute the 16 byte ESSIV (as described elsewhere in this document) and pass a pointer to it to your crypto algorithm (as the pbIV and cbIV) on calls to BCryptEncrypt and BCryptDecrypt. If you set UseESSIV to false FESF will pass a pointer to a 16-byte buffer containing the byte offset of the block being encrypted to your crypto algorithm (as the pbIV and cbIV) on calls to BCryptEncrypt and BCryptDecrypt. These two options should allow you to perform whatever type of encryption you need.
o When using legacy encryption algorithm selection (setting the FesfPolicyAlgorithmVersion field to FE2_POLICY_ALGORITHM_VERSION::VERSION1) you may set algorithm properties by specifying the PropertiesCount and Properties vector. FESF does not provide a way to specify key properties.
o Note again that when using new style encryption algorithm selection, algorithm or key properties are never used and may not be specified, even if you are using a custom provider. The PropertiesCount and Properties vector are ignored. However, specifying properties should never be necessary. If you using AES CBC ESSIV, FESF will automatically set the CBC mode property. If you are using a custom crypto algorithm provider, your custom algorithm provider must internally set or manage any properties required.
|
Software version |
FESF V1 (and later) |
|
Header |
PolDllApi.h |