1/* 2 SSL/TLS abstraction layer for neon 3 Copyright (C) 2003-2006, 2009, 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 <sys/types.h> 29 30#include "ne_defs.h" 31 32NE_BEGIN_DECLS 33 34/* A "distinguished name"; a unique name for some entity. */ 35typedef struct ne_ssl_dname_s ne_ssl_dname; 36 37/* Returns a single-line string representation of a distinguished 38 * name, intended to be human-readable (e.g. "Acme Ltd., Norfolk, 39 * GB"). Return value is a UTF-8-encoded malloc-allocated string and 40 * must be free'd by the caller. */ 41char *ne_ssl_readable_dname(const ne_ssl_dname *dn); 42 43/* Returns zero if 'dn1' and 'dn2' refer to same name, or non-zero if 44 * they are different. */ 45int ne_ssl_dname_cmp(const ne_ssl_dname *dn1, const ne_ssl_dname *dn2); 46 47/* An SSL certificate. */ 48typedef struct ne_ssl_certificate_s ne_ssl_certificate; 49 50/* Read a certificate from a file in PEM format; returns NULL if the 51 * certificate could not be parsed. */ 52ne_ssl_certificate *ne_ssl_cert_read(const char *filename); 53 54/* Write a certificate to a file in PEM format; returns non-zero if 55 * the certificate could not be written. */ 56int ne_ssl_cert_write(const ne_ssl_certificate *cert, const char *filename); 57 58/* Export a certificate to a base64-encoded, NUL-terminated string. 59 * The returned string is malloc-allocated and must be free()d by the 60 * caller. */ 61char *ne_ssl_cert_export(const ne_ssl_certificate *cert); 62 63/* Import a certificate from a base64-encoded string as returned by 64 * ne_ssl_cert_export(). Returns a certificate object or NULL if 65 * 'data' was not valid. */ 66ne_ssl_certificate *ne_ssl_cert_import(const char *data); 67 68/* Returns the identity of the certificate, or NULL if none is given. 69 * For a server certificate this will be the hostname of the server to 70 * which the cert was issued. A NUL-terminated UTF-8-encoded string 71 * is returned, which is valid for the lifetime of the certificate 72 * object. */ 73const char *ne_ssl_cert_identity(const ne_ssl_certificate *cert); 74 75/* Return the certificate of the entity which signed certificate 76 * 'cert'. Returns NULL if 'cert' is self-signed or the issuer 77 * certificate is not available; if non-NULL, the pointer is valid for 78 * the lifetime of the certificate object. */ 79const ne_ssl_certificate *ne_ssl_cert_signedby(const ne_ssl_certificate *cert); 80 81/* Returns the distinguished name of the certificate issuer. */ 82const ne_ssl_dname *ne_ssl_cert_issuer(const ne_ssl_certificate *cert); 83 84/* Returns the distinguished name of the certificate subject. */ 85const ne_ssl_dname *ne_ssl_cert_subject(const ne_ssl_certificate *cert); 86 87#define NE_SSL_DIGESTLEN (60) 88 89/* Calculate the certificate digest ("fingerprint") and format it as a 90 * NUL-terminated hex string in 'digest', of the form "aa:bb:...:ff". 91 * Returns zero on success or non-zero if there was an internal error 92 * whilst calculating the digest. 'digest' must be at least 93 * NE_SSL_DIGESTLEN bytes in length. */ 94int ne_ssl_cert_digest(const ne_ssl_certificate *cert, char *digest); 95 96/* Copy the validity times for the certificate 'cert' into 'from' and 97 * 'until' (either may be NULL). If the time cannot be represented by 98 * a time_t value, then (time_t)-1 will be written. */ 99void ne_ssl_cert_validity_time(const ne_ssl_certificate *cert, 100 time_t *from, time_t *until); 101 102#define NE_SSL_VDATELEN (30) 103/* Copy the validity times into buffers 'from' and 'until' as 104 * NUL-terminated human-readable strings, using RFC 1123-style date 105 * formatting (and not localized, so always using English month/week 106 * names). The buffers must be at least NE_SSL_VDATELEN bytes in 107 * length, and either may be NULL. */ 108void ne_ssl_cert_validity(const ne_ssl_certificate *cert, 109 char *from, char *until); 110 111/* Returns zero if 'c1' and 'c2' refer to the same certificate, or 112 * non-zero otherwise. */ 113int ne_ssl_cert_cmp(const ne_ssl_certificate *c1, 114 const ne_ssl_certificate *c2); 115 116/* Deallocate memory associated with certificate. */ 117void ne_ssl_cert_free(ne_ssl_certificate *cert); 118 119/* A client certificate (and private key). A client certificate 120 * object has state; the object is either in the "encrypted" or 121 * "decrypted" state. */ 122typedef struct ne_ssl_client_cert_s ne_ssl_client_cert; 123 124/* Read a client certificate and private key from a PKCS12 file; 125 * returns NULL if the file could not be parsed, or otherwise 126 * returning a client certificate object. The returned object may be 127 * in either the encrypted or decrypted state. */ 128ne_ssl_client_cert *ne_ssl_clicert_read(const char *filename); 129 130/* Returns non-zero if client cert is in the encrypted state. */ 131int ne_ssl_clicert_encrypted(const ne_ssl_client_cert *ccert); 132 133/* Returns the "friendly name" given for the client cert, or NULL if 134 * none given. Returns a NUL-terminated, UTF-8-encoded string. This 135 * function may be used on a ccert object in either encrypted or 136 * decrypted state. */ 137const char *ne_ssl_clicert_name(const ne_ssl_client_cert *ccert); 138 139/* Decrypt the encrypted client cert using the given password. 140 * Returns non-zero on failure, in which case, the ccert object 141 * remains in the encrypted state and the function may be called again 142 * with a different password. This function has undefined behaviour 143 * for a ccert object which is in the decrypted state. */ 144int ne_ssl_clicert_decrypt(ne_ssl_client_cert *ccert, const char *password); 145 146/* Return the actual certificate part of the client certificate (never 147 * returns NULL). This function has undefined behaviour for a ccert 148 * object which is in the encrypted state. */ 149const ne_ssl_certificate *ne_ssl_clicert_owner(const ne_ssl_client_cert *ccert); 150 151/* Destroy a client certificate object. This function may be used on 152 * a ccert object in either the encrypted or decrypted state. */ 153void ne_ssl_clicert_free(ne_ssl_client_cert *ccert); 154 155 156/* SSL context object. The interfaces to manipulate an SSL context 157 * are only needed when interfacing directly with ne_socket.h. */ 158typedef struct ne_ssl_context_s ne_ssl_context; 159 160/* Context creation modes: */ 161#define NE_SSL_CTX_CLIENT (0) /* client context */ 162#define NE_SSL_CTX_SERVER (1) /* default server context */ 163#define NE_SSL_CTX_SERVERv2 (2) /* SSLv2-specific server context */ 164 165/* Create an SSL context. */ 166ne_ssl_context *ne_ssl_context_create(int mode); 167 168/* Client mode: trust the given certificate 'cert' in context 'ctx'. */ 169void ne_ssl_context_trustcert(ne_ssl_context *ctx, const ne_ssl_certificate *cert); 170 171/* Server mode: use given cert and key (filenames to PEM certificates). */ 172int ne_ssl_context_keypair(ne_ssl_context *ctx, 173 const char *cert, const char *key); 174 175/* Server mode: set client cert verification options: required is non-zero if 176 * a client cert is required, if ca_names is non-NULL it is a filename containing 177 * a set of PEM certs from which CA names are sent in the ccert request. */ 178int ne_ssl_context_set_verify(ne_ssl_context *ctx, int required, 179 const char *ca_names, const char *verify_cas); 180 181#define NE_SSL_CTX_SSLv2 (0) 182/* Set a flag for the SSL context. */ 183void ne_ssl_context_set_flag(ne_ssl_context *ctx, int flag, int value); 184 185/* Destroy an SSL context. */ 186void ne_ssl_context_destroy(ne_ssl_context *ctx); 187 188NE_END_DECLS 189 190#endif 191