2.2.74 FW_CRYPTO_SET

  • Article

This structure contains a list of cryptographic suite elements that are ordered from highest to lowest preference and are negotiated with remote peers to establish cryptographic protection algorithms.

 typedef struct _tag_FW_CRYPTO_SET {
   struct _tag_FW_CRYPTO_SET* pNext;
   unsigned short wSchemaVersion;
   [range(FW_IPSEC_PHASE_INVALID+1, FW_IPSEC_PHASE_MAX-1)] 
     FW_IPSEC_PHASE IpSecPhase;
   [string, range(1,255), ref] wchar_t* wszSetId;
   [string, range(1,10001)] wchar_t* wszName;
   [string, range(1,10001)] wchar_t* wszDescription;
   [string, range(1,10001)] wchar_t* wszEmbeddedContext;
   [switch_type(FW_IPSEC_PHASE), switch_is(IpSecPhase)] 
     union {
     [case(FW_IPSEC_PHASE_1)] 
       struct {
       unsigned short wFlags;
       [range(0,1000)] unsigned long dwNumPhase1Suites;
       [size_is(dwNumPhase1Suites)] PFW_PHASE1_CRYPTO_SUITE pPhase1Suites;
       unsigned long dwTimeoutMinutes;
       unsigned long dwTimeoutSessions;
     };
     [case(FW_IPSEC_PHASE_2)] 
       struct {
       FW_PHASE2_CRYPTO_PFS Pfs;
       [range(0,1000)] unsigned long dwNumPhase2Suites;
       [size_is(dwNumPhase2Suites)] PFW_PHASE2_CRYPTO_SUITE pPhase2Suites;
     };
   };
   [range(FW_RULE_ORIGIN_INVALID,FW_RULE_ORIGIN_MAX-1)] 
     FW_RULE_ORIGIN_TYPE Origin;
   [string, range(1,10001)] wchar_t* wszGPOName;
   FW_RULE_STATUS Status;
   unsigned long dwCryptoSetFlags;
 } FW_CRYPTO_SET,
  *PFW_CRYPTO_SET;

pNext: A pointer to the next FW_CRYPTO_SET in the list.

wSchemaVersion: Specifies the version of the set.

IpSecPhase: This field is of type FW_IPSEC_PHASE, and it specifies if this cryptographic set applies for Phase1 (main mode) or Phase2 (quick mode).

wszSetId: A pointer to a Unicode string that uniquely identifies the set. The primary set for this policy object is identified with the "{E5A5D32A-4BCE-4e4d-B07F-4AB1BA7E5FE1}" string for Phase1 and with the "{E5A5D32A-4BCE-4e4d-B07F-4AB1BA7E5FE2}" string for Phase2.

wszName: A pointer to a Unicode string that provides a friendly name for the set.

wszDescription: A pointer to a Unicode string that provides a friendly description for the set.

wszEmbeddedContext: A pointer to a Unicode string. A client implementation MAY use this field to store implementation-specific client context. The server MUST NOT interpret the value of this string. The server MUST preserve the value of this string unmodified.

wFlags: This field is a combination of the FW_PHASE1_CRYPTO_FLAGS enumeration bit flags.

dwNumPhase1Suites: Specifies the number of Phase1 suites that the structure contains.

pPhase1Suites: A pointer to an array of dwNumPhase1Suites contiguous FW_PHASE1_CRYPTO_SUITE elements.

dwTimeoutMinutes: This value is a lifetime in minutes before a Phase1 established key is renegotiated.

dwTimeoutSessions: This value is the number of sessions before a Phase1 established key is renegotiated.

Pfs: This field MUST contain a valid value of those in the FW_PHASE2_CRYPTO_PFS enumeration. It describes the perfect forward secrecy used for quick mode cryptographic operations.

dwNumPhase2Suites: Specifies the number of Phase2 suites that the structure contains.

pPhase2Suites: A pointer to an array of FW_PHASE2_CRYPTO_SUITE elements. The number of elements is given by dwNumPhase2Suites.

Origin: This field is the set origin, as specified in the FW_RULE_ORIGIN_TYPE enumeration. It MUST be filled on enumerated rules and ignored on input.

wszGPOName: A pointer to a Unicode string containing the displayName of the GPO containing this object. When adding a new object, this field is not used. The client SHOULD set the value to NULL, and the server MUST ignore the value. When enumerating an existing object, if the client does not set the FW_ENUM_RULES_FLAG_RESOLVE_GPO_NAME flag, the server MUST set the value to NULL. Otherwise, the server MUST set the value to the displayName of the GPO containing the object or NULL if the object is not contained within a GPO. For details about how the server initializes an object from a GPO, see section 3.1.3. For details about how the displayName of a GPO is stored, see [MS-GPOL] section 2.3.

Status: The status code of the set, as specified by the FW_RULE_STATUS enumeration. This field is filled out when the structure is returned as output. On input, this field MUST be set to FW_RULE_STATUS_OK.

dwCryptoSetFlags: Bit flags from FW_CRYPTO_SET_FLAGS.

