This appendix provides a quick reference to HTTP metainformation, for use in metafiles, PHP scripts, and other mechanisms that can manipulate HTTP header fields. For most transactions, Stronghold determines the proper metainformation to use and you do not need to intervene. There are five kinds of HTTP metainformation fields:

• General
  
  

  General metainformation is not specifically related to the client, server, or HTTP.

• Request
  
  

  Request metainformation is used in HTTP client requests.

• Response
  
  

  Response metainformation is used in HTTP server responses.

• Entity
  
  

  Entity metainformation describes the data that follows the header.

• Proxy Security
  
  

  Proxy security metainformation provides information about SSL-secured proxy connections.

Both client requests and server responses use the general header fields listed in this section, although some are more commonly used by one or the other.

• Syntax: Cache-Control: directive1 [directive2 directive3 ...]
  
• Context: general
  

  Cache-Control sets the cache options for the current transactions. Requests and responses use separate directives.

  The following are the possible request directives:

  Cache Request Directive	Description
  no-cache	Do not cache the request.
  no-store	Remove the information immediately after forwarding the request.
  max-age=seconds	Do not send responses older than the value specified by seconds.
  max-stale[=seconds]	If max-stale appears alone, Stronghold is allowed to return expired data. If seconds is specified, Stronghold only sends data that has been expired for less than the given number of seconds.
  min-fres =seconds	Return the data only if it has not expired by the specified number of seconds.
  only-if-cached	Return only cached data.

  The following are the possible response directives:

  Cache Response Directive	Description
  public	Any host may cache the data.
  private	A shared cache is not allowed to cache the data.
  no-cache	Do not cache.
  no-store	Remove the information immediately after forwarding the response.
  no-transform	Do not convert the data to another format.
  must-revalidate	Revalidate the data.
  proxy-revalidate	Except when using a private cache, the client must revalidate the data.
  max-age=seconds	The data expires in the specified number of seconds.

• Syntax: Connection: option1 [option2 ...]
  
• Context: general
  

  Connection specifies options specific to the current connection. For example, when keepalive is enabled, the client or server can use this field to close the connection:

  Connection: close
  
  

• Syntax: Date: date time
  
• Context: general
  

  This field indicates the current date and time. RFC 1123 specifies the most current format for date and time, which looks like this:

  Thu, 14 November 1996 09:46:03 GMT
  
  

  However, you can also use the older RFC 850 and ANSI C formats for backward compatability:

  Thursday, 14-Nov-96 09:46:03 GMT
  Thu Nov 6 09:46:03 1996
  
  

• Syntax: MIME-Version: version
  
• Context: general
  

  If this field is not included, the default value is 1.0. Otherwise, MIME-Version specifies the version of MIME used in the transaction. It is unnecessary if the message body does not conform to MIME.

• Syntax: Pragma: no-cache
  
• Context: general
  

  Pragma is generally an HTTP 1.0 field; in HTTP 1.1, Cache Control takes its place. The only value is "no-cache," which instructs a proxy to request the document from a server instead of retrieving it from the local cache.

• Syntax: Transfer-Encoding: type
  
• Context: general
  

  This field specifies the type of encoding applied to the message body. The only value currently defined by HTTP is "chunked."

• Syntax: Upgrade: protocol/version
  
• Context: general
  

  When using the response code 101 (Switching Protocols), this field specifies the prefered protocol and version.

• Syntax: Via: protocol host ["comment"] ...
  
• Context: general
  

  HTTP 1.1 requires that gateways and proxies use this field to specify which protocols and hosts process the transaction in transit between the client and the server. It is used to track message forwards, avoid request loops, and identify the protocol capabilities of intermediate hosts.

Clients include the headers listed in this section when transmitting requests to servers.

• Syntax: Accept: type/subtype1[; q=qvalue][, type/subtype2[; q=qvalue] ...]
  
• Context: request
  

  The Accept header specifies one or more media types that the client can accept, ranked using an optional qvalue. The qvalue is a floating point number between 0 and 1, with 1 being the most preferred media type.

• Syntax: Accept-Charset: char-set1[; q=qvalue][, char-set2[;q=qvalue]...]
  
• Context: request
  

  This header field specifies one or more character sets that the client can accept, ranked using an optional qvalue. The qvalue is a floating point number between 0 and 1, with 1 being the most preferred character set.

• Syntax: Accept-Encoding: encoding-type1[, encoding-type2 ...]
  
• Context: request
  

  This header field specifies one or more encoding schemes that the client can accept. It can contain as many encoding types as needed. If this field is omitted or is empty, then the client does not accept any encoding types.

