J3 Attachment - SPEC 1207.docx

Specification 1207:2020 Delivery of Braille Book and Magazine Files via the Internet

Revision History

Version 2.0 December 2024

NLS Specification No. 806 December 2024 Revision History

Final Approval Head, Engineering Section

(John Brown)

Head, Quality Assurance Section

(Margaret Goergen-Rood)

Chief, Materials Development Division

(Michael Katzmann)

Director

(Karen Keninger)

Table of ContentsTable of Contents

Scope This specification covers the delivery of electronic braille files (BRF) via the Internet to the National Library Service for the Blind and Physically HandicappedPrint Disabled (NLS), Library of Congress.

Reference documents The following documents and publications form a part of this specification. In the event of conflict between the documents and publications referenced herein and the content of this specification, the content of this specification shall be considered a superseding requirement.

Specifications The Internet Engineering Task Force (IETF) SSH File Transfer Protocol The document cited above is available from:

http://tools.ietf.org/id/draft-ietf-secsh-filexfer-13.txt

The Secure Shell (SSH) Authentication Protocol The document cited above is available from:

www.ietf.org/rfc/rfc4252

The MD5 Message-Digest Algorithm (RFC 1321, April 1992) The document cited above is available from:

www.ietf.org/rfc/rfc1321 National Library Service for the Blind and Physically HandicappedPrint Disabled, Library of Congress NLS Specification 800 Braille Books and Pamphlets

NLS Specification 801 Braille Magazines and Newspapers

NLS Specification 806 Packaging of Electronic Braille Files

The documents cited above are available from:

National Library Service for the Blind and Physically HandicappedPrint Disabled Library of Congress 1291 Taylor Street, NW Washington, DC 20542 https://www.loc.gov/nls/about/organization/standards-guidelines/contract-specifications/ www.loc.gov/nls/specs/

PKWARE, Inc.

.ZIP File Format Specification

The document cited above is available from:

PKWARE, Inc.

648 N. Plankinton Avenue, Suite 220 Milwaukee, WI 53203 www.pkware.com/documents/casestudies/APPNOTE.TXT

Standards Braille Authority of North America

Code for Computer Braille Notation, current edition The document cited above is available from:

www.brailleauthority.org/cbc/cbc.html

English Braille, American Edition The document cited above is available from:

www.brailleauthority.org/literary/literary.html

Unified English Braille The document cited above is available from:

http://www.iceb.org/ueb.html

Definitions Comment by Kyle Downes: Add BOPF Definition

BRF BOPF (Braille Ready FilesPackage File): Files that represent finished braille pages using North American ASCII-braille convention to represent the braille cellsAn XML file conforming to the requirements in NLS Specification 806.

BRF (Braille Ready Files): Files that represent finished braille pages using North American ASCII-braille convention to represent the braille cells.

SFTP (Secure File Transfer Protocol): A standard network protocol used to transfer files from one host to another.

MD5 (Message-Digest algorithm 5): An algorithm used to validate data integrity.

SCP (Secure Copy): A protocol that uses a simple public key infrastructure and encryption to allow users to securely transfer files between UNIX host systems.

ZIP: An archive file format that supports lossless data compression.

Requirements Uploading Obtaining access Contractors of braille books and/or magazines shall be provided credentials to access an account on the NLS/BPH computer server (nlsupload.loc.gov) Required information To obtain access, an application shall be made to the NLS/BPH automation officerthe PCS Contract Monitor via e‑mail to NLSautomation@loc.gov containing the following information:

a. Contractor’s name

b. Contact(s) [actual person(s) who will do uploading]

c. E-mail address(es) of the contact(s) specified above

d. Phone number(s) of the contact(s) specified above

e. Physical address (i.e., street address) of computer that will access nlsupload.loc.gov

f. NLS contract number, for example LCNLS08D0172

g. Scheduled final delivery date for the contract

h. IP address(es) from which the NLS/BPH server (nlsupload.loc.gov) will be accessed. These may discrete addresses or may be one or more ranges of address(es) (example 64.244.137.33 / 27). If the addresses apply to multiple locations, for each address(es) the relevant contact given in a) above shall be identified.

