1.\" $OpenBSD: X509v3_addr_validate_path.3,v 1.5 2023/09/30 19:07:38 tb Exp $ 2.\" 3.\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 30 2023 $ 18.Dt X509V3_ADDR_VALIDATE_PATH 3 19.Os 20.Sh NAME 21.Nm X509v3_addr_validate_path , 22.Nm X509v3_addr_validate_resource_set , 23.Nm X509v3_asid_validate_path , 24.Nm X509v3_asid_validate_resource_set 25.Nd RFC 3779 path validation for IP address and AS number delegation 26.Sh SYNOPSIS 27.In openssl/x509v3.h 28.Ft int 29.Fn X509v3_addr_validate_path "X509_STORE_CTX *ctx" 30.Ft int 31.Fo X509v3_addr_validate_resource_set 32.Fa "STACK_OF(X509) *chain" 33.Fa "IPAddrBlocks *addrblocks" 34.Fa "int allow_inherit" 35.Fc 36.Ft int 37.Fn X509v3_asid_validate_path "X509_STORE_CTX *ctx" 38.Ft int 39.Fo X509v3_asid_validate_resource_set 40.Fa "STACK_OF(X509) *chain" 41.Fa "ASIdentifiers *asid" 42.Fa "int allow_inherit" 43.Fc 44.Sh DESCRIPTION 45Both RFC 3779 extensions require additional checking in the certification 46path validation. 47.Bl -enum 48.It 49The initial set of allowed IP address and AS number resources is defined in 50the trust anchor, where inheritance is not allowed. 51.It 52An issuer may only delegate subsets of resources present in its 53RFC 3779 extensions or subsets of resources inherited from its issuer. 54.It 55If an RFC 3779 extension is present in a certificate, 56the same type of extension must also be present in its issuer. 57.It 58All RFC 3779 extensions 59appearing in the validation path must be in canonical form 60according to 61.Xr X509v3_addr_is_canonical 3 62and 63.Xr X509v3_asid_is_canonical 3 . 64.El 65.Pp 66.Fn X509v3_addr_validate_path 67and 68.Fn X509v3_asid_validate_path 69are called from 70.Xr X509_verify_cert 3 71as part of the verification chain building. 72On encountering an error or a violation of the above rules, 73.Fa error , 74.Fa error_depth , 75and 76.Fa current_cert 77are set on 78.Fa ctx 79and the verify callback is called with 80.Fa ok 81set to 0. 82.Dv X509_V_ERR_INVALID_EXTENSION 83indicates a non-canonical resource, 84.Dv X509_V_ERR_UNNESTED_RESOURCE 85indicates a violation of the other rules above. 86In rare circumstances, the error can be 87.Dv X509_V_ERR_UNSPECIFIED 88and for IP address resources 89.Dv X509_V_ERR_OUT_OF_MEM 90is also possible. 91.Pp 92.Fn X509v3_addr_validate_resource_set 93validates the resources in 94.Fa addrblocks 95against a specific certificate 96.Fa chain . 97After checking that 98.Fa addrblocks 99is canonical, its IP addresses are checked to be covered in 100the certificate at depth 0, 101then the chain is walked all the way to the trust anchor 102until an error or a violation of the above rules is encountered. 103.Fa addrblocks 104is allowed to use inheritance according to 105.Xr X509v3_addr_inherits 3 106if and only if 107.Fa allow_inherit 108is non-zero. 109.Pp 110.Fn X509v3_asid_validate_resource_set 111performs similar checks as 112.Fn X509v3_addr_validate_resource_set 113for 114.Fa asid . 115.Sh RETURN VALUES 116All these functions return 1 on successful validation and 0 otherwise. 117.Pp 118For 119.Fn X509v3_addr_validate_path 120and 121.Fn X509v3_asid_validate_path 122a non-empty 123.Fa chain 124and a 125.Fa verify_cb 126must be present on 127.Fa ctx , 128otherwise they fail and set the 129.Fa error 130on 131.Fa ctx 132to 133.Dv X509_V_ERR_UNSPECIFIED . 134The 135.Fa verify_cb 136is called with the error codes described above 137on most errors encountered during validation. 138Some malformed extensions can lead to an error 139that cannot be intercepted by the callback. 140With the exception of an allocation error, 141no error codes are set on the error stack. 142.Pp 143.Fn X509v3_addr_validate_resource_set 144accepts a 145.Dv NULL 146.Fa addrblocks 147and 148.Fn X509v3_asid_validate_resource_set 149accepts a 150.Dv NULL 151.Fa asid 152as valid. 153They fail if 154.Fa chain 155is 156.Dv NULL 157or empty. 158If 159.Fa allow_inherit 160is 0, 161.Fa addrblocks 162or 163.Fa asid 164is checked for inheritance with 165.Xr X509v3_addr_inherits 3 166or 167.Xr X509v3_asid_inherits 3 . 168The remaining failure cases are the same as for 169.Fn X509v3_addr_validate_path 170and 171.Fn X509v3_asid_validate_path . 172They cannot and do not attempt to communicate 173the cause of the error to the caller. 174.Sh SEE ALSO 175.Xr ASIdentifiers_new 3 , 176.Xr crypto 3 , 177.Xr IPAddressRange_new 3 , 178.Xr X509_new 3 , 179.Xr X509_STORE_CTX_get_error 3 , 180.Xr X509_verify_cert 3 , 181.Xr X509v3_addr_add_inherit 3 , 182.Xr X509v3_addr_inherits 3 , 183.Xr X509v3_asid_add_id_or_range 3 184.Sh STANDARDS 185RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: 186.Bl -dash -compact 187.It 188section 2.3: IP Address Delegation Extension Certification Path Validation 189.It 190section 3.3: Autonomous System Identifier Delegation Extension Certification 191Path Validation 192.El 193.Pp 194RFC 5280: Internet X.509 Public Key Infrastructure Certificate 195and Certificate Revocation List (CRL) Profile 196.Bl -dash -compact 197.It 198section 6: Certification Path Validation 199.El 200.Sh HISTORY 201These functions first appeared in OpenSSL 0.9.8e 202and have been available since 203.Ox 7.1 . 204