• Syntax: Accept-Language: language1[; q=qvalue][, language2
  [; q=qvalue] ...]
  
• Context: request
  

  This header field specifies one or more languages that the client can accept, ranked using an optional qvalue. The qvalue is a floating point number between 0 and 1, with 1 being the most preferred characters set. Language is a two-character abbreviation such as "en" for English, "de" for German, and so on.

• Syntax: Authorization: scheme credentials
  
• Context: request
  

  When Stronghold responds to a request with a WWW-Authenticate header, the client replies with the Authorization header, specifying an authentication scheme (such as basic or digest) and credentials (a username and password).

• Syntax: Cookie: name=value
  
• Context: request
  

  If a cookie is set for the requested URL, the client sends the cookie name with the request. If the client specifies multiple cookies, they must be separated by semicolons.

• Syntax: From: email-address
  
• Context: request
  

  The From header specifies the email address of the user sending the request.

• Syntax: Host: hostname[:port]
  
• Context: request
  

  This header specifies the hostname and, optionally, the port number of the URI. HTTP 1.1 requires this field, for distinguishing between multiple hosts on the same server platform when the URL is ambiguous.

• Syntax: If-Modified-Since: date
  
• Context: request
  

  Clients can use this header to instruct the server to send the document only if it has been modified since the date. If the document has not been modified since the given date, Stronghold responds with status code 304 (Not Modified). Usually, the client then retrieves a local cached copy.

• Syntax: If-Match: entity-tag
  
• Context: request
  

  This is a conditional header that requests the document only if it matches the specified entity-tag, which can take wildcard strings.

• Syntax: If-None-Match: entity-tag
  
• Context: request
  

  This is a conditional header that requests the document only if it does not match the specified entity-tag, which can take wildcard strings.

• Syntax: If-Range: entity-tag|date
  
• Context: request
  

  This is a conditional header that can only be used in conjunction with a Range header. The value can be either an entity tag or a date, indicating a partial entity that the client has already received.

• Syntax: If-Unmodified-Since: date
  
• Context: request
  

  This is a conditional header that requests a document only if it has not been modified since the given date. The value for date should follow the format specified in the Date header.

• Syntax: Max-Forwards: n
  
• Context: request
  

  This header limits the number of hops between the client and server to n.

• Syntax: Proxy-Authorization: credentials
  
• Context: request
  

  When Stronghold acts as a proxy server, clients use this header instead of the Authorization header.

• Syntax: Range: bytes=n-m[,n-m ...]
  
• Context: request
  

  A client can use this header to request one or more segments of a document. The segments are specified with bytes ranges separated by commas.

• Syntax: Referer: URL
  
• Context: request
  

  The Referer header indicates the URL of the document that refers to the requested URL, meaning the document in which the user followed a link to the request document.

• Syntax: User-Agent: string
  
• Context: request
  

  This header gives information about the client, such as the application, version number, platform, and so on.

Stronghold uses the headers listed in this section to respond to client requests.

• Syntax: Accept-Ranges: bytes|none
  
• Context: response
  

  When a client requests a segment of a document using the Range header, Stronghold responds with Accept-Ranges to indicate a successful range request.

• Syntax: Age: seconds
  
• Context: response
  

  Stronghold can use this header to specify the age of the message body in seconds.

• Syntax: Proxy-Authenticate: scheme realm
  
• Context: response
  

  When Stronghold responds with the 407 (Proxy Authentication Required) status code, is also sends this header to indicate the authentication scheme (such as basic or digest) and the authentication realm (set with the AuthName directive).

• Syntax: Public: method1[,method2,method3 ...]
  
• Context: response
  

  Public indicates one or more request methods that Stronghold supports. To indicate methods supported only for an individual URI, use the Allow header instead.

• Syntax: Retry-After: date|seconds
  
• Context: response
  

  When Stronghold uses the 503 (Service Unavailable) status code, it also sends this header to indicate when the client should resubmit the request. The value can be either a date (in a format specified by the Date header) or an integer indicating a period of seconds.

• Syntax: Server: string
  
• Context: response
  

  The Server header specifies the name and version number of the server, including its Apache core. In Stronghold Web Server's case, this is

  Server: Stronghold/2.4.1 Apache/1.3.2
  

• Syntax: Set-Cookie: name=value[; expires=date; path=pathname; domain=domain; secure]
  
• Context: response
  

  The Set-Cookie header passes a cookie to the client for use with the requested URL. Only the name value is required.

• Syntax: Vary: *|headers
  
• Context: response
  

  The Vary header indicates that the requested document exists in more than one form, and that the form sent with the response is affected by one or more specified request headers. The value is "*" if the document form is affected by factors other than request headers.

