Menu
▾
▴
[Dnssec-tools-cvs] dnssec-tools/lib/libval/doc validator_api.xml,1.14,1.15
|
From: Suresh K <hs...@us...> - 2006-02-26 06:43:46
|
Update of /cvsroot/dnssec-tools/dnssec-tools/lib/libval/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3117 Modified Files: validator_api.xml Log Message: Grammar, content fixes Index: validator_api.xml =================================================================== RCS file: /cvsroot/dnssec-tools/dnssec-tools/lib/libval/doc/validator_api.xml,v retrieving revision 1.14 retrieving revision 1.15 diff -C2 -d -r1.14 -r1.15 *** validator_api.xml 25 Feb 2006 18:24:44 -0000 1.14 --- validator_api.xml 26 Feb 2006 06:43:39 -0000 1.15 *************** *** 5,13 **** <!DOCTYPE rfc SYSTEM "rfc2629.dtd"> ! <rfc ipr="full3978" docName="draft-dnssec-validator-api-00"> <front> <title> DNSSEC Validator API </title> ! <author initials="S." surname="Krishnaswamy" ! fullname="Suresh Krishnaswamy"> <organization> SPARTA, Inc. </organization> <address> --- 5,14 ---- <!DOCTYPE rfc SYSTEM "rfc2629.dtd"> ! <rfc ipr="full3978" docName="draft-hayatnagarkar-dnsext-validator-api-00"> <front> <title> DNSSEC Validator API </title> ! ! <author initials="A." surname="Hayatnagarkar" ! fullname="Abhijit Hayatnagarkar"> <organization> SPARTA, Inc. </organization> <address> *************** *** 19,28 **** <country>US</country> </postal> ! <email>suresh AT sparta.com</email> </address> </author> ! <author initials="A." surname="Hayatnagarkar" ! fullname="Abhijit Hayatnagarkar"> <organization> SPARTA, Inc. </organization> <address> --- 20,29 ---- <country>US</country> </postal> ! <email>abhijit AT sparta.com</email> </address> </author> ! <author initials="S." surname="Krishnaswamy" ! fullname="Suresh Krishnaswamy"> <organization> SPARTA, Inc. </organization> <address> *************** *** 34,38 **** <country>US</country> </postal> ! <email>abhijit AT sparta.com</email> </address> </author> --- 35,39 ---- <country>US</country> </postal> ! <email>suresh AT sparta.com</email> </address> </author> *************** *** 63,67 **** DNS. The validator is a piece of software that performs this test by checking the cryptographic signatures that cover DNS records and by ! verifying a sequence of such records up to a <xref target="refs.RFC4033">trust anchor</xref>. </t> <t> --- 64,69 ---- DNS. The validator is a piece of software that performs this test by checking the cryptographic signatures that cover DNS records and by ! verifying a sequence of such records from a <xref target="refs.RFC4033">trust anchor</xref> to ! this data. </t> <t> *************** *** 84,91 **** <t> The low-level validator API gives more control over the validation process and allows detailed inspection of validation ! status for each element of the <xref target="refs.RFC4033">chain of trust</xref>. </t> <t> Context management is orthogonal to the process of validation. ! Results returned by the validator are often guided by local policy decisions. The context management API provides functions to manage validator policies.</t> --- 86,93 ---- <t> The low-level validator API gives more control over the validation process and allows detailed inspection of validation ! status for each element of the <xref target="refs.RFC4033">authentication chain</xref>. </t> <t> Context management is orthogonal to the process of validation. ! Results returned by the validator can be guided by local policy decisions. The context management API provides functions to manage validator policies.</t> *************** *** 104,109 **** <!-- ############# --> ! <t> ! The following terms are used in this specification: </t> <list style="hanging"> --- 106,110 ---- <!-- ############# --> ! <t> Some of the terminology used in this specification are defined below: <list style="hanging"> *************** *** 121,131 **** <t hangText="validator context:"> ! An opaque structure encapsulating the validator policy that may be used by ! applications to fine tune and control their validation processes. The validator context is the application's handle to the validator policy. Contexts also maintain a reference to a "policy scope" (see definition below), which may be explicitly changed ! by applications. ! </t> <t> </t> --- 122,130 ---- <t hangText="validator context:"> ! An opaque structure encapsulating the validator policy. The validator context is the application's handle to the validator policy. Contexts also maintain a reference to a "policy scope" (see definition below), which may be explicitly changed ! by applications. </t> <t> </t> *************** *** 134,139 **** This policy is looked up whenever a policy attribute not existing in other more specific policy scopes is required. A "default" base policy can also be defined ! to provide the definitions for system-wide policy attribute defaults. ! </t> <t> </t> --- 133,137 ---- This policy is looked up whenever a policy attribute not existing in other more specific policy scopes is required. A "default" base policy can also be defined ! to provide the definitions for system-wide policy attribute defaults. </t> <t> </t> *************** *** 142,149 **** Policy scopes are useful when it becomes necessary to override certain policy attributes in specific ! environments. As an example, an application may support functions for a web browser ! as well as a mail client with slighty differing validator policies for ! each piece of functionality. In such cases the application may define a common ! base policy and have overrides for specific scopes -- one for the mail client and one for the web browser. </t> --- 140,146 ---- Policy scopes are useful when it becomes necessary to override certain policy attributes in specific ! environments. As an example, an application may require different validator policies ! for a web browser and a mail client. In such cases the application may define a common ! base policy and have overrides for specific scopes: one for the mail client and one for the web browser. </t> *************** *** 158,162 **** file in increasing order of specificity.</t> ! </list> </section> <!-- Terminology --> --- 155,159 ---- file in increasing order of specificity.</t> ! </list> </t> </section> <!-- Terminology --> *************** *** 219,223 **** These functions are DNSSEC-aware versions of the gethostbyname(), gethostbyname_r(), gethostbyaddr() and gethostbyaddr_r() functions and ! can be used by applications to get the validation status of DNS queries performed during the name-to-address or address-to-name translations. </t> --- 216,220 ---- These functions are DNSSEC-aware versions of the gethostbyname(), gethostbyname_r(), gethostbyaddr() and gethostbyaddr_r() functions and ! an be used by applications to get the validation status of DNS queries performed during the name-to-address or address-to-name translations. </t> *************** *** 249,256 **** </t> <t> ! The val_status parameter is used to return the status of DNSSEC validation, and must contain the address of a variable of type val_status_t. Possible values for val_status_t are defined in <xref target="val-ret-codes"/>. ! A validation status of VALIDATE_SUCCESS will be returned only if both the address and canonical name(s) (if present) have been validated successfully. </t> --- 246,253 ---- </t> <t> ! The val_status parameter returns the status of DNSSEC validation, and must contain the address of a variable of type val_status_t. Possible values for val_status_t are defined in <xref target="val-ret-codes"/>. ! A validation status of VAL_SUCCESS will be returned only if both the address and canonical name(s) (if present) have been validated successfully. </t> *************** *** 303,307 **** of the addrinfo structure. It contains an additional val_status field that represents the status of DNSSEC validation for that particular answer. It will ! contain a validation status of VALIDATE_SUCCESS only if both the address and canonical name (if present) have been validated successfully. The memory for the value returned in *res is dynamically allocated by this function. The --- 300,304 ---- of the addrinfo structure. It contains an additional val_status field that represents the status of DNSSEC validation for that particular answer. It will ! contain a validation status of VAL_SUCCESS only if both the address and canonical name (if present) have been validated successfully. The memory for the value returned in *res is dynamically allocated by this function. The *************** *** 374,385 **** resp array. The response field of this element will have a format similar to the answer returned by res_query(). The validation status will be ! VALIDATE_SUCCESS only if all the individual RRsets have been successfully validated. Otherwise, the validation status will be an error code. ! Note that if this flag is used and a value other than VALIDATE_SUCCESS is returned with multiple RRsets in the answer, it will not be possible to know which RRset resulted in the error status.</t> <t> The val_query() function returns 0 on success and a non-zero error code ! on failure. The error code NO_SPACE is returned if the resp array does not contain enough elements or memory to hold all results returned by the validator. In this case, on return *resp_count will contain the total --- 371,382 ---- resp array. The response field of this element will have a format similar to the answer returned by res_query(). The validation status will be ! VAL_SUCCESS only if all the individual RRsets have been successfully validated. Otherwise, the validation status will be an error code. ! If this flag is used and a value other than VAL_SUCCESS is returned with multiple RRsets in the answer, it will not be possible to know which RRset resulted in the error status.</t> <t> The val_query() function returns 0 on success and a non-zero error code ! on failure. The error code VAL_NO_SPACE is returned if the resp array does not contain enough elements or memory to hold all results returned by the validator. In this case, on return *resp_count will contain the total *************** *** 387,391 **** val_query() with the appropriate number of elements in the resp array.</t> ! <!-- Value of NO_SPACE ? --> </postamble> </figure> --- 384,388 ---- val_query() with the appropriate number of elements in the resp array.</t> ! <!-- Value of VAL_NO_SPACE ? --> </postamble> </figure> *************** *** 401,405 **** The low-level validator API provides the application with greater control and visibility into the validation process. The functions and data structures defined in this API are ! summarized below. </t>e <section title="val_resolve_and_check, val_free_result, val_free_assertion_chain, val_free_query_chain"> --- 398,402 ---- The low-level validator API provides the application with greater control and visibility into the validation process. The functions and data structures defined in this API are ! summarized below. </t> <section title="val_resolve_and_check, val_free_result, val_free_assertion_chain, val_free_query_chain"> *************** *** 426,430 **** val_status_t val_rc_status; struct val_assertion_chain *val_rc_trust; ! struct val_result *val_rc_next; }; --- 423,427 ---- val_status_t val_rc_status; struct val_assertion_chain *val_rc_trust; ! struct val_result_chain *val_rc_next; }; *************** *** 459,465 **** for the <domain_name, class, type> tuple and verifies and validates the responses received. The verification step checks RRSIGs and the ! validation step performs verification up the chain of trust to a trust ! anchor. All the information necessary for inspecting the validation ! chain of trust is available through the results, assertions and queries parameters. </t> --- 456,462 ---- for the <domain_name, class, type> tuple and verifies and validates the responses received. The verification step checks RRSIGs and the ! validation step performs verification down the authentication chain from a trust ! anchor. All the information necessary for inspecting the ! authentication chain is available through the results, assertions and queries parameters. </t> *************** *** 471,495 **** when the query type is ANY or when a proof of non-existence is returned, in which case RRsets of type NSEC and SOA may also be returned. ! The val_rc_trust field points to the next element in the chain of trust sequence and the val_rc_next field can be used to iterate through the list of all results returned by the validator. The consolidated validation status value for an RRset in the DNS response based on the ! individual status values for all components in the chain of trust is stored in val_rc_status, which is of type val_status_t. Possible values for this type are listed in <xref target="val-ret-codes"/>.</t> <t> The validator may initiate multiple queries to the DNS while trying to construct the ! chain of trust. Each response is encapsulated within one or more elements of the struct val_assertion_chain linked list. However not all elements in this list are present in the chain of trust. ! For instance, responses for glue-fetching operations are not directly a part of the chain of trust and are not validated. The assertions parameter in val_resolve_and_check() returns a pointer to the set ! of all responses ! received over the course of validating an answer including data received for any ancillary information. assertions may also be thought of as a cache of responses obtained during the validation process.</t> <t> Most applications would only be interested in the results parameter ! since this provides a single error code that represents the authenticity of returned data. Sophisticated applications, such as a DNSSEC troubleshooting utility, may look more closely at an individual assertion or query to identify ! the particular component in the chain of trust that led to validation failure. ! Given a pointer to an element of type struct val_assertion_chain within the chain of trust, it is possible to inspect further details of the validation status of each component therein using this structure's member variables. </t> --- 468,491 ---- when the query type is ANY or when a proof of non-existence is returned, in which case RRsets of type NSEC and SOA may also be returned. ! The val_rc_trust field points to the next element in the authentication chain sequence and the val_rc_next field can be used to iterate through the list of all results returned by the validator. The consolidated validation status value for an RRset in the DNS response based on the ! individual status values for all components in the authentication chain is stored in val_rc_status, which is of type val_status_t. Possible values for this type are listed in <xref target="val-ret-codes"/>.</t> <t> The validator may initiate multiple queries to the DNS while trying to construct the ! authentication chain. Each response is encapsulated within one or more elements of the struct val_assertion_chain linked list. However not all elements in this list are present in the authentication chain; ! for instance, responses for glue-fetching operations are not directly a part of the authentication chain and are not validated. The assertions parameter in val_resolve_and_check() returns a pointer to the set ! of all responses received for each query sent during validation including data received for any ancillary information. assertions may also be thought of as a cache of responses obtained during the validation process.</t> <t> Most applications would only be interested in the results parameter ! since this provides a single error code for representing the authenticity of returned data. Sophisticated applications, such as a DNSSEC troubleshooting utility, may look more closely at an individual assertion or query to identify ! the particular component in the authentication chain that led to validation failure. ! Given a pointer to an element of type struct val_assertion_chain within the authentication chain, it is possible to inspect further details of the validation status of each component therein using this structure's member variables. </t> *************** *** 499,505 **** The val_ac_rrset_next member inside struct val_assertion_chain points to the next answer within the set of responses returned for a query. ! In cases where validation fails due to some non-DNSSEC error, the val_ac_query_more variable can be used to identify the query where the error was encountered. ! val_ac_trust points to the next element in the chain of trust. Its value is NULL when the current element in the linked list points to a valid trust anchor. val_ac_next can be used to iterate through the list of DNS responses within the struct val_assertion_chain linked list.</t> --- 495,501 ---- The val_ac_rrset_next member inside struct val_assertion_chain points to the next answer within the set of responses returned for a query. ! In cases where validation fails due to some non-DNSSEC error, the val_ac_query_more variable identifies the query where the error was encountered. ! val_ac_trust points to the next element in the authentication chain. Its value is NULL when the current element in the linked list points to a valid trust anchor. val_ac_next can be used to iterate through the list of DNS responses within the struct val_assertion_chain linked list.</t> *************** *** 531,538 **** val_qc_raw_response_length and val_qc_raw_response respectively. val_qc_answer points to the set of answers created for the response and may be NULL when no responses are returned. ! val_qc_creator is used to identify which link in the chain of trust led to the generation of this query and is NULL for the initial query issued by the val_resolve_and_check() function. val_qc_next can be used to iterate through the list of DNS queries within the struct val_query_chain linked list. ! The combination of the previous two functions makes it possible to identify all queries sent out in order to validate a particular assertion. </t> --- 527,534 ---- val_qc_raw_response_length and val_qc_raw_response respectively. val_qc_answer points to the set of answers created for the response and may be NULL when no responses are returned. ! val_qc_creator identifies the link in the authentication chain that led to the generation of this query and is NULL for the initial query issued by the val_resolve_and_check() function. val_qc_next can be used to iterate through the list of DNS queries within the struct val_query_chain linked list. ! The combination of the previous two functions makes it possible to identify all queries sent in order to validate a particular assertion. </t> *************** *** 554,646 **** <t> <list style="hanging"> <t> </t> ! <t hangText="VAL_NO_ERROR:"> ! Returned if no error was encountered. ! </t> ! <t> </t> ! <t hangText="NOT_IMPLEMENTED:"> Returned if the implementation does not support a desired feature. </t> <t> </t> ! <t hangText="OUT_OF_MEMORY:"> Returned if memory could not be allocated for an operation. </t> <t> </t> ! <t hangText="BAD_ARGUMENT:"> Returned if an unexpected value was passed as an argument. </t> <t> </t> ! <t hangText="INTERNAL_ERROR:"> Returned if an internal error was encountered in the validator library. </t> <t> </t> ! <t hangText="NO_PERMISSION:"> Returned if the application lacked sufficient privileges to perform an operation. </t> <t> </t> ! <t hangText="RESOURCE_UNAVAILABLE:"> Returned if some resource necessary for an operation was unavailable. </t> <t> </t> ! <t hangText="CONF_PARSE_ERROR:"> Returned if the validator configuration file contains errors. </t> <t> </t> ! <t hangText="CONF_NOT_FOUND:"> Returned if the validator configuration file could not be located. </t> <t> </t> ! <t hangText="NO_POLICY:"> Returned if the policy identifier being referenced could not be located or is invalid for the current context. </t> - <t> </t> - <t hangText="ERROR:"> - Represents a generic error. - </t> </list></t> <t> val_status_t defines the list of error codes returned by the validator ! to an application for a DNSSEC response. Individual components of the chain of ! trust have their own val_astatus_t variable for maintaining per-rrset error codes, and queries have a val_qstatus_t variable to track errors in name resolution. Possible values for val_status_t are listed below. ! (Author's note: the definition of possible values for val_astatus_t, as in the case of values for val_qstatus_t will draw upon efforts within the IETF to generate a complete list of error codes for the validator.) </t> <t> <list style="hanging"> <t> </t> ! <t hangText="VALIDATE_SUCCESS:"> Returned if the response was verified and validated. </t> <t> </t> ! <t hangText="LOCAL_ANSWER:"> Returned if the response was obtained locally from a configuration file such as /etc/hosts. </t> <t> </t> ! <t hangText="BARE_RRSIG:"> Returned if the response was for a query of type RRSIG. RRSIGs contain the cryptographic signatures for other DNS data and cannot themselves be validated. </t> <t> </t> ! <t hangText="NONEXISTENT_NAME:"> Returned if the proof for denial of existence for a domain name was validated. </t> <t> </t> ! <t hangText="NONEXISTENT_TYPE:"> Returned if the proof for denial of existence for the resource record type for the name queried was validated. </t> <t> </t> ! <t hangText="INDETERMINATE:"> ! Returned if the validator lacked detail to complete validation up the chain of trust. </t> <t> </t> ! <t hangText="BOGUS:"> Returned if the origin authenticity for the response could not be verified. </t> <t> </t> ! <t hangText="VALIDATION_ERROR:"> Returned if the DNS returned some error for the original query. </t> <t> </t> ! <t hangText="PROVABLY_UNSECURE:"> Returned if the zone to which the response belongs can be shown to be legitimately un-signed. --- 550,634 ---- <t> <list style="hanging"> <t> </t> ! <t hangText="VAL_NOT_IMPLEMENTED:"> Returned if the implementation does not support a desired feature. </t> <t> </t> ! <t hangText="VAL_OUT_OF_MEMORY:"> Returned if memory could not be allocated for an operation. </t> <t> </t> ! <t hangText="VAL_BAD_ARGUMENT:"> Returned if an unexpected value was passed as an argument. </t> <t> </t> ! <t hangText="VAL_INTERNAL_ERROR:"> Returned if an internal error was encountered in the validator library. </t> <t> </t> ! <t hangText="VAL_NO_PERMISSION:"> Returned if the application lacked sufficient privileges to perform an operation. </t> <t> </t> ! <t hangText="VAL_RESOURCE_UNAVAILABLE:"> Returned if some resource necessary for an operation was unavailable. </t> <t> </t> ! <t hangText="VAL_CONF_PARSE_ERROR:"> Returned if the validator configuration file contains errors. </t> <t> </t> ! <t hangText="VAL_CONF_NOT_FOUND:"> Returned if the validator configuration file could not be located. </t> <t> </t> ! <t hangText="VAL_NO_POLICY:"> Returned if the policy identifier being referenced could not be located or is invalid for the current context. </t> </list></t> <t> val_status_t defines the list of error codes returned by the validator ! to an application for a DNSSEC response. Individual components of the authentication ! chain have their own val_astatus_t variable for maintaining per-rrset error codes, and queries have a val_qstatus_t variable to track errors in name resolution. Possible values for val_status_t are listed below. ! (author's note: the definition of possible values for val_astatus_t, as in the case of values for val_qstatus_t will draw upon efforts within the IETF to generate a complete list of error codes for the validator.) </t> <t> <list style="hanging"> <t> </t> ! <t hangText="VAL_SUCCESS:"> Returned if the response was verified and validated. </t> <t> </t> ! <t hangText="VAL_LOCAL_ANSWER:"> Returned if the response was obtained locally from a configuration file such as /etc/hosts. </t> <t> </t> ! <t hangText="VAL_BARE_RRSIG:"> Returned if the response was for a query of type RRSIG. RRSIGs contain the cryptographic signatures for other DNS data and cannot themselves be validated. </t> <t> </t> ! <t hangText="VAL_NONEXISTENT_NAME:"> Returned if the proof for denial of existence for a domain name was validated. </t> <t> </t> ! <t hangText="VAL_NONEXISTENT_TYPE:"> Returned if the proof for denial of existence for the resource record type for the name queried was validated. </t> <t> </t> ! <t hangText="VAL_INDETERMINATE:"> ! Returned if the validator lacked detail to complete validation down the authentication chain. </t> <t> </t> ! <t hangText="VAL_BOGUS:"> Returned if the origin authenticity for the response could not be verified. </t> <t> </t> ! <t hangText="VAL_ERROR:"> Returned if the DNS returned some error for the original query. </t> <t> </t> ! <t hangText="VAL_PROVABLY_UNSECURE:"> Returned if the zone to which the response belongs can be shown to be legitimately un-signed. *************** *** 657,664 **** <t> ! Local policy for the validator is stored in the validator configuration file (for example /etc/dnsval.conf). Applications can use local policy to influence the decision about when the validator must break ! out from the process of constructing a chain of trust with either a success or failure condition. Examples of local policy elements include trust anchors for --- 645,652 ---- <t> ! Local policy for the validator is stored in the validator configuration file, /etc/dnsval.conf. Applications can use local policy to influence the decision about when the validator must break ! out from the process of constructing the authentication chain with either a success or failure condition. Examples of local policy elements include trust anchors for *************** *** 668,676 **** applications and operation scenarios. </t> ! <t> ! The context management and validator policy API allows an application ! some flexibility in choosing its validator policy based on its scope of execution. </t> <section title="val_get_context, val_free_context"> --- 656,680 ---- applications and operation scenarios. </t> + <t>Multiple validator policies can be specified in the same validator configuration file. Policies are identified by simple text strings also referred to as labels, which must be unique within the configuration file. As an example, "browser" could be used as the label for a policy that defines the base policy for all web-browsers in a system. The ':' character in the label specifies a new scope within a given policy. Thus, "mail:mozilla:browser" could be used as the identifier to refer to the mail-specific validator policy for the mozilla suite. The default base policy in the configuration file has a label value of ':'. </t> ! <t> Policy definitions have the following structure. </t> ! <t> <label> <KEYWORD> <additional-data>; </t> ! <t> The only possible value for <KEYWORD> is "trust-anchor". (author's note: this will no doubt have to be extended.) The <additional-data> depends on the type of keyword. For the "trust-anchor" keyword this is a sequence of the zone name and a quoted string containing the RDATA portion for the trust anchor's ! DNSKEY. An example is given below. </t> ! <figure> ! <artwork> ! browser trust-anchor example.com "257 3 5 AQO8XS4y9r77X9SHBmrx \ ! MoJf1Pf9AT9Mr/L5BBGtO9/e9f/zl4FFgM2l B6M2XEm6mp6 \ ! mit4tzpB/sAEQw1McYz6bJdKkTiqtuWTCfDmgQhI6/Ha0 Ef \ ! GPNSqnY 99FmbSeWNIRaa4fgSCVFhvbrYq1nXkNVyQPeEVHk \ ! oDNCAlr qOA3lw==" ; ! </artwork> ! <postamble> ! </postamble> ! </figure> + <t> + The functions provided below allow an application some flexibility in + choosing its validator policy based on its scope of execution. </t> <section title="val_get_context, val_free_context"> *************** *** 685,703 **** <t> The val_get_context() function returns a pointer to the val_context_t structure in the newcontext parameter. A NULL context is returned if some error was encountered. The application must release the memory allocated by the val_get_context() function using the val_free_context() function once it is done with using the validator context.</t> ! <t> ! The label parameter identifies the particular policy to be used as the base policy for the context during validation. The policy label is a simple text string that can be used to identify the policy in the validator configuration file. As an example "browser" could be used as the label for a policy that defines the base policy for all web-browsers in a system. ! The ':' character in the label string is used to specify a new scope within a given policy. Thus, "mail:mozilla:browser" could be used as the identifier to refer to the mail-specific validator policy for the mozilla suite. </t> ! ! <t> ! The label parameter in val_get_context() must be uniquely defined within the validator configuration file. A NULL ! label creates a context with the default base policy. The default base policy is identified within the validator configuration file by a lable value of ':'.</t> ! ! <t> ! The val_get_context() function returns 0 on success, and a non-zero value on error. ! </t> </postamble> --- 689,702 ---- <t> The val_get_context() function returns a pointer to the val_context_t structure in the newcontext parameter. + + The label parameter identifies the particular policy to be used as the base policy for the context during validation. + The label parameter in val_get_context() must be uniquely defined within the validator configuration file. A NULL + label creates a context with the default base policy. + A NULL context is returned if some error was encountered. The application must release the memory allocated by the val_get_context() function using the val_free_context() function once it is done with using the validator context.</t> ! <t> The val_get_context() function returns 0 on success, and an error code from <xref target="val-ret-codes"/> on failure. </t> </postamble> *************** *** 715,720 **** This function allows applications to switch their current validator context to a particular policy scope. The validator context supplied in ctx must not be NULL. The API only allows the context to switch its policy to a valid scope. Thus, trying to switch the policy scope to "mail:mozilla:browser" when the context was created with a base policy of "safari:browser" would result in an error. - A NULL label switches the context's current policy scope to its base policy. </t> </postamble> </figure> --- 714,720 ---- This function allows applications to switch their current validator context to a particular policy scope. The validator context supplied in ctx must not be NULL. The API only allows the context to switch its policy to a valid scope. Thus, trying to switch the policy scope to "mail:mozilla:browser" when the context was created with a base policy of "safari:browser" would result in an error. A NULL label switches the context's current policy scope to its base policy. </t> + + <t> The val_switch_policy_scope() function returns 0 on success, and an error code from <xref target="val-ret-codes"/> on failure. </t> </postamble> </figure> *************** *** 725,729 **** <artwork> int val_get_scopes_within_context( val_context *ctx, ! char **scopes, int *count ); </artwork> --- 725,729 ---- <artwork> int val_get_scopes_within_context( val_context *ctx, ! char *scopes[], int *count ); </artwork> *************** *** 731,740 **** <t> This function allows applications to obtain the list of policy scopes available within a given context. ! The application must allocate the scopes array to be large enough to hold all available answers. ! Each element in the array must be pre-allocated to at least MAX_POLICY_ID_LENGTH. count is a value-result parameter that must be set to the number of elements allocated in the scopes array. ! If the size of the array is not large enough to hold all answers, the function returns -1 and *count contains ! the actual number of scopes available within the context. 0 is returned on success and *count contains ! the number of scopes. </t> </postamble> </figure> --- 731,740 ---- <t> This function allows applications to obtain the list of policy scopes available within a given context. ! The application must allocate the *scopes array to be large enough to hold all available answers. ! Each element in the array must be pre-allocated to at least VAL_MAX_POLICY_ID_LENGTH. count is a value-result parameter that must be set to the number of elements allocated in the scopes array. ! The function returns 0 on success and sets *count to the number of scopes available. ! If the size of the array is not large enough to hold all answers, the function returns VAL_NO_SPACE and *count contains the actual number of scopes available within the context. ! Other error codes from <xref target="val-ret-codes"/> may also be returned on failure in which case the value of *count is undefined. </t> </postamble> </figure> *************** *** 758,765 **** <t> The val_set_scope_definition() function allows an application to modify an existing policy scope or ! define a new policy scope within a context. A label of NULL can be used to ! update the base policy within the context.</t> ! <t> ! The validator context supplied in the ctx parameter for these functions must not be NULL.</t> </postamble> </figure> --- 758,766 ---- <t> The val_set_scope_definition() function allows an application to modify an existing policy scope or ! define a new policy scope within a context. A NULL label updates the base policy within the context. </t> ! ! <t> ! The validator context supplied in the ctx parameter for these functions must not be NULL. ! The above functions returns 0 on success and an error code from <xref target="val-ret-codes"/> on failure. </t> </postamble> </figure> *************** *** 789,793 **** </t> <t> ! The validator API functions return a status of LOCAL_ANSWER if they get the answer to the query locally (for example, from the /etc/hosts file). The application cannot assume that these answers can be trusted, unless the --- 790,794 ---- </t> <t> ! The validator API functions return a status of VAL_LOCAL_ANSWER if they get the answer to the query locally (for example, from the /etc/hosts file). The application cannot assume that these answers can be trusted, unless the *************** *** 797,801 **** communication path between the DHCP server and the client system is secured. If these conditions are not satisfied and if the application chooses to trust ! a validation status of LOCAL_ANSWER, there exists a potential attack vector whereby an attacker can poison the /etc/hosts file and an application using this API may trust the result. --- 798,802 ---- communication path between the DHCP server and the client system is secured. If these conditions are not satisfied and if the application chooses to trust ! a validation status of VAL_LOCAL_ANSWER, there exists a potential attack vector whereby an attacker can poison the /etc/hosts file and an application using this API may trust the result. *************** *** 806,810 **** expected to be DNSSEC-aware. If the name server pointed to by /etc/resolv.conf is not DNSSEC-aware (i.e. it does not return DNSSEC records), this API will not ! be able to perform validation. This will prevent applications from getting results of DNSSEC validation. The system on which the validator runs must ensure that the name servers listed in /etc/resolv.conf are DNSSEC-aware. --- 807,811 ---- expected to be DNSSEC-aware. If the name server pointed to by /etc/resolv.conf is not DNSSEC-aware (i.e. it does not return DNSSEC records), this API will not ! perform validation. This will prevent applications from getting results of DNSSEC validation. The system on which the validator runs must ensure that the name servers listed in /etc/resolv.conf are DNSSEC-aware. *************** *** 820,824 **** system administrator must ensure that the list of trust anchors are kept up-to-date in the event of key-rollovers. If the trust anchors are outdated, ! the validator will not be able to validate responses from DNS. </t> </section> <!-- Security Considerations --> --- 821,825 ---- system administrator must ensure that the list of trust anchors are kept up-to-date in the event of key-rollovers. If the trust anchors are outdated, ! the validator will not validate responses from the DNS. </t> </section> <!-- Security Considerations --> |