Subversion Repositories planix.SVN

Rev

Rev 2 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 2 Rev 33
Line 1... Line 1...
1 
.TH PUSHTLS 2
 1 
.TH PUSHTLS 2
2 
.SH NAME
 2 
.SH NAME
3 
pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
 3 
pushtls, tlsClient, tlsServer, initThumbprints, freeThumbprints, okThumbprint, okCertificate, readcert, readcertchain \- attach TLS1 or SSL3 encryption to a communication channel
4 
.SH SYNOPSIS
 4 
.SH SYNOPSIS
5 
.B #include <u.h>
 5 
.B #include <u.h>
6 
.br
 6 
.br
7 
.B #include <libc.h>
 7 
.B #include <libc.h>
8 
.PP
 8 
.PP
Line 27... Line 27...
27 
.PP
 27 
.PP
28 
.B
 28 
.B
29 
PEMchain *readcertchain(char *filename)
 29 
PEMchain *readcertchain(char *filename)
30 
.PP
 30 
.PP
31 
.B
 31 
.B
32 
Thumbprint *initThumbprints(char *ok, char *crl)
 32 
Thumbprint *initThumbprints(char *ok, char *crl, char *tag)
33 
.PP
 33 
.PP
34 
.B
 34 
.B
35 
void	freeThumbprints(Thumbprint *table)
 35 
void	freeThumbprints(Thumbprint *table)
36 
.PP
 36 
.PP
37 
.B
 37 
.B
38 
int	okThumbprint(uchar *hash, Thumbprint *table)
 38 
int	okThumbprint(uchar *hash, int len, Thumbprint *table)
- 
 
 39 
.PP
- 
 
 40 
.B
- 
 
 41 
int	okCertificate(uchar *cert, int len, Thumbprint *table)
39 
.SH DESCRIPTION
 42 
.SH DESCRIPTION
40 
Transport Layer Security (TLS) comprises a record layer protocol,
 43 
Transport Layer Security (TLS) comprises a record layer protocol,
41 
doing message digesting and encrypting in the kernel,
 44 
doing message digesting and encrypting in the kernel,
42 
and a handshake protocol,
 45 
and a handshake protocol,
43 
doing initial authentication and secret creation at
 46 
doing initial authentication and secret creation at
Line 59... Line 62...
59 
.IR secret .
 62 
.IR secret .
60 
These parameters must have been arranged at the two ends of the
 63 
These parameters must have been arranged at the two ends of the
61 
conversation by other means.
 64 
conversation by other means.
62 
For example,
 65 
For example,
63 
.I hashalg
 66 
.I hashalg
64 
could be
 67 
could be
65 
.BR sha1 ,
 68 
.BR sha1 ,
66 
.I encalg
 69 
.I encalg
67 
could be
 70 
could be
68 
.BR rc4_128 ,
 71 
.BR rc4_128 ,
69 
and
 72 
and
70 
.I secret
 73 
.I secret
71 
could be the base-64 encoding of two (client-to-server and server-to-client)
 74 
could be the base-64 encoding of two (client-to-server and server-to-client)
72 
20-byte digest keys and two corresponding 16-byte encryption keys.
 75 
20-byte digest keys and two corresponding 16-byte encryption keys.
73 
.I Pushtls
 76 
.I Pushtls
74 
returns a file descriptor for the TLS data channel.  Anything written to this
 77 
returns a file descriptor for the TLS data channel.  Anything written to this
75 
descriptor will get encrypted and authenticated and then written to the
 78 
descriptor will get encrypted and authenticated and then written to the
76 
file descriptor,
 79 
file descriptor,
77 
.IR fd .
 80 
.IR fd .
- 
 
 81 
.I Pushtls ,
- 
 
 82 
.IR tlsClient
- 
 
 83 
and
- 
 
 84 
.IR tlsServer
- 
 
 85 
close the original file descriptor on success.
78 
If
 86 
If
79 
.I dir
 87 
.I dir
80 
is non-zero, the path name of the connection directory is copied into
 88 
is non-zero, the path name of the connection directory is copied into
81 
.IR dir .
 89 
.IR dir .
82 
This path name is guaranteed to be less than 40 bytes long.
 90 
This path name is guaranteed to be less than 40 bytes long.
Line 93... Line 101...
93 
.EX
 101 
.EX
94 
typedef struct TLSconn {
 102 
typedef struct TLSconn {
95 
	char	dir[40];		/* OUT    connection directory */
 103 
	char	dir[40];		/* OUT    connection directory */
96 
	uchar *cert;		/* IN/OUT certificate */
 104 
	uchar *cert;		/* IN/OUT certificate */
97 
	uchar *sessionID;	/* IN/OUT session ID */
 105 
	uchar *sessionID;	/* IN/OUT session ID */
- 
 
 106 
	uchar *psk;		/* opt IN pre-shared key */
98 
	int	certlen, sessionIDlen;
 107 
	int	certlen, sessionIDlen, psklen;
99 
	void	(*trace)(char*fmt, ...);
 108 
	int	(*trace)(char*fmt, ...);
100 
	PEMChain *chain;
 109 
	PEMChain *chain;
101 
	char	*sessionType;	/* opt IN  session type */
 110 
	char	*sessionType;	/* opt IN  session type */
102 
	uchar *sessionKey;	/* opt IN/OUT session key */
 111 
	uchar *sessionKey;	/* opt IN/OUT session key */
103 
	int	sessionKeylen;	/* opt IN  session key length */
 112 
	int	sessionKeylen;	/* opt IN  session key length */
104 
	char	*sessionConst;	/* opt IN  session constant */
 113 
	char	*sessionConst;	/* opt IN  session constant */
- 
 
 114 
	char	*serverName;	/* opt IN  server name */
- 
 
 115 
	char	*pskID;		/* opt IN  pre-shared key ID */
105 
} TLSconn;
 116 
} TLSconn;
106 
.EE
 117 
