|
TReK ANSI-C
5.3.3
All ANSI-C APIs
|
The trek_toolkit_cfdp_api library provides ANSI C functions that configure the CCSDS File Delivery Protocol (CFDP) library, groups CFDP transaction requests and delivers files using CFDP on both Windows 10 and Red Hat Enterprise Linux 7, operating systems. A simple text file of name-value pairs and primitives is used to configure the TReK CFDP library.
Background
The TReK CFDP library is dependent on either the GSFC CFDP library and API or the Interplanetary Overlay Network (ION) CFDP over Disruption-Tolerant Network (DTN) Bundle Protocol (BP) libraries and API. The TReK CFDP library is also dependent on OpenSSL libraries and API to supports encyption and decryption of files and data streams.
GSFC CFDP Library:
The GSFC CFDP library (referenced as native CFDP) implements the CFDP "put" directive as defined by the CCSDS CFDP Blue Book (document CCSDS 727.0-B-2). It does not define or implement a transport layer for file delivery.
The library provides two levels of CFDP service: CFDP class 1 service and CFDP class 2 service. CFDP class 1 service is a "send and forget" level of service that sends files without any acknowledgement of their receipt by the recipient. CFDP class 2 service requires file delivery acknowledgements in the form of ACKs and NAKs from the recipient. The ACKs and NAKs identify successful file receipt or missing file segments that must be retransmitted. CFDP class 2 library configuration parameters include the maximum number of allowable ACK and NAK timeouts and the maximum amount of time to wait for an ACK or NAK. The GSFC CFDP library has defined a simple "put" primitive to describe the file delivery request. The format of a "put" primitive string is as follows:
put <class of service> <"source path and filename"> <remote entity ID> <"destination path and filename">
Providing a "put" primitive to the library initiates a file transfer transaction. The primitive identifies class 1 or class 2 service, the path and name of the source file, the destination node or remote Entity ID (EID) and the destination path and filename. EIDs are pre-assigned integer values that have a corresponding Internet Protocol (IP) address and port. The GSFC CFDP library uses a dotted octet string representation of the EID. For example, the dotted octet string representation of 256 is 1.0 and 65535 is 255.255. CFDP requires EID assignment for every node participating in the file delivery transaction. The GSFC CFDP library sends file delivery status messages to the user through a series of registered callback functions. Additional enhancements have been made to the GSFC CFDP library to support file store actions (e.g., create file, delete file, append file...), messages and "gets" implemented as "proxy puts" as defined by the CCSDS CFDP Blue Book. The TReK CFDP library may also be configured to create native CFDP dropboxes.
ION CFDP Library:
The ION software is an implementation of Disruption-Tolerant Networking (DTN) architecture as described in Internet RFC 4838. DTN is a digital communication networking technology that enables data to be conveyed between two communicating entities automatically and reliably even if one or more of the network links in the end-to-end path between those entities is subject to very long signal propagation latency and/or prolonged intervals of unavailability. The ION CFDP software (referenced as ION CFDP or CFDP over BP) implements the CFDP class 1 "put" directive and includes file store actions and messages as defined by the CFDP Blue Book. ION implements the CFDP transport layer with DTN's BP. ION BP provides a variety of transmission properties to ensure timely bundle delivery to a destination. These properties include standard or expedited priorities, custody transfer between nodes and bundle criticality. The ION CFDP library includes an event queue with information on the transmission and receipt of metadata and end of file Protocol Data Units (PDU)s as well as transaction initiation, progress and completion status. Without ION support for CFDP class 2 service, the final CFDP transaction result (e.g. success or fail) is not known by the platform that made the transaction request. However, if the TReK CFDP library is being used to initiate and service both ends of the transaction, TReK may be configured to provide a CFDP message that returns transaction results to the source of the transaction request.
TReK also provides a "get" directive, using CFDP messages, if the TReK CFDP library is being used on both ends of the transaction.
In addition, the TReK CFDP library may be configured to create CFDP over BP dropboxes.
TReK Encryption Library:
The TReK encryption library uses OpenSSL's FIPS 140-2 validated cryptographic module and public/private key pairs to encrypt and decrypt files and packets. TReK encryption library support is provided on 32 bit and 64 bit Linux operating systems and 64 bit Windows operating systems. TReK encryption library support is not available on 32 bit Window operating systems. Both the flight platform and ground platform generate public/private key pairs using TReK's "trek_crypt" application. TReK's public key/private key encryption architecture is based on Elliptic Curve Cryptography (ECC) using curve P-256 providing 128-bit security with 128 or 256 bit keys. The cipher packages included with the TReK encryption library are the Advance Encryption Standard (AES) Galois/Counter Mode(AES GCM) and the AES Counter with CBC-MAC (AES CCM) ciphers offering confidentiality, authenticity and integrity. The library supports 128 and 256 bit cipher key sizes and provides AES 128 and 256 bit key-wrap/unwrap functions. Fresh Cipher Encryption Keys (CEK) are created for files and packets using a Password-Based Key Derivation Function 2 (PBKDF2).
TReK's "trek_crypt" application generates the public and private key pair using ECC. The private key is wrapped prior to storing in a file with a default passphrase or an optional user passphrase up to 63 characters in length. If a user passphrase is used to wrap the private key, the passphrase must be provided during runtime. Three methods are available to provide the user passphrase at runtime: enter the passphrase using the TReK CFDP GUI, include the passphrase as a seperate parameter after the path and filename of the CFDP configuration file when launching the TReK CFDP console application or provide the passphrase programmatically using the TReK API. The latter method requires recompilation of the TReK CFDP console application or user application. A shared secred key is generated using the private key and the remote/destination platform's public key referred to as the peer public key. The peer public key (i.e., the public key of the destination platform) must be exchanged manually prior to encryption or decryption, no automated key exchange mechanisms is implemented. The TReK encryption library generates a new CEK for every encrypted file and may be configured to generate a new CEK for every encrypted packet in a packet stream. The TReK encryption library may also be configured to generate a new CEK, for a packet stream, once every "x" seconds to support encryption of high rate packet stream. No "encryption handshaking" is required between flight and ground hardware during the encryption and decryption of packets.
Files may be encrypted and decrypted using TReK encryption or decryption dropboxes. Native CFDP may be configured to encrypt and decrypt the CFDP packet streams associated with CFDP transactions. The native CFDP stream encryption configuration automatically encrypts and decrypts files as they are being transferred between the source platform and destination platform requiring no encryption or decryption dropbox. In addition, native CFDP stream encryption may be configured to encrypt a time stamp, Time To Live (TTL) value and sequence count to provide replay resistance time authentication in support of Safety Conditional KuIP Services (SCKIPS). The encrypted TTL value is in seconds and must be between 0-65535. The time authentication software compares the packet's decrypted time stamp with the operating system time (plus or minus the decrypted TTL) to determine if the packet's decrypted time falls within the authentication time window. In addition, the time authentication software does not allow a packet to be processed if the decrypted time and sequence count stays the same or decreases when compared to the previous decrypted packet time and sequence count. The CFDP packet stream encryption option is not available for ION CFDP. ION CFDP must use the encryption and decryption dropboxes to encrypt and decrypt files. Review the description of the CFDP configuration file's remote entity IDs for further information on packet stream encryption and native CFDP.
TReK CFDP Library
Initialeization:
The InitToolkitCfdp function initializes the TReK CFDP library by reading parameters from a TReK CFDP configuration file to determine if TReK CFDP is being configured to communicate with the GSFC's CFDP library (native CFDP) or JPL's CFDP libraries (ION CFDP or CFDP over BP). For native CFDP, the InitToolkitCfdp function creates a UDP socket to send and receive CFDP PDUs. CFDP PDUs are data packets containing the file metadata and the file segments that enable delivery of the file to the destination platform or node. For CFDP over BP, ION creates the sockets that are used to send and receive the bundles of PDUs.
An application should call the InitToolkitCfdp function prior to using any of the TReK CFDP API functions. The path and filename of a TReK CFDP configuration file are included with the call to the InitToolkitCfdp function. The format of a TReK CFDP configuration file is a series of name value pairs that configure the library to meet user requirements. One or more spaces separate individual parameters on each line in the file. The following table identifies and describes the configuration file parameters. The third column in the table identifies parameters that are required/relevant for the two CFDP library device mode settings. The TReK CFDP library ignores parameters in the file that are not relevant to its configuration or device mode. The TReK CFDP library
GetDeviceMode function returns the device mode configuration (NATIVE_CFDP or ION_CFDP) of the TReK CFDP library.
| CFDP Configuration File Parameter | Description | Device Mode |
| CFDP_configuration_version | The configuration file version number. The first parameter in the configuration file must be the version number or TReK CFDP initialization will fail. | NATIVE_CFDP ION_CFDP |
| cfdp_library_device_name | A unique reference that may be used to communicate with other TReK library devices. | NATIVE_CFDP ION_CFDP |
| trek_device_mode | The TReK device mode parameter is set to NATIVE_CFDP if the TReK CFDP library is communicating with GSFC's CFDP library or to ION_CFDP if TReK is communicating with JPL's CFDP library. | NATIVE_CFDP ION_CFDP |
| log_messages_in_file | The log messages in file boolean controls message logging. If true, messages are recorded in a log file. The default value is false. | NATIVE_CFDP ION_CFDP |
| log_debug_messages | The log debug messages boolean controls logging debug messages. If true, debug messages are recorded in a log file. The default value is false. | NATIVE_CFDP ION_CFDP |
| log_file_path | The log file path is the absolute path to the directory where the log file should be written. If an empty string is provided, the default path is the user's home directory. | NATIVE_CFDP ION_CFDP |
| log_file_name | The log file name is the name to use for the log file. The default value "toolkit_cfdp_log". | NATIVE_CFDP ION_CFDP |
| record_stat_snapshot_in_file | The record stat snapshot in file boolean controls recording statistics. If "true", a statistic snapshot is recorded in a file. The default value is false. | NATIVE_CFDP ION_CFDP |
| record_packet_statistics | The record packet statistics boolean controls recording packet statistics in addition to device statistics. If "true", packet statistics are recorded in a file. The default value is false. | NATIVE_CFDP ION_CFDP |
| record_stat_file_path | The record stat file path is the absolute path to the directory where the statistics file should be recorded. If an empty string is provided, the default path is the user's home directory. | NATIVE_CFDP ION_CFDP |
| record_stat_file_name | The record stat file name is the name to use for the statistics file. The default value is "toolkit_cfdp_statistics". | NATIVE_CFDP ION_CFDP |
| record_cfdp_metrics_snapshot_in_file | The record CFDP metrics snapshot in file boolean controls recording CFDP metrics. If "true", a CFDP metric snapshot is recorded in a file. The default value is false. | NATIVE_CFDP ION_CFDP |
| record_cfdp_metrics_file_path | The record CFDP metrics file path is the absolute path to the directory where the CFDP metrics file should be recorded. If an empty string is provided, the default path is the user's home directory. | NATIVE_CFDP ION_CFDP |
| record_cfdp_metrics_file_name | The record CFDP metrics file name is the name to use for the CFDP metrics file. The default value is "toolkit_cfdp_metrics". | NATIVE_CFDP ION_CFDP |
| support_cfdp_status_requests | The support cfdp status requests boolean enables monitoring the status of CFDP transactions by a user application. If "true", CFDP transaction monitoring is enabled. The default value is false. | NATIVE_CFDP ION_CFDP |
| public_key_path_and_file_name | The public key path and filename is the absolute path and file name of the local entity's public key file. It is used to encrypt and decrypt files and CFDP PDU packets. The public key file is created by TReK's "trek_crypt" program. | NATIVE_CFDP ION_CFDP |
| private_key_path_and_file_name | The private key path and filename is the absolute path and file name of the local entity's private key file. It is used to encrypt and decrypt files and CFDP PDU packets. The private key file is created by TReK's "trek_crypt" program. | NATIVE_CFDP ION_CFDP |
| packet_encryption_key_time_interval | The packet encryption key time interval determines how often the packet encryption key is changed while encrypting a stream of native CFDP PDU packets. The time interval is measured in seconds. If the packet encryption key time interval is set to zero, the TReK encryption library will generate a new packet encryption key for every packet in the stream. The TReK encryption library can support the encryption of high rate packet streams by setting the packet encryption key time interval to a non-zero value. The default value is 10 seconds. | NATIVE_CFDP |
| cipher_class | The cipher class is the cipher package that the TReK encryption library will use to encrypt and decrypt files and streams of native CFDP PDU packets. The four cipher class values are AES_128_GCM, AES_256_GCM, AES_128_CCM and AES_256_CCM which support either a 128 bit or 256 bit symmetric key. An AES 256 cipher will require more CPU resources to encrypt and decrypt files and streams then an AES 128 cipher. | NATIVE_CFDP ION_CFDP |
| Dropbox Encrypt or Decrypt Primitives | Creates and configures TReK encryption or decryption dropboxes using "dropbox" primitives. The default primitive list is empty. | NATIVE_CFDP ION_CFDP |
| Dropbox CFDP Primitives | Creates and configures TReK CFDP dropboxes using "dropbox" primitives. The default primitive list is empty. | NATIVE_CFDP ION_CFDP |
| CFDP Primitives | Initialize the CFDP application with TReK CFDP primitives (e.g., "put", "get", "message", "create_file", "delete_file" ...). An additional CFDP library function (SendAllRequests) must be called prior to processing the list of CFDP primitives. The default primitive list is empty. | NATIVE_CFDP ION_CFDP |
| ack_timeout | The CFDP library sends positive acknowledgment on reception of the end-of-file packet and finished packet. This timeout defines the number of seconds the CFDP library will wait for the ACK packet to arrive prior to retransmitting the end-of-file or finished packet. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 15 seconds. | NATIVE_CFDP |
| ack_limit | The ACK limit is the number of ack timeouts that may occur prior to cancelling the CFDP transaction. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 25. | NATIVE_CFDP |
| nak_timeout | The CFDP library sends a NAK packet identifying the CFDP packets that were not received by the CFDP library. This timeout defines the number of seconds the CFDP library will wait for the retransmission of the requested CFDP packets. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 15 seconds. | NATIVE_CFDP |
| nak_limit | The NAK limit is the number of Nak timeouts that may occur prior to cancelling the CFDP transaction. Minimum value is 1, maximum value is 2147483647 and the default value is 100. | NATIVE_CFDP |
| nak_max_pdu_size | The NAK maximum PDU size is the maximum size of a NAK PDU packet in bytes. If the CFDP transactions identifies multiple gaps in the data transmission and the gap information cannot fit in a single NAK PDU, the CFDP library will generate multiple NAK PDUs until all the data gaps are filled or the number of NAK PDU's surpasses the NAK limit. Providing a limit on the maximum size of the NAK PDU ensures the PDU will not be dropped because its size exceeds the limits of its transport medium. Minimum value is 50, maximum value is 64042 and the default value is 16000. | NATIVE_CFDP |
| inactivity_timeout | The inactivity timeout is the length of time, in seconds, the CFDP library is required to wait between CFDP packet receptions prior to cancelling the CFDP transaction. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 300 seconds. | NATIVE_CFDP |
| outgoing_file_chunk_size | The outgoing file chunk size is the maximum size, in bytes, of the data zone of the CFDP packets created by the CFDP library. Minimum value is 1, maximum value is 65,200 and the default value is 1,300 bytes. | NATIVE_CFDP |
| aggregate_file_transfer_bit_rate | The aggregate file transfer rate represents the maximum transmission rate, in bits per second, of the CFDP packets created by the CFDP library. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 10,000,000 bits/second. | NATIVE_CFDP |
| socket_queue_size | The UDP socket that is created to receive CFDP packets may store CFDP packets in a queue prior to the packets being processed by the CFDP library. This queue minimizes the chances of a CFDP packet being dropped due to packet transmission bursts or a temporary CPU spike on the receiving platform. In general, a larger queue size is needed for higher transmission rates. If an unacceptable number of CFDP packet retransmissions is occurring, increasing the queue size or decreasing the file transfer rate may help decrease or eliminate the CFDP packet retransmissions. Minimum value is 0, maximum value is 1,000,000 and the default value is 1000. | NATIVE_CFDP |
| transaction_cycle_time_interval | The transaction cycle time interval, in milliseconds, controls the processing rate of CFDP library transactions. Minimizing the cycle time, increases the transaction speed or processing rate. The default value is 1 milliseconds. The minimum value is 0 millisecond and the maximum value is 2,147,483,647 milliseconds. This value should be incremented if CPU usage on the host platform is unexpectedly high while idling or while processing a transaction. | NATIVE_CFDP |
| steps_per_transaction_cycle | The step per transaction cycle defines how many steps or transaction cycles are performed prior to delaying the prescribed transaction cycle time. Increasing the steps per transaction cycle, increases the transaction speed or processing rate. The default value is 10. The minimum value is 1 and the maximum value is 2,147,483,647. This value should be incremented if the CFDP library is not able to achieve the aggregate file transfer rate. This value should be decremented if CPU usage on the host platform is unexpectedly high while idling or while processing a transaction. | NATIVE_CFDP |
| class_of_service | The class of service defines the CFDP level of service for the file transfer. The two CFDP levels of service are class1 and class2. CFDP class1 service is a "send and forget" level of service that sends files without any acknowledgement of their receipt by the recipient. CFDP class2 service requires file delivery acknowledgements in the form of ACKs and NAKs from the recipient. The default value is class2. | NATIVE_CFDP |
| auto_resize_nak_max_pdu_size | The auto_resize_nak_max_pdu_size boolean enables the automatic detection of dropped NAK PDUs and the resizing of the NAK maximum PDU packet size. The auto resize capability is advantageous when a CFDP transaction experiences a very large number of dropped packets or data gaps and the size of the NAK PDU packet that is identifying the gaps exceeds the capability of the transport medium (i.e., the NAK PDU packet is heavily fragmented and cannot successfully reach its destination). Under these conditions, CFDP's best option is to reduce the size of NAK PDU by splitting it up across multiple NAK PDUs. The CFDP auto resize code attempts to determine an acceptable value for the NAK maximum PDU size given the limitations of the transport medium and the understanding that the CFDP library's best performance is achieved by setting the NAK maximum PDU size to the largest value supported by the transport medium. If auto resize of the NAK maximum PDU size has been enabled and a CFDP transaction determines no NAK PDU packet has been successfully transmitted to its destination, the auto resize code automatically halves the NAK maximum PDU size and retransmits the PDU. The auto resize code continues to halve the NAK maximum PDU size and retransmit a smaller NAK PDU until the NAK PDU reaches its destination or the NAK maximum PDU size drops below 1280 bytes. Once a NAK PDU packet is successfully transmitted to its destination, the auto resize code is no longer exercised for that transaction and subsequent dropped NAK PDUs are not resized. Each new CFDP transaction initiates a new instance of the auto resize code. Therefore, the value for the maximum NAK PDU size may be different with different CFDP transactions. The auto resize code initialize the maximum NAK PDU size to the value provided by the nak_max_pdu_size CFDP parameter. By resetting the nak_max_pdu_size CFDP parameter in the CDFP configuration file or CFDP GUI to the value determined by the auto resize code, the CFDP application may avoid dropping NAK PDU packets that are too large to be supported by the transport medium. The default value is true. | NATIVE_CFDP |
| auto_suspend_and_resume | The auto suspend and resume boolean enables the automatic suspension or resumption of all CFDP transactions associated with a remote entity ID when a network connection to that remote entity ID has been lost or found. The TReK CFDP library creates a UPD socket that sends and receives four byte packets to confirm network connectivity. This capability may be used to detect Acquisition Of Signal (AOS) and Loss Of Signal (LOS) events enabling native CFDP to successfully transfer files across multiple AOS/LOS windows without manual intervention. Auto suspend and resume is only supported by the TReK CFDP library. Therefore, the TReK CFDP library software must be running on both the local and remote nodes. The default value is false. | NATIVE_CFDP |
| auto_suspend_and_resume_mode | The auto suspend and resume mode identifies the auto suspend and resume relationship between the local node and the remote nodes. The three auto suspend and resume mode parameter values are PEER_TO_PEER_MODE, CLIENT_OR_GROUND_MODE and SERVER_OR_FLIGHT_MODE. A peer to peer configuration allows all peer to peer nodes to perform CFDP transactions with each other. A client server configuration restricts CFDP transactions. A client may only perform CFDP transactions with a server and a server may only perform CFDP transactions with a client. A client may perform CFDP transactions with multiple server nodes and a server may perform CFDP transactions with multiple client nodes. The four byte connectivity packet is always being transmitted by all nodes in a peer to peer configuration regardless of network connectivity or AOS/LOS periods. In a client/ground and server/flight configuration the connectivity packet is always being transmitted by the client/ground node but the server/flight node only transmits the connectivity packet over a confirmed network connection during AOS periods. The default value is PEER_TO_PEER_MODE. | NATIVE_CFDP |
| auto_suspend_and_resume_port | The auto suspend and resume port is used to create the UDP socket that sends and receives the four byte connectivity packet. The default port value is 45600 (minimum value 0 and maximum value 65535). | NATIVE_CFDP |
| auto_suspend_and_resume_connection_timeout | The auto suspend and resume connection timeout value is the length of time, in seconds, that must pass between the receipt of connectivity packets before a connection between two entity IDs or nodes is declared lost. Connectivity packets are sent once every half second. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 5. | NATIVE_CFDP |
| local_entity_id local_ip_address local_port | The pre-assigned local entity ID integer value and its associated local IP address and local port. Only one local EID entry is supported by the CFDP library. The default local_ip_address value is 127.0.0.1. The default local_port value is 4560(minimum value 0 and maximum value 65535). | NATIVE_CFDP |
| remote_entity_id remote_ip_address remote_port | The pre-assigned remote entity ID integer value and its associated remote IP address and remote port. Multiple remote entity ID entries are supported by the CFDP library. | NATIVE_CFDP |
| remote_entity_id remote_ip_address remote_port peer_pub_key_path_and_file_name | The pre-assigned remote entity ID integer value and its associated remote IP address, remote port and the absolute path and name of the file containing the peer public key to encrypt and decrypt the native CFDP PDU packets. The peer public key is the public key of the remote/destination platform and is created by TReK's "trek_crypt" program. A peer public key path and file name must be provided to enable encryption and decryption of all CFDP transactions with the remote entity. Multiple remote entity ID entries are supported by the CFDP library. | NATIVE_CFDP |
| remote_entity_id remote_ip_address remote_port peer_pub_key_path_and_file_name time_to_live | The pre-assigned remote entity ID integer value and its associated remote IP address, remote port and the absolute path and name of the file containing the peer public key to encrypt and decrypt the native CFDP PDU packets. The peer public key is the public key of the remote/destination platform and is created by TReK's "trek_crypt" program. A peer public key path and file name must be provided to enable encryption and decryption of all CFDP transactions with the remote entity. If the encrypted CFDP session requires an encrypted timestamp, sequence count and TTL value to provide replay resistance time authentication in support of SCKIPS, include the TTL value, in seconds, after the peer public key path and file name. Multiple remote entity ID entries are supported by the CFDP library. Minimum TTL value is 0, maximum TTL value is 65535 and the default TTL value is 60. | NATIVE_CFDP |
| lifespan | The lifespan is the bundle's TTL in seconds. The bundle is destroyed if its TTL has expired and it has not reached its destination. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 86400. | ION_CFDP |
| bp_class_of_service | The BP class of service defines the transmission priority of outbound bundles from three ION priority queues corresponding to bulk, standard and expedited priorities. The three BP class of service parameter values are BULK_PRIORITY, STD_PRIORITY and EXPEDITED_PRIORITY. The expedited priority queue must be empty before bundles in the standard or bulk queues are serviced by ION. Therefore, bundles with EXPEDITED_PRIORITY should only be sent in critical/emergency situations. The default value is STD_PRIORITY. | ION_CFDP |
| expedited_priority_ordinal | The expedited priority ordinal is only associated with the EXPEDITED_PRIORITY class of service. Ordinal values range from 0 (lowest priority) to 254 (highest priority). The default value is 0. | ION_CFDP |
| transmission_mode | The transmission mode defines the reliability of bundle delivery to a destination. The three transmission mode parameter values are BEST_EFFORT, ASSURED and ASSURED_WITH_CUSTODY_TRANSFER. BEST_EFFORT relies upon the underlying convergence-layer protocol (e.g., Transmission Control Protocol or TCP) to retransmit missing bundles. ASSURED is a step up in reliability and includes BP support in detecting a lost TCP connection and re-forwarding of bundles assumed aborted by the convergence-layer protocol failure. ASSURED_WITH_CUSTODY_TRANSFER requires the reception, by the sending node, of a custody acceptance or refusal signal (packaged in a bundle) from the receiving node. The default value is ASSURED. | ION_CFDP |
| criticality | A critical bundle is one that has to reach its destination as soon as is physically possible. For this reason, bundles flagged as critical may not include custody transfer and require an ION configuration with contact graph routing. In some cases, a critical bundle may be sent over multiple routes to ensure delivery to its final destination. Critical bundles are placed in the expedited priority queue and should only be used in emergency situations. The two criticality parameters are NOT_CRITICAL and CRITICAL. The default value is NOT_CRITICAL. | ION_CFDP |
| support_transaction_result_message | The support transaction result boolean enables the generation and transmission of a CFDP transaction result message to the source node. If the source node receives the transaction result message within a designated time window, it will update its transaction status with the transaction result (e.g., success or fail). If the support transaction result boolean is set to "true" and the result message is not received within a designated time window, the source node's transaction status is set to "unknown". If this boolean is set to "false" and the source node did not experience any problems while transmitting the CFDP transaction request, the final transaction status is set to "finished". This capability is only supported by the TReK CFDP library. Therefore, the TReK CFDP library software must be running on both the source and destination nodes. The default value is true. | ION_CFDP |
| transaction_result_message_timeout | The transaction result message timeout is the length of time, in seconds, the TReK CFDP library will wait for a transaction result message prior to setting the final status of the transaction to "unknown". Choosing the proper transaction result message timeout is problematic. ION CFDP processes CFDP transactions sequentially so careful considerations must be made when setting this value. If a large number of files are being uplinked and downlinked simultaneously, a larger timeout value may be necessary. In addition, the timeout value should include LOS windows if the file transfer will span LOS periods (the result message timer is not paused during an LOS). Too small a value will unnecessarily set the final status of a transaction to "unknown", too large a value will introduce an unnecessary wait prior to setting the final status of the transaction to "unknown" if a final status message is never received. It is best to choose too large a value versus too small a value. Minimum value is 1, maximum value is 2,147,483,647 and the default value is 300. | ION_CFDP |
| add_tmp_cfdp_filename_extension | The "tmp_cfdp" file name extension boolean should be set to "true" if ION is transferring one or more files to a TReK dropbox directory. The most common scenario is if an encryption dropbox has been created and configured to place an encrypted file in an ION CFDP dropbox. If the ION CFDP dropbox is configured to transfer the encrypted file to a decryption dropbox on the destination platform, the "tmp_cfdp" file name extension boolean must be "true" on the source or sending platform to properly decrypt the file on the destination platform. If this boolean is set to "true", a temporay file name is created for all file transfers by adding a ".tmp_cfdp" file name extension to the original file name on the destination platform. Upon successful completion of the file transfer, the ".tmp_cfdp" extension is removed from the file name on the destination platform. If the destination is a dropbox, the dropbox will use the file name to determine both when the file has completed its transfer and when the file may safely be decrypted by the dropbox. If this boolean is set to "false", no temporary file name is used during the file transfer and ION "put" transfers to a TReK dropbox directory are not supported. Native CFDP uses a temporary "tmp_cfdp" file name for all file transfers and does not require this boolean flag when transferring files to a dropbox directory. Setting the "tmp_cfdp" file name extension boolean to "true" even if a file transfer destination is not a TReK dropbox directory is supported and does not impact performance. However, the destination platform must be hosting TReK version 5.2.0 or higher to properly remove the ".tmp_cfdp" file name extension. The default value is true. | ION_CFDP |
| display_console_menu | The display console menu boolean controls displaying the console command primitive menu during startup of the console application. The default value is true. | NATIVE_CFDP ION_CFDP |
| display_error_messages | The display error messages boolean controls displaying error messages by the CFDP GUI and console applications. If "true", error messages are displayed by the CFDP GUI or console applications. The default value is true. | NATIVE_CFDP ION_CFDP |
| display_warning_messages | The display warning messages boolean controls displaying warning messages by the CFDP GUI and console applications. If "true", warning messages are displayed by the CFDP GUI and console applications. The default value is false. | NATIVE_CFDP ION_CFDP |
| display_info_messages | The display info messages boolean controls displaying information messages by the CFDP GUI and console applications. If "true", information messages are displayed by the CFDP GUI and console applications. The default value is true. | NATIVE_CFDP ION_CFDP |
| display_progress_messages | The display progress messages boolean controls displaying progress messages by the CFDP GUI and console applications. If "true", progress messages are displayed by the CFDP GUI and console applications. The default value is false. | NATIVE_CFDP ION_CFDP |
| display_debug_messages | The display debug messages boolean controls displaying debug messages by the CFDP GUI and console applications. If "true", debug messages are displayed by the CFDP GUI applications. The default value is false. | NATIVE_CFDP ION_CFDP |
| default_remote_entity_id * | The default remote entity ID is used by the CFDP GUI application to save a default value for the remote EID. The default value is blank. | NATIVE_CFDP ION_CFDP |
| default_destination_command_line * | The default destination command line is used by the CFDP GUI application to save a selected default command line destination path from the list of default destination paths. The default value is blank. | NATIVE_CFDP ION_CFDP |
| default_destination_command_list * | The default destination command list is used by the CFDP GUI application to save a selected default command list destination path from the list of default destination paths. The default value is blank. | NATIVE_CFDP ION_CFDP |
| default_destination_path * | The default destination path is used by the CFDP GUI application to save the list of default destination paths. The default value is blank. | NATIVE_CFDP ION_CFDP |
| gui_command_line_primitive * | Used by the CFDP GUI application to save the command line primitive. The default value is blank. | NATIVE_CFDP ION_CFDP |
* This parameter is not relevant for user applications.
Put:
The TReK CFDP library provides a series of "put" functions to push files to a remote destination. The Put library function initiates a file transfer process using TReK's CFDP library configuration file parameters, the source and destination pathnames and a destination EID or node number. The PutCFDP library function initiates a file transfer process by delivering a "put" primitive character string to the CFDP library.
Acceptable formats of the "put" primitive string for native CFDP are as follows:
The first format example is a "put" of a file. The second format examples is a "put" of all the files in a directory.
A "/" at the end of the source and destination strings identifies the primitive as a "put" of all the files in the directory. Note, the CCSDS CFDP Blue Book does not define a "put" directory request. The TReK CFDP library creates individual "put" file requests from a single "put" directory request.
Acceptable formats of the "put" primitive string for ION CFDP are as follows:
The first and third format examples are a "put" of a file. The second and forth format examples are a "put" of all the files in a directory.
The third and fourth examples of primitive strings use the parameter values in the TReK CFDP library configuration file to set TTL, priority, mode and criticality if they were not specified in the primitive string. The TReK CFDP library does not use dotted octet string representation of the EID. The integer value of the EID or its string equivalent is required. The PutComponentCFDP and PutComponentION functions perform the same function as PutCFDP function but instead of describing the file transfer with a primitive string, the functions' input parameters are the individual components of the primitive string. The AddPut function adds a "put" transaction request to a list of CFDP "put" requests using TReK's CFDP library configuration file parameters and the source and destination pathnames and destination EID or node number. The AddPutRequest function adds a "put" primitive to the list of CFDP "put" requests. AddPutComponentRequest and AddPutComponentRequestION perform similar function but works with "put" primitive components instead of a "put" primitive string. The AddPut functions do not initiate the file delivery process.
The SendAllPutRequests initiate file transfer process by delivering each "put" request in the "put" list to the CFDP library. The native CFDP library simultaneously executes each "put" request in the list. The library does not execute each "put" request sequentially. ION CFDP executes each put request sequentially in a first in first out order assuming the all transactions have the same priority.
After a "put" list has been delivered to the CFDP library, the "put" requests should be removed from the list. The RemoveAllPutRequests function removes all the "put" requests from the "put" list. Alternatively, individual "put" requests may be removed from the "put" list by calling the RemovePutRequest function or RemovePutComponentRequest function and passing the "put" primitive or "put" primitive components to the appropriate RemovePut function.
Get:
The TReK CFDP library also provides a series of "get" functions to get or retrieve files from a remote destination.
The CCSDS CFDP Blue Book describes implementation of a "get" as a proxy "put". Enhancements were made to the GSFC CFDP library to support the CCSDS CFDP Blue Book's proxy "put" implementation (proxy request and response messages). However, no such enhancements were made to the ION CFDP library. Therefore, the "get" request and response messages for ION CFDP will only succeed if both sides of the file delivery transaction are using the TReK CFDP library. The TReK CFDP library's "get" functions mirror the "put" functions. The Get and GetCFDP function initiates the file transfer process by delivering a "get" request in the form of a proxy "put" request containing an equivalent "put" primitive character string to the remote platform's CFDP library (i.e., CFDP implements a "get" file from a remote platform by performing a "put" file from the remote platform). There is an error scenario in which the initiator of the ION CFDP “get” receives no feedback. If an ION CFDP “get” request message or “get” response message never reaches its target platform, the initiator will receive no status describing the result of the “get” request.
Acceptable formats of the "get" primitive string for native CFDP are as follows:
The first format example is a "get" of a file. The second format examples is a "get" of all the files in a directory.
A "/" at the end of the source and destination strings identifies the primitive as a "get" of all the files in the directory. Note, the CCSDS CFDP Blue Book does not define a "get" directory request so the request will only succeed if both sides of the file delivery transaction are using the TReK CFDP library.
Acceptable formats of the "get" primitive string for ION CFDP are as follows:
The first and third format examples are a "get" of a file. The second and forth format examples are a "get" of all the files in a directory.
The third and fourth examples of primitive strings use the parameter values in the TReK CFDP library configuration file to set TTL, priority, mode and criticality if they were not specified in the primitive string. The GetComponentCFDP and GetComponentION functions perform the same function as GetCFDP function but instead of the describing the file transfer transaction with a primitive string, the functions' input parameters are the individual components of the primitive string. The AddGet function adds a "get" transaction request to a list of CFDP "get" requests using TReK's CFDP library configuration file parameters and the source and destination pathnames and destination EID or node number. The AddGetRequest function adds a "get" primitive to a list of CFDP "get" requests. AddGetComponentRequest and AddGetComponentRequestION perform similar function but works with "get" primitive components instead of a "get" primitive string. The AddGet functions do not initiate the file delivery process. The SendAllGetRequests initiate file transfer process by retrieving each "get" request in the "get" list and delivering an equivalent "put" primitive character string to the remote platform's CFDP library. The remote CFDP library executes each "put" request that corresponds to a "get" request in the "get" list. After a "get" list has been executed, the "get" requests should be removed from the list. The RemoveAllGetRequests function removes all the "get" requests from the "get" list. Alternatively, individual "get" requests may be removed from the "get" list by calling the RemoveGetRequest function or RemoveGetComponentRequest function and passing the "get" primitive or "get" primitive components to the appropriate RemoveGet function.
Filestore Actions:
The TReK CFDP library provides a series of filestore functions to act on files or directories on a remote platform.
The following table identifies the filestore action and defines its required pathname parameter(s):
| Filestore Action Primitive | Pathname Parameter(s) |
| create_file | (1) Pathname of new file |
| delete_file | (1) Pathname of file to be deleted |
| rename_file | (1) Pathname of old file |
| append_file | (1) Pathname whose name and content forms first part of new file |
| replace_file | (1) Pathname of file to be replaced |
| create_dir | (1) Path of new directory |
| remove_dir | (1) Path of directory to be removed (directory must be empty) |
| deny_file | (1) Pathname of file to be deleted (does not fail if file does not exist) |
| deny_dir | (1) Path of directory to be removed (directory must be empty and does not fail if directory does not exist) |
The Filestore library function initiates a filestore action using TReK's CFDP library configuration file parameters, one or more pathnames and a destination EID or node number. The FilestoreCFDP library function initiates a filestore action by delivering a filestore primitive character string to the CFDP library.
Acceptable formats of the filestore primitive string for native CFDP are as follows:
Acceptable formats of the filestore primitive string for ION CFDP are as follows:
The second and third examples of the ION filestore primitive strings use the parameter values in the TReK CFDP library configuration file to set TTL, priority, mode and criticality. The FilestoreComponent and FilestoreComponentION function performs the same function as FilestoreCFDP function but instead of describing the filestore action with a primitive string, the functions' input parameters are the individual components of the primitive string. The AddFilestore function adds a filestore transaction request to a list of CFDP filestore requests using TReK's CFDP library configuration file parameters the first pathname, the second pathname (if required) and the destination EID or node number. The AddFilestoreRequest function adds a filestore primitive to the list of CFDP filestore requests. AddFilestoreComponentRequest and AddFilestoreComponentRequestION perform a similar function but work with filestore primitive components instead of a filestore primitive string. The AddFilestore functions do not initiate the filestore transaction.
The SendAllFilestoreRequests initiate filestore transaction by delivering each filestore request in the filestore list to the CFDP library. After a filestore list has been delivered to the CFDP library, the filestore requests should be removed from the list. The RemoveAllFilestoreRequests function removes all the filestore requests from the filestore list. Alternatively, individual filestore requests may be removed from the filestore list by calling the RemoveFilestoreRequest function or RemoveFilestoreComponentRequest function and passing the filestore primitive or primitive components to the appropriate RemoveFilestore function.
CFDP Messages:
The TReK CFDP library provides a messaging capability to send a message to a remote platform.
The Message library function initiates a message action using a string no greater than 256 characters in length including the NULL terminator and a destination EID or node number. The MessageCFDP library function initiates a message action by delivering a message primitive character string to the CFDP library.
Acceptable formats of the message primitive string for native CFDP are as follows:
Acceptable formats of the message primitive string for ION CFDP are as follows:
The second and third examples of the ION message primitive strings use the parameter values in the TReK CFDP library configuration file to set TTL, priority, mode and criticality. The MessageComponent and MessageComponentION function performs the same function as MessageCFDP function but instead of describing the message action with a primitive string, the function's input parameters are the individual components of the primitive string. The AddMessage function adds a message transaction request to a list of CFDP message requests using TReK's CFDP library configuration file parameters the message and the destination EID or node number. The AddMessageRequest function adds a message primitive to the list of CFDP message requests. AddMessageComponentRequest and AddMessageComponentRequestION perform a similar function but work with message primitive components instead of a message primitive string. The AddMessage functions do not initiate the message transaction.
The SendAllMessageRequests initiate message transaction by delivering each message request in the message list to the CFDP library. After a message list has been delivered to the CFDP library, the message requests should be removed from the list. The RemoveAllMessageRequests function removes all the message requests from the message list. Alternatively, individual message requests may be removed from the message list by calling the RemoveMessageRequest function or RemoveMessageComponentRequest function and passing the message primitive or primitive components to the appropriate RemoveMessage function.
The TReK CFDP library includes two functions that act on all the transaction lists. The SendAllRequests functions sends all put, get, filestore and message transaction requests in the transaction lists. The RemoveAllRequests removes all transaction requests in the transaction lists. The SaveAllRequestsToFile saves all transaction requests in the transaction lists to a primitives file and adds the "primitive_version X NATIVE_CFDP" or "primitive_version X ION_CFDP" identification text to the beginning of the file (the "X" in the text is a version number that may be incremented in future releases).
CFDP Dropboxes:
The TReK CFDP library provides the ability to create one or more CFDP dropboxes to push files to a remote destination. A TReK CFDP configuration file "dropbox" primitive defines a CFDP dropbox's operation parameters including where the dropbox is located and the destination of each file placed in the dropbox. CFDP dropboxes are created during initialization of the TReK CFDP library when InitToolkitCfdp function reads the TReK CFDP configuration file. A CFDP dropbox file is transferred to the dropbox destination immediately after the file is copied to the dropbox. Pre-existing dropbox files are immediately transferred after the creation of the dropbox.
Acceptable formats of the CFDP "dropbox" primitive string for native CFDP are as follows:
The CFDP dropbox primitive for native CFDP includes class 1 or class 2 service, the dropbox path, the remote entity ID, the destination path, the retry limit and the successful transaction path. The retry limit defines the number of additional attempts at transferring a file before declaring the transaction unsuccessful.
The successful transaction path is the path to a directory, on the dropbox source platform, where successfully transferred files are stored upon completion of a transaction. If the successful transaction path is empty, as shown in the second example, the dropbox will delete the file, on the source platform, if the file is successfully transferred to its destination.
For class 1 service, files are simply moved or deleted from the dropbox directory when the transaction has completed the number of retry attempts.
Acceptable formats of the CFDP "dropbox" primitive string for ION CFDP are as follows:
The CFDP dropbox primitive for ION CFDP is identical to native CFDP except "class1" or "class2" is replaced by the ION CFDP parameter values in the TReK CFDP configuration file (TTL, priority, mode and criticality) if the values were not specified in the primitive string. Another important distinction between ION and native CFDP dropboxes is associated with the retry limit. An ION CFDP dropbox ignores the retry limit value in the dropbox primitive and resets the value to zero in the TReK CFDP library. There are two important reasons why the ION CFDP dropbox does not attempt to retransmit failed CFDP transactions:
CFDP dropbox files are renamed with a ".dropbox" extension while they are being processed by the dropbox. If a CFDP dropbox fails to successfully transfer a file to the destination directory, a class 2 native CFDP dropbox will initiate additional transfer attempts up to the "retry limit" designated in the dropbox primitive. A class 1 native CFDP dropbox will blindly repeat the file transfer up to the "retry limit". If the final status message of a file transaction identifies an unsuccessful file transfer, the file is renamed with an ".unsuccessful" extension. If the CFDP library fails to receive the final status of a file transaction, the file is renamed with an ".unknown" extension.
If an error occurred during the file transfer, the file is renamed with a ".droperror" extension. Only successfully transferred files are moved or deleted from the dropbox directory.
Encrypt and Decrypt Dropboxes:
The TReK CFDP library provides the ability to create one or more encrypt and decrypt dropboxes to encrypt and decrypt files. A TReK CFDP configuration file dropbox primitive defines an encrypt or decrypt dropbox's operation parameters including where the dropbox is located and the local destination directory of each newly created encrypted or decrypted file. Encrypt and decrypt dropboxes are created during initialization of the TReK CFDP library when InitToolkitCfdp function reads the TReK CFDP configuration file. An encrypt or decrypt dropbox file is encrypted or decrypted prior to being transferred to a local destination directory on the dropbox platform. Pre-existing dropbox files are immediately encrypted or decrypted after the creation of the dropbox. If the local destination directory of an encrypt dropbox is a CFDP dropbox, the encrypted file will automatically be transferred to the CFDP dropbox's remote destination directory. If the CFDP dropbox's remote destination directory is a decrypt dropbox the encrypted file will automatically be decrypted and placed in the decrypt dropbox's destination directory.
By chaining together encrypt and decrypt dropboxes with a CFDP dropbox, a completely automated encrypt, CFDP file transfer, decrypt chain may be created and set in motion by placing a file in the local encrypt dropbox. The encrypt, decrypt, CFDP dropbox chain is currently the only method TReK provides to automate file encryption/decryption using ION CFDP.
Unlike ION CFDP, native CFDP provides access to the CFDP PDUs, making it possible to configure the TReK native CFDP application to encrypt and decrypt all CFDP transactions (e.g., "put", "get", "message", "create_file", "delete_file" ...) and avoid creating encrypt and decrypt dropboxes. Simply add a peer public key path and_file name to the end of the remote entity line in the native section of the CFDP configuration file. Review the description of the CFDP configuration file's remote entity IDs in the CFDP Library section of this document for further information on this native CFDP encrypt/decrypt configuration option.
Acceptable formats of the encrypt/decrypt dropbox primitive string are as follows:
The encrypt/decrypt dropbox primitive includes the encrypt or decrypt service, the dropbox path, the peer public key path and filename, the destination path, the crypt block size and the successful transaction path. The encrypt or decrypt service identifies whether the dropbox is encrypting or decrypting files. The dropbox path defines the location of the encrypt or decrypt dropbox while the peer public key path and filename define the location and name of the peer public key file. The peer public key is the public key of the destination platform. The encrypt/decrypt dropbox primitive includes a destination path to the local directory where the new encrypted or decrypted file is created and stored.
The crypt block size is an unsigned 32 bit value identifying the number of bytes that are read and encrypted or decrypted with every file read. A large crypt block size improves encryption and decryption performance but may also tax a CPU. If the successful transaction path is defined, as shown in the first example, the dropbox will move the original file placed in the dropbox to the successful transaction directory if and only if a new encrypted or decrypted file is successfully created and stored in the dropbox's destination directory. If the successful transaction path is empty, as shown in the second example, the dropbox will delete the original file placed in the dropbox if and only if a new encrypted/decrypted file is successfully created and stored in the dropbox's destination directory. If the encrypt or decrypt dropbox fails to encrypt or decrypt a file, the file will be renamed with a time tagged ".droperror" extension and remain in the dropbox. The encrypt or decrypt dropbox will not attempt to encrypt or decrypt a file with a ".droperror" extension in its filename. The TReK encryption architecture uses OpenSSL's FIPS 140-2 validated cryptographic module.
Frag and Defrag Dropboxes:
The TReK CFDP library provides the ability to transfer very large, multi-Gigabyte, files by splitting the files apart using a fragmentation dropbox, transferring the file fragments, using a CFDP dropbox, to a defragmentation dropbox where the file fragments are put back together producing the original very large, multi-Gigabyte, file. A TReK CFDP configuration file frag or defrag dropbox primitive defines a frag or defrag dropbox's operation parameters including where the dropbox is located, the size of the file fragments and the frag or defrags destination directory and successful transaction directory. Frag and defrag dropboxes are created during initialization of the TReK CFDP library when InitToolkitCfdp function reads the TReK CFDP configuration file. Pre-existing dropbox files are immediately fragmented after the creation of the frag dropbox. If the local destination directory of a frag dropbox is a CFDP dropbox, the file fragment will automatically be transferred to the CFDP dropbox's remote destination directory. If the CFDP dropbox's remote destination directory is a defrag dropbox, the fragmented file will automatically be put back together and moved to the defrag dropbox's destination directory when all the file fragments have been received by the defrag dropbox. By chaining together frag and defrag dropboxes with a CFDP dropbox, a completely automated file fragmentation, CFDP file transfer, file defragmentation chain may be created and set in motion by placing a file in the local frag dropbox. In addition, encrypt and decrypt dropboxes may be chained to the frag and defrag dropboxes producing an automated sequence of file encryption, file fragmentaion, CFDP file transfer, file defragmentation and file decryption. The fragmentation dropbox comes in two flavors: "frag" or "frag_cfdp". A "frag" dropbox creates a series of file fragments and immediately places the fragments in the dropbox's destination directory which may or may not be a CFDP dropbox directory. If the "frag" dropbox destination directory is a CFDP dropbox, the file fragments are downlinked simultaneously in a series of independent CFDP transactions. A "frag_cfdp" dropbox creates a series of fragments but only after the successful CFDP transfer of the previous file fragment to the remote destination of CFDP dropbox. In other words, a "frag_cfdp" dropbox's destination directory must be a CDFP dropbox directory and the "frag_cfdp" dropbox will only create the next file fragment after the previous file fragment has been successfully transferred by the CFDP dropbox. For this reason, a "frag_cfdp" dropbox's destination directory must be CFDP dropbox directory. If multiple files are added to a "frag_cfdp" dropbox simultaneously, the "frag_cfdp" dropbox will process the files one at a time, fragmenting and transferring all the fragments from one file prior to fragmenting and transferring all the fragments from the next file in the "frag_cfdp" dropbox. A "frag_cfdp" dropbox will require more time to transfer a very large file but has the advantage of an orderly and immediate cancellation of file fragmentation if there are problems transferring a file fragment using CFDP.
Acceptable formats of the frag/defrag dropbox primitive string are as follows:
The frag/frag_cfdp dropbox primitive includes the frag or frag_cfdp service, the dropbox path, the destination path, the 32 bit file fragmentation size, in bytes, and the successful transaction path. The defrag dropbox primitive includes the defrag service, the dropbox path, the destination path and the successful transaction path. The frag, frag_cfdp or defrag service identifies whether the dropbox is fragmenting or defragmenting/reconstructing files. The frag or frag_cfdp dropbox breaks up a file into
fragments sized to match the desired file fragmentation size, in bytes, and creates a new file fragment name by adding the current file fragment count and total fragment count to the fragmented file's dropbox extension. The defrag dropbox parses the file fragment name to identify the file's current and total fragment count prior to reconstructing the original file. The frag and defrag dropbox primitives also include a destination path to the local directory where the file fragments or reconstructed files are stored. If the successful transaction path is defined, as shown in the first example, the dropbox will move the original file or file fragments placed in the dropbox to the successful transaction directory if and only if new file fragments or reconstructed files are successfully created and stored in the dropbox's destination directory. If the successful transaction path is empty, as shown in the second example, the dropbox will delete the original file or file fragments placed in the dropbox if and only if new file fragments or reconstructed files are successfully created and stored in the dropbox's destination directory. If the frag or defrag dropbox fails to fragment or reconstruct the file, the file will be renamed with a time tagged ".droperror" extension and remain in the dropbox. The frag or defrag dropbox will not attempt to fragment or defragment/reconstruct a file with a ".droperror" extension in its filename.
Bit Rate:
The TReK native CFDP library provides the ability to change the aggregate file transfer bit rate, in real time, for local or remote entities without deactivating/reactivating the TReK CFDP service or application. A TReK "bit_rate" primitive has been defined that includes the desired bit rate, in bits per second, and the affected entity ID. The "bit_rate" primitive is delivered to a remote entity in the form of a TReK CFDP message. The "bit_rate" primitive is not supported by ION CFDP.
The acceptable format of the "bit_rate" primitive string for native CFDP is as follows:
Close TReK Record Files:
The TReK CFDP library provides the ability to send a directive to a TReK Record library to close one or all open record files. A TReK "close_rec_file" primitive has been defined that includes the library device name of the TReK Record library, the record file name and the affected entity ID. If the record file name is not included in the primitive, all open record files associated with record library are closed. The TReK Record library automatically opens a new record file after it closes a current record file.
If the record file is closed without recording any packets it is deleted by the TReK Record library. The record library device name and record file names must be defined in the TReK Record library's configuration file. The "close_rec_file" primitive is delivered to a remote entity in the form of a TReK CFDP message.
The acceptable formats of the "close_rec_file" primitive string for native CFDP are as follows:
Primitive Files:
In addition to working with individual primitives, the TReK CFDP library may also populate its lists of put, get, filestore and message transaction requests by reading a file of primitives using the ProcessFileOfCFDPPrimitives function. The primitive file format also supports a "process" primitive of the form:
process <"primitive_file_path_and_filename">
The "process" primitive references the full path and filename of another file of primitives and is functionally recursive. All valid primitive files must begin with the text string "primitive_version X NATIVE_CFDP" or "primitive_version X ION_CFDP" on a single line (the "X" in the text is a version number that may be incremented in future releases). Files that do not contain the primitive version text string are considered invalid and will not be read.
Transaction Directives:
The TReK CFDP library provides functions to suspend, resume, cancel or get a report on a current CFDP transaction or all CFDP transactions. The transaction may be identified using a transaction ID or destination path and filename and destination EID. The native CFDP transaction ID string is a combination of the dotted octet EID string and transaction number (e.g., 1.0_1, 255.255_2...). The ION transaction ID string is a combination of the EID string and transaction number (e.g., 32123_1, 32123_2...). The transaction ID may be found in some of the messages generated by the CFDP library and in the cfdp structure that is returned by the callback function associated with RegisterCFDPDeviceData.
Transaction Suspension:
Native CFDP transaction suspension suspends both data transmission and timeout clocks associated with the platform’s file transfer transactions. The destination platform is not notified of the suspension of file transfer transactions on the source platform and may exceed its timeout limits if the source platform does not resume its file transfer transactions for an extended period of time. If the file transfer suspension is for an extended period of time, the destination platform must process a separate suspend transaction command to avoid exceeding its timeout limits. Both platforms may resume file transfer transactions when they receive separate resume file transfer transaction commands. With this understanding, if a "get" transaction is only suspended on the platform that initiated the "get", the timeout clocks and the file transmission thread will be suspended but the platform's file reception thread will continue to process the "get" transaction and produce a file. No ACK or NAK packets will be transmitted to the source platform and the source platform will eventually "abandon" the transaction. To properly suspend a "get" transaction, the suspend request must be made on the platform that is the source of the file. If a platform attempts to suspend a transaction immediately after it was submitted, the transaction may not have time to generate a transaction ID and the suspension will fail. This is more likely to occur when immediately suspending transactions using the destination pathname and eid.
ION CFDP completes its file transfer responsibilities when it hands off to ION’s BP application. The handoff may be relatively quick depending on the size of the file. The suspend transaction request for ION CFDP will not suspend a files transfer after the ION CFDP application hands off a transaction to ION’s BP application. The suspend transaction request does not affect ION CFDP file reception.
The lifespan of the packet bundles must also be considered when suspending for an extended period of time.
Transaction Monitoring:
The TReK CFDP library includes two functions to monitor the status of a file/filestore transaction requests (CFDP message transactions are not considered file/filestore transactions): PopulateCFDPStructArray and MonitorAllCFDPTransactions.
The PopulateCFDPStructArray function may be used to poll the CFDP library requesting the status of file/filestore transactions. The function returns an array of pointers to CFDP structures containing the status of the current CFDP transactions. It does not return the status of user messages or CFDP user operations (i.e., proxy messages) and they are not included in the transaction_count.
The format of the CFDP structure is as follows:
| Data Type | Member Variable Name | Description |
| char [256] | source_pathname | The path and filename of the source file. |
| char [256] | destination_pathname | The path and filename of the destination file. |
| long long | eid | Native CFDP sets the entity ID or eid to the remote entity ID associated with the platform's transaction. ION CFDP sets the eid to the destinaion eid associated with the transaction. |
| char [50] | transaction_id | The transaction ID string combining the decimal dotted notation EID with a transaction number. |
| unsigned short | percent_transferred | The percentage of the file that has been transferred. |
| unsigned long | bytes_transferred | The number of bytes of the file that have been transferred. |
| unsigned long | file_size | The size of the file in bytes. |
| time_t | start_time | The transaction start time in seconds that have passed since midnight, 1st January 1970 GMT. |
| time_t | finish_time | The transaction finish time in seconds that have passed since midnight, 1st January 1970 GMT. |
| time_t | suspend_time | The most recent transaction suspend time in seconds that have passed since midnight, 1st January 1970 GMT. |
| time_t | resume_time | The most recent transaction resume time in seconds that have passed since midnight, 1st January 1970 GMT. |
| double | transaction_timespan | The length of time, in seconds, to complete the transaction. Does not include any suspend time. |
| unsigned short | nak_count | The number of NAK PDU's that were sent or received. |
| unsigned char | cfdp_message_operation | Set to 1 if true (e.g., proxy operation message, directory listing operation message ...) otherwise 0. |
| char [256] | message | A user message received in a DTN BP metadata PDU. |
| char [32] | cfdp_action_string | A string describing the CFDP action (e.g. put, create file, delete file ...). |
| unsigned long | cfdp_filestore_action | CFDP filestore action (e.g., CFDP_UNDEFINED_FILESTORE_ACTION_TYPE, CFDP_CREATE_FILE, CFDP_DELETE_FILE, CFDP_RENAME_FILE,...). |
| unsigned long | cfdp_configuration | CFDP configuration (e.g., DS_DEVICE_SENDING, DS_DEVICE_RECEIVING). |
| unsigned long | cfdp_status | CFDP status (e.g., DS_PACKET_SENDING, DS_PACKET_RECEIVING, DS_SUSPEND, DS_RESUME, DS_CANCEL, DS_SUCCESS, DS_FAIL, DS_ABANDON, DS_UNKNOWN). |
| char [32] | response_string | A string describing the response to a proxy transaction request (i.e., a get request). |
The user is responsible for allocating the array's memory and deallocating the array's memory when transaction status monitoring is no longer required. The MonitorAllCFDPTransactions function monitors the status of all current transactions and does not return to the calling application until all transactions have completed or the monitor time has exceeded the timeout parameter associated with the request. The function returns an array of CFDP structures containing the completion status of the CFDP transactions. It does not return the status of user messages or CFDP user operations (i.e., proxy messages) and they are not included in the transaction_count. The user is responsible for deallocating the array's memory. Problems may develop when freeing the memory associated with the CFDP stucture array if the CFDP library's compiler or run time environment does not match the application code's compiler or run time environment. The FreeCFDPStructArrayMemoryAlloc function is provided to avoid those problems by freeing the memory in the same library that allocated it. The CFDP configuration file parameter "support_cfdp_status_requests" must be "true" for PopulateCFDPStructArray and MonitorAllCFDPTransactions to operate correctly. If "support_cfdp_status_requests" is "false", these functions return an error and the CFDP structure array is not updated.
CFDP Transactions in an AOS/LOS Environment:
Maintaining CFDP transactions across extended LOS periods is problematic. ION CFDP solves this issue by relying on DTN's store and forward infrastructure.
A contact plan that predicts AOS/LOS periods may be used to support ION CFDP transactions between a flight node and a ground node if the two nodes are communicating directly with each other. If the ION CFDP transaction communication path includes the Huntsville Operations Support Center DTN2 node, the DTN2 node will store and forward the ION CFDP transaction during AOS/LOS periods. Native CFDP is not supported by an underlying store and forward DTN infrastructure. A user must configure timeouts or manually suspend and resume CFDP at both ends of a transaction to maintain the transaction across an LOS period. The TReK CFDP library solves this native CFDP issue by providing an automatic suspend and resume capability during LOS and AOS periods. When the TReK CFDP library senses an LOS event, it automatically suspends all CFDP transactions. When the TReK CFDP library senses an AOS event, it automatically resumes all CFDP transactions. TReK identifies AOS and LOS events by sending and receiving a four byte connectivity packet over a predefined UDP socket. TReK's automatic suspend and resume design maintains native CFDP transactions across multiple LOS periods without adjusting timeout values or requiring user intervention. If new CFDP transactions are requested during an LOS period, the pending transaction requests are placed in a queue and are submitted to the TReK CFDP library at the beginning of the next AOS period. The automatic suspend and resume parameters in the TReK CFDP configuration file configure and control TReK's automatic suspend and resume feature.
See the TReK CFDP configuration table at the beginning of this page for a more detailed explanation on each of the automatic suspend and resume parameters.
TReK Messages:
A callback function may be used to deliver error, warning, information, progress and debug messages to a user application. The user must register their callback function using the RegisterMessage function. The callback function returns messages inside a message structure defined as follows:
| Data Type | Member Variable Name | Description |
| char | time_stamp | The GMT time the message was generated |
| enum message_category | category | The message category (e.g., MSG_CAT_ERROR, MSG_CAT_ERROR_ALERT, MSG_CAT_WARNING, MSG_CAT_WARNING_ALERT, MSG_CAT_INFO, MSG_CAT_INFO_ALERT, MSG_CAT_PROGRESS, MSG_CAT_DEBUG) |
| char | message | The message |
A user application may use the GetDisplayMessageMask function to determine if a message should be displayed. The function populates an unsigned integer with a mask value using the display message parameters in the configuration file. An arithmetic "and" of the mask and the message category associated with a message will produce a value greater than zero if a message should be displayed.
A variety of transaction status messages are generated by the CFDP library. A user application may receive these transaction status messages by registering a callback function with the library's RegisterCFDPDeviceData. The transaction status messages are delivered to the user callback function in CFDP status structures as defined in the Transaction Monitoring section of this document.
Logging:
The TReK CFDP library debug, progress, information, warning and error messages may be logged to a user specified file using the StartLoggingCFDPMessages function. A user application may also write messages to the log file using the LogMessage function. The StopLoggingCFDPMessages function stops writing messages to the log file and prepends a time tag to the log file name. The StartLoggingCFDPMessages function and StopLoggingCFDPMessages function are simple wrapper functions for the DS library's StartLoggingMessages function and StopLoggingMessages function.
Statistics:
The TReK CFDP library may record a snapshot of device and packet statistics to a user specified file using the StartRecordingCFDPStatSnapshot function. The snapshot of device and packet statistics is updated once a second with current statistics information at both the device and packet level. Device statistics provides information on all packets that are being received or sent by the device. Packet statistics provides information on the individual packet groups that are being received or sent by the device. Note, The ability to identify and group packets is not currently exposed in the DS library. Device and packet statistics information for all devices may be reset to zero by calling the ResetCFDPStatistics function.
The StopRecordingCFDPStatSnapshot function closes a statistics file and prepends a time tag to the file name. The file generated by statistics recording is a text file with values separated by commas. A ".csv" file extension is also added to the end of the filename if no file extension is provided.
Spreadsheet applications may be used to view the statistics file. The StartRecordingCFDPStatSnapshot function, StopRecordingCFDPStatSnapshot function and ResetCFDPStatistics function are simple wrapper functions for the DS library's StartRecordingStatSnapshot function, StopRecordingStatSnapshot function and ResetStatistics function. The following two tables identify and describe the device and packet statistics parameters. Note, ION CFDP relies upon the the bundle protocol to assure delivery of file segments therefore, device and packet statistics are not relevant.
| Device Statistics Parameter | Description |
| Device Key | A character string that uniquely identifies each device. |
| IP Address | The IP address of the device if it is a socket. |
| Port (C/L/S) | The port number of the device if it is a socket. If the socket is a client socket then the port number will be followed by two "/". If the client socket is connected to a listener socket, the listener's port number is also listed. If the socket is a server socket then the client port number that is connected to the server is listed first, followed by two "/" and the server's listener port number. If the socket is a listener socket the listener's port number is listed between two "/". |
| Protocol | The IP transportation protocol, either TCP or UDP, of a socket device. |
| Segments Rcvd | The number of segments received by the device if the device is a TCP socket. |
| Pkts Rcvd | The total number of packets received by the device. |
| Pkts Sent | The total number of packets sent by the device. |
| Pkt Rcv Rate | The number of packets received by the device in the last second. |
| Max Pkt Rcv Rate | The maximum packet receive rate experienced by the device. |
| Kbit Rcv Rate | The number of kilobits received by the device in the last second. |
| Max Kbit Rcv Rate | The maximum kilobit receive rate experienced by the device. |
| Pkt Send Rate | The number of packets sent by the device in the last second. |
| Max Pkt Send Rate | The maximum packet send rate experienced by the device. |
| Kbit Send Rate | The number of kilobits sent by the device in the last second. |
| Max Kbit Send Rate | The maximum kilobit send rate experienced by the device. |
| Pkts Dropped | The total number of packets that were dropped because they could not be temporarily stored in a queue or buffer. The most likely cause of dropped packets is packets arriving at very high packet rates and/or a queue size that is too small. |
| Packet Statistics Parameter | Description |
| Packet Key | A character string that uniquely identifies each packet type. |
| Pkts Rcvd | The total number of packets that are received and identified as this packet type. |
| Pkts Sent | The total number of packets that are sent and identified as this packet type. |
| Pkt Rcv Rate | The number of packets received and identified as this packet type in the last second. |
| Max Pkt Rcv Rate | The maximum packet receive rate experienced by this packet type. |
| Kbit Rcv Rate | The number of kilobits received and identified as this packet type in the last second. |
| Max Kbit Rcv Rate | The maximum kilobit receive rate experienced by this packet type. |
| Pkt Send Rate | The number of packets of this packet type sent in the last second. |
| Max Pkt Send Rate | The maximum packet send rate experienced by this packet type. |
| Kbit Send Rate | The number of kilobits of this packet type sent in the last second. |
| Max Kbit Send Rate | The maximum kilobit send rate experienced by this packet type. |
| Pkts Dropped | The number of packets, of this type, that were dropped because they could not be processed by another device. The most likely cause of dropped packets is packets arriving at very high packet rates. |
| Pkt Seq Errors | The total number of packet sequence errors identified for this packet type. For example, the primary header of the CCSDS packet contains a 14-bit number that is used as a sequence count. For each packet that arrives, the sequence count is compared to the sequence count of the previous packet. If the count is not the next in the sequence, the packet sequence error value is incremented. |
| Max Pkt Seq Error | The maximum packet sequence error experienced by this packet type. |
Metrics:
The TReK CFDP library may record a snapshot of CFDP transaction metrics to a user specified file using the StartRecordingCFDPMetricsSnapshot function. The snapshot of CFDP metrics is updated once a second with the completion status of each CFDP transaction. The CFDP metrics are divided into sending and receiving categories and grouped by file size ranging from less than a one megabyte to over a gigabyte. The metrics include calculations on the number and percent of files sent or received, the minimum, maximum and average file transfer time and the number and percent of files that required packet retransmission. All CFDP metrics information may be reset to zero by calling the ResetCFDPMetrics function. The StopRecordingCFDPMetricsSnapshot function closes a metrics file and prepends a time tag to the file name. The file generated by CFDP metrics recording is a text file with values separated by commas.
A ".csv" file extension is also added to the end of the filename if no file extension is provided. Spreadsheet applications may be used to view the CFDP metrics file. The following table identifies and describes the CFDP metrics parameters. Note, ION CFDP relies upon the the bundle protocol to assure delivery of file segments therefore, NAK metrics are not relevant.
| CFDP Metrics Parameter | Description |
| File Size (MB) | The minimum and maximum file size, in megabytes, for the group. |
| Success Count | The number of successful file transfers. |
| Success % | The percentage of successful file transfers. |
| Cancel Count | The number of canceled file transfers. |
| Abandon Count | The number of abandoned file transfers. |
| Fail Count | The number of failed file transfers. |
| Unknown Count | The number of unknown file transfers. |
| Min Trans Time (sec) | The minimum successful file transfer time in seconds. |
| Max Trans Time (sec) | The maximum successful file transfer time in seconds. |
| Avg Trans Time (sec) | The average successful file transfer time in seconds. |
| Success W/ NAK Cnt * | The number of successful file transfers that required one or more NAK packets. |
| Success W/ NAK % * | The percentage of successful file transfers that required one or more NAK packets. |
| Min NAK CNT/Trans * | The minimum number of NAK packets that had to be transferred for a successful file transfers requiring NAK packets. |
| Max NAK Cnt/Trans * | The maximum number of NAK packets that had to be transferred for a successful file transfer requiring NAK packets. |
| Avg NAK Cnt/Trans * | The average number of NAK packets that had to be transferred for a successful file transfer requiring NAK packets. |
* This parameter is not relevant for ION CFDP.
Email and Text Alerts:
The TReK CFDP GUI provides the capability to generate and send an email or text alert to a list of designated recipients identifying the success or failure of a CFDP file transaction. This feature is not supported in the TReK CFDP console application. Please review the "Manage E-Mail and Text Settings" in the CFDP User Guide or online Help for details on how to configure TReK to send CFDP file transaction email and text alerts.
The TReK CFDP GUI also has the ability to send a TReK CFDP status report alert in the form of a text or email, every twelve or twenty four hours. The CFDP status report text alert identifies the number of CFDP transactions that were a success, were a failure, were cancelled, were abandoned or were unknown over a twelve and twenty four hour period. The CFDP status report text alert also includes infomation on the number of TReK error messages that were generated and the number of Native CFDP AOS windows exceeding sixty seconds (assuming TReK Native CFDP is configured to automatically suspend and resume CFDP transactions) that were encountered over the same period. The CFDP status report email alert includes all the information found in the CFDP status report text alert but also provides an email file attachment detailing each individual transaction, error message and Native CFDP AOS window. The twelve hour CFDP status report alert is sent as a text and/or email at 6:00 p.m. local time and the twenty four hour CFDP status report is sent as a text and/or email at 6:00 a.m. local time. After the twenty four CFDP status report alert is sent, all transaction counts, error counts and Native CFDP AOS window counts are reset to zero. The CFDP status report email file attachment includes the last fifty TReK error messages for the twelve and twenty four hour periods and also includes the details about the Native CFDP AOS windows that exceed sixty seconds in duration for the twelve and twenty four hour periods.
The following is an example of a TReK CFDP status report and includes the messages only found in the CFDP status report email file attachment:
Final Notes
The TReK CFDP library is thread safe. The size of the file that may be transferred by the library must be greater than zero and less than 4.29 gigabytes for native CFDP and greater than zero for ION CFDP. The absolute upper limit for the number of files that may be opened simultaneously on a Windows computer using native CFDP is 2048. The maximum concurrent transactions for native CFDP is 2000. The maximum primitive string length for native CFDP is 255 characters.
The maximum source path and filename length for ION CFDP is 255 characters. The maximum destination path and filename length for ION CFDP is 246 characters.
If you attempt to transfer an item to a destination and the item already exists at the destination, you will see a "cancelled (Filestore rejection)" or "Failed" error message and the existing item will not be overwritten. Call the DSCleanUp function prior to exiting to gracefully shut down and properly clean up the TReK CFDP library. Be sure to look at the examples provided with this library for a better understanding on how to use the library functions. Dynamic Link Libraries (DLLs) for all the examples may be found in a DLL folder in the TReK install directory.
Click on this link toolkit_cfdp_api_ansi_c.h to go to the header file with all the functions.
Functions from other APIs
LogMessage
RegisterMessage
DSCleanUp
GetMessageCategoryAsString
GetMessageCategoryAsPaddedString
TCAACGetHomeDirectory
Examples
The following examples are provided to show how to use the TReK CFDP library functions supporting native CFDP:
Simple CFDP destination node
An application that is acting as the destination/remote EID or node for the CFDP examples applications.
Source File:
cfdp_destination/main.c
CFDP Put a Single File
Shows how to CFDP put a single file to the CFDP destination application using PutComponentCFDP and PopulateCFDPStructArray functions.
Source File:
cfdp_put_example_1/main.c
CFDP Put Multiple Files
Shows how to CFDP put multiple files to the CFDP destination application using AddPutComponentRequest, SendAllPutRequests and MonitorAllCFDPTransactions functions.
Source File:
cfdp_put_example_2/main.c
CFDP Get a Single File
Shows how to CFDP get a single file from the CFDP destination application using GetComponentCFDP and PopulateCFDPStructArray functions.
Source File:
cfdp_get_example_1/main.c
CFDP Get Multiple Files
Shows how to CFDP get multiple files from the CFDP destination application using AddGetComponentRequest, SendAllGetRequests and MonitorAllCFDPTransactions functions.
Source File:
cfdp_get_example_2/main.c
CFDP Filestore Example
Shows how to CFDP create, delete, append and rename files on the CFDP destination host platform using Filestore, FilestoreComponent, AddFilestore, AddFilestoreComponentRequest, SendAllRequests, MonitorAllCFDPTransactions and RemoveFilestoreComponentRequest functions.
Source File:
cfdp_filestore_example/main.c
Process a file of CFDP Command Primitives
Shows how to use a file of CFDP command primitives to put and get multiple files from the CFDP destination application using ProcessFileOfCFDPPrimitives, MonitorAllCFDPTransactions and RemoveAllRequests functions.
Source File:
cfdp_process_primitive_file/main.c
The following examples are provided to show how to use the TReK CFDP library functions supporting ION CFDP or CFDP over BP:
Simple CFDP BP destination node
An application that is acting as the destination/remote EID or node for the CFDP BP examples applications.
Source File:
cfdp_bp_destination/main.c
CFDP BP Put Multiple Files
Shows how to CFDP put multiple files to the CFDP destination application using Put, AddPut, AddPutComponentRequestION, SendAllPutRequests, MonitorAllCFDPTransactions and RemovePutComponentRequest functions.
Source File:
cfdp_bp_put_example/main.c
CFDP BP Get Multiple Files
Shows how to CFDP get multiple files from the CFDP destination application using Get, AddGet, AddGetComponentRequestION, SendAllGetRequests, MonitorAllCFDPTransactions and RemoveGetComponentRequest functions.
Source File:
cfdp_bp_get_example/main.c
CFDP BP Filestore Example
Shows how to CFDP create, delete, append and rename files on the CFDP destination host platform using Filestore, FilestoreComponentION, AddFilestore, AddFilestoreComponentRequestION, SendAllRequests, MonitorAllCFDPTransactions and RemoveFilestoreComponentRequest functions.
Source File:
cfdp_bp_filestore_example/main.c
Process a file of CFDP BP Command Primitives
Shows how to create and process a file of CFDP BP put, get, filestore and message primitives to put, get, rename and create files using ProcessFileOfCFDPPrimitives, MonitorAllCFDPTransactions and RemoveAllRequests functions.
Source File:
cfdp_bp_process_primitive_file/main.c
CFDP Console application
Shows how to develop a menu driven CFDP console application using a variety of TReK CFDP and DS library functions.
Source File:
trek_cfdp_console.cpp
Configuration File:
toolkit_cfdp_config.txt
Additional Dependencies
The TReK CFDP API is also dependent on the following libraries.
trek_toolkit_common_api
trek_toolkit_ds_api
trek_toolkit_dropbox_device_api
trek_toolkit_cfdp_api
trek_dropbox_device_api
trek_cfdp_device_api (Native CFDP)
cfdp_plus (Native CFDP)
trek_bp_device_api (ION CFDP)
trek_opencrypt_device_api (Cryptography)
libeay32 (Cryptography)
ssleay32 (Cryptography)