The following are semantic checks that cryptographic sets MUST pass:

  • The wSchemaVersion field MUST NOT be less than 0x000200.

  • The wszSetId field MUST NOT contain the pipe (|) character, MUST NOT be NULL, MUST be a string at least 1 character long, and MUST NOT be greater than or equal to 255 characters.

  • If the wszName field string is not NULL, it MUST be at least 1 character long, MUST NOT be greater than or equal to 10,000 characters, and MUST NOT contain the pipe (|) character.

  • If the wszDescription field string is not NULL, it MUST be at least 1 character long, MUST NOT be greater than or equal to 10,000 characters, and MUST NOT contain the pipe (|) character.

  • If the wszEmbeddedContext field string is not NULL, it MUST be at least 1 character long, MUST NOT be greater than or equal to 10,000 characters, and MUST NOT contain the pipe (|) character.

  • The IpSecPhase field MUST have valid FW_IPSEC_PHASE values.

  • If the IpSecPhase field is FW_IPSEC_PHASE_1:

    • The wszSetId field MUST be equal to the primary Phase1 cryptographic set ID. (There is only one Phase1 cryptographic set allowed per store.)

    • The wFlags field of the set MUST NOT be greater than or equal to FW_PHASE1_CRYPTO_FLAGS_MAX.

    • The dwTimeoutMinutes field of the set MUST be greater than or equal to 1, and MUST be less than or equal to 2,879.

    • The dwTimeoutSessions field of the set MUST be less than or equal to 2,147,483,647.

    • The cryptographic set MUST have at least one Phase1 cryptographic suite.

    • The pPhase1Suites array MUST contain exactly dwNumPhase1Suites entries.

    • All cryptographic suites within the set MUST have the same value in the KeyExchange field and MUST have valid values.

    • All Phase1 suites MUST NOT have a KeyExchange field with the FW_CRYPTO_ENCRYPTION_INVALID value and MUST have valid values.

    • If the set has a schema policy version of 0x0200, all Phase1 suites MUST NOT have an Encryption field with values greater than or equal to FW_CRYPTO_ENCRYPTION_MAX_V2_0.

    • All Phase1 suites MUST NOT have an Encryption field with the FW_CRYPTO_ENCRYPTION_NONE value and MUST have valid values less than FW_CRYPTO_ENCRYPTION_MAX_V2_0.

    • If the set has a schema policy version of 0x0200, all Phase1 suites MUST NOT have a Hash field that has values greater than or equal to FW_CRYPTO_HASH_MAX_V2_0.

    • All Phase1 suites MUST NOT have a Hash field that has the FW_CRYPTO_HASH_NONE value and MUST have either MD5 (FW_CRYPTO_HASH_MD5) or SHA (FW_CRYPTO_HASH_SHA1, FW_CRYPTO_HASH_SHA256, FW_CRYPTO_HASH_SHA384) valid values.

  • If the IpSecPhase field is FW_IPSEC_PHASE_2:

    • The wszSetId field MUST NOT have the primary Phase2 cryptographic set ID as a prefix.

    • The cryptographic set MUST have at least one Phase2 cryptographic suite.

    • The pPhase2Suites array MUST contain exactly dwNumPhase2Suites entries.

    • The Pfs field MUST NOT be FW_PHASE2_CRYPTO_PFS_INVALID and MUST have valid values.

    • If the set has a schema policy version of 0x0200, all Phase2 cryptographic suites MUST NOT have an AhHash field or EspHash field with values greater than or equal to FW_CRYPTO_HASH_MAX_V2_0.

    • If the set has a schema policy version of 0x0200, all Phase2 suites MUST NOT have an Encryption field with values greater than or equal to FW_CRYPTO_ENCRYPTION_MAX_V2_0.

    • All Phase2 suites within the set MUST NOT have a dwTimeoutMinutes field less than FW_MIN_CRYPTO_PHASE2_TIMEOUT_MINUTES (5) or greater than FW_MAX_CRYPTO_PHASE2_TIMEOUT_MINUTES (48 * 60 -1).

    • All Phase2 suites within the set MUST NOT have a dwTimeoutKBytes field of less than FW_MIN_CRYPTO_PHASE2_TIMEOUT_KBYTES (20480) or greater than FW_MAX_CRYPTO_PHASE2_TIMEOUT_KBYTES (2147483647).

    • All the Phase2 suites within the set MUST NOT have a Protocol field with FW_CRYPTO_PROTOCOL_INVALID and MUST have valid values.

    • For all suites that have the Protocol field equal to FW_CRYPTO_PROTOCOL_AH or to FW_CRYPTO_PROTOCOL_BOTH:

      • All suites MUST NOT have an AhHash field with the FW_CRYPTO_HASH_NONE value, and MUST have valid values not equal to FW_CRYPTO_HASH_SHA384.

    • For all suites that have the Protocol field equal to FW_CRYPTO_PROTOCOL_BOTH:

      • All suites MUST have the AhHash field equal to the EspHash field.

    • For all suites that have the Protocol field equal to FW_CRYPTO_PROTOCOL_ESP:

      • All suites MUST have an EspHash field with valid values, including FW_CRYPTO_HASH_NONE. The EspHash field MUST NOT equal FW_CRYPTO_HASH_SHA384.

      • All suites MUST have an Encryption field with valid values, including FW_CRYPTO_ENCRYPTION_NONE.

      • All suites MUST not have both the EspHash field equal to FW_CRYPTO_HASH_NONE and the Encryption field equal to FW_CRYPTO_ENCRYPTION_NONE.

      • All suites that have the Encryption field equal to FW_CRYPTO_ENCRYPTION_AES_GCM128, 192, or 256 MUST also have a corresponding FW_CRYPTO_HASH_AES_GMAC128, 192, or 256 value on the EspHash field. An AES GCM encryption algorithm corresponds to an AES GMAC hash algorithm if both use the same bit size.