-
null
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the X-Header Insertion and Encryption features and provides detailed information on the following topics:
The X-Header Insertion and X-Header Encryption features, collectively known as Header Enrichment, enables to append headers to HTTP/WSP GET and POST request packets, and HTTP Response packets for use by end applications, such as mobile advertisement insertion (MSISDN, IMSI, IP address, user-customizable, and so on).
In this release, the X-Header Insertion and Encryption features are supported only on the GGSN and P-GW.
X-Header Insertion and X-Header Encryption are both licensed Cisco features. A separate feature license may be required. Contact your Cisco account representative for detailed information on specific licensing requirements. For information on installing and verifying licenses, refer to the Managing License Keys section of the Software Management Operations chapter in the System Administration Guide.
This section provides an overview of the X-Header Insertion feature.
Extension header (x-header) fields are the fields not defined in RFCs or standards but can be added to headers of protocol for specific purposes. The x-header mechanism allows additional entity-header fields to be defined without changing the protocol, but these fields cannot be assumed to be recognizable by the recipient. Unrecognized header fields should be ignored by the recipient and must be forwarded by transparent proxies.
The X-Header Insertion feature enables inserting x-headers in HTTP/WSP GET and POST request packets and HTTP response packets. Operators wanting to insert x-headers in HTTP/WSP request and HTTP response packets, can configure rules for it. The charging-action associated with the rules will contain the list of x-headers to be inserted in the packets.
For example, if you want to insert the field x-rat-type in the HTTP header with a value of rat-type, the header inserted should be:
x-rat-type: geran
where, rat-type is geran for the current packet.
This section provides an overview of the X-Header Encryption feature.
X-Header Encryption enhances the X-header Insertion feature to increase the number of fields that can be inserted, and also enables encrypting the fields before inserting them.
If x-header insertion has already happened for an IP flow (because of any x-header format), and if the current charging-action has the first-request-only flag set, x-header insertion will not happen for that format. If the first-request-only flag is not set in a charging-action, then for that x-header format, insertion will continue happening in any further suitable packets in that IP flow.
Changes to x-header format configuration will not trigger re-encryption for existing calls. The changed configuration will however, be applicable for new calls. The changed configuration will also apply at the next re-encryption time to those existing calls for which re-encryption timeout is specified. If encryption is enabled for a parameter while data is flowing, since its encrypted value will not be available, insertion of that parameter will stop.
Recovery of flows is not supported for this feature.
ECS handles TCP OOO packets in two ways depending on the rulebase configuration:
Transmit Immediately: If the rulebase is configured to transmit immediately for TCP OOO packets, the OOO packets will be forwarded immediately, and a copy of this packet will be added to the OOO queue for analysis.
Transmit After Reordering: If the rulebase is configured to transmit after reordering for TCP OOO packets, the OOO packets will be added to the OOO queue for analysis. Header insertion on OOO request packets occurs on reordering packets that are received before the OOO request timeout. When a reordering packet is received, the queued packets are forwarded. However, if a reordering packet is not received before the OOO queue timeout, the queued packet will be forwarded without any analysis done to those packets.
When TCP OOO processing has been configured in the rulebase, a session manager crash might be observed due to overlapping TCP segments and/or reordering packet arriving within TCP OOO configured timeout value or default value (5 sec). This issue can be resolved by changing the rulebase configuration for TCP OOO packets from transmit after-reordering to transmit immediately.
If x-header insertion is only for the request packet, then out-of-order buffering will be supported till the header completion of the request packet.
If x-header insertion is only for the response packet, then out-of-order buffering will be supported till the header completion of the response packet.
If x-header insertion is for both request and response packets, then out-of-order buffering will be supported till the completion of HTTP headers for that packet.
This enhancement will be supported only for HTTP flows of x-header enrichment feature.
In case of pipeline flows with multiple transactions, if a new OOO request/response is received while the previous request/response is still going on, then x-header insertion will not work for the new request/response of that flow.
ECS can perform Header Enrichment to IP fragmented packets when all the fragments are received before the reassembly timeout. If the packet size after Header Enrichment exceeds the MSS of the session, the reassembled packet gets segmented, the multiple segments are forwarded.
This section lists known limitations to insertion and encryption of x-header fields in HTTP/WSP request and HTTP response packets.
The following are limitations to insertion and encryption of x-header fields in HTTP headers.
Limitations in StarOS 14.0 and later releases:
Header insertion does not occur for packets with incomplete HTTP headers.
If a flow has x-header insertion and later some IP fragments are received for which reassembly fails, sequence space of that segment will be mismatched.
ECS does not support applying more than one modifying action on an inbound packet before sending it on the outbound interface. For example, if header insertion is applied on a packet, then the same packet is not allowed to be modified for NAT/ALG and MSS insertion.
Header enrichment works only for the first request of a packet with concatenated requests, when the packets are buffered at DCCA. There are no limitations on header enrichment for single GET or pipelined GET requests.
Header enrichment works for packets at DCCA only when the packets pending of header insertion is buffered.
Receive window will not be considered during header enrichment. That is, after header enrichment if packet exceeds receive window, ECS will not truncate the packet.
The maximum bytes per request after header enrichment is 2400 bytes. If concatenated requests exist, a maximum of 2400 bytes after header enrichment can be inserted.
If due to header insertion, the packet size exceeds this limit, the behavior is unpredictable.
Only those x-header fields in header portion of application protocol that begin with "x-" are parsed at HTTP analyzer. In URL and data portion of HTTP any field can be parsed.
EDR generation for x-header fields in Response packets will not be supported.
Limitations in StarOS 12.3 and earlier releases:
The packet size is assumed to be less than "Internal MED MTU size, the size of header fields inserted". If the total length of packet exceeds the internal MTU size, header insertion will not occur after the addition of fields.
Header insertion occurs for both HTTP GET and POST requests. However, for POST requests, the resulting packet size will likely be larger than for GET requests due to the message body contained in the request. If the previous limitation applies, then POST request will suffer a bigger limit due to this.
Header insertion does not occur for retransmitted packets.
Header insertion does not occur for packets with incomplete HTTP headers.
Header insertion does not occur for TCP OOO and IP fragmented packets.
If a flow has x-header insertion and later some IP fragments are received for which reassembly fails, sequence space of that segment will be mismatched.
ECS does not support applying more than one modifying action on an inbound packet before sending it on the outbound interface. For example, if header insertion is applied on a packet, then the same packet is not allowed to be modified for NAT/ALG and MSS insertion.
If a packet is buffered by ICAP, header insertion will not occur for that packet.
Receive window will not be considered during header enrichment. That is, after header enrichment if packet exceeds receive window, ECS will not truncate the packet.
Packet size limit is 2400 bytes, if due to header insertion packet size exceeds this limit, behavior is unpredictable.
Only those x-header fields in header portion of application protocol that begin with "x-" are parsed at HTTP analyzer. In URL and data portion of HTTP any field can be parsed.
The following are limitations to insertion and encryption of x-header fields in WSP headers:
x-header fields are not inserted in IP fragmented packets.
In case of concatenated request, x-header fields are only inserted in first GET or POST request (if rule matches for the same). X-header fields are not inserted in the second or later GET/POST requests in the concatenated requests. For example, if there is ACK+GET in packet, x-header is inserted in the GET packet. However, if GET1+GET2 is present in the packet and rule matches for GET2 and not GET1 x-header is still inserted in GET2. In case of GET+POST also, x-header is not inserted in POST.
In case of CO, x-header fields are not inserted if the WTP packets are received out of order (even after proper re-ordering).
If route to MMS is present, x-headers are not inserted.
x-headers are not inserted in WSP POST packet when header is segmented. This is because POST contains header length field which needs to be modified after addition of x-headers. In segmented WSP headers, header length field may be present in one packet and header may complete in another packet.
x-headers are not inserted in case of packets buffered at DCCA.
This section provides information on the different x-headers supported by ECS.
ECS supports insertion of various x-header fields in the HTTP/WSP GET and POST request packets and HTTP response packets. The x-headers are inserted at the end of the HTTP/WSP header.
The following bearer-related x-headers are supported:
The following HTTP-related x-headers are supported:
In addition, ECS also allows string constants to be inserted as an x-header. For more information on configuring the x-header formats, see the insert command section in the ACS x-Header Format Configuration Mode Commands chapter of the Command Line Interface Reference.
This section provides an overview of the x-Header Enrichment Anti-Spoofing feature.
The Header Enrichment feature allows operators to encrypt and insert subscriber-specific fields as x-headers in to the HTTP headers of URL requests. However, this might leave the header open to spoofing by malicious external devices. The Anti-Spoofing feature enables deletion and modification of the existing x-header fields to protect the operators and subscribers from spoofing, and provides a fraud detection mechanism when an external portal is used for a subscriber or content authorization.
The feature detects and removes user-generated HTTP headers if the header name is similar to the header name used in the x-header format, and when multiple entries of the same field exist in the header, all the similar entries are removed and one with a modified value is inserted at the end of the HTTP header.
When anti-spoofing is enabled, and if the HTTP header in the GET or POST request spawns across more than one packet, the packets with incomplete HTTP header will be buffered. The buffered packets are sent out once the HTTP header is completed.
The Anti-Spoofing feature is disabled by default and can be enabled/disabled at a field level in the CLI.
Header enrichment does not occur if a route to the MMS analyzer exist in the rulebase.
Header enrichment works only for the first request of a packet with concatenated requests, when the packets are buffered at DCCA.
If a packet is buffered by ICAP, header insertion will not occur for that packet.
ECS will not be able to perform header enrichment when all fragments are not received before reassembly timeout in the case of IP fragments packets.
ECS does not perform more than one flow action which modifies the inbound packet before sending it on the outbound interface.
If the HTTP GET or POST header is not completed in three packets, anti-spoofing will occur only for the last packet in which the header completes, as buffering supported only up to a maximum of two packets.
Though insertion of fields is allowed without having "x-" in the field name, extension header fields that do not start with "x-" are not deleted.
The anti-spoofing feature will not be supported for x-headers inserted in Response messages.
This section describes the steps involved to configure the X-Header Insertion and X-Header Encryption features.
The following steps describe how X-Header Insertion works:
The following steps describe how X-Header Encryption works:
| Step 1 | X-header insertion, encryption, and the encryption certificate is configured in the CLI. |
| Step 2 | When the call gets connected, and after each regeneration time, the encryption certificate is used to encrypt the strings. |
| Step 3 | When a packet hits a ruledef that has x-header format configured in its charging-action, x-header insertion into that packet is done using the given x-header-format. |
| Step 4 | If x-header-insertion is to be done for fields which are marked as encrypt, the previously encrypted value is populated for that field accordingly. |
This section describes how to configure the X-Header Insertion and Encryption features, collectively known as Header Enrichment.
This section describes how to configure the X-Header Insertion feature.
This feature is license dependent. Please contact your Cisco account representative for more information.
To configure the X-Header Insertion feature:
| Step 1 | Create/configure a ruledef to identify the HTTP packets in which the x-headers must be inserted. For information on how to create/configure ruledefs, see Configuring Rule Definitions. |
| Step 2 | Create/configure a rulebase and configure the charging-action, which will insert the x-header fields into the HTTP packets. For information on how to create/configure rulebases, see Configuring Rulebase. |
| Step 3 | Create the x-header format as described in Creating the X-Header Format. |
| Step 4 | Configure the x-header format as described in Configuring the X-Header Format. |
| Step 5 | Configure insertion of the x-header fields as described in Configuring Charging Action for Insertion of X-Header Fields. |
To create an x-header format, use the following configuration:
configure active-charging service <ecs_service_name> xheader-format <xheader_format_name> end
To configure an x-header format, use the following configuration:
configure active-charging service <ecs_service_name> xheader-format <xheader_format_name> insert <xheader_field_name> { string-constant <xheader_field_value> | variable { bearer { 3gpp { apn | charging-characteristics | charging-id | imei | imsi | qos | rat-type | s-mcc-mnc | sgsn-address } | acr | customer-id | ggsn-address | mdn | msisdn-no-cc | radius-string | radius-calling-station-id | session-id | sn-rulebase | subscriber-ip-address | username } [ encrypt ] | http { host | url } } end
To configure a charging action for insertion of x-header fields, use the following configuration:
configure active-charging service <ecs_service_name> charging-action <charging_action_name> xheader-insert xheader-format <xheader_format_name> [ encryption rc4md5 [ encrypted ] key <key> ] [ first-request-only ] [ msg-type { response-only | request-and-response } ] [ -noconfirm ] end
Notes:
This section describes how to configure the X-Header Encryption feature.
This feature is license dependent. Please contact your Cisco account representative for more information.
To configure the X-Header Encryption feature:
| Step 1 | Configure X-Header Insertion as described in Configuring X-Header Insertion. |
| Step 2 | Create/configure a rulebase and configure the encryption certificate to use and the re-encryption parameter as described in Configuring X-Header Encryption. |
| Step 3 | Configure the encryption certificate to use as described in Configuring Encryption Certificate. |
To configure X-Header Encryption, use the following configuration example:
configure active-charging service <ecs_service_name> rulebase <rulebase_name> xheader-encryption certificate-name <certificate_name> xheader-encryption re-encryption period <re-encryption_period> end
Notes:
This configuration enables X-Header Encryption for all subscribers using the specified rulebase <rulebase_name>.
If the certificate is removed, ECS will continue using the copy that it has. It will only free its copy if the certificate name is removed from the rulebase.
Changes to x-header format configuration will not trigger re-encryption for existing calls. The changed configuration will however, be applicable for new calls. The changed configuration will also apply at the next re-encryption time to those existing calls for which re-encryption timeout is specified. If encryption is enabled for a parameter while data is flowing, since its encrypted value will not be available, insertion of that parameter will stop.
To configure the encryption certificate, use the following configuration example:
configure certificate name <certificate_name> pem { { data <pem_certificate_data> private-key pem [ encrypted ] data <pem_pvt_key> } | { url <url> private-key pem { [ encrypted ] data <pem_pvt_key> | url <url> } } end
Enter the following command in the Exec Mode to verify your configuration:
show active-charging xheader-format name <xheader_format_name>
This section provides information on the show commands and/or their outputs available to support this feature.
The output of this command displays statistics for X-header information.
The output of this command displays the Header Enrichment statistics.
HTTP header buffering limit reached
Feedback