tls.h

Go to the documentation of this file.

#ifndef PROTON_TLS_H
#define PROTON_TLS_H 1
 
/*
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */
 
#include <proton/import_export.h>
#include <proton/raw_connection.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct pn_tls_config_t pn_tls_config_t;
 
typedef struct pn_tls_t pn_tls_t;
 
typedef enum {
  PN_TLS_MODE_CLIENT = 1, 
  PN_TLS_MODE_SERVER      
} pn_tls_mode_t;
 
#define PN_TLS_OK (0)                   
#define PN_TLS_INIT_ERR (-1)            
#define PN_TLS_PROTOCOL_ERR (-2)        
#define PN_TLS_AUTHENTICATION_ERR (-3)  
#define PN_TLS_STATE_ERR (-4)           
PN_TLS_EXTERN pn_tls_config_t *pn_tls_config(pn_tls_mode_t mode);
 
PN_TLS_EXTERN void pn_tls_config_free(pn_tls_config_t *domain);
 
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);
 
PN_TLS_EXTERN int pn_tls_config_set_trusted_certs(pn_tls_config_t *domain,
                                const char *certificate_db);
 
typedef enum {
  PN_TLS_VERIFY_NULL = 0,   
  PN_TLS_VERIFY_PEER,       
  PN_TLS_ANONYMOUS_PEER,    
  PN_TLS_VERIFY_PEER_NAME   
} pn_tls_verify_mode_t;
 
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);
 
PN_TLS_EXTERN int pn_tls_config_set_impl_ciphers(pn_tls_config_t *domain, const char *ciphers);
 
PN_TLS_EXTERN pn_tls_t *pn_tls(pn_tls_config_t *domain);
 
PN_TLS_EXTERN int pn_tls_start(pn_tls_t *tls);
 
 
PN_TLS_EXTERN void pn_tls_free(pn_tls_t *tls);
 
PN_TLS_EXTERN bool pn_tls_get_cipher(pn_tls_t *tls, const char **cipher, size_t *size);
 
PN_TLS_EXTERN int pn_tls_get_ssf(pn_tls_t *tls);
 
PN_TLS_EXTERN bool pn_tls_get_protocol_version(pn_tls_t *tls, const char **version, size_t *size);
 
PN_TLS_EXTERN int pn_tls_set_peer_hostname(pn_tls_t *tls, const char *hostname);
 
PN_TLS_EXTERN int pn_tls_get_peer_hostname(pn_tls_t *tls, char *hostname, size_t *bufsize);
 
PN_TLS_EXTERN const char* pn_tls_get_remote_subject(pn_tls_t *tls);
 
typedef enum {
  PN_TLS_CERT_SUBJECT_COUNTRY_NAME,
  PN_TLS_CERT_SUBJECT_STATE_OR_PROVINCE,
  PN_TLS_CERT_SUBJECT_CITY_OR_LOCALITY,
  PN_TLS_CERT_SUBJECT_ORGANIZATION_NAME,
  PN_TLS_CERT_SUBJECT_ORGANIZATION_UNIT,
  PN_TLS_CERT_SUBJECT_COMMON_NAME
} pn_tls_cert_subject_subfield;
 
typedef enum {
  PN_TLS_SHA1,   /* Produces hash that is 20 bytes long */
  PN_TLS_SHA256, /* Produces hash that is 32 bytes long */
  PN_TLS_SHA512, /* Produces hash that is 64 bytes long */
  PN_TLS_MD5     /* Produces hash that is 16 bytes long */
} pn_tls_hash_alg;
 
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);
 
PN_TLS_EXTERN const char* pn_tls_get_remote_subject_subfield(pn_tls_t *tls, pn_tls_cert_subject_subfield field);
 
PN_TLS_EXTERN bool pn_tls_is_encrypt_output_pending(pn_tls_t *tls);
PN_TLS_EXTERN bool pn_tls_is_decrypt_output_pending(pn_tls_t *tls);
 
 
// True if peers have negotiated a TLS session.  False indicates handshake in progress or protocol error.
PN_TLS_EXTERN bool pn_tls_is_secure(pn_tls_t *tls);
 
 
// ----------------------------------------------------------------------------------------------------------------------
 
// A common pool of buffers to put both encrypted and decrypted bytes in:
// - this could easily just be split into 2 result buffer sets if preferred.
 
// Give buffers to store encryption/decryption results
// returns the number of buffers taken - it's possible that we don't have space
// to record all of them
PN_TLS_EXTERN size_t pn_tls_give_encrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t const*, size_t count);
PN_TLS_EXTERN size_t pn_tls_give_decrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t const*, size_t count);
 
 
// Take result buffers back into app ownership, return the actual number of buffers returned
// keep calling these until the number returned is 0 to make sure you get all buffers currently available
// Gives only buffers with encrypted/decrypted content before pn_tls_stop() and all buffers afterwards.
PN_TLS_EXTERN size_t pn_tls_take_decrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
PN_TLS_EXTERN size_t pn_tls_take_encrypt_output_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
 
// Stage data to be encrypted by the engine at a future pn_tls_process() step.
// returned value is number of buffers taken (ownership transfer)
// i.e. held by the tls code - governed by capacity.
PN_TLS_EXTERN size_t pn_tls_give_encrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t const* bufs, size_t count_bufs);
 
