Loading...
Searching...
No Matches
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 */
pn_raw_buffer_t
A descriptor used to represent a single raw buffer in memory.
Definition raw_connection.h:54
pn_tls_get_alpn_protocol
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_get_cipher
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_get_peer_hostname
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_start
PN_TLS_EXTERN int pn_tls_start(pn_tls_t *tls)
Start a TLS session.
pn_tls_config_free
PN_TLS_EXTERN void pn_tls_config_free(pn_tls_config_t *domain)
Release an TLS configuration domain.
pn_tls_get_cert_fingerprint
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
pn_tls_hash_alg
Enumeration identifying hashing algorithm.
Definition tls.h:366
pn_tls_set_peer_hostname
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_config
PN_TLS_EXTERN pn_tls_config_t * pn_tls_config(pn_tls_mode_t mode)
Create an TLS configuration domain.
pn_tls_config_set_trusted_certs
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.
pn_tls_t
struct pn_tls_t pn_tls_t
Definition tls.h:86
pn_tls_get_remote_subject_subfield
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_mode_t
pn_tls_mode_t
Determines the type of TLS endpoint.
Definition tls.h:91
pn_tls_verify_mode_t
pn_tls_verify_mode_t
Determines the level of peer validation.
Definition tls.h:196
pn_tls_config_set_peer_authentication
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_get_protocol_version
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_config_set_credentials
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_config_set_impl_ciphers
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_get_remote_subject
PN_TLS_EXTERN const char * pn_tls_get_remote_subject(pn_tls_t *tls)
Get the subject from the peers certificate.
pn_tls_cert_subject_subfield
pn_tls_cert_subject_subfield
Enumeration identifying the sub fields of the subject field in the tls certificate.
Definition tls.h:354
pn_tls_config_t
struct pn_tls_config_t pn_tls_config_t
API for using TLS separate from AMQP connections.
Definition tls.h:81
pn_tls
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_get_ssf
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_config_set_alpn_protocols
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_MODE_SERVER
@ PN_TLS_MODE_SERVER
Local connection endpoint is an TLS server.
Definition tls.h:93
PN_TLS_MODE_CLIENT
@ PN_TLS_MODE_CLIENT
Local connection endpoint is an TLS client.
Definition tls.h:92
PN_TLS_VERIFY_NULL
@ PN_TLS_VERIFY_NULL
internal use only
Definition tls.h:197
PN_TLS_VERIFY_PEER_NAME
@ PN_TLS_VERIFY_PEER_NAME
require valid certificate and matching name
Definition tls.h:200
PN_TLS_VERIFY_PEER
@ PN_TLS_VERIFY_PEER
require peer to provide a valid identifying certificate
Definition tls.h:198
PN_TLS_ANONYMOUS_PEER
@ PN_TLS_ANONYMOUS_PEER
do not require a certificate nor cipher authorization
Definition tls.h:199
raw_connection.h