NNTP: Network News Transfer Protocol

Classes
struct	nntp_groupdesc
	NNTP group descriptor. More...
struct	nntp_grouplabel
	NNTP group label (description string) More...

Macros
#define	NNTP_ANUM_T_MAX   ULONG_MAX
	Maximum value this implementation supports for nntp_anum_t. More...
#define	MAIN_ERR_PREFIX   "NNTP: "
	Message prefix for NNTP module. More...
#define	NNTP_HANDLEMAX   1U
	Maximum number of simultaneous NNTP connections. More...
#define	NNTP_LINELENGTHMAX   (size_t) 512
	Maximum line length (for command/response, not payload) More...

Typedefs
typedef unsigned long int	nntp_anum_t
	Article number. More...

Enumerations
enum	nntp_cmd {   NNTP_CMD_INIT , NNTP_CMD_QUIT , NNTP_CMD_CAPABILITIES , NNTP_CMD_MODE_READER ,   NNTP_CMD_COMPRESS , NNTP_CMD_AUTHINFO_USER , NNTP_CMD_AUTHINFO_PASS , NNTP_CMD_LIST ,   NNTP_CMD_LIST_NEWSGROUPS , NNTP_CMD_LIST_MOTD , NNTP_CMD_LIST_DISTRIB_PATS , NNTP_CMD_LIST_SUBSCRIPTIONS ,   NNTP_CMD_GROUP , NNTP_CMD_OVER , NNTP_CMD_ARTICLE_BY_MID , NNTP_CMD_ARTICLE ,   NNTP_CMD_HEAD , NNTP_CMD_BODY , NNTP_CMD_POST }

Functions
int	nntp_open (int *handle, const char *servername, const char *service, const char *logfile, int enc, int auth,...)
	Open connection to NNTP server. More...
void	nntp_close (int *handle, unsigned int flags)
	Disconnect from NNTP server. More...
int	nntp_get_capa_list_motd (int handle)
	Get message of the day capability of NNTP server. More...
int	nntp_get_motd (int handle, char **data, size_t *len)
	Get message of the day. More...
int	nntp_get_distrib_pats (int handle, const char **data, size_t *len)
	Get distribution patterns. More...
int	nntp_get_capa_list_subscriptions (int handle)
	Get message of the day capability of NNTP server. More...
int	nntp_get_subscriptions (int handle, char **data, size_t *len)
	Get subscription proposals. More...
struct nntp_groupdesc *	nntp_group_descriptor_constructor (const char *name)
	Allocate and initialize a descriptor for group. More...
int	nntp_get_grouplist (int handle, size_t *groupcount, struct nntp_groupdesc **p)
	Get group list. More...
int	nntp_get_group_labels (int handle, size_t *groupcount, struct nntp_grouplabel **p)
	Get additional group information. More...
int	nntp_set_group (int handle, const char *name, struct nntp_groupdesc **gd)
	Set current group. More...
int	nntp_get_capa_over (int handle)
	Get overview capability of NNTP server. More...
int	nntp_get_overview (int handle, nntp_anum_t first, nntp_anum_t last, char **data, size_t *len)
	Get overview for article range. More...
int	nntp_get_article_by_mid (int handle, const char *mid, char **article, size_t *len)
	Get complete article via Message-ID. More...
int	nntp_get_article (int handle, const nntp_anum_t *id, char **article, size_t *len)
	Get complete article. More...
int	nntp_get_article_header (int handle, const nntp_anum_t *id, char **header, size_t *len)
	Get article header. More...
int	nntp_get_article_body (int handle, const nntp_anum_t *id, char **body, size_t *len)
	Get article body. More...
int	nntp_post_article (int handle, const char *article)
	Post article. More...

Connection closing flags
#define	NNTP_CLOSE_NOQUIT   1U

Newsgroup flags
#define	NNTP_GROUP_FLAG_ASCII   0x01U
#define	NNTP_GROUP_FLAG_PA   0x02U

