Qpid Proton C API  0.37.0
tls.h
Go to the documentation of this file.
1 #ifndef PROTON_TLS_H
2 #define PROTON_TLS_H 1
3 
4 /*
5  *
6  * Licensed to the Apache Software Foundation (ASF) under one
7  * or more contributor license agreements. See the NOTICE file
8  * distributed with this work for additional information
9  * regarding copyright ownership. The ASF licenses this file
10  * to you under the Apache License, Version 2.0 (the
11  * "License"); you may not use this file except in compliance
12  * with the License. You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing,
17  * software distributed under the License is distributed on an
18  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19  * KIND, either express or implied. See the License for the
20  * specific language governing permissions and limitations
21  * under the License.
22  *
23  */
24 
25 #include <proton/import_export.h>
26 #include <proton/raw_connection.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
81 typedef struct pn_tls_config_t pn_tls_config_t;
82 
86 typedef struct pn_tls_t pn_tls_t;
87 
91 typedef enum {
95 
100 #define PN_TLS_OK (0)
101 #define PN_TLS_INIT_ERR (-1)
102 #define PN_TLS_PROTOCOL_ERR (-2)
103 #define PN_TLS_AUTHENTICATION_ERR (-3)
104 #define PN_TLS_STATE_ERR (-4)
119 
126 PN_TLS_EXTERN void pn_tls_config_free(pn_tls_config_t *domain);
127 
153  const char *credential_1,
154  const char *credential_2,
155  const char *password);
156 
178  const char *certificate_db);
179 
196 typedef enum {
202 
228  const pn_tls_verify_mode_t mode,
229  const char *trusted_CAs);
230 
241 PN_TLS_EXTERN int pn_tls_config_set_impl_ciphers(pn_tls_config_t *domain, const char *ciphers);
242 
249 PN_TLS_EXTERN pn_tls_t *pn_tls(pn_tls_config_t *domain);
250 
261 PN_TLS_EXTERN int pn_tls_start(pn_tls_t *tls);
262 
263 
264 PN_TLS_EXTERN void pn_tls_free(pn_tls_t *tls);
265 
279 PN_TLS_EXTERN bool pn_tls_get_cipher(pn_tls_t *tls, const char **cipher, size_t *size);
280 
287 PN_TLS_EXTERN int pn_tls_get_ssf(pn_tls_t *tls);
288 
301 PN_TLS_EXTERN bool pn_tls_get_protocol_version(pn_tls_t *tls, const char **version, size_t *size);
302 
325 PN_TLS_EXTERN int pn_tls_set_peer_hostname(pn_tls_t *tls, const char *hostname);
326 
340 PN_TLS_EXTERN int pn_tls_get_peer_hostname(pn_tls_t *tls, char *hostname, size_t *bufsize);
341 
349 PN_TLS_EXTERN const char* pn_tls_get_remote_subject(pn_tls_t *tls);
350 
354 typedef enum {
355  PN_TLS_CERT_SUBJECT_COUNTRY_NAME,
356  PN_TLS_CERT_SUBJECT_STATE_OR_PROVINCE,
357  PN_TLS_CERT_SUBJECT_CITY_OR_LOCALITY,
358  PN_TLS_CERT_SUBJECT_ORGANIZATION_NAME,
359  PN_TLS_CERT_SUBJECT_ORGANIZATION_UNIT,
360  PN_TLS_CERT_SUBJECT_COMMON_NAME
362 
366 typedef enum {
367  PN_TLS_SHA1, /* Produces hash that is 20 bytes long */
368  PN_TLS_SHA256, /* Produces hash that is 32 bytes long */
369  PN_TLS_SHA512, /* Produces hash that is 64 bytes long */
370  PN_TLS_MD5 /* Produces hash that is 16 bytes long */
372 
386 PN_TLS_EXTERN int pn_tls_get_cert_fingerprint(pn_tls_t *tls0,
387  char *fingerprint,
388  size_t fingerprint_length,
389  pn_tls_hash_alg hash_alg);
390 
404 
405 PN_TLS_EXTERN bool pn_tls_is_encrypt_output_pending(pn_tls_t *tls);
406 PN_TLS_EXTERN bool pn_tls_is_decrypt_output_pending(pn_tls_t *tls);
407 
408 
409 // True if peers have negotiated a TLS session. False indicates handshake in progress or protocol error.
410 PN_TLS_EXTERN bool pn_tls_is_secure(pn_tls_t *tls);
411 
412 
413 // ----------------------------------------------------------------------------------------------------------------------
414 
415 // A common pool of buffers to put both encrypted and decrypted bytes in:
416 // - this could easily just be split into 2 result buffer sets if preferred.
417 
418 // Give buffers to store encryption/decryption results
419 // returns the number of buffers taken - it's possible that we don't have space
420 // to record all of them
421 PN_TLS_EXTERN size_t pn_tls_give_encrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t const*, size_t count);
422 PN_TLS_EXTERN size_t pn_tls_give_decrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t const*, size_t count);
423 
424 
425 // Take result buffers back into app ownership, return the actual number of buffers returned
426 // keep calling these until the number returned is 0 to make sure you get all buffers currently available
427 // Gives only buffers with encrypted/decrypted content before pn_tls_stop() and all buffers afterwards.
428 PN_TLS_EXTERN size_t pn_tls_take_decrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
429 PN_TLS_EXTERN size_t pn_tls_take_encrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
430 
431 // Stage data to be encrypted by the engine at a future pn_tls_process() step.
432 // returned value is number of buffers taken (ownership transfer)
433 // i.e. held by the tls code - governed by capacity.
434 PN_TLS_EXTERN size_t pn_tls_give_encrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t const* bufs, size_t count_bufs);
435 
436 // returned value is number of buffers taken
437 PN_TLS_EXTERN size_t pn_tls_give_decrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t const* bufs, size_t count_bufs);
438 
439 // Take input buffers back into app ownership, return the actual number of buffers returned
440 // Returns buffers whose data is fully processed (or pn_tls_stop() called).
441 // keep calling these until the number returned is 0 to make sure you get all buffers currently available
442 PN_TLS_EXTERN size_t pn_tls_take_encrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
443 PN_TLS_EXTERN size_t pn_tls_take_decrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
444 
445 // Return the max number of additional input buffers we can hold
446 PN_TLS_EXTERN size_t pn_tls_get_encrypt_input_buffer_capacity(pn_tls_t*);
447 PN_TLS_EXTERN size_t pn_tls_get_decrypt_input_buffer_capacity(pn_tls_t*);
448 
449 // True if there is no remaining space in the XXcrypt result buffers owned by the
450 // engine and there is XXcryped data available to put in a result buffer since
451 // the last pn_tls_process()
452 PN_TLS_EXTERN bool pn_tls_need_encrypt_output_buffers(pn_tls_t*);
453 PN_TLS_EXTERN bool pn_tls_need_decrypt_output_buffers(pn_tls_t*);
454 
455 PN_TLS_EXTERN size_t pn_tls_get_encrypt_output_buffer_capacity(pn_tls_t*);
456 PN_TLS_EXTERN size_t pn_tls_get_decrypt_output_buffer_capacity(pn_tls_t*);
457 
458 // Number of buffers ready to be returned by take operation since last pn_tls_process() or pn_tls_stop()
459 PN_TLS_EXTERN size_t pn_tls_get_decrypt_output_buffer_count(pn_tls_t*);
460 PN_TLS_EXTERN size_t pn_tls_get_encrypt_output_buffer_count(pn_tls_t*);
461 
462 PN_TLS_EXTERN uint32_t pn_tls_get_last_decrypt_output_buffer_size(pn_tls_t*);
463 PN_TLS_EXTERN uint32_t pn_tls_get_last_encrypt_output_buffer_size(pn_tls_t*);
464 
465 
466 // Configurable. Zero implies "use default". No effect after pn_tls_start().
467 PN_TLS_EXTERN void pn_tls_set_encrypt_input_buffer_max_capacity(pn_tls_t*, size_t s);
468 PN_TLS_EXTERN void pn_tls_set_decrypt_input_buffer_max_capacity(pn_tls_t*, size_t s);
469 PN_TLS_EXTERN void pn_tls_set_encrypt_output_buffer_max_capacity(pn_tls_t*, size_t s);
470 PN_TLS_EXTERN void pn_tls_set_decrypt_output_buffer_max_capacity(pn_tls_t*, size_t s);
471 
472 // Process as much unencrypted data to encrypted result data as possible.
473 // Also process as much undecrypted data to decryptedcrypted result data as possible.
474 // Check for TLS engine errors here.
475 // Always returns an error if called before pn_tls_start() or after pn_tls_stop().
476 PN_TLS_EXTERN int pn_tls_process(pn_tls_t* tls);
477 
478 // Future pn_tls_process() or pn_tls_give_xxx() are no-ops.
479 // Unused encrypt/decrypt result buffers become zero length encrypted/decrypted result
480 // buffers and can be reclaimed.
481 // Future: If no closure from peer or self closure not written to result buffer, session resume cancelled.
482 PN_TLS_EXTERN int pn_tls_stop(pn_tls_t* tls);
483 
484 // Confirms receipt of the peer's TLS closure record. This confirms clean shutdown and
485 // the absence of a truncation attack.
486 PN_TLS_EXTERN bool pn_tls_is_input_closed(pn_tls_t* tls);
487 
488 // Closes the encrypt side and appends the TLS closure record to the pending encypted
489 // output. pn_tls_give_encrypt_input_buffers() will no longer take any supplied buffers.
490 PN_TLS_EXTERN void pn_tls_close_output(pn_tls_t* tls);
491 
492 // If non-zero the TLS session was unable to start or was aborted.
493 // The application should stop all read activity, and take all
494 // remaining encrypted content and write it onto the connection
495 // (i.e. until pn_tls_is_encrypt_output_pending() is false), then
496 // close the associated connection. This will allow the error to be
497 // propagated to the peer if expected by the TLS protocol. Specific return values TBD (INIT_FAILED,
498 // BAD_AUTH, TLS_PROTOCOL_ERROR, ...).
499 PN_TLS_EXTERN int pn_tls_get_session_error(pn_tls_t* tls);
500 
501 // Error string associated with the fatal TLS session error. zero if no error, buf is null or buf_len is 0.
502 PN_TLS_EXTERN size_t pn_tls_get_session_error_string(pn_tls_t* tls, char *buf, size_t buf_len);
503 
525 PN_TLS_EXTERN int pn_tls_config_set_alpn_protocols(pn_tls_config_t *domain, const char **protocols, size_t protocol_count);
526 
539 PN_TLS_EXTERN bool pn_tls_get_alpn_protocol(pn_tls_t *tls, const char **protocol_name, size_t *size);
540 
541 // TODO: Tracing. Session tickets.
542 
547 #ifdef __cplusplus
548 }
549 #endif
550 
551 #endif /* tls.h */
A descriptor used to represent a single raw buffer in memory.
Definition: raw_connection.h:54
PN_TLS_EXTERN bool pn_tls_get_alpn_protocol(pn_tls_t *tls, const char **protocol_name, size_t *size)
Get the name of the negotiated application protocol.
PN_TLS_EXTERN bool pn_tls_get_cipher(pn_tls_t *tls, const char **cipher, size_t *size)
Get the name of the Cipher that is currently in use.
PN_TLS_EXTERN const char * pn_tls_get_remote_subject_subfield(pn_tls_t *tls, pn_tls_cert_subject_subfield field)
Returns a char pointer that contains the value of the sub field of the subject field in the tls certi...
PN_TLS_EXTERN int pn_tls_get_peer_hostname(pn_tls_t *tls, char *hostname, size_t *bufsize)
Access the configured peer identity.
PN_TLS_EXTERN int pn_tls_start(pn_tls_t *tls)
Start a TLS session.
PN_TLS_EXTERN void pn_tls_config_free(pn_tls_config_t *domain)
Release an TLS configuration domain.
PN_TLS_EXTERN int pn_tls_get_cert_fingerprint(pn_tls_t *tls0, char *fingerprint, size_t fingerprint_length, pn_tls_hash_alg hash_alg)
Get the fingerprint of the certificate.
pn_tls_hash_alg
Enumeration identifying hashing algorithm.
Definition: tls.h:366
PN_TLS_EXTERN int pn_tls_set_peer_hostname(pn_tls_t *tls, const char *hostname)
Set the expected identity of the remote peer.
PN_TLS_EXTERN int pn_tls_config_set_trusted_certs(pn_tls_config_t *domain, const char *certificate_db)
Configure the set of trusted CA certificates used by this domain to verify peers.
struct pn_tls_t pn_tls_t
Definition: tls.h:86
pn_tls_mode_t
Determines the type of TLS endpoint.
Definition: tls.h:91
pn_tls_verify_mode_t
Determines the level of peer validation.
Definition: tls.h:196
PN_TLS_EXTERN const char * pn_tls_get_remote_subject(pn_tls_t *tls)
Get the subject from the peers certificate.
PN_TLS_EXTERN int pn_tls_config_set_peer_authentication(pn_tls_config_t *domain, const pn_tls_verify_mode_t mode, const char *trusted_CAs)
Configure the level of verification used on the peer certificate.
PN_TLS_EXTERN bool pn_tls_get_protocol_version(pn_tls_t *tls, const char **version, size_t *size)
Get the name of the TLS protocol that is currently in use.
PN_TLS_EXTERN int pn_tls_config_set_credentials(pn_tls_config_t *domain, const char *credential_1, const char *credential_2, const char *password)
Set the certificate that identifies the local node to the remote.
PN_TLS_EXTERN int pn_tls_config_set_impl_ciphers(pn_tls_config_t *domain, const char *ciphers)
Configure the list of permitted ciphers.
PN_TLS_EXTERN pn_tls_t * pn_tls(pn_tls_config_t *domain)
Create a new TLS session object derived from a domain.
pn_tls_cert_subject_subfield
Enumeration identifying the sub fields of the subject field in the tls certificate.
Definition: tls.h:354
struct pn_tls_config_t pn_tls_config_t
API for using TLS separate from AMQP connections.
Definition: tls.h:81
PN_TLS_EXTERN int pn_tls_get_ssf(pn_tls_t *tls)
Get the SSF (security strength factor) of the Cipher that is currently in use.
PN_TLS_EXTERN int pn_tls_config_set_alpn_protocols(pn_tls_config_t *domain, const char **protocols, size_t protocol_count)
Provide an ordered list of application protols for RFC 7301 negotiation.
PN_TLS_EXTERN pn_tls_config_t * pn_tls_config(pn_tls_mode_t mode)
Create an TLS configuration domain.
@ PN_TLS_MODE_SERVER
Local connection endpoint is an TLS server.
Definition: tls.h:93
@ PN_TLS_MODE_CLIENT
Local connection endpoint is an TLS client.
Definition: tls.h:92
@ PN_TLS_VERIFY_NULL
internal use only
Definition: tls.h:197
@ PN_TLS_VERIFY_PEER_NAME
require valid certificate and matching name
Definition: tls.h:200
@ PN_TLS_VERIFY_PEER
require peer to provide a valid identifying certificate
Definition: tls.h:198
@ PN_TLS_ANONYMOUS_PEER
do not require a certificate nor cipher authorization
Definition: tls.h:199