.EE
107 
.PP
 118 
.PP
108 
defined in
 119 
defined in
109 
.IR tls.h .
 120 
.IR libsec.h .
110 
On input, the caller can provide options such as
 121 
On input, the caller can provide options such as
111 
.IR cert ,
 122 
.IR cert ,
112 
the local certificate, and
 123 
the local certificate, and
113 
.IR sessionID ,
 124 
.IR sessionID ,
114 
used by a client to resume a previously negotiated security association.
 125 
used by a client to resume a previously negotiated security association.
Line 175... Line 186...
175 
.I filename
 186 
.I filename
176 
and return a pointer to a linked list of
 187 
and return a pointer to a linked list of
177 
.IR malloc ed
 188 
.IR malloc ed
178 
.B PEMChain
 189 
.B PEMChain
179 
structures, defined in
 190 
structures, defined in
180 
.IR tls.h :
 191 
.IR libsec.h :
181 
.IP
 192 
.IP
182 
.EX
 193 
.EX
183 
typedef struct PEMChain PEMChain;
 194 
typedef struct PEMChain PEMChain;
184 
struct PEMChain {
 195 
struct PEMChain {
185 
	PEMChain*next;
 196 
	PEMChain*next;
Line 187... Line 198...
187 
	int	pemlen;
 198 
	int	pemlen;
188 
};
 199 
};
189 
.EE
 200 
.EE
190 
.LP
 201 
.LP
191 
By setting
 202 
By setting
192 
.IP
 203 
.IP
193 
.EX
 204 
.EX
194 
conn->chain = readcertchain("intermediate-certs.pem");
 205 
conn->chain = readcertchain("intermediate-certs.pem");
195 
.EE
 206 
.EE
196 
.LP
 207 
.LP
197 
the server can present extra certificate evidence
 208 
the server can present extra certificate evidence
198 
to establish the chain of trust to a root authority
 209 
to establish the chain of trust to a root authority
Line 203... Line 214...
203 
be freed by the application whenever convenient.
 214 
be freed by the application whenever convenient.
204 
.SH EXAMPLES
 215 
.SH EXAMPLES
205 
Start the client half of TLS and check the remote certificate:
 216 
Start the client half of TLS and check the remote certificate:
206 
.IP
 217 
.IP
207 
.EX
 218 
.EX
208 
uchar hash[SHA1dlen];
 - 
 
209 
 
 - 
 
210 
conn = (TLSconn*)mallocz(sizeof *conn, 1);
 219 
conn = (TLSconn*)mallocz(sizeof *conn, 1);
211 
fd = tlsClient(fd, conn);
 220 
fd = tlsClient(fd, conn);
212 
sha1(conn->cert, conn->certlen, hash, nil);
 221 
if(!okCertificate(conn->cert, conn->certlen, table))
213 
if(!okThumbprint(hash,table))
 - 
 
214 
	exits("suspect server");
 222 
	sysfatal("suspect server: %r");
215 
\fI...application begins...\fP
 223 
\fI...application begins...\fP
216 
.EE
 224 
.EE
217 
.PP
 225 
.PP
218 
Run the server side:
 226 
Run the server side:
219 
.IP
 227 
.IP
Line 244... Line 252...
244 
.SH DIAGNOSTICS
 252 
.SH DIAGNOSTICS
245 
Return \-1 on failure.
 253 
Return \-1 on failure.
246 
.SH BUGS
 254 
.SH BUGS
247 
Client certificates and client sessionIDs are not yet
 255 
Client certificates and client sessionIDs are not yet
248 
implemented.
 256 
implemented.
- 
 
 257 
.PP
- 
 
 258 
Note that
- 
 
 259 
.IR pushtls ,
- 
 
 260 
.IR tlsClient
- 
 
 261 
and
- 
 
 262 
.IR tlsServer
- 
 
 263 
do not close the original file descriptor on failure,
- 
 
 264 
only on success.
- 
 
 265 
.PP
- 
 
 266 
The
- 
 
 267 
.IR sessionID
- 
 
 268 
and
- 
 
 269 
.IR cert
- 
 
 270 
pointers in the
- 
 
 271 
.IR TLSconn
- 
 
 272 
structure have to be freed by the caller.
249 
.PP
 273 
.PP
250 
Note that in the TLS protocol
 274 
Note that in the TLS protocol
251 
.I sessionID
 275 
.I sessionID
252 
itself is public;  it is used as a pointer to
 276 
itself is public;  it is used as a pointer to
253 
secrets stored in
 277 
secrets stored in