1 PACKAGE IBY_SECURITY_PKG AS
2 /* $Header: ibysecs.pls 120.14.12010000.7 2008/08/30 06:37:30 lmallick ship $ */
3
4 --
5 -- module name used for the application debugging framework
6 --
7 G_DEBUG_MODULE CONSTANT VARCHAR2(100) := 'iby.plsql.IBY_SECURITY_PKG';
8
9 -- Encryption modes
10 G_ENCRYPT_MODE_SCHED CONSTANT VARCHAR2(30) := 'SCHEDULED';
11 G_ENCRYPT_MODE_NONE CONSTANT VARCHAR2(30) := 'NONE';
12 G_ENCRYPT_MODE_INSTANT CONSTANT VARCHAR2(30) := 'IMMEDIATE';
13
14 -- Mask options
15 G_MASK_NONE CONSTANT VARCHAR2(30) := 'DISPLAY_ALL';
16 G_MASK_ALL CONSTANT VARCHAR2(30) := 'DISPLAY_NONE';
17 G_MASK_PREFIX CONSTANT VARCHAR2(30) := 'DISPLAY_LAST';
18 G_MASK_POSTFIX CONSTANT VARCHAR2(30) := 'DISPLAY_FIRST';
19
20 -- Clear-text encoding schemes
21 G_ENCODING_NUMERIC CONSTANT VARCHAR2(30) := 'NUMERIC';
22 G_ENCODING_UTF8_AL32 CONSTANT VARCHAR2(30) := 'AL32UTF8';
23
24 --
25 -- Maximum length (in bytes) of a triple DES key.
26 --
27 G_DES3_MAX_KEY_LEN CONSTANT INTEGER := 24;
28
29 --
30 -- shared FND wallet; used for making http callouts from the
31 -- database
32 --
33 C_SHARED_WALLET_LOC_PROP_NAME CONSTANT VARCHAR2(50) := 'FND_DB_WALLET_DIR';
34
35 -- Masking character
36 G_MASK_CHARACTER CONSTANT VARCHAR2(1) := 'X';
37
38 -- Expiry date string format to be used before encryption
39 -- Do not modify this variable. This might cause existing
40 -- data corruption !!
41 G_ENCRYPTED_EXPDATE_FORMAT VARCHAR2(20) := 'MMYYYY';
42 G_MASKED_EXPDATE_FORMAT VARCHAR2(20) := 'MM/YY';
43
44
45 SUBTYPE DES3_KEY_TYPE IS RAW(24);
46
47
48 --
49 -- USE
50 -- Validates the system security key
51 --
52 -- ARGS
53 -- p_sys_sec_key => system security key in plain text form
54 --
55 -- OUTS
56 -- x_err_code => IBY_XXXX type error code if the key failed to validate
57 -- or NULL if validation succeeds
58 --
59 PROCEDURE Validate_Sys_Key
60 (p_sys_sec_key IN DES3_KEY_TYPE,
61 x_err_code OUT NOCOPY VARCHAR2
62 );
63
64 --
65 -- USE
66 -- Creates the system security key
67 --
68 -- ARGS
69 -- p_sys_sec_key => the system security key
70 -- p_wallet_path => the path of the key wallet
71 --
72 -- NOTES
73 -- note that it may be padded or otherwised changed by the
74 -- prepare_des3key() function
75 --
76 PROCEDURE Create_Sys_Key
77 (p_commit IN VARCHAR2,
78 p_sys_sec_key IN DES3_KEY_TYPE,
79 p_wallet_path IN VARCHAR2
80 );
81
82 --
83 -- USE
84 -- Changes the system security key
85 --
86 -- ARGS
87 -- p_commit => Whether to commit changes
88 -- p_sys_key_old => The system security key
89 -- p_sys_key_new => The new security key
90 -- p_wallet_path_new => New wallet patch location
91 --
92 -- NOTES
93 -- note that the new key may be padded or otherwised changed by the
94 -- prepare_des3key() function
95 --
96 PROCEDURE Change_Sys_Key
97 (p_commit IN VARCHAR2 := FND_API.G_FALSE,
98 p_sys_key_old IN DES3_KEY_TYPE,
99 p_sys_key_new IN DES3_KEY_TYPE,
100 p_wallet_path_new IN VARCHAR2
101 );
102
103 --
104 -- USE
105 -- Gets the next system subkey, creating a new one if the current
106 -- key has exceeded its usage limit
107 --
108 -- ARGS
109 -- p_commit => Whether to commit changes
110 -- p_masterkey => The system master key
111 -- p_instrument_use_flag => If 'N' then the key is being used on existing
112 -- data; else it is for new data and so increase
113 -- its use count
114 -- x_subkey_id => primary key of the sub-key to use
115 -- x_subkey => subkey clear text
116 --
117 PROCEDURE Get_Sys_Subkey
118 (p_commit IN VARCHAR2 := FND_API.G_FALSE,
119 p_masterkey IN DES3_KEY_TYPE,
120 p_inc_use_flag IN VARCHAR2,
121 x_subkey_id OUT NOCOPY iby_sys_security_subkeys.sec_subkey_id%TYPE,
122 x_subkey OUT NOCOPY DES3_KEY_TYPE
123 );
124
125 --
126 -- USE
127 -- Gets the subkey based upon its cipher-text values from the database
128 -- ARGS
129 -- p_masterkey => The system master key
130 -- p_subkey_cipher => The subkey cipher text
131 --
132 FUNCTION Get_Sys_Subkey
133 (p_sys_key IN DES3_KEY_TYPE,
134 p_subkey_cipher IN iby_sys_security_subkeys.subkey_cipher_text%TYPE
135 )
136 RETURN DES3_KEY_TYPE;
137
138 --
139 -- USE
140 -- Gets the next system subkey, creating a new one if the current
141 -- key has exceeded its usage limit
142 -- This is similar to the Get_Sys_Subkey API, except for the fact
143 -- that it returns the Hex representation of the subkey as a
144 -- varchar2 value. This can be used by the java layer encryption.
145 --
146 -- ARGS
147 -- p_commit => Whether to commit changes
148 -- p_sys_key => The system master key
149 -- p_instrument_use_flag => If 'N' then the key is being used on existing
150 -- data; else it is for new data and so increase
151 -- its use count
152 -- x_subkey_id => primary key of the sub-key to use
153 -- x_subkey_Hex => Hex value of the subkey clear text
154 --
155 PROCEDURE Get_Sys_Subkey_Hex
156 (p_commit IN VARCHAR2 := FND_API.G_FALSE,
157 p_sys_key IN DES3_KEY_TYPE,
158 p_inc_use_flag IN VARCHAR2,
159 x_subkey_id OUT NOCOPY iby_sys_security_subkeys.sec_subkey_id%TYPE,
160 x_subkey_Hex OUT NOCOPY VARCHAR2
161 );
162
163 --
164 -- USE
165 -- Gets the Hex form of subkey based upon the subkey_id
166 -- This API will be called to pass the Hex key to java
167 -- layer, which would be in turn used to decrypt the
168 -- acknowledgment files.
169 -- ARGS
170 -- p_sys_key => The system master key
171 -- p_subkey_id => The subkey id
172 --
173 FUNCTION Get_Sys_Subkey_Hex
174 (p_subkey_id IN iby_sys_security_subkeys.sec_subkey_id%TYPE,
175 p_sys_key IN DES3_KEY_TYPE
176 )
177 RETURN VARCHAR2;
178
179
180 --
181 -- USE
182 -- Pads or otherwise prepares clear text to be ciphered
183 --
184 -- ARGS
185 -- p_cleartxt => the data (unencrypted) to prepare
186 -- p_padchar => padding character to use
187 --
188 -- RETURN
189 -- The data padded and ready to be input to a cipher function
190 --
191 FUNCTION Prepare_Cleartxt( p_cleartxt IN VARCHAR2, p_padchar IN VARCHAR2 )
192 RETURN VARCHAR2;
193
194 --
195 -- USE
196 -- Unpacks or otherwise unpads clear text that was ciphered
197 --
198 -- ARGS
199 -- p_cleartxt => the clear text in its to-be-packed form
200 -- p_padchar => padding character used to pack it
201 --
202 -- RETURN
203 -- The clear text/data as it originally was
204 --
205 FUNCTION Unpack_Cleartxt( p_cleartxt IN VARCHAR2, p_padchar IN VARCHAR2 )
206 RETURN VARCHAR2;
207
208 --
209 -- USE
210 -- Light-weight ciphering function; does not do any key validation, and
211 -- choses strong encryption was encoding based on in input parameter
212 --
213 -- ARGS
214 -- p_data => the data to cipher
215 -- p_sec_key => encryption key to use; should be already validated
216 -- p_pad => character used to pad the data to appropriate length
217 -- p_encrypt => 'Y' if data should be encrypted; otherwise it will be
218 -- encoded and the passed security key ignored
219 --
220 FUNCTION Cipher_Data
221 (p_data IN VARCHAR2,
222 p_sec_key IN IBY_SECURITY_PKG.DES3_KEY_TYPE,
223 p_pad IN VARCHAR2,
224 p_encrypt IN VARCHAR2
225 )
226 RETURN VARCHAR2;
227
228 --
229 -- USE
230 -- Gets the hash value of a string
231 -- ARGS
232 -- p_text => the text
233 -- p_salt => if FND_API.G_TRUE, then the text is "salted"
234 --
235 FUNCTION Get_Hash( p_text IN VARCHAR2, p_salt IN VARCHAR2 )
236 RETURN VARCHAR2;
237
238 --
239 -- USE
240 -- Gets the hash value of a string
241 -- ARGS
242 -- p_text => the text
243 -- p_salt => if FND_API.G_TRUE, then the text is "salted"
244 -- p_site_salt => RAWTOHEX(IBY_SECURITY_PKG.get_site_salt())
245 --
246 -- bug 7228583
247 FUNCTION Get_Hash( p_text IN VARCHAR2, p_salt IN VARCHAR2, p_site_salt IN VARCHAR2)
248 RETURN VARCHAR2;
249
250 --
251 -- USE
252 -- Gets raw site salt
253
254 FUNCTION get_site_salt
255 RETURN RAW;
256
257 --
258 -- USE
259 -- Gets the version of the salting scheme
260 --
261 FUNCTION get_salt_version RETURN NUMBER;
262
263 --
264 -- USE
265 -- Generates hashes for RAW values
266 --
267 FUNCTION Get_Raw_Hash( p_data IN RAW ) RETURN RAW;
268
269 --
270 -- USE
271 -- Generates the (salted) hash for a key
272 --
273 FUNCTION Get_Key_Hash( p_sys_key IN RAW ) RETURN RAW;
274
275 --
276 -- USE
277 -- Masks the given data
278 -- ARGS
279 -- p_data => the text to mask
280 -- p_mask_option => on the of the mask option constants; whether to
281 -- mask all, none, from the beginning, or from the end
282 -- of the data
283 -- p_unmask_len => number of characters to expose
284 -- p_mask_char => masking character
285 --
286 FUNCTION Mask_Data
287 (p_data IN VARCHAR2,
288 p_mask_option IN VARCHAR2,
289 p_unmask_len IN NUMBER,
290 p_mask_char IN VARCHAR2
291 )
292 RETURN VARCHAR2;
293
294 --
295 -- USE
296 -- Masks the given date value
297 -- ARGS
298 -- p_date => the date value to mask
299 -- p_return_format => The date format in which the
300 -- the returned mask value needs to
301 -- be in.
302 -- p_mask_char => masking character
303 --
304 FUNCTION Mask_Date_Field
305 (p_date IN DATE,
306 p_return_format IN VARCHAR2,
307 p_mask_char IN VARCHAR2
308 )
309 RETURN VARCHAR2;
310
311 --
312 -- USE
313 -- Gets the unmasked portion of the given data
314 -- ARGS
315 -- p_data => the text to mask
316 -- p_mask_option => on the of the mask option constants; whether to
317 -- mask all, none, from the beginning, or from the end
318 -- of the data
319 -- p_unmask_len => number of characters to expose
320 --
321 FUNCTION Get_Unmasked_Data
322 ( p_data IN VARCHAR2, p_mask_option IN VARCHAR2, p_unmask_len IN NUMBER )
323 RETURN VARCHAR2;
324
325 --
326 -- USE
327 -- Encodes a number into a compressed binary representation
328 -- ARGS
329 -- p_number => The number to encode
330 -- p_des3mask => Whether to mask the data for DES3 encryption
331 -- RETURN
332 -- The number encoded in a unit 8 length hex string
333 -- NOTES
334 -- !!! DO NOT MODIFY THE ESSENTIAL CHARACTERISTICS OF THIS FUNCTION !!!
335 -- !!! DOING SO COULD LEAD TO CREDIT CARD DATA CORRUPTION !!!
336 --
337 FUNCTION Encode_Number( p_number IN VARCHAR2, p_des3mask IN BOOLEAN )
338 RETURN VARCHAR2;
339
340 --
341 -- USE
342 -- Decodes a number after decryption
343 -- ARGS
344 -- p_number => The encoded number
345 -- p_length => The number length (in base 10 representation)
346 -- p_des3mask => Whether to unmask the data from DES3 encryption
347 -- NOTES
348 -- !!! DO NOT MODIFY THE ESSENTIAL CHARACTERISTICS OF THIS FUNCTION !!!
349 -- !!! DOING SO COULD LEAD TO CREDIT CARD DATA CORRUPTION !!!
350 --
351 FUNCTION Decode_Number
352 ( p_number IN VARCHAR2, p_length IN NUMBER, p_des3mask IN BOOLEAN )
353 RETURN VARCHAR2;
354
355 --
356 -- USE
357 -- Encodes a number into a compressed binary representation
358 -- This does exactly the same thing as the Encode_Number API
359 -- The only difference is, it pads the input number to
360 -- 32-Bytes. This is a PABP mandate for cvv values.
361 -- ARGS
362 -- p_number => The number to encode (CVV)
363 -- p_des3mask => Whether to mask the data for DES3 encryption
364 -- RETURN
365 -- The number encoded in a unit 32 length hex string
366 -- NOTES
367 -- !!! DO NOT MODIFY THE ESSENTIAL CHARACTERISTICS OF THIS FUNCTION !!!
368 -- !!! DOING SO COULD LEAD TO CREDIT CARD DATA CORRUPTION !!!
369 --
370 FUNCTION Encode_CVV( p_number IN VARCHAR2, p_des3mask IN BOOLEAN )
371 RETURN VARCHAR2;
372
373
374 -- USE
375 -- Creates a secure segment using the next subkey.
376 -- ARGS
377 -- p_commit => if FND_API.G_TRUE, commit the data
378 -- p_segment => raw segment data
379 -- p_encoding => binary encoding scheme for the segment data
380 -- p_sys_key => The system key
381 -- OUTS
382 -- x_segment_id => Primary key of the segment created
383 --
384 PROCEDURE Create_Segment
385 (p_commit IN VARCHAR2 := FND_API.G_FALSE,
386 p_segment IN RAW,
387 p_encoding IN VARCHAR2,
388 p_sys_key IN DES3_KEY_TYPE,
389 x_segment_id OUT NOCOPY iby_security_segments.sec_segment_id%TYPE
390 );
391
392 PROCEDURE Update_Segment
393 (p_commit IN VARCHAR2 := FND_API.G_FALSE,
394 p_segment_id IN iby_security_segments.sec_segment_id%TYPE,
395 p_segment IN RAW,
396 p_encoding IN VARCHAR2,
397 p_sys_key IN DES3_KEY_TYPE,
398 p_subkey_cipher IN DES3_KEY_TYPE
399 );
400
401 --
402 -- USE
403 -- Creates a security credential for the given key
404 --
405 PROCEDURE Store_Credential( p_key IN VARCHAR2, x_cred OUT NOCOPY NUMBER );
406
407 --
408 -- USE
409 -- Verifies if the given credential was issued for the given
410 -- key.
411 --
412 PROCEDURE Verify_Credential
413 ( p_key IN VARCHAR2, p_cred IN NUMBER, x_verify OUT NOCOPY VARCHAR2 );
414
415 --
416 -- USE
417 -- Utility function for reciphering subkeys
418 --
419 FUNCTION Recipher_Key
420 ( p_data IN RAW, p_oldkey IN DES3_KEY_TYPE, p_newkey IN DES3_KEY_TYPE )
421 RETURN RAW;
422
423 FUNCTION Gen_Des3_Key( p_random_seed IN RAW ) RETURN RAW;
424
425 --
426 -- USE
427 -- PKCS5 padding function; copied from AFSOCTKB.pls
428 FUNCTION PKCS5_Pad(p_data IN RAW) RETURN RAW;
429
430 --
431 -- USE
432 -- PKCS5 unpadding function; copied from AFSOCTKB.pls
433 --
434 FUNCTION PKCS5_Unpad(p_data raw) RETURN RAW;
435
436 /* Bug 6018583: Implementation of the sceurity around Account Option Values
437 and Transmission Values
438 The entire code written below is added for the above purpose.
439 */
440
441 --
442 -- encrypt_field_vals
443 -- This function returns sec_segment_id.
444 --
445 FUNCTION encrypt_field_vals
446 (
447 p_value IN VARCHAR2,
448 master_key_in IN DES3_KEY_TYPE,
449 p_sec_segment_id IN NUMBER,
450 p_commit IN VARCHAR2 DEFAULT 'N'
451 ) RETURN NUMBER;
452
453 --
454 -- encrypt_num_field_vals
455 -- This function returns sec_segment_id.
456 --
457 FUNCTION encrypt_num_field_vals
458 (
459 p_value IN NUMBER,
460 master_key_in IN DES3_KEY_TYPE,
461 p_sec_segment_id IN NUMBER,
462 p_commit IN VARCHAR2 DEFAULT 'N'
463 ) RETURN NUMBER;
464
465 --
466 -- encrypt_date_field_vals
467 -- This function returns sec_segment_id.
468 -- This function will truncate the date value to
469 -- mmyyyy format and then create the corresponding
470 -- cipher text.
471 --
472 FUNCTION encrypt_date_field
473 (
474 p_value IN DATE,
475 master_key_in IN DES3_KEY_TYPE,
476 p_sec_segment_id IN NUMBER,
480 --
477 p_commit IN VARCHAR2 DEFAULT 'N'
478 ) RETURN NUMBER;
479
481 -- decrypt_field_vals
482 -- This function returns decrypted value.
483 --
484 FUNCTION decrypt_field_vals
485 (
486 p_sec_segment_id IN NUMBER,
487 master_key_in IN DES3_KEY_TYPE
488 ) RETURN VARCHAR2;
489
490 --
491 -- decrypt_num_field_vals
492 -- This function returns decrypted value.
493 --
494 FUNCTION decrypt_num_field_vals
495 (
496 p_sec_segment_id IN NUMBER,
497 master_key_in IN DES3_KEY_TYPE
498 ) RETURN NUMBER;
499 --
500 -- decrypt_date_field_vals
501 -- This function returns decrypted date value that is
502 -- truncated to the last day of month.
503 --
504 FUNCTION decrypt_date_field
505 (
506 p_sec_segment_id IN NUMBER,
507 master_key_in IN DES3_KEY_TYPE
508 ) RETURN DATE;
509
510 END IBY_SECURITY_PKG;