@@ -45,31 +45,70 @@ class CDOC_EXPORT CDocReader {
4545 */
4646 virtual const std::vector<Lock> getLocks () = 0;
4747 /* *
48- * @brief Fetches the lock for certificate
48+ * @brief Finds the lock index for given certificate
4949 *
5050 * Returns the first lock that can be opened by the private key of the certificate holder.
5151 * @param cert a x509 certificate (der)
5252 * @return lock index or error code
5353 */
5454 virtual int getLockForCert (const std::vector<uint8_t >& cert) = 0;
5555 /* *
56- * @brief Fetches FMK from provided lock
56+ * @brief Fetches FMK from given lock
5757 *
58- * Fetches FMK (File Master Key) from the provided decryption lock . Depending on the lock type it uses a relevant CryptoBackend and/or
58+ * Fetches FMK (File Master Key) from the lock with given index . Depending on the lock type it uses a relevant CryptoBackend and/or
5959 * NetworkBackend method to either fetch secret and derive key or perform external decryption of encrypted KEK.
6060 * @param fmk The FMK of the document
61- * @param lock a lock (from document lock list)
61+ * @param lock_idx the index of a lock (in the document lock list)
6262 * @return error code or OK
6363 */
6464 virtual int getFMK (std::vector<uint8_t >& fmk, unsigned int lock_idx) = 0;
6565
6666 // Pull interface
67+ /* *
68+ * @brief beginDecryption start decrypting document
69+ *
70+ * Starts decryption of the document. This may involve parsing and decrypting headers, checking
71+ * file and key integrity etc.
72+ * @param fmk File Master Key of the document
73+ * @return error code or OK
74+ */
6775 virtual int beginDecryption (const std::vector<uint8_t >& fmk) = 0;
76+ /* *
77+ * @brief nextFile start decrypting the next file
78+ *
79+ * Begins decrypting the next file in document. On success the file name and size are filled and the
80+ * method returns OK. If there are no more file in the document, END_OF_STREAM is returned.
81+ * It is OK to call nextFile before reading the whole data from the previous one.
82+ * @param name the name of the next file
83+ * @param size the size of the next file
84+ * @return error code, OK or END_OF_STREAM
85+ */
6886 virtual int nextFile (std::string& name, int64_t & size) = 0;
69- int nextFile (FileInfo& info) { return nextFile (info.name , info.size ); }
87+ /* *
88+ * @brief readData read data from the current file
89+ *
90+ * Read bytes from the current file into the buffer. The number of bytes read is always the
91+ * requested number, unless end of file is reached or error occurs. Thus the end of file is marked
92+ * by returning 0.
93+ * @param dst destination byte buffer
94+ * @param size the number of bytes to read
95+ * @return the number of bytes actually read or error code
96+ */
7097 virtual int64_t readData (uint8_t *dst, size_t size) = 0;
98+ /* *
99+ * @brief finishDecryption finish decryption of file
100+ *
101+ * Finishes the decryption of file. This may onvolve releasing buffers, closing hardware keys etc.
102+ * @return error code or OK
103+ */
71104 virtual int finishDecryption () = 0;
72105
106+ /* *
107+ * @brief nextFile start decrypting the next file
108+ * @param info a FileInfo structure
109+ * @return error code, OK or END_OF_STREAM
110+ */
111+ int nextFile (FileInfo& info) { return nextFile (info.name , info.size ); }
73112
74113 // Push interface
75114 /* *
@@ -90,12 +129,40 @@ class CDOC_EXPORT CDocReader {
90129 /* *
91130 * @brief try to determine the cdoc file version
92131 * @param path a path to file
93- * @return version, -1 if not a valid CDoc file
132+ * @return version or error code if not a readable CDoc file
94133 */
95134 static int getCDocFileVersion (const std::string& path);
135+ /* *
136+ * @brief try to determine the cdoc file version
137+ * @param src the container source
138+ * @return version or error code if not a readable CDoc file
139+ */
96140 static int getCDocFileVersion (DataSource *src);
97141
142+ /* *
143+ * @brief createReader create CDoc document reader
144+ *
145+ * Creates a new document reader if source is a valid CDoc container (either version 1 or 2).
146+ * The network backend may be null if keyservers are not used.
147+ * @param src the container source
148+ * @param take_ownership if true the source is deleted in reader destructor
149+ * @param conf a configuration object
150+ * @param crypto a cryptographic backend implementation
151+ * @param network a network backend implementation
152+ * @return a new CDocReader or null
153+ */
98154 static CDocReader *createReader (DataSource *src, bool take_ownership, Configuration *conf, CryptoBackend *crypto, NetworkBackend *network);
155+ /* *
156+ * @brief createReader create CDoc document reader
157+ *
158+ * Creates a new document reader if file is a valid CDoc container (either version 1 or 2)
159+ * The network backend may be null if keyservers are not used.
160+ * @param path the path to file
161+ * @param conf a configuration object
162+ * @param crypto a cryptographic backend implementation
163+ * @param network a network backend implementation
164+ * @return a new CDocReader or null
165+ */
99166 static CDocReader *createReader (const std::string& path, Configuration *conf, CryptoBackend *crypto, NetworkBackend *network);
100167
101168#if LIBCDOC_TESTING
0 commit comments