NNTP capabilities
The flags can be bitwise ORed together.
#define	NNTP_CAPA_MODE_READER   0x0001U
#define	NNTP_CAPA_READER   0x0002U
#define	NNTP_CAPA_LIST   0x0004U
#define	NNTP_CAPA_LIST_MOTD   0x0008U
#define	NNTP_CAPA_LIST_DISTRIB_PATS   0x0010U
#define	NNTP_CAPA_LIST_SUBSCRIPTIONS   0x0020U
#define	NNTP_CAPA_OVER   0x0040U
#define	NNTP_CAPA_POST   0x0080U
#define	NNTP_CAPA_AUTHINFO_USER   0x0100U
#define	NNTP_CAPA_COMPRESS   0x0200U

Algorithms for NNTP compression extension
The flags can be bitwise ORed together.
#define	NNTP_COMPRESS_DEFLATE   0x0001U

Detailed Description

This transport subsystem should behave RFC 1951, RFC 977, RFC 2980, RFC 3977, RFC 4643 and RFC 6048 conformant.

Secure NNTPS connections can be requested if TLS support is available.

The AUTHINFO USER/PASS extension from RFC 4643 is supported if TLS support is available. The AUTHINFO SASL extension from RFC 4643 is not supported.

Compression support is used according to RFC 8054. Compression is used if advertised by the server (with COMPRESS capability), the required local libraries (e.g. zlib for DEFLATE algorithm) are available and compression isn't disabled by configuration (CONF_COMPRESSION parameter).

Note

Authentication is always done before enabling compression.

RFC 3977 allows non-ASCII encoded group names, but recommend not to use them. They are supported nevertheless by this transport driver

Attention

RFC 5536 conformant messages can't use Unicode group names. RFC 5536 mandates that the whole header must be ASCII encoded and forbids MIME encoded words as defined in RFC 2047 for the group identifiers inside the "Newsgroups" and "Followup-To" header fields.

Note

Unicode identifiers are ambigous by definition and can't simply be used as received without an additional normalization step. As long as there is no "canonical" normalization algorithm defined for the USENET, it is in general a good idea to not use Unicode for identifiers at all.

Macro Definition Documentation

MAIN_ERR_PREFIX

#define MAIN_ERR_PREFIX   "NNTP: "

Message prefix for NNTP module.

Definition at line 77 of file nntp.c.

NNTP_ANUM_T_MAX

#define NNTP_ANUM_T_MAX   ULONG_MAX

Maximum value this implementation supports for nntp_anum_t.

Definition at line 52 of file nntp.h.

NNTP_CAPA_AUTHINFO_USER

#define NNTP_CAPA_AUTHINFO_USER   0x0100U

Definition at line 105 of file nntp.c.

NNTP_CAPA_COMPRESS

#define NNTP_CAPA_COMPRESS   0x0200U

Definition at line 106 of file nntp.c.

NNTP_CAPA_LIST

#define NNTP_CAPA_LIST   0x0004U

Definition at line 99 of file nntp.c.

NNTP_CAPA_LIST_DISTRIB_PATS

#define NNTP_CAPA_LIST_DISTRIB_PATS   0x0010U

Definition at line 101 of file nntp.c.

NNTP_CAPA_LIST_MOTD

#define NNTP_CAPA_LIST_MOTD   0x0008U

Definition at line 100 of file nntp.c.

NNTP_CAPA_LIST_SUBSCRIPTIONS

#define NNTP_CAPA_LIST_SUBSCRIPTIONS   0x0020U

Definition at line 102 of file nntp.c.

NNTP_CAPA_MODE_READER

#define NNTP_CAPA_MODE_READER   0x0001U

Definition at line 97 of file nntp.c.

NNTP_CAPA_OVER

#define NNTP_CAPA_OVER   0x0040U

Definition at line 103 of file nntp.c.

NNTP_CAPA_POST

#define NNTP_CAPA_POST   0x0080U

Definition at line 104 of file nntp.c.

NNTP_CAPA_READER

#define NNTP_CAPA_READER   0x0002U