// returned value is number of buffers taken
PN_TLS_EXTERN size_t pn_tls_give_decrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t const* bufs, size_t count_bufs);
 
// Take input buffers back into app ownership, return the actual number of buffers returned
// Returns buffers whose data is fully processed (or pn_tls_stop() called).
// keep calling these until the number returned is 0 to make sure you get all buffers currently available
PN_TLS_EXTERN size_t pn_tls_take_encrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
PN_TLS_EXTERN size_t pn_tls_take_decrypt_input_buffers(pn_tls_t*, pn_raw_buffer_t*, size_t count);
 
// Return the max number of additional input buffers we can hold
PN_TLS_EXTERN size_t pn_tls_get_encrypt_input_buffer_capacity(pn_tls_t*);
PN_TLS_EXTERN size_t pn_tls_get_decrypt_input_buffer_capacity(pn_tls_t*);
 
// True if there is no remaining space in the XXcrypt result buffers owned by the
// engine and there is XXcryped data available to put in a result buffer since
// the last pn_tls_process()
PN_TLS_EXTERN bool pn_tls_need_encrypt_output_buffers(pn_tls_t*);
PN_TLS_EXTERN bool pn_tls_need_decrypt_output_buffers(pn_tls_t*);
 
PN_TLS_EXTERN size_t pn_tls_get_encrypt_output_buffer_capacity(pn_tls_t*);
PN_TLS_EXTERN size_t pn_tls_get_decrypt_output_buffer_capacity(pn_tls_t*);
 
// Number of buffers ready to be returned by take operation since last pn_tls_process() or pn_tls_stop()
PN_TLS_EXTERN size_t pn_tls_get_decrypt_output_buffer_count(pn_tls_t*);
PN_TLS_EXTERN size_t pn_tls_get_encrypt_output_buffer_count(pn_tls_t*);
 
PN_TLS_EXTERN uint32_t pn_tls_get_last_decrypt_output_buffer_size(pn_tls_t*);
PN_TLS_EXTERN uint32_t pn_tls_get_last_encrypt_output_buffer_size(pn_tls_t*);
 
 
// Configurable.  Zero implies "use default".  No effect after pn_tls_start().
PN_TLS_EXTERN void pn_tls_set_encrypt_input_buffer_max_capacity(pn_tls_t*, size_t s);
PN_TLS_EXTERN void pn_tls_set_decrypt_input_buffer_max_capacity(pn_tls_t*, size_t s);
PN_TLS_EXTERN void pn_tls_set_encrypt_output_buffer_max_capacity(pn_tls_t*, size_t s);
PN_TLS_EXTERN void pn_tls_set_decrypt_output_buffer_max_capacity(pn_tls_t*, size_t s);
 
// Process as much unencrypted data to encrypted result data as possible.
// Also process as much undecrypted data to decryptedcrypted result data as possible.
// Check for TLS engine errors here.
// Always returns an error if called before pn_tls_start() or after pn_tls_stop().
PN_TLS_EXTERN int pn_tls_process(pn_tls_t* tls);
 
// Future pn_tls_process() or pn_tls_give_xxx() are no-ops.
// Unused encrypt/decrypt result buffers become zero length encrypted/decrypted result
// buffers and can be reclaimed.
// Future: If no closure from peer or self closure not written to result buffer, session resume cancelled.
PN_TLS_EXTERN int pn_tls_stop(pn_tls_t* tls);
 
// Confirms receipt of the peer's TLS closure record.  This confirms clean shutdown and
// the absence of a truncation attack.
PN_TLS_EXTERN bool pn_tls_is_input_closed(pn_tls_t* tls);
 
// Closes the encrypt side and appends the TLS closure record to the pending encypted
// output.  pn_tls_give_encrypt_input_buffers() will no longer take any supplied buffers.
PN_TLS_EXTERN void pn_tls_close_output(pn_tls_t* tls);
 
// If non-zero the TLS session was unable to start or was aborted.
// The application should stop all read activity, and take all
// remaining encrypted content and write it onto the connection
// (i.e. until pn_tls_is_encrypt_output_pending() is false), then
// close the associated connection.  This will allow the error to be
// propagated to the peer if expected by the TLS protocol.  Specific return values TBD (INIT_FAILED,
// BAD_AUTH, TLS_PROTOCOL_ERROR, ...).
PN_TLS_EXTERN int pn_tls_get_session_error(pn_tls_t* tls);
 
// Error string associated with the fatal TLS session error. zero if no error, buf is null or buf_len is 0.
PN_TLS_EXTERN size_t pn_tls_get_session_error_string(pn_tls_t* tls, char *buf, size_t buf_len);
 
PN_TLS_EXTERN int pn_tls_config_set_alpn_protocols(pn_tls_config_t *domain, const char **protocols, size_t protocol_count);
 
PN_TLS_EXTERN bool pn_tls_get_alpn_protocol(pn_tls_t *tls, const char **protocol_name, size_t *size);
 
// TODO:  Tracing.  Session tickets.
 
#ifdef __cplusplus
}
#endif
 
#endif /* tls.h */