FwdLockConv.h revision fdd65a0fc7df2c878cc601e4c0f4021cb264f051 
1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef __FWDLOCKCONV_H__
18#define __FWDLOCKCONV_H__
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24#include <sys/types.h>
25
26/**
27 * The size of the data and header signatures combined. The signatures are adjacent to each other in
28 * the produced output file.
29 */
30#define FWD_LOCK_SIGNATURES_SIZE (2 * 20)
31
32/**
33 * Data type for the output from FwdLockConv_ConvertData.
34 */
35typedef struct FwdLockConv_ConvertData_Output {
36    /// The converted data.
37    void *pBuffer;
38
39    /// The size of the converted data.
40    size_t numBytes;
41
42    /// The file position where the error occurred, in the case of a syntax error.
43    off64_t errorPos;
44} FwdLockConv_ConvertData_Output_t;
45
46/**
47 * Data type for the output from FwdLockConv_CloseSession.
48 */
49typedef struct FwdLockConv_CloseSession_Output {
50    /// The final set of signatures.
51    unsigned char signatures[FWD_LOCK_SIGNATURES_SIZE];
52
53    /// The offset in the produced output file where the signatures are located.
54    off64_t fileOffset;
55
56    /// The file position where the error occurred, in the case of a syntax error.
57    off64_t errorPos;
58} FwdLockConv_CloseSession_Output_t;
59
60/**
61 * Data type for the output from the conversion process.
62 */
63typedef union FwdLockConv_Output {
64    FwdLockConv_ConvertData_Output_t fromConvertData;
65    FwdLockConv_CloseSession_Output_t fromCloseSession;
66} FwdLockConv_Output_t;
67
68/**
69 * Data type for the Posix-style read function used by the converter in pull mode.
70 *
71 * @param[in] fileDesc The file descriptor of a file opened for reading.
72 * @param[out] pBuffer A reference to the buffer that should receive the read data.
73 * @param[in] numBytes The number of bytes to read.
74 *
75 * @return The number of bytes read.
76 * @retval -1 Failure.
77 */
78typedef ssize_t FwdLockConv_ReadFunc_t(int fileDesc, void *pBuffer, size_t numBytes);
79
80/**
81 * Data type for the Posix-style write function used by the converter in pull mode.
82 *
83 * @param[in] fileDesc The file descriptor of a file opened for writing.
84 * @param[in] pBuffer A reference to the buffer containing the data to be written.
85 * @param[in] numBytes The number of bytes to write.
86 *
87 * @return The number of bytes written.
88 * @retval -1 Failure.
89 */
90typedef ssize_t FwdLockConv_WriteFunc_t(int fileDesc, const void *pBuffer, size_t numBytes);
91
92/**
93 * Data type for the Posix-style lseek function used by the converter in pull mode.
94 *
95 * @param[in] fileDesc The file descriptor of a file opened for writing.
96 * @param[in] offset The offset with which to update the file position.
97 * @param[in] whence One of SEEK_SET, SEEK_CUR, and SEEK_END.
98 *
99 * @return The new file position.
100 * @retval ((off64_t)-1) Failure.
101 */
102typedef off64_t FwdLockConv_LSeekFunc_t(int fileDesc, off64_t offset, int whence);
103
104/**
105 * The status codes returned by the converter functions.
106 */
107typedef enum FwdLockConv_Status {
108    /// The operation was successful.
109    FwdLockConv_Status_OK = 0,
110
111    /// An actual argument to the function is invalid (a program error on the caller's part).
112    FwdLockConv_Status_InvalidArgument = 1,
113
114    /// There is not enough free dynamic memory to complete the operation.
115    FwdLockConv_Status_OutOfMemory = 2,
116
117    /// An error occurred while opening the input file.
118    FwdLockConv_Status_FileNotFound = 3,
119
120    /// An error occurred while creating the output file.
121    FwdLockConv_Status_FileCreationFailed = 4,
122
123    /// An error occurred while reading from the input file.
124    FwdLockConv_Status_FileReadError = 5,
125
126    /// An error occurred while writing to the output file.
127    FwdLockConv_Status_FileWriteError = 6,
128
129    /// An error occurred while seeking to a new file position within the output file.
130    FwdLockConv_Status_FileSeekError = 7,
131
132    /// The input file is not a syntactically correct OMA DRM v1 Forward Lock file.
133    FwdLockConv_Status_SyntaxError = 8,
134
135    /// Support for this DRM file format has been disabled in the current product configuration.
136    FwdLockConv_Status_UnsupportedFileFormat = 9,
137
138    /// The content transfer encoding is not one of "binary", "base64", "7bit", or "8bit"
139    /// (case-insensitive).
140    FwdLockConv_Status_UnsupportedContentTransferEncoding = 10,
141
142    /// The generation of a random number failed.
143    FwdLockConv_Status_RandomNumberGenerationFailed = 11,
144
145    /// Key encryption failed.
146    FwdLockConv_Status_KeyEncryptionFailed = 12,
147
148    /// The calculation of a keyed hash for integrity protection failed.
149    FwdLockConv_Status_IntegrityProtectionFailed = 13,
150
151    /// There are too many ongoing sessions for another one to be opened.
152    FwdLockConv_Status_TooManySessions = 14,
153
154    /// An unexpected error occurred.
155    FwdLockConv_Status_ProgramError = 15
156} FwdLockConv_Status_t;
157
158/**
159 * Opens a session for converting an OMA DRM v1 Forward Lock file to the internal Forward Lock file
160 * format.
161 *
162 * @param[out] pSessionId The session ID.
163 * @param[out] pOutput The output from the conversion process (initialized).
164 *
165 * @return A status code.
166 * @retval FwdLockConv_Status_OK
167 * @retval FwdLockConv_Status_InvalidArgument
168 * @retval FwdLockConv_Status_TooManySessions
169 */
170FwdLockConv_Status_t FwdLockConv_OpenSession(int *pSessionId, FwdLockConv_Output_t *pOutput);
171
172/**
173 * Supplies the converter with data to convert. The caller is expected to write the converted data
174 * to file. Can be called an arbitrary number of times.
175 *
176 * @param[in] sessionId The session ID.
177 * @param[in] pBuffer A reference to a buffer containing the data to convert.
178 * @param[in] numBytes The number of bytes to convert.
179 * @param[in,out] pOutput The output from the conversion process (allocated/reallocated).
180 *
181 * @return A status code.
182 * @retval FwdLockConv_Status_OK
183 * @retval FwdLockConv_Status_InvalidArgument
184 * @retval FwdLockConv_Status_OutOfMemory
185 * @retval FwdLockConv_Status_SyntaxError
186 * @retval FwdLockConv_Status_UnsupportedFileFormat
187 * @retval FwdLockConv_Status_UnsupportedContentTransferEncoding
188 * @retval FwdLockConv_Status_RandomNumberGenerationFailed
189 * @retval FwdLockConv_Status_KeyEncryptionFailed
190 * @retval FwdLockConv_Status_DataEncryptionFailed
191 */
192FwdLockConv_Status_t FwdLockConv_ConvertData(int sessionId,
193                                             const void *pBuffer,
194                                             size_t numBytes,
195                                             FwdLockConv_Output_t *pOutput);
196
197/**
198 * Closes a session for converting an OMA DRM v1 Forward Lock file to the internal Forward Lock
199 * file format. The caller must update the produced output file at the indicated file offset with
200 * the final set of signatures.
201 *
202 * @param[in] sessionId The session ID.
203 * @param[in,out] pOutput The output from the conversion process (deallocated and overwritten).
204 *
205 * @return A status code.
206 * @retval FwdLockConv_Status_OK
207 * @retval FwdLockConv_Status_InvalidArgument
208 * @retval FwdLockConv_Status_OutOfMemory
209 * @retval FwdLockConv_Status_IntegrityProtectionFailed
210 */
211FwdLockConv_Status_t FwdLockConv_CloseSession(int sessionId, FwdLockConv_Output_t *pOutput);
212
213/**
214 * Converts an open OMA DRM v1 Forward Lock file to the internal Forward Lock file format in pull
215 * mode.
216 *
217 * @param[in] inputFileDesc The file descriptor of the open input file.
218 * @param[in] fpReadFunc A reference to a read function that can operate on the open input file.
219 * @param[in] outputFileDesc The file descriptor of the open output file.
220 * @param[in] fpWriteFunc A reference to a write function that can operate on the open output file.
221 * @param[in] fpLSeekFunc A reference to an lseek function that can operate on the open output file.
222 * @param[out] pErrorPos
223 *   The file position where the error occurred, in the case of a syntax error. May be NULL.
224 *
225 * @return A status code.
226 * @retval FwdLockConv_Status_OK
227 * @retval FwdLockConv_Status_InvalidArgument
228 * @retval FwdLockConv_Status_OutOfMemory
229 * @retval FwdLockConv_Status_FileReadError
230 * @retval FwdLockConv_Status_FileWriteError
231 * @retval FwdLockConv_Status_FileSeekError
232 * @retval FwdLockConv_Status_SyntaxError
233 * @retval FwdLockConv_Status_UnsupportedFileFormat
234 * @retval FwdLockConv_Status_UnsupportedContentTransferEncoding
235 * @retval FwdLockConv_Status_RandomNumberGenerationFailed
236 * @retval FwdLockConv_Status_KeyEncryptionFailed
237 * @retval FwdLockConv_Status_DataEncryptionFailed
238 * @retval FwdLockConv_Status_IntegrityProtectionFailed
239 * @retval FwdLockConv_Status_TooManySessions
240 */
241FwdLockConv_Status_t FwdLockConv_ConvertOpenFile(int inputFileDesc,
242                                                 FwdLockConv_ReadFunc_t *fpReadFunc,
243                                                 int outputFileDesc,
244                                                 FwdLockConv_WriteFunc_t *fpWriteFunc,
245                                                 FwdLockConv_LSeekFunc_t *fpLSeekFunc,
246                                                 off64_t *pErrorPos);
247
248/**
249 * Converts an OMA DRM v1 Forward Lock file to the internal Forward Lock file format in pull mode.
250 *
251 * @param[in] pInputFilename A reference to the input filename.
252 * @param[in] pOutputFilename A reference to the output filename.
253 * @param[out] pErrorPos
254 *   The file position where the error occurred, in the case of a syntax error. May be NULL.
255 *
256 * @return A status code.
257 * @retval FwdLockConv_Status_OK
258 * @retval FwdLockConv_Status_InvalidArgument
259 * @retval FwdLockConv_Status_OutOfMemory
260 * @retval FwdLockConv_Status_FileNotFound
261 * @retval FwdLockConv_Status_FileCreationFailed
262 * @retval FwdLockConv_Status_FileReadError
263 * @retval FwdLockConv_Status_FileWriteError
264 * @retval FwdLockConv_Status_FileSeekError
265 * @retval FwdLockConv_Status_SyntaxError
266 * @retval FwdLockConv_Status_UnsupportedFileFormat
267 * @retval FwdLockConv_Status_UnsupportedContentTransferEncoding
268 * @retval FwdLockConv_Status_RandomNumberGenerationFailed
269 * @retval FwdLockConv_Status_KeyEncryptionFailed
270 * @retval FwdLockConv_Status_DataEncryptionFailed
271 * @retval FwdLockConv_Status_IntegrityProtectionFailed
272 * @retval FwdLockConv_Status_TooManySessions
273 */
274FwdLockConv_Status_t FwdLockConv_ConvertFile(const char *pInputFilename,
275                                             const char *pOutputFilename,
276                                             off64_t *pErrorPos);
277
278#ifdef __cplusplus
279}
280#endif
281
282#endif // __FWDLOCKCONV_H__
283