1 package dbms_network_acl_utility is
2
3 /*
4 * DBMS_NETWORK_ACL_UTILITY is the PL/SQL package that provides the utility
5 * functions to facilitate the evaluation of ACL assignments governing
6 * TCP connections to network hosts.
7 */
8
9 -----------
10 -- Types --
11 -----------
12 type domain_table is table of varchar2(1000);
13
14 ----------------
15 -- Exceptions --
16 ----------------
17 access_denied EXCEPTION;
18 PRAGMA EXCEPTION_INIT(access_denied, -24247);
19 access_denied_num constant PLS_INTEGER := -24247;
20
21 /*
22 * For a given host, return the domains whose ACL assigned will be used to
23 * determine if a user has the privilege to access the given host or not.
24 * When the IP address of the host is given, return the subnets instead.
25 *
26 * PARAMETERS
27 * host the network host.
28 * RETURN
29 * The domains or subnets for the given host.
30 * EXCEPTIONS
31 *
32 * NOTES
33 * This function cannot handle IPv6 addresses. Nor can it generate
34 * subnets of arbitrary number of prefix bits for an IPv4 address.
35 */
36 function domains(host in varchar2) return domain_table pipelined;
37
38 /*
39 * Return the domain level of the given host name, domain, or subnet.
40 *
41 * PARAMETERS
42 * host the network host, domain, or subnet.
43 * RETURN
44 * The domain level of the given host, domain, or subnet.
45 * EXCEPTIONS
46 *
47 * NOTES
48 * This function cannot handle IPv6 addresses and subnets, and subnets
49 * in Classless Inter-Domain Routing (CIDR) notation.
50 */
51 function domain_level(host in varchar2) return number deterministic;
52
53 /*
54 * Determines if the two given hosts, domains, or subnets are equal. For
55 * IP addresses and subnets, this function can handle different
56 * representations of the same address or subnet. For example, an IPv6
57 * representation of an IPv4 address versus its IPv4 representation.
58 *
59 * PARAMETERS
60 * host1 the network host, domain, or subnet to compare.
61 * host2 the network host, domain, or subnet to compare.
62 * RETURN
63 * 1 if the two hosts, domains, or subnets are equal. 0 when not equal.
64 * NULL when either of the hosts is NULL.
65 * EXCEPTIONS
66 *
67 * NOTES
68 * This function does not perform domain name resolution when comparing
69 * any host or domain for equality.
70 */
71 function equals_host(host1 in varchar2, host2 in varchar2) return number
72 deterministic;
73 pragma interface(C, equals_host);
74
75 /*
76 * Determines if the given host is equal to or contained in the given host,
77 * domain, or subnet. For IP addresses and subnets, this function can handle
78 * different representations of the same address or subnet. For example, an
79 * IPv6 representation of an IPv4 address versus its IPv4 representation.
80 *
81 * PARAMETERS
82 * host the network host.
83 * domain the host, domain, or subnet.
84 * RETURN
85 * A non-NULL value will be returned if the given host is equal to or
86 * contained in the given host, domain, or subnet:
87 * - if domain is a hostname, the level of its domain + 1 will be
88 * returned;
89 * - if domain is a domain name, the domain level will be returned;
90 * - if domain is an IP address or subnet, the number of significant
91 * address bits of the IP address or subnet will be returned;
92 * - if domain is the wildcard "*", 0 will be returned.
93 * The non-NULL value returned indicates the precedence of the domain or
94 * subnet for ACL assignment. The higher the value, the higher is the
95 * precedence. NULL will be returned if the host is not equal to or
96 * contained in the given host, domain or subnet. NULL will also be
97 * returned if either the host or domain is NULL.
98 * EXCEPTIONS
99 *
100 * NOTES
101 * This function does not perform domain name resolution when evaluating
102 * any host or domain.
103 */
104 function contains_host(host in varchar2, domain in varchar2) return number
105 deterministic;
106 pragma interface(C, contains_host);
107
108 end;