NDIS_IPSEC_PACKET_INFO structure

  • [アーティクル]

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

The NDIS_IPSEC_PACKET_INFO structure specifies information used in offloading Internet Protocol security (IPsec) tasks from the TCP/IP transport to a miniport driver. The NDIS_IPSEC_PACKET_INFO structure is part of the per-packet information (extended out-of-band data) associated with a packet descriptor.

Syntax

typedef struct _NDIS_IPSEC_PACKET_INFO {
  union {
    struct {
      NDIS_HANDLE OffloadHandle;
      NDIS_HANDLE NextOffloadHandle;
    } Transmit;
    struct {
      ULONG SA_DELETE_REQ  :1;
      ULONG CRYPTO_DONE  :1;
      ULONG NEXT_CRYPTO_DONE  :1;
      ULONG CryptoStatus;
    } Receive;
  };
} NDIS_IPSEC_PACKET_INFO, *PNDIS_IPSEC_PACKET_INFO;

Members

  • Transmit

    • OffloadHandle
      Specifies the handle to the outbound security association (SA) for a packet that has just one IPsec payload, regardless of whether that payload is for a transport (end-to-end) connection or a tunnel connection.

    • NextOffloadHandle
      For a packet that has both a transport IPsec payload and a tunnel IPsec payload, NextOffloadHandle specifies the handle to the outbound security association (SA) for the tunnel connection. NextOffloadHandle is specified only if a packet has both tunnel and transport IPsec payloads; otherwise, NextOffloadHandle is set to zero.

  • Receive

    • SA_DELETE_REQ
      When set, indicates that the TCP/IP transport should issue OID_TCP_TASK_IPSEC_DELETE_SA once to delete the inbound security association (SA) over which the packet was received and once again to delete the outbound SA that corresponds to the deleted inbound SA. The miniport driver's NIC must not remove either of these SAs before receiving the corresponding OID_TCP_TASK_IPSEC_DELETE_SA request.

    • CRYPTO_DONE
      When set, indicates that the NIC performed IPsec checking on at least one IPsec payload in the receive packet. When cleared, indicates that the NIC did not perform IPsec checking on the packet.

    • NEXT_CRYPTO_DONE
      When set, indicates that the NIC performed IPsec checking on both the tunnel and transport portions of the receive packet. CRYPTO_DONE must also be set in this case. NEXT_CRYPTO_DONE is set only if a packet has both tunnel and transport IPsec payloads; otherwise, NEXT_CRYPTO_DONE is set to zero.

    • CryptoStatus
      Specifies, as one of the following values, the result of IPsec checking performed by the NIC on a receive packet:

      • CRYPTO_SUCCESS
        The packet was successfully decrypted, if necessary, and the AH checksum(s) and/or ESP checksum(s) in the packet were validated.

      • CRYPTO_GENERIC_ERROR
        The packet failed the IPsec check for an unspecified reason.

      • CRYPTO_TRANSPORT_AH_AUTH_FAILED
        The AH checksum for the transport portion of the packet was invalid.

      • CRYPTO_TRANSPORT_ESP_AUTH_FAILED
        The ESP checksum for the transport portion of the packet was invalid.

      • CRYPTO_TUNNEL_AH_AUTH_FAILED
        The AH checksum for the tunnel portion of the packet was invalid.

      • CRYPTO_TUNNEL_ESP_AUTH_FAILED
        The ESP checksum for the tunnel portion of the packet was invalid.

      • CRYPTO_INVALID_PACKET_SYNTAX
        The receive packet's length is invalid.

      • CRYPTO_INVALID_PROTOCOL
        The IPsec protocol(s) specified in the security association (SA) on which the packet was received do not match the IPsec protocols found in the packet. For example, this error occurs if the SA on which the packet was received specifies the AH protocol but the packet contained only an ESP header.

Remarks

Before the TCP/IP transport passes to a miniport driver a send packet on which the miniport driver's NIC will perform IPsec tasks, it updates the IPsec information in the NDIS_IPSEC_PACKET_INFO structure associated with the packet descriptor. Specifically, the TCP/IP transport supplies an OffloadHandle in the NDIS_IPSEC_PACKET_INFO structure. The OffloadHandle specifies the handle to the outbound security association (SA) for a packet that has just one IPsec payload, regardless of whether that payload is for a transport (end-to-end) security association or a tunnel security association. The OffloadHandle supplied in the NDIS_IPSEC_PACKET_INFO structure has the same value as the OffloadHandle supplied by the TCP/IP transport when it set OID_TCP_TASK_IPSEC_ADD_SA to request the miniport driver to add the outbound SA to its NIC.

If a packet that has both a transport IPsec payload and a tunnel IPsec payload, NextOffloadHandle specifies the handle to the outbound SA for the tunnel connection. NextOffloadHandle is specified only if a packet has both tunnel and transport IPsec payloads; otherwise, NextOffloadHandle is set to zero.

Before indicating up a receive packet that has one or more IPsec payloads, a miniport driver updates the NDIS_IPSEC_PACKET_INFO structure associated with the packet descriptor:

  • If the miniport driver's NIC performed IPsec checks on at least one IPsec payload in the packet, the miniport driver sets the CRYPTO_DONE flag and indicates the results of the checksum validation tests by specifying the appropriate CryptoStatus value.

  • If the miniport driver's NIC performed IPsec checking on both the tunnel and transport portions of a receive packet, the miniport driver also sets the Next_ CRYPTO_DONE flag. The NEXT_CRYPTO_DONE flag is set only if a packet has both tunnel and transport IPsec payloads; otherwise, NEXT_CRYPTO_DONE is set to zero.

  • If the miniport driver's NIC did not perform IPsec checks on the packet, the miniport driver does not set the CRYPTO_DONE flag or the Next_ CRYPTO_DONE flag and does not supply a CryptoStatus value.

To make room for another SA on the NIC, the miniport driver can set SA_DELETE_REQ in the NDIS_IPSEC_PACKET_INFO structure for a receive packet. The TCP/IP transport subsequently issues OID_TCP_TASK_IPSEC_DELETE_SA once to delete the inbound security association (SA) over which the packet was received and once again to delete the outbound SA that corresponds to the deleted inbound SA. The miniport driver's NIC must not remove either of these SAs before receiving the corresponding OID_TCP_TASK_IPSEC_DELETE_SA request. The miniport driver can set SA_DELETE_REQ independently of CRYPTO_DONE.

To obtain a pointer to the NDIS_IPSEC_PACKET_INFO structure, drivers should call the NDIS_PER_PACKET_INFO_FROM_PACKET macro with an InfoType of IpSecNdisTask. Alternatively, drivers can call the NDIS_PACKET_EXTENSION_FROM_PACKET macro to obtain a pointer to the NDIS_PACKET_EXTENSION structure associated with a given packet descriptor. The driver can then use the IpSecNdisTask array index to obtain a pointer that points to the NDIS_IPSEC_PACKET_INFO structure.

Requirements

Header

 Ndis.h (include Ndis.h)

See also

NDIS_PACKET_EXTENSION

NDIS_PACKET_EXTENSION_FROM_PACKET

NDIS_PER_PACKET_INFO_FROM_PACKET

OID_TCP_TASK_IPSEC_ADD_SA

OID_TCP_TASK_IPSEC_DELETE_SA

 

 

Send comments about this topic to Microsoft