Definition at line 98 of file nntp.c.

NNTP_CLOSE_NOQUIT

#define NNTP_CLOSE_NOQUIT   1U

Don't send quit command before closing connection to server

Definition at line 57 of file nntp.h.

NNTP_COMPRESS_DEFLATE

#define NNTP_COMPRESS_DEFLATE   0x0001U

Definition at line 114 of file nntp.c.

NNTP_GROUP_FLAG_ASCII

#define NNTP_GROUP_FLAG_ASCII   0x01U

Group name contains only printable ASCII characters

Definition at line 63 of file nntp.h.

NNTP_GROUP_FLAG_PA

#define NNTP_GROUP_FLAG_PA   0x02U

Posting to group is allowed

Definition at line 65 of file nntp.h.

NNTP_HANDLEMAX

#define NNTP_HANDLEMAX   1U

Maximum number of simultaneous NNTP connections.

Definition at line 80 of file nntp.c.

NNTP_LINELENGTHMAX

#define NNTP_LINELENGTHMAX   (size_t) 512

Maximum line length (for command/response, not payload)

Must be at least 512 characters.
RFC 977 : Maximum command line length is 512 characters
RFC 3977: Maximum length of first line of response is 512 characters

Definition at line 90 of file nntp.c.

Typedef Documentation

nntp_anum_t

typedef unsigned long int nntp_anum_t

Article number.

RFC 3977 requires at least 31 bit storage for article numbers. The constant NNTP_ANUM_T_MAX must be set to the maximum value that is supported by this implementation. According to RFC 3977, article number zero is reserved.

Attention

This must always be an unsigned integer type.

Definition at line 28 of file nntp.h.

Enumeration Type Documentation

nntp_cmd

enum nntp_cmd

Definition at line 122 of file nntp.c.

Function Documentation

nntp_close()

void nntp_close	(	int *	handle,
		unsigned int	flags
	)

Disconnect from NNTP server.

Parameters

[in,out]	handle	Pointer to server descriptor
[in]	flags	Control flags (use NNTP_CLOSE_xxx constants)

Definition at line 2042 of file nntp.c.

References NNTP_CLOSE_NOQUIT.

nntp_get_article()

int nntp_get_article	(	int	handle,
		const nntp_anum_t *	id,
		char **	article,
		size_t *	len
	)

Get complete article.

Parameters

[in]	handle	Server descriptor
[in]	id	Pointer to article identifier
[out]	article	Pointer to article buffer pointer
[out]	len	Pointer to article buffer size

On success, a pointer to the article buffer is written to article and the caller is responsible to free the associated memory. The size of this buffer is written to len .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 3106 of file nntp.c.

nntp_get_article_body()

int nntp_get_article_body	(	int	handle,
		const nntp_anum_t *	id,
		char **	body,
		size_t *	len
	)

Get article body.

Parameters

[in]	handle	Server descriptor
[in]	id	Pointer to article identifier
[out]	body	Pointer to article body buffer pointer
[out]	len	Pointer to article body buffer size

On success, a pointer to the article body buffer is written to body and the caller is responsible to free the associated memory. The size of this buffer is written to len .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 3206 of file nntp.c.

nntp_get_article_by_mid()

int nntp_get_article_by_mid	(	int	handle,
		const char *	mid,
		char **	article,
		size_t *	len
	)

Get complete article via Message-ID.

Parameters

[in]	handle	Server descriptor
[in]	mid	Pointer to article Message-ID
[out]	article	Pointer to article buffer pointer
[out]	len	Pointer to article buffer size

On success, a pointer to the article buffer is written to article and the caller is responsible to free the associated memory. The size of this buffer is written to len .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 3056 of file nntp.c.

nntp_get_article_header()

int nntp_get_article_header	(	int	handle,
		const nntp_anum_t *	id,
		char **	header,
		size_t *	len
	)

Get article header.

Parameters

[in]	handle	Server descriptor
[in]	id	Pointer to article identifier
[out]	header	Pointer to article header buffer pointer
[out]	len	Pointer to article header buffer size