The Internet address(es) provided must be the static addresses of systems under the control of the contractor.

Changes to required information The NLS automation officerPCS Contract Monitor shall be notified a minimum of four weeks prior to any changes taking effect in the data provided in section 3.1.1.13.1.1.1. Access to nlsupload.loc.gov will be possible only from the IP address(es) provided in section 3.1.1.13.1.1.1. A change to the contractor’s Internet connection that alters its IP address(es) will prevent access.

Account maintenance Comment by Kyle Downes: I don’t think this applies any longer The contractor shall change the password of the account provided once every 50 days. Failure to take this action will prevent access to the NLS/BPH server.

Upload location and directory naming Files shall be uploaded to directories under the root directoryhome directory nlsupload.loc.gov/ingest/acme. Where “acme” is a subdirectory named for the contractor by NLS/BPH when the account is created.

Location for books Files for books shall be uploaded to a subdirectory called “braille.books” under the root directory.

(e.g. nlsupload.loc.gov/ingest/acmeabc/braille.books) Location for magazines Files for magazines shall be uploaded to a subdirectory called “braille.magazines” under the root directory.

(e.g. nlsupload.loc.gov/ingest/acmeabc/braille.magazines) Separate directory for each book or magazine Files shall be uploaded to a separate directory for each book or magazine. For books, the directory shall be named using the book’s 5-digit book number assigned by NLS and the 2-letter prefix BRbr. For magazines, the directory shall be named using the magazine’s NLS assigned name and the 2-letter prefix BRbr.

(e.g. nlsupload.loc.gov/ingest/acmeabc/braille.books/br12345) Limitation of files uploaded to directories No files other than those specified below will be uploaded.

File transfer protocols Files shall be uploaded using either Secure Copy (SCP) or Secure File Transfer Protocol (SFTP).

Required files Comment by Kyle Downes: Update this to align with 806 Only the following filesA ZIP file containing the following files shall be copied to the directory for each book or magazine specified in section 3.1.2 above:

a. A ZIP file containing all and only the BRF files for all of the volumes of a braille book or all parts of a braille magazine as required by NLS Specifications 800 and 801. The ZIP file shall be readable by the UNIX program unzip version 5.3.2.

b. A BOPF file as specified in NLS Spec 806

