Mercurial > trustbridge

annotate common/listutil.h @ 1255:2a1aa9df8f11

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(issue133) Improve API documentation
author Andre Heinecke <andre.heinecke@intevation.de>
date Thu, 25 Sep 2014 17:58:12 +0200
parents edbf5e5e88f4
children
rev   line source
404
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
1 /* Copyright (C) 2014 by Bundesamt für Sicherheit in der Informationstechnik
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
2 * Software engineering by Intevation GmbH
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
3 *
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
4 * This file is Free Software under the GNU GPL (v>=2)
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
5 * and comes with ABSOLUTELY NO WARRANTY!
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
6 * See LICENSE.txt for details.
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 286
diff changeset
7 */
7
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
8 #ifndef LISTUTIL_H
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
9 #define LISTUTIL_H
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
10
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
11 #ifdef __cplusplus
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
12 extern "C" {
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
13 #endif
4
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
14
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
15 #include <stddef.h>
1081
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
16 #include <stdio.h>
4
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
17
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
18 /**
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
19 * @file listutil.h
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
20 * @brief Functions to work with the certificate list.
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
21 */
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
22
7
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
23 /**
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
24 * @brief Status of the List Operations
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
25 */
4
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
26 typedef enum {
578
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
27 Valid = 100, /*! Could be read and signature matched */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
28 UnknownError = 1, /*! The expected unexpected */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
29 TooLarge = 2, /*! Failed because the file exeeds the limit */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
30 InvalidFormat = 3, /*! File does not appear to be in list format */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
31 InvalidSignature = 4, /*! Signature was invalid */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
32 SeekFailed = 5, /*! Could not seek in the file */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
33 ReadFailed = 6, /*! File exists but could not read the file */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
34 IncompatibleVersion = 7, /*! The Format Version does not match */
bf54c9fc0d63 Doxygen comments for list_status_t
Andre Heinecke <aheinecke@intevation.de>
parents: 404
diff changeset
35 NoList = 8 /*! No list parsed */
4
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
36 } list_status_t;
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
37
68
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
38 /* Definitions based on the format */
123
571f68c7a38f Specified line length is 9999 and not 1000!
Andre Heinecke <aheinecke@intevation.de>
parents: 70
diff changeset
39 #define MAX_LINE_LENGTH 9999
68
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
40 #define MAX_LINES 1000
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
41
4
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
42 /**
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
43 * @brief Obtain the complete and verified Certificate list.
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
44 *
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
45 * This checks if the file fileName is a valid certificate
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
46 * list signed by the key specified in pubkey.h
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
47 *
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
48 * The caller has to free data.
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
49 *
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
50 * @param[in] fileName Name of the file (UTF-8 encoded).
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
51 * @param[out] data Newly allocated pointer to the file content.
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
52 * @param[out] size Size in Bytes of the file content.
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
53 *
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
54 * @return status of the operation.
9849250f50f2 Start implementation of certificatelist parser
Andre Heinecke <aheinecke@intevation.de>
parents:
diff changeset
55 */
28
e783fd99a9eb Add public key parsing
Andre Heinecke <aheinecke@intevation.de>
parents: 22
diff changeset
56 list_status_t read_and_verify_list(const char *fileName, char **data, size_t *size);
59
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
57
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
58 /** @brief verify the certificate list
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
59 *
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
60 * The public key to verify against is the static publicKeyPEM data defined
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
61 * in the pubkey header.
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
62 *
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
63 * @param [in] data the list data
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
64 * @param [in] size the size of the data
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
65 *
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
66 * @returns 0 if the list is valid a polarssl error or -1 otherwise
3f6378647371 Start work on cinst. Strhelp new helpers to work with C String
Andre Heinecke <aheinecke@intevation.de>
parents: 31
diff changeset
67 */
68
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
68 int verify_list(const char *data, const size_t size);
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
69
286
881ce5126f07 Add helper function to get all certificates in a list
Andre Heinecke <aheinecke@intevation.de>
parents: 123
diff changeset
70 /** @brief get a list of the certificates marked with I: or R:
68
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
71 *
286
881ce5126f07 Add helper function to get all certificates in a list
Andre Heinecke <aheinecke@intevation.de>
parents: 123
diff changeset
72 * Get a list of certificates that are contained in the
68
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
73 * certificatelist pointed to by data.
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
74 * On Success this function makes a copy of the certificates
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
75 * and the certificates need to be freed by the caller.
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
76 *
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
77 * @param [in] data the certificatelist to parse
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
78 * @param [in] size the size of the certificatelist
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
79 *
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
80 * @returns a newly allocated array of strings containing the encoded
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
81 * certificates or NULL on error.
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
82 * */
286
881ce5126f07 Add helper function to get all certificates in a list
Andre Heinecke <aheinecke@intevation.de>
parents: 123
diff changeset
83 char **get_certs_from_list (char *data, const size_t size);
68
8ffbb48528ae Add certificate installation for windows
Andre Heinecke <aheinecke@intevation.de>
parents: 59
diff changeset
84
769
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
85 /**
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
86 * @brief Read a file into memory.
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
87 *
1081
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
88 * The caller needs to free data. If fptr is not NULL it will
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
89 * recieve the pointer to the read file structure. The caller
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
90 * is responsible for closing this.
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
91 * fptr only needs to be closed and is only valid if the
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
92 * return value is 0.
769
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
93 *
1053
78798d3af8f0 Fixed doxygen build warnings.
Emanuel Schuetze <emanuel@intevation.de>
parents: 769
diff changeset
94 * @param[in] file_name Name of the file.
769
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
95 * @param[out] data the file content
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
96 * @param[out] size size in bytes of the file content.
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
97 * @param[in] max_size the maximum amount of bytes to read.
1081
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
98 * @param[out] fptr pointer to recieve the FILE ptr or NULL
769
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
99 *
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
100 * @return 0 on success an error code otherwise.
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
101 */
44257ecdae6d Make Read File public
Andre Heinecke <andre.heinecke@intevation.de>
parents: 578
diff changeset
102 int read_file(const char *file_name, char **data, size_t *size,
1081
edbf5e5e88f4 (issue118) Extend verify_binary to carry an open file
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1053
diff changeset
103 const size_t max_size, FILE **fptr);
7
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
104 #ifdef __cplusplus
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
105 }
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
106 #endif
992c0ec57660 Add unit tests make CertificateList work.
Andre Heinecke <aheinecke@intevation.de>
parents: 4
diff changeset
107 #endif
http://wald.intevation.org/projects/trustbridge/