1 /*===========================================================================
2 *
3 *                            PUBLIC DOMAIN NOTICE
4 *               National Center for Biotechnology Information
5 *
6 *  This software/database is a "United States Government Work" under the
7 *  terms of the United States Copyright Act.  It was written as part of
8 *  the author's official duties as a United States Government employee and
9 *  thus cannot be copyrighted.  This software/database is freely available
10 *  to the public for use. The National Library of Medicine and the U.S.
11 *  Government have not placed any restriction on its use or reproduction.
12 *
13 *  Although all reasonable efforts have been taken to ensure the accuracy
14 *  and reliability of the software and data, the NLM and the U.S.
15 *  Government do not and cannot warrant the performance or results that
16 *  may be obtained by using this software or data. The NLM and the U.S.
17 *  Government disclaim all warranties, express or implied, including
18 *  warranties of performance, merchantability or fitness for any particular
19 *  purpose.
20 *
21 *  Please cite the author in any work or product based on this material.
22 *
23 * ===========================================================================
24 *
25 */
26 
27 #ifndef _h_krypto_wgaencryptfile_
28 #define _h_krypto_wgaencryptfile_
29 
30 #ifndef _h_krypto_extern_
31 #include <krypto/extern.h>
32 #endif
33 
34 #ifndef _h_klib_defs_
35 #include <klib/defs.h>
36 #endif
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 
43 /*--------------------------------------------------------------------------
44  * forwards
45  */
46 struct KFile;
47 
48 
49 /*--------------------------------------------------------------------------
50  * KFile
51  *  wga extensions
52  */
53 
54 /* MakeWGAEncRead
55  *
56  * Parameters:
57  *   pself is a KFile that will represent the unencrypted side of operations.
58  *
59  *   encrypted is a KFile that will represent the encrypted side of operations.
60  *
61  *   key is an arbitrary array of characters
62  *
63  *   key_size is how many bytes to use from key.  Maximum used is 256.
64  *
65  *   encoding is one of the three values defined by FER_ENCODING above.  Any
66  *   other values will cause a failure.
67  *
68  * KFileMakeWGAEncRead
69  *   A file opened for read can only read and decrypt an encrypted file.  Seeks
70  *   within the file are allowed if the KFile for the encrypted file allows
71  *    seeks.
72  *
73  * KFileMakeWGAEncUpdate
74  *   A file opened for update must be able to read and write from the encrypted
75  *   file.  Seeks within the file are allowed if the KFile for the encrypted
76  *   file allows seeks.
77  *
78  * KFileMakeWGAEncRead
79  *   A Write opened file can only be written.  Seeks backwards are not allowed.
80  *   Seeks forward will cause NUL data bytes to be inserted before encryption.
81  *   An attempt will be made to truncate the encrypted file but failure of that
82  *   operation will not fail this call.  Writes will begin at position 0.  If
83  *   the file already existed and could not be truncated a corrupt file will
84  *   result if the whole of the old contents are not over-written.
85  *
86  *
87  * NOTE: cipher must be of type kcipherAES
88  *
89  */
90 KRYPTO_EXTERN rc_t CC KFileMakeWGAEncRead (const struct KFile ** pself,
91                                            const struct KFile * encrypted,
92                                            const char * key,
93                                            size_t key_size);
94 
95 
96 /* IsWGAEnc
97  *  identify whether a file is a KFileWGAEnc type encrypted file by the header.
98  *  read the header into a buffer and pass it into this function.
99  *  The buffer_size needs to be at least 8 but more bytes lead to a better
100  *  check up to the size of the header of a KFileWGAEnc type encrypted file.
101  *  This file type is deprecated and is not versioned.  Hopefully we won't
102  *  have to deal with changes to the format.
103  *
104  * Possible returns:
105  *  0:
106  *      the file is an identified KFileWGAEnc type file.  False positives are
107  *      possible if a file happens to match at 8 or more bytes
108  *
109  *  RC (rcFS, rcFile, rcIdentifying, rcFile, rcWrongType)
110  *      the file is definitely not a KFileWGAEnc type encrypted file.
111  *
112  *  RC (rcFS, rcFile, rcIdentifying, rcParam, rcNull)
113  *      bad parameters in the call
114  *
115  *  RC (rcFS, rcFile, rcIdentifying, rcBuffer, rcInsufficient)
116  *      not a large enough buffer to make an identification
117  */
118 KRYPTO_EXTERN rc_t CC KFileIsWGAEnc (const void * buffer, size_t buffer_size);
119 
120 KRYPTO_EXTERN rc_t CC WGAEncValidate (const struct KFile * file,
121                                       const char * password,
122                                       size_t password_size);
123 
124 #ifdef __cplusplus
125 }
126 #endif
127 
128 #endif /* _h_kfs_wgaencryptfile_ */
129