1 /* 2 SSL/TLS abstraction layer for neon 3 Copyright (C) 2003-2004, Joe Orton <joe@manyfish.co.uk> 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Library General Public 7 License as published by the Free Software Foundation; either 8 version 2 of the License, or (at your option) any later version. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Library General Public License for more details. 14 15 You should have received a copy of the GNU Library General Public 16 License along with this library; if not, write to the Free 17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, 18 MA 02111-1307, USA 19 20 */ 21 22 /* ne_ssl.h defines an interface for loading and accessing the 23 * properties of SSL certificates. */ 24 25 #ifndef NE_SSL_H 26 #define NE_SSL_H 1 27 28 #include "ne_defs.h" 29 30 BEGIN_NEON_DECLS 31 32 /* A "distinguished name"; a unique name for some entity. */ 33 typedef struct ne_ssl_dname_s ne_ssl_dname; 34 35 /* Returns a single-line string representation of a distinguished 36 * name, intended to be human-readable (e.g. "Acme Ltd., Norfolk, 37 * GB"). Return value is a UTF-8-encoded malloc-allocated string and 38 * must be free'd by the caller. */ 39 char *ne_ssl_readable_dname(const ne_ssl_dname *dn); 40 41 /* Returns zero if 'dn1' and 'dn2' refer to same name, or non-zero if 42 * they are different. */ 43 int ne_ssl_dname_cmp(const ne_ssl_dname *dn1, const ne_ssl_dname *dn2); 44 45 /* An SSL certificate. */ 46 typedef struct ne_ssl_certificate_s ne_ssl_certificate; 47 48 /* Read a certificate from a file in PEM format; returns NULL if the 49 * certificate could not be parsed. */ 50 ne_ssl_certificate *ne_ssl_cert_read(const char *filename); 51 52 /* Write a certificate to a file in PEM format; returns non-zero if 53 * the certificate could not be written. */ 54 int ne_ssl_cert_write(const ne_ssl_certificate *cert, const char *filename); 55 56 /* Export a certificate to a base64-encoded, NUL-terminated string. 57 * The returned string is malloc-allocated and must be free()d by the 58 * caller. */ 59 char *ne_ssl_cert_export(const ne_ssl_certificate *cert); 60 61 /* Import a certificate from a base64-encoded string as returned by 62 * ne_ssl_cert_export(). Returns a certificate object or NULL if 63 * 'data' was not valid. */ 64 ne_ssl_certificate *ne_ssl_cert_import(const char *data); 65 66 /* Returns the identity of the certificate, or NULL if none is given. 67 * For a server certificate this will be the hostname of the server to 68 * whom the cert was issued. */ 69 const char *ne_ssl_cert_identity(const ne_ssl_certificate *cert); 70 71 /* Return the certificate of the entity which signed certificate 72 * 'cert'. Returns NULL if 'cert' is self-signed or the issuer 73 * certificate is not available. */ 74 const ne_ssl_certificate *ne_ssl_cert_signedby(const ne_ssl_certificate *cert); 75 76 /* Returns the distinguished name of the certificate issuer. */ 77 const ne_ssl_dname *ne_ssl_cert_issuer(const ne_ssl_certificate *cert); 78 79 /* Returns the distinguished name of the certificate subject. */ 80 const ne_ssl_dname *ne_ssl_cert_subject(const ne_ssl_certificate *cert); 81 82 #define NE_SSL_DIGESTLEN (60) 83 84 /* Calculate the certificate digest ("fingerprint") and format it as a 85 * NUL-terminated hex string in 'digest', of the form "aa:bb:...:ff". 86 * Returns zero on success or non-zero if there was an internal error 87 * whilst calculating the digest. 'digest' must be at least 88 * NE_SSL_DIGESTLEN bytes in length. */ 89 int ne_ssl_cert_digest(const ne_ssl_certificate *cert, char *digest); 90 91 #define NE_SSL_VDATELEN (30) 92 93 /* Copy the validity dates into buffers 'from' and 'until' as 94 * NUL-terminated human-readable strings. The buffers must be at 95 * least NE_SSL_VDATELEN bytes in length. */ 96 void ne_ssl_cert_validity(const ne_ssl_certificate *cert, 97 char *from, char *until); 98 99 /* Returns zero if 'c1' and 'c2' refer to the same certificate, or 100 * non-zero otherwise. */ 101 int ne_ssl_cert_cmp(const ne_ssl_certificate *c1, 102 const ne_ssl_certificate *c2); 103 104 /* Deallocate memory associated with certificate. */ 105 void ne_ssl_cert_free(ne_ssl_certificate *cert); 106 107 /* A client certificate (and private key). */ 108 typedef struct ne_ssl_client_cert_s ne_ssl_client_cert; 109 110 /* Read a client certificate and private key from a PKCS12 file; 111 * returns NULL if the file could not be parsed. If the client cert 112 * is encrypted, it must be decrypted before use. */ 113 ne_ssl_client_cert *ne_ssl_clicert_read(const char *filename); 114 115 /* Returns the "friendly name" given for the client cert, or NULL if 116 * none given. This can be called before or after the client cert has 117 * been decrypted. Returns a NUL-terminated string. */ 118 const char *ne_ssl_clicert_name(ne_ssl_client_cert *ccert); 119 120 /* Returns non-zero if client cert is encrypted. */ 121 int ne_ssl_clicert_encrypted(const ne_ssl_client_cert *ccert); 122 123 /* Decrypt the encrypted client cert using given password. Returns 124 * non-zero on failure, in which case, the function can be called 125 * again with a different password. For a ccert on which _encrypted() 126 * returns 0, calling _decrypt results in undefined behaviour. */ 127 int ne_ssl_clicert_decrypt(ne_ssl_client_cert *ccert, const char *password); 128 129 /* Return the actual certificate part of the client certificate (never 130 * returns NULL). */ 131 const ne_ssl_certificate *ne_ssl_clicert_owner(const ne_ssl_client_cert *ccert); 132 133 /* Deallocate memory associated with a client certificate. */ 134 void ne_ssl_clicert_free(ne_ssl_client_cert *ccert); 135 136 /* An SSL context; only necessary when interfacing with ne_socket.h. */ 137 typedef struct ne_ssl_context_s ne_ssl_context; 138 139 /* Create an SSL context. */ 140 ne_ssl_context *ne_ssl_context_create(void); 141 142 /* Trust the given certificate 'cert' in context 'ctx'. */ 143 void ne_ssl_ctx_trustcert(ne_ssl_context *ctx, const ne_ssl_certificate *cert); 144 145 /* Destroy an SSL context. */ 146 void ne_ssl_context_destroy(ne_ssl_context *ctx); 147 148 END_NEON_DECLS 149 150 #endif 151