• Syntax: Warning: code host[:port] "string"
  
• Context: response
  

  Stronghold uses the Warning header to expound on status code information. This is usually used by caching proxies. Code is a two-digit code, and string is the recommended descriptive string for the code, as follows:

  Code	String
  10	Response is stale
  11	Revalidation failed
  12	Disconnected operation
  13	Heuristic expiration
  14	Transformation applied
  99	Miscellaneous warning (or an arbitrary string)

  Host is the hostname of the server or one of its virtual hosts, with an optional port number.

• Syntax: WWW-Authenticate: scheme realm
  
• Context: response
  

  When Stronghold responds with the 401 (Unauthorized) status code, it also sends this header to indicate the authentication scheme (such as basic or digest) and the realm (set with the AuthName directive), so that the client can return the appropriate username and password.

Entity headers supply information about the message body in an HTTP message, which can be either a client request or a server response.

• Syntax: Allow: method1[,method2,method3 ...]
  
• Context: entity
  

  This header indicates acceptable request methods for the requested URI. When Stronghold uses this header in a response, it is combined with the 405 (Method Not Allowed) status code.

• Syntax: Content-Base: URI
  
• Context: entity
  

  Content-Base specifies an absolute URI to use as a base for all relative URLs.

• Syntax: Content-Encoding: encoding-type[,encoding-type,encoding-type ...]
  
• Context: entity
  

  This header specifies one or more encoding types used to encode the message body, in the order in which they were used. The possible values for encoding-type are as follows:

  • "gzip"
    
    
  • "x-gzip"
    
    
  • "compress"
    
    
  • "x-compress"
    
    

• Syntax: Content-Language: language
  
• Context: entity
  

  Content-Language specifies the language used in the message body, using a two-character code such as "en" for English, "de" for German, and so on.

• Syntax: Content-Length: bytes
  
• Context: entity
  

  This header gives the length of the message body in bytes. In dynamic requests, this figure is often unknown; in that case, the header can be omitted.

• Syntax: Content-Location: URI
  
• Context: entity
  

  When a document exists in several locations, Stronghold can include this header in the response to indicate the source of the copy it sends to the client.

• Syntax: Content-MD5: digest
  
• Context: entity
  

  The client can use this header to check the integrity of the message. Digest is an MD5 digest of the message body.

• Syntax: Content-Range: bytes n-m/length
  
• Context: entity
  

  When the client requests a partial document using the Range header, Stronghold can respond with the Content-Range header to indicate which segment is enclosed in the message body. The values are a byte range and the total number of bytes in the segment.

• Syntax: Content-Transfer-Encoding: scheme
  
• Context: entity
  

  If Stronghold transforms the message body for transfer over the network, it uses this header to specify the encoding type, such as "7bit," "8bit," "binary," "base64," or "quoted-printable."

• Syntax: Content-Type: type/subtype
  
• Context: entity
  

  Stronghold uses this header to specify the media type and subtype of the message body. Generally, the server returns media types that the client specifies with the Accept header.

• Syntax: ETag: entity-tag
  
• Context: entity
  

  When a client send an If-Match or If-None-Match header, Stronghold responds using the ETag header, which specifies the entity tag for the requested document.

• Syntax: Expires: date
  
• Context: entity
  

  Stronghold can use this header to indicate when the requested document expires. After the given date, a proxy server may refresh its cached copy of the document.

• Syntax: Last-Modified: date
  
• Context: entity
  

  The Last-Modified header indicates when the document was last modified.

• Syntax: Location: URI
  
• Context: entity
  

  When Stronghold responds with a status code such as 201 (Created), 301 (Moved Permanently), or 302 (Moved Temporarily), it includes the Location header to indicate the source of the requested document. URI must be absolute.

• Syntax: URI: <URI>
  
• Context: entity
  

  HTTP 1.1 deprecates this header in favor of Location, but it can still be used for backward compatability.

When Stronghold Web Server performs SSL proxy transactions, it acts as both a server and a client:

• To clients, it behaves like a server that authenticates each client and negotiates session ciphers.
  
  
• To remote servers, it behaves like a client that must meet each server's authentication and encryption requirements.
  
  

In order to fulfill both roles as transparently as possible, Stronghold Web Server must give each SSL server information about its connection to the client originating the request. Servers can ignore this information or use it for authentication, access control, or other purposes.

Stronghold communicates the information in the form of special request headers. If the remote server is a Stronghold Web Server, it extracts the headers and appends "HTTP_" to their names to form environment variables. For example, the header that Stronghold Web Server sends as