On success, a pointer to the article header buffer is written to header and the caller is responsible to free the associated memory. The size of this buffer is written to len .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 3156 of file nntp.c.

nntp_get_capa_list_motd()

int nntp_get_capa_list_motd

(

int

handle

)

Get message of the day capability of NNTP server.

Parameters

[in]

handle

Server descriptor

This function will trigger no communication with the server. It simply reports the currently buffered state for the server associated with handle .

Returns

• LIST MOTD capability flag (nonzero if capability is available)

Definition at line 2110 of file nntp.c.

nntp_get_capa_list_subscriptions()

int nntp_get_capa_list_subscriptions

(

int

handle

)

Get message of the day capability of NNTP server.

Parameters

[in]

handle

Server descriptor

This function will trigger no communication with the server. It simply reports the currently buffered state for the server associated with handle .

Returns

• LIST SUBSCRIPTIONS capability flag (nonzero if capability is available)

Definition at line 2244 of file nntp.c.

nntp_get_capa_over()

int nntp_get_capa_over

(

int

handle

)

Get overview capability of NNTP server.

Parameters

[in]

handle

Server descriptor

This function will trigger no communication with the server. It simply reports the currently buffered state for the server associated with handle .

Returns

• OVER capability flag (nonzero if this capability is available)

Definition at line 2973 of file nntp.c.

nntp_get_distrib_pats()

int nntp_get_distrib_pats	(	int	handle,
		const char **	data,
		size_t *	len
	)

Get distribution patterns.

This option is defined in RFC 3977.

Parameters

[in]	handle	Server descriptor
[out]	data	Pointer to pattern data buffer
[out]	len	Pointer to buffer size

Note

It is allowed to pass NULL for len if the caller is not interested in this value.

This function will trigger no communication with the server. On success it returns a pointer to the currently buffered data for the server associated with handle that was retrieved while opening the connection.

Note

No extra memory is allocated for the caller, so there is nothing to free.

Returns

• 0 on success
• 1 if not available
• -1 on error

Definition at line 2205 of file nntp.c.

References data.

Referenced by core_get_distribution().

nntp_get_group_labels()

int nntp_get_group_labels	(	int	handle,
		size_t *	groupcount,
		struct nntp_grouplabel **	p
	)

Get additional group information.

Parameters

[in]	handle	Server descriptor
[out]	groupcount	Pointer to number of groups
[out]	p	Pointer to array of group descriptors

On success, the caller is responsible for releasing the memory allocated for the array p .

Note

If groupcount is zero, p may be NULL .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 2631 of file nntp.c.

nntp_get_grouplist()

int nntp_get_grouplist	(	int	handle,
		size_t *	groupcount,
		struct nntp_groupdesc **	p
	)

Get group list.

Parameters

[in]	handle	Server descriptor
[out]	groupcount	Pointer to number of groups
[out]	p	Pointer to array of group descriptors

On success, the caller is responsible for releasing the memory allocated for the array p .

Note

If groupcount is zero, p may be NULL .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 2377 of file nntp.c.

nntp_get_motd()

int nntp_get_motd	(	int	handle,
		char **	data,
		size_t *	len
	)

Get message of the day.

This option is defined in RFC 6048.

Parameters

[in]	handle	Server descriptor
[out]	data	Pointer to MOTD data buffer pointer
[out]	len	Pointer to buffer size

On success, the caller is responsible for releasing the memory allocated for the array data .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 2142 of file nntp.c.

nntp_get_overview()

int nntp_get_overview	(	int	handle,
		nntp_anum_t	first,
		nntp_anum_t	last,
		char **	data,
		size_t *	len
	)

Get overview for article range.

Parameters

[in]	handle	Server descriptor
[in]	first	First article identifier of range
[in]	last	Last article identifier of range
[out]	data	Pointer to overview data buffer pointer
[out]	len	Pointer to article buffer size

On success, a pointer to the overview data buffer is written to data and the caller is responsible to free the associated memory. The size of this buffer is written to len .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 3006 of file nntp.c.

