1 PACKAGE DBMS_CRYPTO AS
2
3 ---------------------------------------------------------------------------
4 --
5 -- PACKAGE NOTES
6 --
7 -- DBMS_CRYPTO contains basic cryptographic functions and
8 -- procedures. To use correctly and securely, a general level of
9 -- security expertise is assumed.
10 --
11 -- VARCHAR2 datatype is not supported. Cryptographic operations
12 -- on this type should be prefaced with conversions to a uniform
13 -- character set (AL32UTF8) and conversion to RAW type.
14 --
15 -- Prior to encryption, hashing or keyed hashing, CLOB datatype is
16 -- converted to AL32UTF8. This allows cryptographic data to be
17 -- transferred and understood between databases with different
18 -- character sets, across character set changes and between
19 -- separate processes (for example, Java programs).
20 --
21 ---------------------------------------------------------------------------
22
23
24 -------------------------- ALGORITHM CONSTANTS ----------------------------
25 -- The following constants refer to various types of cryptographic
26 -- functions available from this package. Some of the constants
27 -- represent modifiers to these algorithms.
28 ---------------------------------------------------------------------------
29
30 -- Hash Functions
31 HASH_MD4 CONSTANT PLS_INTEGER := 1;
32 HASH_MD5 CONSTANT PLS_INTEGER := 2;
33 HASH_SH1 CONSTANT PLS_INTEGER := 3;
34 HASH_SH256 CONSTANT PLS_INTEGER := 4;
35 HASH_SH384 CONSTANT PLS_INTEGER := 5;
36 HASH_SH512 CONSTANT PLS_INTEGER := 6;
37
38 -- MAC Functions
39 HMAC_MD5 CONSTANT PLS_INTEGER := 1;
40 HMAC_SH1 CONSTANT PLS_INTEGER := 2;
41 HMAC_SH256 CONSTANT PLS_INTEGER := 3;
42 HMAC_SH384 CONSTANT PLS_INTEGER := 4;
43 HMAC_SH512 CONSTANT PLS_INTEGER := 5;
44
45 -- Block Cipher Algorithms
46 ENCRYPT_DES CONSTANT PLS_INTEGER := 1; -- 0x0001
47 ENCRYPT_3DES_2KEY CONSTANT PLS_INTEGER := 2; -- 0x0002
48 ENCRYPT_3DES CONSTANT PLS_INTEGER := 3; -- 0x0003
49 ENCRYPT_AES CONSTANT PLS_INTEGER := 4; -- 0x0004
50 ENCRYPT_PBE_MD5DES CONSTANT PLS_INTEGER := 5; -- 0x0005
51 ENCRYPT_AES128 CONSTANT PLS_INTEGER := 6; -- 0x0006
52 ENCRYPT_AES192 CONSTANT PLS_INTEGER := 7; -- 0x0007
53 ENCRYPT_AES256 CONSTANT PLS_INTEGER := 8; -- 0x0008
54
55 -- Block Cipher Chaining Modifiers
56 CHAIN_CBC CONSTANT PLS_INTEGER := 256; -- 0x0100
57 CHAIN_CFB CONSTANT PLS_INTEGER := 512; -- 0x0200
58 CHAIN_ECB CONSTANT PLS_INTEGER := 768; -- 0x0300
59 CHAIN_OFB CONSTANT PLS_INTEGER := 1024; -- 0x0400
60
61 -- Block Cipher Padding Modifiers
62 PAD_PKCS5 CONSTANT PLS_INTEGER := 4096; -- 0x1000
63 PAD_NONE CONSTANT PLS_INTEGER := 8192; -- 0x2000
64 PAD_ZERO CONSTANT PLS_INTEGER := 12288; -- 0x3000
65 PAD_ORCL CONSTANT PLS_INTEGER := 16384; -- 0x4000
66
67 -- Stream Cipher Algorithms
68 ENCRYPT_RC4 CONSTANT PLS_INTEGER := 129; -- 0x0081
69
70
71 -- Convenience Constants for Block Ciphers
72 DES_CBC_PKCS5 CONSTANT PLS_INTEGER := ENCRYPT_DES
73 + CHAIN_CBC
74 + PAD_PKCS5;
75
76 DES3_CBC_PKCS5 CONSTANT PLS_INTEGER := ENCRYPT_3DES
77 + CHAIN_CBC
78 + PAD_PKCS5;
79
80 AES_CBC_PKCS5 CONSTANT PLS_INTEGER := ENCRYPT_AES
81 + CHAIN_CBC
82 + PAD_PKCS5;
83
84
85 ----------------------------- EXCEPTIONS ----------------------------------
86 -- Invalid Cipher Suite
87 CipherSuiteInvalid EXCEPTION;
88 PRAGMA EXCEPTION_INIT(CipherSuiteInvalid, -28827);
89
90 -- Null Cipher Suite
91 CipherSuiteNull EXCEPTION;
92 PRAGMA EXCEPTION_INIT(CipherSuiteNull, -28829);
93
94 -- Key Null
95 KeyNull EXCEPTION;
96 PRAGMA EXCEPTION_INIT(KeyNull, -28239);
97
98 -- Key Bad Size
99 KeyBadSize EXCEPTION;
100 PRAGMA EXCEPTION_INIT(KeyBadSize, -28234);
101
102 -- Double Encryption
103 DoubleEncryption EXCEPTION;
104 PRAGMA EXCEPTION_INIT(DoubleEncryption, -28233);
105
106
107 ---------------------- FUNCTIONS AND PROCEDURES ------------------------
108
109 ------------------------------------------------------------------------
110 --
111 -- NAME: Encrypt
112 --
113 -- DESCRIPTION:
114 --
115 -- Encrypt plain text data using stream or block cipher with user
116 -- supplied key and optional iv.
117 --
118 -- PARAMETERS
119 --
120 -- plaintext - Plaintext data to be encrypted
121 -- crypto_type - Stream or block cipher type plus modifiers
122 -- key - Key to be used for encryption
123 -- iv - Optional IV for block ciphers. Default all zeros.
124 --
125 -- USAGE NOTES:
126 --
127 -- Block ciphers may be modified with chaining type (CBC most
128 -- common) and padding type (PKCS5 recommended). Of the four
129 -- common data formats, three have been provided: RAW, BLOB,
130 -- CLOB. For VARCHAR2 encryption, callers should first convert
131 -- to AL32UTF8 character set and then encrypt.
132 --
133 -- Encrypt(UTL_RAW.CAST_TO_RAW(CONVERT(src,'AL32UTF8')),typ,key);
134 --
135 -- As return type for encrypt is RAW, callers should consider
136 -- encoding it with RAWTOHEX or UTL_ENCODE.BASE64_ENCODE to make
137 -- it suitable for VARCHAR2 storage. These functions expand
138 -- data size by 2 and 4/3, respectively.
139 --
140 -- To improve readability, callers should define their own
141 -- package level constants to represent the ciphersuites used
142 -- for encryption and decryption.
143 --
144 -- For example:
145 --
146 -- DES_CBC_PKCS5 CONSTANT PLS_INTEGER := DBMS_CRYPTO.ENCRYPT_DES
147 -- + DBMS_CRYPTO.CHAIN_CBC
148 -- + DBMS_CRYPTO.PAD_PKCS5;
149 --
150 --
151 -- STREAM CIPHERS (RC4) ARE NOT RECOMMENDED FOR STORED DATA ENCRYPTION.
152 --
153 --
154 ------------------------------------------------------------------------
155
156 FUNCTION Encrypt (src IN RAW,
157 typ IN PLS_INTEGER,
158 key IN RAW,
159 iv IN RAW DEFAULT NULL)
160 RETURN RAW;
161
162 PROCEDURE Encrypt (dst IN OUT NOCOPY BLOB,
163 src IN BLOB,
164 typ IN PLS_INTEGER,
165 key IN RAW,
166 iv IN RAW DEFAULT NULL);
167
168 PROCEDURE Encrypt (dst IN OUT NOCOPY BLOB,
169 src IN CLOB CHARACTER SET ANY_CS,
170 typ IN PLS_INTEGER,
171 key IN RAW,
172 iv IN RAW DEFAULT NULL);
173
174
175 ------------------------------------------------------------------------
176 --
177 -- NAME: Decrypt
178 --
179 -- DESCRIPTION:
180 --
181 -- Decrypt crypt text data using stream or block cipher with user
182 -- supplied key and optional iv.
183 --
184 -- PARAMETERS
185 --
186 -- cryptext - Crypt text data to be decrypted
187 -- crypto_type - Stream or block cipher type plus modifiers
188 -- key - Key to be used for encryption
189 -- iv - Optional IV for block ciphers. Default all zeros.
190 --
191 -- USAGE NOTES:
192 -- To retrieve original plain text data, Decrypt must be called
193 -- with the same cipher, modifiers, key and iv used for
194 -- encryption. If crypt text data was converted to hex or
195 -- base64 prior to storage, it must be decoded using HEXTORAW or
196 -- UTL_ENCODE.BASE64_DECODE prior to decryption.
197 --
198 ------------------------------------------------------------------------
199
200 FUNCTION Decrypt (src IN RAW,
201 typ IN PLS_INTEGER,
202 key IN RAW,
203 iv IN RAW DEFAULT NULL)
204 RETURN RAW;
205
206 PROCEDURE Decrypt (dst IN OUT NOCOPY BLOB,
207 src IN BLOB,
208 typ IN PLS_INTEGER,
209 key IN RAW,
210 iv IN RAW DEFAULT NULL);
211
212 PROCEDURE Decrypt (dst IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
213 src IN BLOB,
214 typ IN PLS_INTEGER,
215 key IN RAW,
216 iv IN RAW DEFAULT NULL);
217
218
219 ------------------------------------------------------------------------
220 --
221 -- NAME: Hash
222 --
223 -- DESCRIPTION:
224 --
225 -- Hash source data by cryptographic hash type.
226 --
227 -- PARAMETERS
228 --
229 -- source - Source data to be hashed
230 -- hash_type - Hash algorithm to be used
231 --
232 -- USAGE NOTES:
233 -- SHA-1 (HASH_SH1) is recommended. Consider encoding returned
234 -- raw value to hex or base64 prior to storage.
235 --
236 ------------------------------------------------------------------------
237
238 FUNCTION Hash (src IN RAW,
239 typ IN PLS_INTEGER)
240 RETURN RAW DETERMINISTIC;
241
242 FUNCTION Hash (src IN BLOB,
243 typ IN PLS_INTEGER)
244 RETURN RAW DETERMINISTIC;
245
246 FUNCTION Hash (src IN CLOB CHARACTER SET ANY_CS,
247 typ IN PLS_INTEGER)
248 RETURN RAW DETERMINISTIC;
249
250
251 ------------------------------------------------------------------------
252 --
253 -- NAME: Mac
254 --
255 -- DESCRIPTION:
256 --
257 -- Message Authentication Code algorithms provide keyed message
258 -- protection.
259 --
260 -- PARAMETERS
261 --
262 -- source - Source data to be mac-ed
263 -- mac_type - Mac algorithm to be used
264 -- key - Key to be used for mac
265 --
266 -- USAGE NOTES:
267 -- Callers should consider encoding returned raw value to hex or
268 -- base64 prior to storage.
269 --
270 ------------------------------------------------------------------------
271 FUNCTION Mac (src IN RAW,
272 typ IN PLS_INTEGER,
273 key IN RAW)
274 RETURN RAW;
275
276 FUNCTION Mac (src IN BLOB,
277 typ IN PLS_INTEGER,
278 key IN RAW)
279 RETURN RAW;
280
281 FUNCTION Mac (src IN CLOB CHARACTER SET ANY_CS,
282 typ IN PLS_INTEGER,
283 key IN RAW)
284 RETURN RAW;
285
286
287 ------------------------------------------------------------------------
288 --
289 -- NAME: RandomBytes
290 --
291 -- DESCRIPTION:
292 --
293 -- Returns a raw value containing a pseudo-random sequence of
294 -- bytes.
295 --
296 -- PARAMETERS
297 --
298 -- number_bytes - Number of pseudo-random bytes to be generated.
299 --
300 -- USAGE NOTES:
301 -- number_bytes should not exceed maximum RAW length.
302 --
303 ------------------------------------------------------------------------
304 FUNCTION RandomBytes (number_bytes IN PLS_INTEGER)
305 RETURN RAW;
306
307
308 ------------------------------------------------------------------------
309 --
310 -- NAME: RandomNumber
311 --
312 -- DESCRIPTION:
313 --
314 -- Returns a random Oracle Number.
315 --
316 -- PARAMETERS
317 --
318 -- None.
319 --
320 ------------------------------------------------------------------------
321 FUNCTION RandomNumber
322 RETURN NUMBER;
323
324
325 ------------------------------------------------------------------------
326 --
327 -- NAME: RandomInteger
328 --
329 -- DESCRIPTION:
330 --
331 -- Returns a random BINARY_INTEGER.
332 --
333 -- PARAMETERS
334 --
335 -- None.
336 --
337 ------------------------------------------------------------------------
338 FUNCTION RandomInteger
339 RETURN BINARY_INTEGER;
340
341
342 PRAGMA RESTRICT_REFERENCES(DEFAULT, WNDS, RNDS, WNPS, RNPS);
343
344 END DBMS_CRYPTO;
[Home] [Help]