SP-HTTPS: on

becomes the variable

HTTP_SP_HTTPS=on

when extracted by a Stronghold Web Server. It can then be used in logs, CGI programs, PHP scripts, or other mechanisms.

The valid proxy security headers are as follows:

• Syntax: SP-HTTPS: on|off
  
• Context: secure proxy
  

  "On" or "off," depending on whether SSL is turned on for the current request.

• Syntax: SP-KEYSIZE: n
  
• Context: secure proxy
  

  The full size of the session key, in bits

  NOTE:

  This is different from SP-SECRETKEYSIZE only if you are using an export-crippled cryptography scheme.

  
  

• Syntax: SP-SECRETKEYSIZE: n
  
• Context: secure proxy
  

  The actual size of the session key, in bits

• Syntax: SP-SSL-CIPHER: cipher
  
• Context: secure proxy
  

  The type of cipher used for the current session

• Syntax: SP-SSL-CLIENT: name
  
• Context: secure proxy
  

  The Distinguished Name of the client certificate, which includes the country code, state or province, locality, organization, organizational unit, common name, and email address

• Syntax: SP-CLIENT-CERTIFICATE: hash
  
• Context: secure proxy
  

  A hash of the client's certificate

• Syntax: SP-CLIENT-CERT-START: date
  
• Context: secure proxy
  

  The date on which the client's certificate becomes valid, in ASN1 format

• Syntax: SP-CLIENT-CERT-END: date
  
• Context: secure proxy
  

  The date on which the client's certificate is no longer valid, in ASN1 format

• Syntax: SP-CLIENT-C: country-code
  
• Context: secure proxy
  

  The two-character code for the country specified in the client certificate

• Syntax: SP-CLIENT-SP: state|province
  
• Context: secure proxy
  

  The state or province specified in the client certificate

• Syntax: SP-CLIENT-ST: state|province
  
• Context: secure proxy
  

  The state or province specified in the client certificate

• Syntax: SP-CLIENT-L: locality
  
• Context: secure proxy
  

  The locality, such as a city or town, specified in the client certificate

• Syntax: SP-CLIENT-O: organization
  
• Context: secure proxy
  

  The name of the organization to which the client belongs

• Syntax: SP-CLIENT-OU: organizational-unit
  
• Context: secure proxy
  

  The organizational unit specified in the client certificate

• Syntax: SP-CLIENT-CN: name
  
• Context: secure proxy
  

  The name of the client certificate's bearer

• Syntax: SP-CLIENT-EMAIL: email-address
  
• Context: secure proxy
  

  The email address of the client certificate's bearer

• Syntax: SP-CLIENT-IC: country-code
  
• Context: secure proxy
  

  Issuer Country, the country specified in the certificate of the CA that issued the client certificate

  NOTE:

  In all proxy security headers, "I" stands for "Issuer."

  
  

• Syntax: SP-CLIENT-ISP: state|province
  
• Context: secure proxy
  

  Issuer State/Province, the state or province specified in the certificate of the CA that issued the client certificate

• Syntax: SP-CLIENT-IL: locality
  
• Context: secure proxy
  

  The locality, such as a city or town, specified in the certificate of the CA that issued the client certificate

• Syntax: SP-CLIENT-IC: CA
  
• Context: secure proxy
  

  The name of the CA that issued the client certificate

• Syntax: SP-CLIENT-IOU: organizational-unit
  
• Context: secure proxy
  

  The name of the organizational unit of the CA that issued the client certificate

• Syntax: SP-CLIENT-ICN: hostname
  

  The hostname of the CA that issued the client certificate

• Syntax: SP-CLIENT-IEMAIL: email-address
  
• Context: secure proxy
  

  The contact email address of the CA that issued the client certificate

• Syntax: SP-CLIENT-KEY-ALGORITHM: algorithm
  
• Context: secure proxy
  

  The algorithm used to generate the client's public key

• Syntax: SP-CLIENT-KEY-SIZE: n
  
• Context: secure proxy
  

  The size of the client's public key, in bits

• Syntax: SP-CLIENT-KEY-EXP: n
  
• Context: secure proxy
  

  The exponent used in the client's key

• Syntax: SP-CLIENT-SIGNATURE-ALGORITHM: algorithm
  
• Context: secure proxy
  

  The algorithm used to sign the client certificate

• Syntax: SP-PROTOCOL-VERSION: 2|3
  
• Context: secure proxy
  

  The version of SSL used in this transaction, either version 2 or 3

[Top] [Prev] [Next] [Last]

© 1998 C2Net International Feedback: stronghold-docs@c2.net