c. An XML file shall be created containing the MD5 checksum of the ZIP fileall the files uploaded to that directory. The checksum shall be calculated using the MD5 algorithm as described in the reference cited in Section 2.1 and shall be in the form of 32 hexadecimal digits. The format of the XML file is described by the following DTD, which shall be placed at the beginning of the checksum file.

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE diskcheck [ <!ELEMENT diskcheck (book, file+)> <!ATTLIST diskcheck version CDATA #FIXED "1.0" > <!ELEMENT book (#PCDATA)> <!ELEMENT file (filename, checksum)> <!ATTLIST file type CDATA #IMPLIED content CDATA #IMPLIED > <!ELEMENT filename (#PCDATA)> <!ELEMENT checksum (#PCDATA)> <!ATTLIST checksum type CDATA #REQUIRED> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE diskcheck [ <!ELEMENT diskcheck (book, file+)> <!ATTLIST diskcheck version CDATA #FIXED "1.0" <!ELEMENT book (#PCDATA)> <!ELEMENT file (filename, checksum)> <!ATTLIST file type CDATA #IMPLIED content CDATA #IMPLIED <!ELEMENT filename (#PCDATA)> <!ELEMENT checksum (#PCDATA)> <!ATTLIST checksum type CDATA #REQUIRED The <book> element shall contain the 5-digit book number.match the UID as found in the content of the BOPF dc:identifier (see section 3.3.2.1.h in NLS Specification 806).

The <filename> element shall contain the name of the file for which the checksum is calculated.

The “type” attribute on the <checksum> element shall contain the value “MD5.”

File names for books Comment by Kyle Downes: Check with Martys about naming formats

a. The checksum file for digital braille book files shall be named “br.nnnnn.md5,” where “nnnnn” is the 5-digit book number assigned by NLS. All alphabetic characters shall be lowercase. All numeric characters shall be Arabic.

b. The ZIP file for digital braille book files shall be named “br.nnnn.zip,” where “nnnnn” is the book’s 5-digit book number assigned by NLS. All alphabetic characters shall be lowercase. All numeric characters shall be Arabic.

c. All BRF files shall be named according to the requirements of NLS Specification 800.

d. The BOPF file shall be named according to the requirements of NLS Specification 806.

e.

File names for magazines Comment by Kyle Downes: These are not consistent with the examples in the appendix

a. The checksum file for digital braille magazines shall be named “br.magazinename_YYYY-MM[-DD]. md5xxmddyy.md5,” where “magazinenamexx” is the magazine’s name (supplied by NLS) using two alpha characters, “m” is the month using one alpha character (a-l), “dd” is the day (1-31) using two numeric characters (if single digit, add leading zero), and “yy” is the year using two numeric characters. NLS-assigned name. When an issue date contains a span of dates only the first date in the span shall be included in the filename. Month and day figures shall include leading zeros if needed to make up the two-character requirement. All alphabetic characters shall be lowercase. All numeric characters shall be Arabic.

b. The ZIP file for digital braille magazine files shall be named “br.magazinename_YYYY-MM[-DD].dbb.zip,” where “magazinename” is the magazine’s NLS-assigned name. When an issue date contains a span of dates only the first date in the span shall be included in the filename. Month and day figures shall include leading zeros if needed to make up the 2-character requirement. All alphabetic characters shall be lowercase. All numeric characters shall be Arabic.

c. All BRF magazine files shall be named according to the requirements of NLS Specification 801.

d. All BOPF magazine files shall be named according to the requirements of NLS Specification 806.

Check in For each book or magazine uploaded the contractor shall notify NLS/BPH via the web application called Producer Data Exchange (PDE) by logging on to the PDE and completing the web form .

Appendix Comment by Kyle Downes: Update appendix to make consistent and incorporate any changes made during editing.

Example Directory Contents

1. Sample ingest subdirectory contents for a digital braille book br.18111.zip br.18111.md5

2. Sample ingest subdirectory contents for a digital braille magazine br.rollingstone_2013-04-25.zip

1) br.rollingstonetext_2013-04-25.zip Example ZIP file contents

1. Sample ZIP file contents for a digital braille book

18111v1.brf 18111v2.brf 18111v3.brf 18111v4.brf

1) 18111.bopf

2) 18111v1.brf

3) 18111v2.brf

4) 18111v3.brf

5) 18111v4.brf

6) br.18111.md5

2. Sample ZIP file contents for a digital braille magazine

1) rsd2513.bopf

2) rsd2513a.brf

3) rsd2513b.brf

4) rsd2513.md5 Example Book upload

1. Definitions

1) The contractor is named Acme.

2) The book number we are using in this example is 67271.

3) The contractor’s account on the upload server is acme.

4) The producer’s home directory on the upload server is //ingest/abc.

5) The directory where uploaded books are to be placed on the upload server, in this case /ingest/abc/books/braille.books, already exists on the upload server.

6) The producer is using a UNIX/Linux system with a hostname of abcmachine to transfer the books.

7) The book is in the directory /abc/production/67271 on abcmachine.

8) The NLS uploadserver (at address nlsupload.loc.gov) is an alias to the actual server called sun10sunbsp09.loc.gov.

9) Given these assumptions, a screen capture of the book 67271 being uploaded to the server is given in the next section.

2. Command line SCP session acme@abcmachine% scp -r /acme/production/67271 \ acme@nlsupload.loc.gov:/ingest/acme/books password:

br.67271.zip 100% |***********************| 98606 KB 00:08 br.67271.md5 100% |***********************| 2249 KB 00:00 acme@abcmachine% ssh acme@upload.loc.gov password:

acme@sun10.loc.gov% ls -Fla /ingest/acmeabc/braille.books/67271 total 2570992 drwxr-xr-x 2 acme staff 946 Feb 4 16:28 ./ drwxrwxrwt 67 root sys 273794 Feb 4 16:39 ../ -rwxr-xr-x 1 acme staff 100973111 Feb 4 16:26 br.67271.zip* -rwxr-xr-x 1 acme staff 2249 Feb 4 16:26 br.67271.md5*

image1.png image2.png