nntp_get_subscriptions()

int nntp_get_subscriptions	(	int	handle,
		char **	data,
		size_t *	len
	)

Get subscription proposals.

This option is defined in RFC 6048.

Parameters

[in]	handle	Server descriptor
[out]	data	Pointer to subscriptions data buffer pointer
[out]	len	Pointer to buffer size

On success, the caller is responsible for releasing the memory allocated for the array data .

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 2279 of file nntp.c.

nntp_group_descriptor_constructor()

struct nntp_groupdesc * nntp_group_descriptor_constructor

(

const char *

name

)

Allocate and initialize a descriptor for group.

Parameters

[in]

name

Group name

An empty group descriptor is created and name is copied behind this descriptor so that the whole object can be destroyed as a single memory block.

On success, the caller is responsible to destroy the allocated object.

Returns

• Pointer to initialized group descriptor on success
• NULL on error

Definition at line 2332 of file nntp.c.

References nntp_groupdesc::name.

nntp_open()

int nntp_open	(	int *	handle,
		const char *	servername,
		const char *	service,
		const char *	logfile,
		int	enc,
		int	auth,
			...
	)

Open connection to NNTP server.

Parameters

[out]	handle	Pointer to server descriptor
[in]	servername	Server name or address string
[in]	service	Service name or port
[in]	logfile	Logfile name
[in]	enc	Encryption algorithm ID (for connection)
[in]	auth	Authentication algorithm ID (client against server)

servername must be an IPv4 address in dotted decimal representation, an IPv6 address in colon separated hexadecimal representation or a hostname that can be resolved to an IPv4 address via DNS.

service must be a valid service name like nntp or nntps or it must be the target TCP port on which the NNTP or NNTPS service is listening. The default value is 119 (or 563 for NNTP over TLS respectively).

If logfile is NULL then log data is redirected to /dev/null .

This function handles optional encryption for the connection to the server if enc is nonzero. The following encryption algorithms are supported:

• 0: No encryption
• 1: RFC 2246 / RFC 4346 / RFC 5246 / RFC 8446 conformant TLS
  This includes the authentication of the server against the client using a X509 certificate.
• 2: Same as 1 but additionally offer weak cipher suites to server
  The list includes (at the end) the cipher suite RSA-RSA-RC4-MD5 that was defined as mandatory by RFC 4642 in the past.
  Not recommended! Use only if algorithm 1 is not accepted by server.

This function handles optional authentication of the client against the server if auth is nonzero. The following authentication algorithms are supported:

• 0: No authentication
• 1: RFC 4643 conformant AUTHINFO USER/PASS authentication
  An encrypted connection is mandatory for this algorithm!
  The first optional parameter is a flag of type int that indicates whether authentication should be done immediately.
  There must be two additional string parameters of type const char* that specify username and password as plain text. Both strings are copied and the pointers are not required to stay valid after this function returns.

Returns

• 0 on success (a valid connection handle was written to handle )
• Negative value on error

Definition at line 1777 of file nntp.c.

References PRINT_ERROR.

nntp_post_article()

int nntp_post_article	(	int	handle,
		const char *	article
	)

Post article.

Parameters

[in]	handle	Server descriptor
[in]	article	Pointer to article buffer

article must point to a RFC 5536 conformant article in canonical form. The caller is responsible for the validity check of the article format.

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 3253 of file nntp.c.

nntp_set_group()

int nntp_set_group	(	int	handle,
		const char *	name,
		struct nntp_groupdesc **	gd
	)

Set current group.

Parameters

[in]	handle	Server descriptor
[in]	name	Group name
[out]	gd	Pointer to group descriptor

On success and if gd is not NULL , a pointer to an initialized group descriptor for the group specified by name is written to gd . The caller is responsible for releasing the memory allocated for this group descriptor.

Returns

• 0 on success
• -1 on error
• -2 if connection to server is broken
• -3 if authentication requested by server failed

Definition at line 2818 of file nntp.c.